Integrate React V2 into Development (v0.261.419)

.dockerignore

@@ -4,30 +4,43 @@
 !application/
 !application/single_app/
 !application/single_app/**
+!application/v2_ui/
+!application/v2_ui/**
 !docker-customization/
 !docker-customization/**
+!LICENSE
 
-.git/
-.github/
-.vscode/
-.azure/
-artifacts/
-deployers/
-docs/
-functional_tests/
-ui_tests/
-scripts/
+# ACR's archive matcher needs directory rules without trailing slashes.
+.git
+.github
+.vscode
+.azure
+artifacts
+deployers
+docs
+functional_tests
+ui_tests
+scripts
 
 **/.env
 **/.env.*
-**/.venv/
-**/venv/
-**/__pycache__/
-**/.pytest_cache/
+**/.venv
+**/venv
+**/__pycache__
+**/.pytest_cache
 **/*.pyc
 **/*.pyo
 **/*.pyd
 
-application/single_app/flask_session/
-application/single_app/uploaded_openapi_files/
-application/single_app/instance/
+application/single_app/flask_session
+application/single_app/uploaded_openapi_files
+application/single_app/instance
+# V2 React UI: never ship host build artifacts into the image context.
+# node_modules would overwrite the container's Linux dependency tree with the host's
+# platform-specific one, and a stale static/v2 from a local build would survive alongside
+# the freshly compiled bundle because COPY merges rather than replaces.
+application/v2_ui/node_modules
+application/v2_ui/dist
+application/single_app/static/v2
+application/single_app/native/onenote_extractor/target
+application/single_app/native/onenote_extractor/bin

.github/instructions/cosmos-response-boundaries.instructions.md

@@ -0,0 +1,80 @@
+---
+applyTo: '**/*.py'
+---
+
+# Cosmos document response boundaries
+
+Point reads and returned create/replace/upsert/patch documents in the application's
+pinned Cosmos SDK are `CosmosDict`, a mapping subclass. Query rows and nested JSON
+objects are plain dictionaries. `deepcopy(CosmosDict)` preserves its subclass.
+
+Storage owners must normalize a point response **before copying or passing it to
+an exact-dictionary/strict JSON contract**, using the bootstrap-free
+`normalize_cosmos_document` in `cosmos_document_utils.py`. This helper accepts
+`Mapping`, returns a plain top-level dictionary, preserves all fields and `_etag`,
+and rejects invalid types with `TypeError`. Translate invalid responses through
+the owner's existing failure path. Never normalize arbitrary iterables into a
+document, substitute `{}`, strip ETags, or recursively repair domain values.
+
+Keep domain validators strict. Normalization is not authorization, sanitization,
+metadata stripping, or permission to replay an uncertain external effect. Raw SDK
+responses are compatible with mapping consumers; an exposed wrapper by itself is
+not a product defect. Prove a strict downstream mismatch with a runtime regression
+before changing otherwise-compatible production code.
+
+New Cosmos test containers use the **installed application's SDK `CosmosDict`**
+for point reads and returned write documents by default. Query rows stay plain.
+Plain point responses require an explicit compatibility mode. Preserve ETags,
+partition routing, conditional updates, failure injection and transaction atomicity.
+Domain-level repository mocks do not need to impersonate Cosmos.
+
+## Reviewed inventory and deterministic CI
+
+`functional_tests/cosmos_response_boundaries.json` records point/query calls,
+helper references, consumer classifications and evidence by storage function.
+It separately inventories Cosmos-shaped inline/shared test containers. It is a
+review/change guard, not an interprocedural type checker or proof that every
+external service behaves correctly.
+
+After adding/changing a storage boundary or double:
+
+1. Run `python scripts/check_cosmos_response_boundaries.py --refresh`. Changed
+   implementations become `review-required`; regeneration never approves them.
+2. Review every changed entry's actual consumer. Classify it as
+   `normalized-strict`, `sdk-compatible`, `response-unused`, or `not-cosmos`
+   with a specific contract and runtime test reference. A `not-cosmos` entry
+   needs a concrete explanation of the similarly named non-Cosmos API.
+3. New/changed Cosmos doubles must use `sdk-default`; `legacy-inline` records
+   document unchanged pre-migration doubles, not permission to introduce another.
+   Add a real SDK runtime regression to the inventory's `tests` evidence for
+   changed owners. The gate automatically executes owner-runtime and SDK-default
+   evidence, in addition to its core contracts, so references are not merely
+   checked for existence.
+4. Run `python scripts/check_cosmos_response_boundaries.py --run-contracts`.
+   This checks the inventory and runs its selected suites with
+   `-p test_support.cosmos_network_guard`. Set `PYTHONPATH` to the application
+   and functional test directories using the platform's path separator.
+
+Do not copy a classification blindly, point every owner at a utility-only test,
+or treat a grep match/count as evidence of a defect. Reviews and references are
+invalidated when their implementations disappear or change. Legacy inline
+doubles remain explicitly recorded for staged, owner-specific migration.
+Unchanged legacy mapping consumers distinguish source review plus SDK API
+evidence from owner-runtime SDK coverage. Their source fingerprints form a
+closed baseline; a new or changed owner cannot borrow that limited assurance.
+Replace its baseline entry with real owner-runtime evidence, rather than
+expanding the source-only baseline.
+Owner-runtime evidence executes representative real-owner behavior; it does not
+claim exhaustive branch coverage for every function in that storage owner.
+Existing test-local compatibility seams also have a closed fingerprint baseline.
+A new or changed point override needs explicit `fault-injection` runtime evidence,
+which the gate executes; it cannot silently retain an old easy response override.
+
+The dedicated `cosmos-response-contract-check.yml` installs the existing pinned
+application/test requirements, uses no cloud credentials, and blocks socket/DNS
+network access before test collection. New application storage modules and test
+doubles cannot bypass it by choosing a new filename.
+Tokenizer data needed by the pinned application dependency is warmed during
+dependency setup into a workspace-local cache, before network access is blocked.
+Tests keep the real context-budget calculation; they do not download assets or
+replace budget/token behavior merely to run offline.

.github/instructions/location_of_functional_tests.instructions.md

@@ -96,6 +96,8 @@ if __name__ == "__main__":
     sys.exit(0 if success else 1)
 ```
 
+Under pytest, the `return False` path in this template now fails the test; see **pytest return-False guard (#1572)** below. New checks should use `assert`.
+
 ### **Multi-Test Pattern:**
 ```python
 def test_feature_a():
@@ -119,6 +121,16 @@ if __name__ == "__main__":
     sys.exit(0 if success else 1)
 ```
 
+### pytest return-False guard (#1572)
+
+pytest ignores a test function's return value, so under pytest a template-style test that returned `False` used to be reported as passed. `functional_tests/conftest.py` and `ui_tests/conftest.py` now fail a test that returns exactly `False` under pytest, with a message that names the test and refers to #1572. `True`, `None` and every other value are left alone. `python test_x.py` runs never load a conftest, so they behave as before.
+
+- Write new checks with `assert`. Where a check must still run under `python -O`, raise explicitly, for example `if not saved: raise AssertionError("settings were not saved")`.
+- Use `return True`/`return False` only to feed a `__main__` runner's exit code, as in the templates above. Under pytest, the `return False` path now fails the test, which is the intended outcome.
+- The guard does not cover `async def` tests or `unittest.TestCase` methods. A script whose `__main__` calls `pytest.main()` loads the conftest, so the guard applies to that run.
+- Keep the guard blocks identical. The code between `# --- begin pytest return-False guard (#1572) ---` and `# --- end pytest return-False guard (#1572) ---` must match in both conftest files, and `functional_tests/test_pytest_return_false_guard.py` fails if they differ. Put fixtures for one directory outside the block, and do not add collection hooks to either file.
+- A guard failure means the test returned `False` under pytest in that environment; it is not necessarily a product bug. Many older tests need Azure configuration, a running app, or setup that only their `__main__` runner performs, so run those with `python <file>`.
+
 ## 🔍 **Test Discovery & Reuse**
 
 ### Import Lifecycle and Assertion Safety

.github/instructions/xss-prevention.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: '**/*.js, **/*.html, **/*.py'
+applyTo: '**/*.js, **/*.html, **/*.py, **/*.ts, **/*.tsx, **/*.jsx, **/*.mjs'
 ---
 
 # Security: XSS Prevention and Browser Rendering
@@ -110,24 +110,83 @@ When a static HTML shell is genuinely simpler, it is acceptable only if:
 - It contains no `${...}` interpolation or dynamic concatenation
 - Untrusted values are populated afterward with `textContent`, `setAttribute(...)`, or `dataset`
 
+## React and TypeScript (V2 UI)
+
+The V2 UI in `application/v2_ui/src` is React 18 with TypeScript. React removes most string-to-HTML risk, but not all of it, so the same trust-boundary thinking applies.
+
+### What React 18 escapes
+
+- Text rendered as JSX children, such as `<p>{message.text}</p>`, is inserted as text, never parsed as HTML.
+- String values in attributes are escaped, so a quote in a value cannot break out of the attribute.
+
+### What React 18 does not protect
+
+- **URL-bearing props.** React 18 only logs a development warning for a `javascript:` URL in `href`, `src`, `action` or `formAction`; React 19 blocks it, React 18 does not. Treat these props, plus `srcDoc`, `xlinkHref` and router `to` on `Link`, `NavLink` and `Navigate`, as sinks.
+- **`dangerouslySetInnerHTML`.** The value is parsed as HTML with no escaping.
+- **Refs and DOM APIs.** `ref.current.innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`, `createContextualFragment`, and `DOMParser` output appended to the page all bypass React.
+- **DOM URL properties.** `element.href`, `element.src`, `form.action`, `frame.srcdoc` and `setAttribute('href', ...)` are not React props, so React never inspects them.
+- **Navigation.** `window.open(url)`, `location.href = url`, `location = url`, and `location.assign(url)` or `location.replace(url)` can run a `javascript:` URL with the page's origin.
+- **String-to-code APIs.** `eval`, `new Function`, and `setTimeout`/`setInterval` with a string argument.
+
+### Required patterns
+
+- Render untrusted text as JSX children. Never route text through `dangerouslySetInnerHTML` to get formatting.
+- Use `dangerouslySetInnerHTML` only with the output of `DOMPurify.sanitize(...)`, either inline or through a clearly named `const`. Rich renderers must also run their own safe mode first: KaTeX with `trust: false`, Mermaid with `securityLevel: 'strict'` and `htmlLabels: false`.
+- Give every dynamic URL prop or navigation value one of these safe sources:
+  - a literal, or a same-origin path built from a literal prefix and `encodeURIComponent(...)` segments;
+  - a reviewed URL builder (the lists are `TS_SAME_ORIGIN_URL_BUILDERS` and `TS_HREF_URL_BUILDERS` in `scripts/check_xss_sinks.py`; add a builder there only after reviewing that it cannot return a script URL);
+  - a `sanitize*Url`, `normalize*Url` or `safe*Url` helper;
+  - a guard such as `isSafeOriginHref(url)` or an `http(s)` scheme test, in the same expression or in an enclosing `if` or early return.
+- `iframe`, `script`, `embed`, `object` and worker sources are stricter. A pinned `https://host/` prefix or a same-origin path with encoded segments is fine; an arbitrary host or `//` is not.
+- Keep `react-markdown` raw HTML off. Do not add `rehype-raw`, `allowDangerousHtml: true`, or a `urlTransform` that returns the URL unchanged; keep the default URL transform.
+- `<img src>` and media sources are not script sinks, so the checker does not flag them. Still pass them through the same helpers when the value comes from a user.
+
+### React examples
+
+```tsx
+<p>{message.text}</p>
+<a href={isSafeOriginHref(link) ? link : undefined}>Open</a>
+<Link to={`/workspace/${encodeURIComponent(workspaceId)}`}>Open workspace</Link>
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(renderedSvg) }} />
+```
+
+Unsafe, because nothing proves the value's scheme or origin:
+
+```tsx
+<a href={message.link}>Open</a>
+<div dangerouslySetInnerHTML={{ __html: modelOutput }} />
+window.location.href = searchParams.get('next') ?? '/';
+```
+
+### Suppressions in TypeScript
+
+In `.ts`, `.tsx`, `.jsx` and `.mjs` files the suppression token counts only when a reason follows it on the same line. Put it within four lines above the finding:
+
+```tsx
+{/* xss-check: ignore reviewed: value is restricted to https URLs before it is stored */}
+<a href={agent.homepage}>Homepage</a>
+```
+
+A bare token does not suppress anything; the finding stays and says the reason is missing.
+
 ## PR Review Checklist
 
-For any JavaScript, HTML, or Python change that affects browser rendering:
+For any JavaScript, TypeScript, HTML, or Python change that affects browser rendering:
 
 1. Identify the trust boundary for every value that reaches the browser.
-2. Prefer DOM node creation and `textContent` for untrusted text.
-3. Normalize dynamic URLs before assigning them to clickable or loadable attributes.
+2. Prefer DOM node creation and `textContent` for untrusted text; in React, render it as JSX children.
+3. Normalize dynamic URLs before assigning them to clickable or loadable attributes, React props, or navigation calls.
 4. If HTML rendering is required, document the sanitizer boundary explicitly.
 5. Add or update a regression test when untrusted data reaches a browser-rendering path.
 
 ## Workflow Guardrail
 
-This repository includes a Development PR check in `.github/workflows/xss-sink-check.yml` backed by `scripts/check_xss_sinks.py`.
+This repository includes a PR check in `.github/workflows/xss-sink-check.yml` backed by `scripts/check_xss_sinks.py`. It runs on PRs into `Development` and, until the V2 branch merges into `Development`, on PRs into `paullizer-react-v2-ui`. It checks the added lines of changed `.js`, `.html`, `.py`, `.ts`, `.tsx`, `.jsx` and `.mjs` files under `application/`, and skips vendored browser assets such as `application/v2_ui/public/vendor/`. `.github/workflows/xss-full-scan.yml` runs the same checker over whole files on demand.
 
 If a reviewed exception is unavoidable, add the suppression token below near the specific line and include a justification comment:
 
 ```text
 xss-check: ignore
 ```
 
-Use that escape hatch rarely. It is for reviewed legacy exceptions, not for normal rendering code.
+Use that escape hatch rarely. It is for reviewed legacy exceptions, not for normal rendering code. In TypeScript-family files the justification must follow the token on the same line.

.github/prompts/prepare-for-pull-request.prompt.md

@@ -100,11 +100,12 @@ When Python route files changed:
   `python functional_tests/route_tests/test_route_unauthenticated_policy_contract.py`
   `python functional_tests/route_tests/test_route_policy_test_coverage.py`
 
-When JavaScript, HTML, or Python browser-rendering surfaces changed:
+When JavaScript, TypeScript, HTML, or Python browser-rendering surfaces changed:
 
-- Run `python scripts/check_xss_sinks.py` against changed `application/**/*.js`, `application/**/*.html`, and `application/**/*.py` files.
+- Run `python scripts/check_xss_sinks.py` against changed `application/**/*.js`, `application/**/*.html`, `application/**/*.py`, `application/**/*.ts`, `application/**/*.tsx`, `application/**/*.jsx`, and `application/**/*.mjs` files.
 - If validating only committed changes, prefer changed-line mode:
   `python scripts/check_xss_sinks.py --base-sha <remote>/Development --head-sha HEAD <files>`.
+  For a PR into the temporary V2 branch `paullizer-react-v2-ui`, use `<remote>/paullizer-react-v2-ui` as the base instead.
 - If the working tree has uncommitted changes, use `--full-file` for those files because they are not represented by `HEAD`.
 
 When Python authorization-sensitive surfaces changed: