development-reference.md

# Development reference

Build, test and implementation notes accumulated as the SDK evolved. Dated slices describe what each delivered and how it is checked; use [Getting started](getting-started.md) for the current setup path and the [project overview](../README.md) for current scope.

New here: [Getting started](../docs/getting-started.md) takes you to a new project from a qualified starter or an attachment to an existing backend, and to two tracks, [Build tic-tac-toe with React](build-tic-tac-toe-with-react.md) and [Build the notes application with Lit](build-notes-with-lit.md), whose Lit track runs the demonstration. Every command is checked against the repository. [Public installation](public-install.md) covers Lit and React registry recipes; local qualification and Lit starters use separately built candidate packages. To change a component and trace allowed, denied and unauthenticated requests through an action, read [Change a component and trace allowed and denied requests](actions.md).

React applications: follow [the React consumer dependency guide](../docs/react-consumers.md) for the public A2UI imports, separate Zod majors and required npm/pnpm Markdown pin.

saga a2ui: Simple Agentic Apps — by [Machine Wisdom](https://machine-wisdom.ai).

TypeScript middleware for connecting existing services to assistant experiences, with renderer choice, explicit data-sharing rules, and server authorization hooks.

## Status

The seven SDK packages belong to the public release set, including both renderers and both MCP stacks. See [public installation](public-install.md) for registry availability and exact-version recipes, and [release preparation](release-packages.md) for artifact qualification. Local development uses private candidate artifacts to exercise unpublished source changes; later dated slices preserve their original qualification state.

The workspace has seven owned packages: `packages/core`, `packages/mcp`, `packages/components` (shared FaithfulCard reading, policy and application definitions), `packages/react` (typed surfaces, action integration and optional FaithfulCard rendering), `packages/lit`, and the two stack packages `packages/react-mcp-stack` and `packages/lit-mcp-stack` (see "The MCP stacks and the card application (E1, E2)"). A minimal private Lit application (`apps/lit-host`) builds and renders locally, and a retained Lynx Web qualification fixture (`apps/lynx-fixture`, see ACT3; not an adapter, and the owner retired the Lynx delivery chain on 2026-10-19, so it is history and not a requirement) runs ACT1's action runtime on ReactLynx. The shared action contract (`@saga-a2ui/core/actions`, with the opt-in Lit and React controls) is implemented as local and server actions, and the Lit application's Play runs on it; "The action contract across the current codebase (ACT7)" below says what it supports and what retained owners keep. The repository is public; publication of a package version is a separate owner decision.

SAGA views run in ChatGPT web, Claude web and Alexa+; [host compatibility](host-compatibility.md) describes the interactions in each host. The notes browse and its row actions also run through a React consumer of the same contract, server and actions (see "Browsing the notes workflow through React (REACT1)"; qualified in the local fixture host), and the protected Play through a React control of the same controller and actions (see "Playing through React (REACT2)"; also qualified locally). Both React and Lit support the implemented surface, action and card composition described in [view composition](../blueprints/features/view_composition.blueprint.md). Named-host observations are recorded per application and resource in [host compatibility](host-compatibility.md).

## Packages

| Package | Responsibility and state |
| --- | --- |
| `@saga-a2ui/core` | Renderer-independent value objects and processing interfaces, with protocol-specific implementations in separate modules (public) |
| `@saga-a2ui/mcp` | MCP app integration, data and action boundaries, and protocol error mapping (public) |
| `@saga-a2ui/components` | Optional renderer-neutral FaithfulCard contracts, reader, content policy, consent and application definition (public) |
| `@saga-a2ui/react` | React renderer integration: typed `/a2ui` surfaces, `/actions` bindings and optional `/faithful-card` rendering (public) |
| `@saga-a2ui/react-mcp-stack` | The React renderer joined to MCP delivery; an application installs it plus the React peers (public release set) |
| `@saga-a2ui/lit` | Lit renderer integration (public release set) |
| `@saga-a2ui/lit-mcp-stack` | The Lit renderer joined to MCP delivery (public release set) |
| `@saga-a2ui/lynx` | Lynx renderer integration (retired on 2026-10-19; no package exists and none is planned) |

"Public" means a member of the seven-package release set; registry availability is recorded in [public installation](public-install.md). Developers retain their normal renderer tools and write the code that calls their APIs. A2A is a later integration; no placeholder package is published.

## Content safety

**Standard** permits validated HTTPS links through the host and images from explicitly allowed HTTPS hosts. **Strict** keeps every link inert, shows blocked fragments as accessible placeholders the reader can reveal as text, and loads a permitted image only after the reader chooses Show images. Both preserve ordinary Markdown formatting and retain server authorization and data-sharing checks. Application code controls the policy.

The optional FaithfulCard component displays supplied Markdown without rewriting or silent truncation. The packages belong to the public release set; the dated "The passive FaithfulCard and an installed second consumer" section records its original preparation evidence. Ansari-specific branding and presentation rules remain in Ansari.

## Development

This is an npm workspace; the root contains development tooling and is never published. Build and test commands for the local Lit application are under Local development below. See [contributing](../CONTRIBUTING.md) and [package layout](../packages/README.md).

## License

The SDK uses [Apache-2.0](../LICENSE). Preserve applicable third-party licenses and notices when adding dependencies or extracted code.

## Local development

Requires Node 22.23.3 or newer (pinned in `.nvmrc`; `nvm use`) and npm. No global tools are needed.

    npm ci                              # install from the committed lockfile
    npm ci --prefix apps/lynx-fixture   # the Lynx fixture's own lockfile (see ACT3); verify and CI need it
    npm start                           # Vite dev server at http://127.0.0.1:5173
    npm run build                       # build the Lit app into apps/lit-host/dist
    npm run typecheck                   # tsc --noEmit
    npm run test:headless               # protocol decoding/processing in plain Node (no DOM, no browser)
    npx playwright install chromium    # explicit browser install; verify does not download one
    npm run test:browser                # serves the built page and checks the visible title
    npm run verify                      # guards, typecheck, build, tests, LFS, and version enrollment

`test:browser` expects `npm run build` to have run first; it loads the built page in Chromium and asserts that the heading "SAGA A2UI" is visible. The full CI route installs Chromium, then runs `npm run verify`. Verify includes typecheck, build, the headless tests and the browser check, so CI does not run that suite a second time.

### Formatting and hooks

Formatting hooks are enabled for SDK development. Install and verify them before
committing in each development checkout or worktree, including Hermes Helmet
worker checkouts. Preserve existing Git safety guards.

Use the Node version in `.nvmrc` (22.23.3) or a compatible later release. The
following commands install the pinned root tools and enable the hooks:

```sh
npm ci --workspaces=false --ignore-scripts
npm run hooks:install
npm run hooks:check
```

Verification prints `SAGA formatter hook verified` with the effective hook path.
Setup is idempotent, changes no Git configuration and installs no consumer
lifecycle script. Normal SDK consumers do not install hooks. Full SDK development
still needs the workspace dependencies described above.

The installer uses Git's effective hooks directory, including `core.hooksPath`.
It preserves an existing executable pre-commit as `pre-commit.saga-original`,
runs it first and respects its failure, then runs pinned lint-staged/Prettier
from the committing worktree. The pre-push hook and its default-branch/force-push
guards are untouched. Git normally shares hooks between linked worktrees;
worktrees predating this tooling continue to run the original guard. Install
root dependencies in each worktree that has the formatter. No global hook
setting is changed. A symlink or non-executable existing hook requires its owner
to resolve it before setup; an existing backup plus an unknown hook requires
inspection rather than replacement. If another installer replaces the wrapper,
`hooks:check` reports that drift. Preserve the backup when repairing it.

Prettier 3.9.10 and lint-staged 16.2.7 are pinned development tools; the latter
supports Node 20.17+ and therefore the repository's earlier Node 22.12 baseline. Its newer
17.6.0 release requires Node 22.22.1+. One small wrapper composes the existing
hook; a second hook manager would add another owner for the same file.

Only staged JS/TS (including JSX/TSX and MJS/CJS), JSON, CSS and YAML are selected.
`.prettierignore` excludes generated output, lockfiles, retained evidence,
vendored material and Markdown/HTML source-quotation documents. lint-staged owns
index updates and restores unstaged portions; do not use `--no-stash` or
`--no-hide-partially-staged`. The source/configuration baseline is normalized
with this same formatter so future edits avoid unrelated formatting hunks.
The hook formats whole selected files, including lines outside the staged hunk.
Formatting a touched source file can change quoted guide snippets: reconcile
those quotes and run `npm run test:docs` before review.

For selected files, run `npm run format -- PATH...`. For a branch, run
`npm run format:check -- BASE HEAD --merge-base`; the check never writes files.
The CI backstop uses that same selection and pinned configuration on changed
files. Documentation-only changes select no formatter inputs and retain the
existing cheap document checks. `npm run test:tooling` exercises real isolated
commits, partial staging, preserved hooks and linked worktrees without building
an application or opening a browser.

If a hook cannot find Node, make the supported runtime available on the Git
process's PATH (including IDE/agent launches). If dependencies are absent, run
the root installation command above. Resolve formatting failures with the pinned
local formatter and retry the commit; inspect the index and worktree after any
lint-staged restoration conflict. There is no automatic network download in the
hook.

### Source and output authority

[`scripts/owned-filesystem.ts`](../scripts/owned-filesystem.ts) is the one owner of which files maintained
tooling reads as source and which directories it empties or writes as output (SECURITY.md invariant 5).
Repair a defect there, not at a call site.

- **Reads.** Template export, snippet extraction and the generated release documentation read a file only
  through `readContainedFile`: every step below the root is a real directory and the leaf a regular
  file, a link or special file is refused, and the file is opened without following a link. A template
  that holds a link, and a release specification whose version, guide slug or component id is not one
  safe path segment, fail before anything is written. `build.directory` of a publication release input
  must resolve inside the input's own directory, like every other path in it.
- **Source identity.** `release:pack` and `candidate:pack` copy only the files Git tracks below each package
  (plus the repository license and notices, each of which must itself be one regular tracked file) from the working tree, so an untracked or ignored file cannot
  enter a tarball whatever a package's `files` list selects; Git LFS content is the working tree's, as a
  clean checkout smudges it. `release.json` records, per package, `sourceSha256` (the staged tracked
  content, the license and notices included) and `excludedUntracked` (files Git does not track, ignored ones included, left out). The `dirty` flag still means tracked files
  differ from the commit; a dirty build remains preparation only.
- **Output.** `release:pack`, `candidate:pack`, the `tarballs` command of `scripts/release-candidate.ts` and `candidate:rehearse`
  create their output directory or authenticate it (a real directory, never a link, owned by the running
  user), keep its identity, and check it before every removal or write. `packages` below it must be a real
  directory; `candidate:pack` empties it and refuses the repository root as the output. Fixed files such
  as `candidate.json` and every packed tarball replace their leaf through a temporary file and are never written
  through a link: `npm pack` writes into a private scratch directory, never into the output.
- **Formatter.** `npm run format` and the pre-commit hook refuse a selected path that is a link, a special
  file or outside the checkout, and replace a file through a temporary file after checking that it is the
  file that was read.
- **Scope.** Each check runs in the call immediately before the operation it guards. Ancestors of a path
  the operator named are the operator's own. An attacker who can already rewrite the checkout's tracked
  files or run code as the same user is outside this boundary.

If a command reports a link at an output path, remove or move that link; the tool will not follow it.

### Advisory correctness lint

`npm run lint` checks tracked JS/TS and workflow files. Pass explicit paths to
limit it (`npm run lint -- scripts/saga.ts`), or use
`npm run lint -- --base BASE HEAD --merge-base` for a PR. A dependency or analyzer
configuration change rechecks all tracked inputs. Deleted files are ignored;
Markdown/artwork-only changes start no analyzer. The separate Advisory lint
workflow is path-filtered and installs only root tooling and actionlint. It runs
no SDK build, browser, fixture service or release rehearsal.

The development baseline is Node 22.23.3, the current Node 22 patch checked on
2026-10-21. ESLint 10.13.0 needs Node 22.13+ (or supported newer majors); ESLint
9.39.5 is marked unsupported, so the root tools use maintained ESLint 10 and
pinned typescript-eslint 8.72.0 with the existing TypeScript 5.9.3 compiler. The root TypeScript pin also controls root scripts and example typechecks; keeping
5.9.3 preserves those existing checks. SDK package consumer engine requirements
are unchanged. To install the workflow analyzer locally with Go:

```sh
go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
```

Put Go's binary directory on PATH, or set `ACTIONLINT` to that executable.
`npm run lint:workflows -- .github/workflows/ci.yml` runs only that analyzer.
Shellcheck and pyflakes integrations are explicitly disabled to keep the selected
workflow rules reproducible without additional tools. actionlint itself still
checks workflow keys, expressions, job references, matrices and action syntax.
A missing analyzer is reported as an execution failure, never as a clean scan.

The seven ESLint rules are warnings, without a warning-count threshold:

| Rule | Useful correctness signal |
| --- | --- |
| `no-async-promise-executor` | Rejections from an async Promise executor can escape the created promise |
| `no-unsafe-finally` | A return/throw in finally can replace an earlier result or error |
| `no-unreachable` | Statements after an unconditional transfer never execute |
| `no-sparse-arrays` | Array holes are skipped by common iteration methods |
| `use-isnan` | Comparing directly with NaN never tests for NaN |
| `valid-typeof` | Misspelled typeof strings make conditions ineffective |
| `@typescript-eslint/no-non-null-asserted-optional-chain` | A non-null assertion hides the undefined case introduced by optional chaining |

No recommended preset, type-aware project build, formatting, naming, complexity
or unused-variable policy is added. Existing unrelated suppression directives
are left alone; unused-disable reporting is off. Warnings are evidence to assess,
not instructions for an automatic repair loop. Do not clean up unrelated code to
make the advisory report quiet.

The workflow uses job-level and analyzer-step `continue-on-error`, retains
ordinary file/rule/line/column diagnostics and summarizes analyzer outcomes even
when installation or execution fails. Local exit 0 means warning-only/clean
analysis, actionlint findings return 1, and execution failures return 2. Syntax
errors can also produce analyzer diagnostics. No hook invokes lint, and no
required check, review setting or branch protection is added or changed.
Existing TypeScript, behavior, source-quote, version, artifact and Git safety
checks retain their current authority. A supported defect found independently
still belongs in ordinary review.

ESLint, typescript-eslint and actionlint are maintained open-source tools with
no per-seat/service fee; the licenses are MIT, MIT and MIT respectively. Adoption
adds pinned root dependencies, one workflow and analyzer-version maintenance;
it sends no code to a new hosted analyzer. A hosted alternative would add
account/access and plan maintenance without simplifying this small rule set,
so none is selected or purchased. GitHub standard hosted runners are free for
public repositories; private repositories use their plan's included minutes and
can incur overage charges.
See [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions).
The implementation PR records observed local/CI runtime.

References: [ESLint severities](https://eslint.org/docs/latest/use/configure/rules),
[typescript-eslint setup](https://typescript-eslint.io/getting-started/), and
[actionlint usage and exit codes](https://github.com/rhysd/actionlint/blob/v1.7.12/docs/usage.md).

### CI checks and release qualification

CI (`.github/workflows/ci.yml`) runs on pull requests, pushes to main and manual
runs. **Documentation, artifacts, policy tests and CI routing** always checks Git
LFS pointers, version enrollment, Python version-policy integration and CI path
routing. It also runs `npm run test:docs`: existing checks for guide
commands, source snippets, generated recipes, local links/headings, tour
references, third-party notices and the consumer boundary scan
(`scripts/consumer-boundary.test.ts`, which reads documentation code fences
and consumer source, so a prohibited fence in a documentation-only change
fails here without the application job). It installs root tools only, using
`npm ci --workspaces=false --ignore-scripts`; no SDK/application workspace,
Lynx fixture, browser or pnpm dependency is installed. The full application's
headless suite also includes these document tests.
The separate **Version policy** PR check still validates the intended versions
against the current base.

| Changes | Application types, builds, tests and release qualification |
| --- | --- |
| Root Markdown; Markdown in `docs/`, `blueprints/` or `diagrams/`; README/CHANGELOG files elsewhere; PNG/JPEG/GIF/WebP/AVIF/SVG/ICO under `assets/brand/`, `docs/` or `diagrams/` | Skipped; focused document and artifact checks run |
| Only those documents and the exact version-policy paths listed in `scripts/ci-scope.py` | Skipped; focused policy checks run |
| All other paths, including source/fixture Markdown, runtime images, executable files in `docs/`, retained evidence/deliverables, dependencies and CI routing/workflow changes | Full qualification |
| Manual CI run, unavailable Git history or an empty/unknown change set | Full qualification |

Markdown/image extensions are case-insensitive. Renames check both paths;
moving a runtime image into documentation still runs full qualification. A PR
uses its merge-base diff; a main push checks its complete before/after diff.
This CI decision is deliberately more conservative than the version-bump
documentation exemption. It does not exempt an entire documentation directory.
Run its real-Git routing cases locally with `python3 scripts/test-ci-scope.py`.
Guide or notice changes remain on the fast path and must pass the focused
document checks; a broken generated recipe or source quote cannot pass merely
because no application build ran.

Every `uses` reference in `.github/workflows` and `.github/actions` is pinned to
a full 40-character commit SHA (or, for a Docker image, a `@sha256` digest); a
trailing comment names the release it came from. The only exemption is a
repository-owned local path that starts with `./`, uses forward slashes only
(a backslash is a path separator on Windows runners, so any reference containing
one is rejected) and has no `..` segment. Tag
and branch references, including major tags such as `@v4`, can move after
review. The always-on CI job runs `npm run check:action-pins`
(`scripts/check-action-pins.mjs`) to reject them, and
`npm run test:action-pins` covers the rules and this repository. The checker
does not read YAML itself: the maintained `yaml` package (YAML 1.2, a pinned
root dev dependency) parses each tracked file, and the checker walks the node
tree, so scalar styles, flow and JSON collections, explicit and block-scalar
keys, anchors, tags, comments, `run: |` text, multiple documents and duplicate
keys are the parser's concern. It enforces `uses` only where it executes: a
direct child of a step, of a job under `jobs` (a reusable workflow) or of a
composite action's `runs`, or of a document's root mapping. A key named `uses`
anywhere else, such as a `with:` input or an `env:` variable, is data and is
never reported, so it needs no quoting or renaming. It fails closed where it
cannot see the executable structure: a `uses` value that is an alias, block
scalar, collection, non-string or empty; an alias or a YAML merge key (`<<`,
including the explicitly tagged `!!merge <<` forms) in place of a step, job,
`steps`, `jobs` or `runs` node or key; any other mapping key of those nodes that
is not a string scalar; and any text the parser reports as an error or a
warning.

The check reads the files as YAML 1.2 and rejects any unusual construct it
cannot classify.

To update an action, resolve the reviewed release tag to its commit
(`gh api repos/OWNER/REPO/commits/TAG --jq .sha`), change the SHA and comment
together, and run both commands.

The full check retains the entire existing route: packed React pnpm consumer,
`npm run verify`, `candidate:pack`, `candidate:rehearse`, and the SHA-named
candidate artifact retained for 14 days. Named steps identify each operation.
The rehearsal rebuilds A and B from the same implementation at different
versions and runs the install, update and rollback procedure across them.

Before any separately authorized release, run **CI → Run workflow** on the
exact release ref (or `gh workflow run ci.yml --ref YOUR_RELEASE_REF`) and require
the full check to pass for that revision. Manual runs always bypass path
exemptions; the artifact upload follows successful packing and rehearsal in
the same job. PR and main code changes also run it automatically. Release
qualification requires the full check, not the docs-only route. This workflow
publishes and deploys nothing and holds no registry credential.

### Repository verification

`npm run verify` is the complete local and full-CI application route. It runs the static guard, headless and browser discovery checks, typecheck, build, headless tests, browser tests, Git LFS pointer check, and version-enrollment check, in that order. It stops at the first failing command and uses that command's exit code. Git LFS must already be installed; the pointer check calls `git lfs`.

Browser installation is an explicit prerequisite. Install the Playwright browser this repository already depends on before verify. Verify does not download a browser and does not substitute a different one:

    npx playwright install chromium

CI runs `npx playwright install --with-deps chromium` before `npm run verify`.

Each invocation writes a disposable receipt to `.wise-agents/verify-receipts/` (ignored) and copies it to `latest.json` in that directory. The receipt records the working directory, the verify process arguments, the Node and npm versions that actually ran, the git commit and tracked dirty state at each command boundary, and each command's name, arguments, timestamps, and exit code. It does not record environment variables or command output, so do not put secrets in command arguments. A run is labeled `pristine-head` only when the commit and tracked dirty state are clean at the start and unchanged through every command that ran. A dirty tracked file or a commit created during verification is recorded as `not-pristine-head`. That label is informational; the run's result is its exit code. State is sampled at command boundaries. `--exec` replaces the repository suite and marks the receipt `exec`; `npm run verify` does not pass it.

The static guard reports `||` whose left operand, after removing parentheses and zero-argument `.trim()` calls, is a string or untagged template that contains fixed non-whitespace text. It reports the file and line and exits nonzero. Identifiers, interpolation-only templates, whitespace-only fixed text, `||` nested inside an interpolation, concatenation, `&&`, `??`, non-zero-argument `.trim()` and other methods are outside the rule. It parses authored `.ts`, `.tsx`, `.mts`, and `.cts` files with the TypeScript compiler and skips `.d.ts`, dependencies, and generated output (`node_modules`, `dist`, `coverage`, `test-results`, `playwright-report`).

Test discovery asks Vitest for its file list (`vitest list --filesOnly` against `vitest.config.ts`) and compares that with authored `*.test.ts` files. Playwright `*.spec.ts` files are compared separately with `playwright test --list`. An authored file omitted by its runner fails the check. The file walk includes fixture and `e2e` tests.

The workspace root and `apps/lit-host` are development tooling, not npm packages. The local host declares no application version. All seven SDK packages have enrolled release versions and public npm releases; [package layout](../packages/README.md), [public installation](public-install.md) and [version policy](version-policy.md) describe their ownership, available versions and update rules.

### Fixture rendering (A2UI v0.9)

`apps/lit-host` renders a developer-authored A2UI v0.9 surface from synthetic public data. Tested, exactly pinned versions: `@a2ui/lit` 0.13.0, `@a2ui/web_core` 0.13.0 (both Apache-2.0), `zod` 3.25.76 (required by both; each installs its own nested copy, see "MCP Apps 2 recipe" below), `lit` 3.3.3, Node 22.12.0+. The optional peer `@a2ui/markdown-it` is deliberately not installed.

Modules in `apps/lit-host/src` (application-local; MCP delivery moved to `@saga-a2ui/mcp` later, see "Reusable MCP connector (CORE1)"):

- `@saga-a2ui/core` (`packages/core`) owns the A2UI v0.9 message cases, `MessageDecoder` and `createMessageSession` that used to live here, plus the Zod 3 alias catalogs author schemas with. See "Core and Lit packages (VIEW1)".
- `saga-panel/contract.ts`, `saga-panel/fixture.ts`: renderer-neutral `SagaPanel` contract and synthetic fixture data.
- `lit/integration.ts`: Lit panel element, catalog, and the explicit `registerLitElements()` setup (nothing registers at import time).
- `lit/saga-app.ts`: the application's `saga-app` element, built on `createA2uiAppElement` from `@saga-a2ui/lit`. The package owns the session, subscriptions, rejection fallback (failures as inert text) and disposal; the application adds the heading, its content policy and the `window.sagaSend` hook.
- `main.ts`: composition root; constructs and connects the above.

Call path: `window.sagaSend(unknown)` -> `saga-app` -> `session.ingest` -> decoder -> visitor -> upstream processor -> surface model -> Lit.

Invalid messages, unknown catalogs/components or wrongly typed properties produce a visible "Could not render this content" alert and clear the surface (see "Core and Lit packages (VIEW1)"). Values render only as Lit text bindings, so supplied markup stays inert text. The description is the one value read as Markdown, under a trusted content policy; see "Standard descriptions (POL1)" below.

`npm run test:headless` (vitest, Node) covers decoding and processing through the public `@saga-a2ui/core` interface only (`packages/core/src/protocols/a2ui/v0_9/protocol.test.ts`). Browser tests cover rendering, binding, inert markup, recovery and mount/unmount.

`e2e/*.spec.ts` drive the real processor through the typed `window.sagaSend` entry point and assert rendered output. Recipe (same commands as above): `npm ci && npm run typecheck && npm run build && npx playwright install chromium && npm run test:browser`.

### MCP tool result in the view (MCP1)

`apps/lit-host` also hosts an ordinary MCP server and renders one of its tool results through the same A2UI session. It serves public synthetic data.

Pinned additions (exact; the MCP packages are the MCPV2 recipe below): `@modelcontextprotocol/ext-apps` 2.0.3 (MIT; its optional `react` peers are not installed) with `client`, `core` and `server` 2.4.0 and `node` 2.1.1 (Apache-2.0), dev-only `vite-plugin-singlefile` 2.3.3, `tsx` 4.23.15, `@types/node` 22.20.5. No MCP-UI, CopilotKit, AG-UI or Ora packages are used; the only overlap is shared standards (MCP, MCP Apps, A2UI).

    npm run build         # app, the single-file view (dist/view/view.html) and the test-only host fixture
    npm run serve:mcp     # MCP server at http://127.0.0.1:3001/mcp (PORT overrides); needs the build first

Modules in `apps/lit-host/src`:

- `mcp/episode.ts`: public contract shared with the view (input shape, bounded `PublicEpisode`); imports only `zod`.
- `mcp/server.ts`: `createEpisodeServer` declares one explicitly public, read-only operation `get_episode` (runtime-validated `episodeId`) and the episode view resource (its `ui://views/view.<policy digest>.v1.html` URI names the content policy and the contract major of the view, see Identity below) through `registerPublicOperation` from `@saga-a2ui/mcp/server`. Only `episodeId`, `title` and `description` are projected from a record. The resource is the built HTML served verbatim, so request data never enters cached HTML; its CSP metadata allows no network or external resources.
- `mcp/listener.ts`: application-owned loopback Streamable HTTP hosting (`POST /mcp`, stateless, JSON responses, Host-header DNS-rebinding protection, no auth because the tool is public).
- `mcp/view.ts`, `view-main.ts`, `view.html`: the view connects the MCP Apps `App` bridge, then turns each tool result into an A2UI data-model update and hands it to the existing session. Decoding stays in `protocols/a2ui`; rendering stays in `lit/`. `vite.view.config.ts` builds it to one HTML file with no server imports.
- `e2e/host-fixture`, `e2e/mcp-view.spec.ts`: a test-only local host with a real `AppBridge` and a `sandbox="allow-scripts"` iframe. The spec makes real `tools/call` and `resources/read` requests over HTTP, delivers the result, and checks the wire result, rendered title, CSP and resource linkage. `e2e/view-bundle.spec.ts` checks the built artifacts for server code and credentials.

### The MCP stacks and the card application (E1, E2)

`@saga-a2ui/react-mcp-stack` and `@saga-a2ui/lit-mcp-stack` (both public and enrolled in `.version-policy.json`) each connect one renderer to the MCP Apps bridge. An application installs one stack and the renderer's framework peers and imports from the stack only. The two have the same shape and the same lifecycle code, copied between them (`running-view`, `container-claim`, `host-connection`, `start-failure`, `faithful-card/document-policy`); a change to one is made in both, and each package's own tests (`stack.test-support.ts` runs a real `AppBridge` over an in-memory transport) check it.

| Entry | Holds |
| --- | --- |
| `.` | `startA2uiView({ container, layout, catalog, actions, readyWhen, sizing, hostContext, onToolResult, onTeardown, onError })`, with the names an own-catalog application writes its view against: the layout (`defineSurface`, `z3`, A2UI's Zod 3), the catalog (`Catalog`, `CommonSchemas`, and for Lit `A2uiLitElement`, `basicCatalog`, `LitComponentApi`; for React `createComponentImplementation`, `ReactCatalogComponent`, `ColumnApi`, `ListApi`, `RowApi`), the actions (`Action`, `ActionBinding`, `ActionButton`, `ActionButtonActivation`, `createLitActions` or `createReactActions`, and for Lit the `HostLinks` type of `ViewHost`), the failures (`StartError` with `StartMisuse`, `StartFailure`, and `ErrorPhase`, the phase an `onError` callback is told), `readingProfile` and the delivery callback types. It imports neither `@saga-a2ui/components` nor Markdown: the emitted bundle of an own-catalog application holds neither. Each stack's `exports.test.ts` bundles the entry's module graph from workspace source to show it, and `scripts/pack1.test.ts` builds the own-catalog and card pages from the packed copies and shows that only the card page carries the parser. |
| `./faithful-card` | `FaithfulCardApp` (the definition builder of `@saga-a2ui/components/faithful-card`), `startFaithfulCardApp(definition, { container, readyWhen, sizing, hostContext, chrome, onError })` (the Lit stack also takes `styles`, the application's constructable stylesheets for its card), the types `CardResultOutcome`, `CardResultReader` and `DeliveredResult`, the card's host link (`useHostLink` in the React stack, `bindHostLink` in the Lit stack), `readingProfile`, and for the Lit stack `contentPolicyFromDocument` and `documentContentSecurityPolicies`. |
| `./content-policy` | `createContentPolicy` and `embedContentPolicy` (and their types): how a server states and embeds the policy that the card application reads back from its document. No renderer and no delivery code. |
| `./server` | `createServerBudgets`, `registerPublicOperation`, `registerProtectedOperation`, `operationViewFromHtml`, `viewUriForMajor`, `viewUriForHtml`, `attachRequestLifetime` and the types `OperationView` and `RequestLifetime`, re-exported from `@saga-a2ui/mcp/server`, which keeps their specification. Node only: no browser entry imports it, and `exports.test.ts` checks that the browser graphs hold no server module and the server graph holds no renderer or components module. |
| `.` (and `./faithful-card`) | `readingProfile(context, hostName)`: the one place that recognises hosts read on a device, from `@saga-a2ui/mcp/view`. |

Both starts return a running view synchronously (`{ ready, dispose }`; the A2UI view also exposes `surface`). The layout is validated before the connection is made, results that arrive during the readiness work are held and the latest is shown once it settles, and the stack owns the view's size reports. A second start on a container with a running view throws `container-busy` and leaves the first alone; after `dispose()` settles the container starts again. The card application is a pure value, `FaithfulCardApp.define({ name, version }).reader(...).policy('document').result(parse).texts(...).build()`; the parse is the application's only decision about a result, and `undefined` is an unsupported result. `apps/lit-host/e2e/card-app-stack.spec.ts` runs both stacks in Chromium against the local host fixture. It also starts a branded card on each stack (the application's stylesheet and its own attribution classifier, `e2e/card-styling/branded.ts`; page CSS for React, the start's `styles` for Lit): semantic structure, the computed rules, the closing marker, font readiness and image-consent reset, the same cases on both stacks. Ending a view in any state removes what it showed, and frees its container, before its connection closes; only a start that failed keeps its failure on screen until it is disposed. `apps/lit-host/e2e/view-stack.spec.ts` runs `startA2uiView` of both stacks the same way: disposal and `pagehide` during the readiness work, throwing `onTeardown` and `onError` callbacks in a starting and in a ready view (one teardown, the `pagehide` listener removed, a later `pagehide` inert, the container started again), and a readiness failure beside a handshake failure. It builds with the other pages but is not part of the installed-package set.

#### The view conversation and operations without a view

`@saga-a2ui/core/conversation` holds the delivery-neutral contract (`Conversation`, `AppendResult`, `RequestOutcome`, `NO_CONVERSATION`; types plus one frozen value, no import), beside `@saga-a2ui/core/host-links`. `conversationFromApp(app, signal)` in `@saga-a2ui/mcp/view` is the MCP Apps implementation, and both stacks give `ViewHost.conversation`, built from the same `App` and lifetime signal as `server` and (Lit) `links`. The stacks re-export the three types. The behaviour is specified in the [view conversation Blueprint](../blueprints/features/view_conversation.blueprint.md); the points a maintainer needs:

- Capabilities (`updateModelContext`, `message`) are read at call time. With `context`, `ui/update-model-context` is sent first (`text` as one text content block, `data` as `structuredContent`), then `ui/message` with role `user` and one text content block, never in parallel. A context that is unsupported, rejected or answered with `isError` stops the message at `stage: 'context'` unless `bestEffort` is set; then the message is still attempted and an accepted one reports `{outcome: 'appended', context: <why>}`.
- Payloads are admitted before anything is sent, against `CONVERSATION_LIMITS` in `packages/mcp/src/view/conversation.ts` (16 KiB of UTF-8 for the message, 16 KiB for the context text, 64 KiB of exact `JSON.stringify` size for the structured data). `snapshotData` copies the data while it measures it, with escapes, braces, colons and commas counted, and the request carries that copy, so the original object is never read again; the context object is read once. The data must be plain objects, arrays, strings, finite numbers, booleans and `null`, at most 32 levels deep without cycles: `undefined`, `bigint`, symbols, functions, non-finite numbers, array holes, accessor properties and non-plain objects (`Map`, `Date`, class instances) are refused, not converted. An over-budget message resolves `denied` at the message stage with nothing sent, context included; an over-budget context resolves `denied` at the context stage and follows the `bestEffort` rules. Nothing is truncated or rewritten, and the walk stops once it passes the budget (an array longer than the budget is refused unread). The limits are the SDK's own.
- Once the lifetime signal has aborted, including while a request is outstanding, the call resolves `unavailable`, sends nothing further and ignores the late answer. Nothing is retried.
- The pinned bridge (`@modelcontextprotocol/ext-apps` 2.0.3) gives `ui/update-model-context` an empty result and rejects any other key, so a host cannot answer a context update with `isError`: its refusal can only be a rejected request, which reads `failed`. `denied` at the context stage is kept for a bridge that allows it. `ui/message` can answer `isError`, which reads `denied`.

Tests: `packages/core/src/conversation.test.ts` (the default instance), `packages/mcp/src/view/conversation.test.ts` (a real `App` and `AppBridge`: message only, the order, a held context, withheld, failed and best-effort contexts, refused, failing and unavailable messages, payloads at and over each budget, exact JSON sizing with escapes, non-JSON values, accessors and large objects, an ended view before and during each request), the `ViewHost.conversation` case in each stack's `start-a2ui-view.test.ts`, and `apps/lit-host/e2e/view-conversation.spec.ts`, which runs the same scenarios through both stacks in Chromium against the local host fixture (probes in `e2e/view-conversation/`, built by `vite.view-conversation.config.ts`; like the view-stack probes, not part of the installed-package set). The fixture (`host-fixture/host.ts`) takes `conversation: {context, message}` in `mountView`, each `accept`, `refuse`, `fail`, `withhold` (the capability is not advertised) or `hold` (recorded, unanswered until `releaseConversation`), and records every request in order (`conversationRequests`).

**Operations without a view.** `view` is optional on `PublicOperation` and `ProtectedOperation`. `register` in `packages/mcp/src/server/operation.ts` is the only view-specific step: with a view it registers the app tool and resource and links every result to the view; without one it calls `McpServer.registerTool` with the same title, description, contracts and annotations and the same callback, registers no resource and adds no `_meta` anywhere. `execute()` is untouched, so input validation, budgets, cancellation, safe failures and (for a protected operation) the identity requirement are the same. A view that is declared must still be complete; an omitted or `undefined` one is a viewless operation. `packages/mcp/src/server/operation-viewless.test.ts` registers each declaration with and without `view` over Streamable HTTP and compares invalid input, refusal, an absent record, an over-budget handler, a throwing handler, cancellation, an asynchronous and a malformed projection and invalid output, then checks the viewless tool definition and every result carry no `_meta.ui` and the server lists no resource, and that a protected declaration still refuses a missing identity. Both stacks' `/server` entries re-export `registerProtectedOperation` beside `registerPublicOperation`, so a stack consumer reaches the viewless registration without naming an MCP Apps server API; `scripts/fixtures/mcp-server-consumer.ts` (a packed, server-only application) declares both access modes without a view, and the two stack consumer fixtures use `host.conversation`.

#### Reading the whole result

The definition owns the interpretation of a result. `@saga-a2ui/core/delivered-result` holds the delivery-neutral value, `DeliveredResult`: a boolean `isError`, `content` (every block in delivered order, each with its `type`, a text block with its `text`, any other block opaque and as supplied) and an optional, unchecked `structuredContent`. An absent `structuredContent`, a present `null` and malformed data stay distinct, so `'structuredContent' in result` tells absence from `null`. `deliveredResultFromToolResult` in `@saga-a2ui/mcp/view` maps an MCP tool result onto it and decides nothing: an error result is not rejected, and no structured content is read. It first counts the result against the view-result admission budget (4 MiB of serialized JSON text, 200000 values, 64 levels, 10000 items per array and 1000 content blocks by default; the byte count is an upper bound on the UTF-8 length of the result's JSON, so a character JSON escapes, such as a quote or a control character, counts at its escaped length; `runToolResultView` applies the same budget before it holds or delivers a result or a tool input, and the limits it reports in a refusal are a frozen copy), and a result over it throws a `ToolResultRefused`, which a stack shows as the definition's problem text without calling the reader. The browser has already received a host message when the view's listener runs; the budget bounds what the SDK keeps, walks, copies and forwards. Both stacks pass that value, unchanged, to the definition's one `result` reader, which returns `{kind: 'content', content}` or `{kind: 'rejected', text?}`:

```ts
import {FaithfulCardApp, type CardResultOutcome, type DeliveredResult} from '@saga-a2ui/react-mcp-stack/faithful-card';

// The application's own protocol: a result it cannot use is rejected with its own words.
const read = (result: DeliveredResult): CardResultOutcome =>
  usable(result)
    ? {kind: 'content', content: {markdown: textOf(result), heading: headingOf(result)}}
    : {kind: 'rejected', text: 'This answer needs a newer version of the app.'};
const definition = FaithfulCardApp.define(identity).reader(readerOptions).policy('document').result(read).texts(texts).build();
```

There is no default reading and no second option on the start: an application whose protocol is only `structuredContent` writes that reader (the answer and React card examples do, each rejecting an error result). The reader receives the result whatever the delivery calls an error, and what an error result means, and what it says, is the application's decision; an application whose protocol words an error with the error's own text returns `{kind: 'rejected', text}` for it, so that text, not an answer card, is shown as the problem. A rejection shows `text` when the application supplies it and the definition's `texts.problem` otherwise; either way the shown answer clears, image consent and the link outcome of the previous presentation end, and the next accepted result recovers. `CardSurface.present` rejecting the content itself leaves the previous card in place, so the stack clears explicitly. A reader that throws, or a tool result whose content cannot be mapped, is reported to `onError` with phase `result` and rejects the result without wording, with the same clearing; the stack does not undo anything the callback already changed. A return that is not an outcome is rejected the same way, because it is unchecked application input.

Three owners each decide once. Core owns the neutral value and imports no delivery, renderer or DOM. The MCP view maps without interpreting. `readCardResult` in `@saga-a2ui/components/faithful-card` is delivery-neutral and shared by both stacks: it runs the delivery's mapping and the definition's reader under one guard, checks the reader's return and reports a throw, and never looks inside a result. Each stack keeps only the rendering of the outcome. The SDK names no application protocol, version or wording: the matrix in `card-app.test.ts` and in each stack's `start-faithful-card-app.test.ts` uses a synthetic envelope and synthetic wording, kept in the application reader of the fixture. It covers a valid envelope, an absent or `null` `structuredContent` falling back to text with its whitespace and terminal newline intact, a reader that considers only the first `text` block and then checks that string (an empty first block is not skipped in favour of a later one; that rule is the fixture's, the SDK imposes none), present-but-malformed structured content rejected even beside usable text (wrong or missing version, a missing, non-string or empty answer, a missing or non-string question, a non-object), an error result rejected carrying its own text (or the unsupported wording when it has none) even beside a valid envelope, an equal answer presented again, and recovery after an error, after a rejection and after a throwing reader. The browser check runs the same through both stacks, and adds a reader that throws after image consent. A tool result whose content cannot be mapped does not reach the view through the bridge, whose own schema rejects it first; the mapper's unit tests cover it.

#### The reading profile and the application's tokens

`readingProfile(context, hostName)` answers `'device'` or `'desktop'` and is exported by both stacks. It recognises the hosts the recorded observations read on a device (Alexa+), the historical `HTMLFragmentWrapper` host name, a host context whose `deviceClass` is an Echo Show class (`echo_show`, `echo_show_8`, `echo_show_15`, matched as a whole underscore-separated word), and a declared `mobile` platform. The `deviceClass` field is an extension beyond the MCP Apps host context schema; the context accepts it and passes it on. The profile decides nothing about presentation: the application calls it from its `hostContext` callback and maps the answer onto its own tokens and its own `data-reading-profile` attribute, with no host-name test of its own. `card-app-stack.spec.ts` shows an `echo_show_15` context setting a 1.6 scale on the application's font-size token with no transform and no sideways overflow.

### The tic-tac-toe example

The [external tic-tac-toe application](https://github.com/MachineWisdomAI/saga-a2ui-examples/tree/b4eaeb909a460f94e44c411f8e3ad4091014e5c4/apps/tic-tac-toe/game) is a game between a person and an assistant, built on the React stack and its local MCP listener. It shows a view adding a message to the conversation (`host.conversation.appendMessage`) and operations without a view, together: `new_game` and `show_game` open the board, and `get_game` and `play_move` return the game as data. The person's click and the assistant's tool call reach the same `play_move`, so one server-side rule set (`server/rules.ts`) and one atomic check-and-apply (`server/game-store.ts`) govern both. Its [README](https://github.com/MachineWisdomAI/saga-a2ui-examples/blob/b4eaeb909a460f94e44c411f8e3ad4091014e5c4/apps/tic-tac-toe/game/README.md) lists the files; the guide [Build tic-tac-toe with React](build-tic-tac-toe-with-react.md) walks through it.

`scripts/tic-tac-toe-source.json` records the examples repository's immutable commit and decompressed archive SHA-256. `npm run stage:tutorial` verifies the archive before extracting the game into ignored `.wise-agents/tutorial-game`. It reads at most 8 MiB of compressed archive from the cache or the download and hashes at most 64 MiB of decompressed output as a stream, stopping at either ceiling before anything is extracted (`archiveLimits` in `scripts/stage-tutorial-game.ts`; the pinned archive is under 100 KiB compressed and 400 KiB expanded). Raise a ceiling there only when the application legitimately outgrows it. The root typecheck, documentation, headless and game-build commands stage it first; a failed download or digest stops qualification. No application source is maintained here.

To update the tutorial, first merge the application change in the examples repository, record that merge SHA and its archive digest in the pin, update the source links and quoted snippets, then run the checks below. Candidate qualification installs packed SDK packages into a disposable copy; ordinary application development uses the examples repository's npm lockfile.

```sh
npm run build:tic-tac-toe                                      # apps/lit-host/dist/tic-tac-toe and tic-tac-toe-guided (ignored; part of npm run build)
npx vitest run scripts/stage-tutorial-game.test.ts scripts/tic-tac-toe.test.ts scripts/tic-tac-toe-document.test.ts
cd apps/lit-host && npx playwright test e2e/tic-tac-toe.spec.ts   # the whole suite is npm run test:browser
```

`scripts/build-tic-tac-toe.ts` reuses the starter's machinery (`scripts/packed-consumer.ts`): the SDK packages are packed, installed into a clean copy of the example, and the example's own Vite configuration builds it. It adds no entry to the example and nothing to the packages. A second build applies the external game's `guided-change/move-list.patch`, the guide's change, to a fresh copy.

- **Application rules, store and controller tests** live with the [game source](https://github.com/MachineWisdomAI/saga-a2ui-examples/tree/b4eaeb909a460f94e44c411f8e3ad4091014e5c4/apps/tic-tac-toe/game/test); examples CI runs them against registry-installed SDK packages.
- **The example** (`scripts/tic-tac-toe.test.ts`): it uses the stack's local listener, keeps application logic outside the transport, imports no `@modelcontextprotocol/ext-apps` module and no `@a2ui/*` package, builds from packed tarballs with no server code in the page, starts with `node dist/server.mjs`, and takes the guided change as a patch to `src/surface.ts` and `src/catalog.tsx` only.
- **The board in Chromium** (`apps/lit-host/e2e/tic-tac-toe.spec.ts`, 27 tests, on the local host fixture): the removable credit on a game in play, a finished game and an unavailable game, opening `https://saga-ai.dev/` and the tutorial through the host; clicks and keyboard moves; the context update with the game in `structuredContent`, then the move message that names the game and draws no board; the message still sent with the context capability withheld; the instruction when no message is accepted; a winning and a drawing X move, each recording one result message with no context and no wait; an O move made through the server and picked up by the wait; stale and repeated moves refused with no effect; New game unaffected by a move request still in flight; a failed append that settles after New game showing nothing on the new game; the continued wait and its recovery button; an expired game; a lost reply recovered by reading the game, and that read, held while New game is pressed, leaving the new board playable before and after it settles; the wait ending with the view; and the guided change's move list. No test asserts which square an assistant chooses. The fixture gained `hold-then-refuse`, which holds a conversation request and refuses it when released.
- **The guide** (`scripts/tic-tac-toe-document.test.ts`): compares the first lesson's application and build files with its full checkpoint, the completed game with the maintained example, and the extension with the guided-change patch. It checks exact dependency pins, one-stack installation and documentation links. `scripts/tic-tac-toe.test.ts` builds and typechecks all three checkpoints against packed SDK packages. The tutorial uses Vite's React/TypeScript generator; its generated project configuration is separate from the repository's contributor build configuration.
- **Runtime behavior.** The automated suite runs locally and in the Chromium host fixture. Actual Claude and ChatGPT observations are recorded in the [getting-started Blueprint's Status](../blueprints/features/getting_started_tracks.blueprint.md#status). The board reads every 1.5 seconds at first, then every 5 seconds while O has the turn; consecutive connection failures end the wait and offer a recovery control. A server registers a view once per address, so `new_game` and `show_game` declare the same page under two addresses (`new-game` and `show-game`) rather than one shared view.

### Consumer boundary scan and package directions

Consumer code holds application meaning only. `scripts/consumer-boundary.ts` scans it for the SDK's own glue, and `scripts/consumer-boundary.test.ts` (part of `npm run test:headless`) judges the result. The scan guards against a duplicated integration rule; it does not forbid a supported lower-level interface used for a documented purpose.

| Scanned (explicit include list) | Excluded (explicit, each with its reason in the configuration) |
| --- | --- |
| `templates/*/src` and `templates/*/server` (all five templates are asserted present), `examples/*/src` and `examples/*/server`, `demo/*/server`, the `apps/lit-host/src` view modules (`mcp/`, `answer-card/`, `playback/`, `lit/`, `react/`, `*-main`), the starter output each qualified template exports, and the code fences of the documentation | `apps/lit-host/src/main.ts`, `saga-panel/` and `lit/saga-app.ts` (the host side, where host-side SDK interfaces are legitimate), `apps/lit-host/e2e` and `apps/lynx-fixture` (protocol and host qualification fixtures send wire messages by design), test files, and a fence whose info string carries `before` or `historical` |

The rules name prohibited glue only: the A2UI wire literals `createSurface:`, `updateComponents:`, `updateDataModel:` and `version: 'v0.9'`; imports of `@modelcontextprotocol/ext-apps` (every subpath), `@saga-a2ui/mcp/view` and `@a2ui/*`; and the `createMessageSession`, `a2uiV0_9Decoder` and `IngestResult` symbols. A raw `pagehide` listener is application behavior and is not a rule. A server consumer takes its backend entry from `@saga-a2ui/mcp/server`. The `ext-apps` package's own `/server` subpath is real backend API, not view glue, so a server that registers a tool or resource with it directly (the notes example's server and the playback server) keeps that one import through a reviewed line with its reason; it is not exempt by pattern, so a new use is reported until a reviewer accepts it, and a template needs none. The test also fails when a file under a `server` directory (or named `server.ts` or `*-server.ts`) in `templates`, `examples`, `demo` or `apps` is neither scanned nor excluded. An application that installs a stack takes its upstream catalog and schema names from the stack (the table above), so its view code carries none of these exemptions; `scripts/consumer-stack-imports.test.ts` checks that the templates, the examples' stack views and their manifests name no upstream renderer or schema package and no lower SDK package the stack re-exports. The files that stay lower-level are listed there with a reason: the notes example's renderer-neutral modules (shared by the Lit and React consumers, which cannot name either stack), its optional-card consumer (`main-card.ts`, the FaithfulCard entry inside an own catalog, which neither stack exports yet), and the answer example's standalone page (no MCP host). A reviewed exception is one line, `// saga-boundary: <rule> <reason>`; there is no file-wide disable, an unknown or reasonless exemption is reported, and so is an exemption on a line with no hit. The test reports hit counts, fails when an include entry matches nothing or the scanned file count falls below its floor, and proves with a known-bad line per rule and each near-miss (a `before` fence, an excluded fixture, an exempted line naming its rule, a `pagehide` listener, a `createSurfaceLayout(` identifier) that the scan reports what it should and only that. Run `npx tsx scripts/consumer-boundary.ts --exempt` to print the report and every exemption with its reason.

Package dependency directions are a separate check. Each package's `exports.test.ts` asserts its own row of `scripts/package-direction.ts` against its manifest and its non-test source, and proves with a deliberate wrong-direction import and a wrong-direction manifest dependency that the assertion can fail: core imports no delivery, renderer or DOM; MCP delivery imports core only; components import core only and no DOM; the renderers import core and components; a stack is the only place a renderer meets a delivery.

### MCP result lifecycle in the view (MCP2)

`createEpisodeView` (`apps/lit-host/src/mcp/view.ts`) decides what each delivered result means for the episode panel and nothing else. `apps/lit-host/src/view-main.ts` starts the view with `startA2uiView` from `@saga-a2ui/lit-mcp-stack`: the stack connects to the host, holds a result that arrives early (the latest wins), applies the host context first, ends the view once on dispose, a host `ui/resource-teardown` request or `pagehide`, and gives the application the bound surface to update. The page writes no A2UI message and imports no bridge, and the typed `surface.update` replaces the session's removal and re-creation messages the earlier view wrote by hand. The page keeps what is its own: the policy it reads from the document it was served in, the content view its descriptions run under (`provideContentView`) and the problem line.

- Initialization: ordering and holding are the stack's (`packages/*-mcp-stack` tests, with the lifecycle cases in `packages/mcp`). A result sent during initialization is shown exactly once, when the view is ready.
- Replacement: each valid public result is applied as an in-place data update and replaces the one shown.
- Failure: an error result, a result that is not a public episode (including undeclared fields) or a rejected update empties the panel (which draws nothing without a title) and shows a plain-text fallback in `[data-testid="view-problem"]`. The next valid result shows the panel again and clears the fallback.
- Consent: image consent is revoked before every result is applied, even a repeat of the one shown, and retired for good by the stack's teardown, once.

Tests: `src/mcp/view.test.ts` (`npm run test:headless`) checks those decisions without a bridge. `e2e/mcp-view.spec.ts` (`npm run test:browser`) controls delivery order through the test-only host fixture's real `AppBridge` against the built view: a result sent during initialization, replacement, each failure kind with recovery, delivery after teardown, and remount.

### Subscriptions for the verified request identity (BROWSE1)

A second, protected MCP endpoint, `POST /subscriptions/mcp`, returns the signed-in user's own subscriptions from a synthetic account fixture. It uses a synthetic account fixture and adds no dependencies. (This section describes the slice as built; its MCP delivery now runs through `@saga-a2ui/mcp`, see "Reusable MCP connector (CORE1)".)

- `mcp/request-auth.ts`: application-owned authentication. A bearer credential is checked by an `OAuthTokenVerifier` (the MCP server package's own interface; an unknown credential is an `OAuthError` with `OAuthErrorCode.InvalidToken`) before any server is built or backend called. Each protected endpoint states the `resource` it is (its canonical URL, as clients and the identity provider know it; there is no default) and the credential's `AuthInfo.resource` (RFC 8707) must be exactly that URL, compared as parsed URLs. A resource identifier has no fragment (RFC 8707), so a credential whose resource carries one is invalid and refused, never normalized into a match. A credential that names no resource, or another, is refused before any scope or identity is read, so a token the same verifier accepts for another service never becomes authority here. `startEpisodeListener` rejects, before it opens a port, any configured protected endpoint whose `resource` is missing, is not an absolute http(s) URL, or carries a fragment, and it takes its own copy of each accepted resource at startup: changing the caller's `URL` afterwards moves nothing. Missing credential: `401` with `WWW-Authenticate: Bearer realm=...`; malformed, unknown, expired or issued for another resource: `401 invalid_token`; verified but not a user (service-only, no account or scope): `403 insufficient_scope`. The accepted credential is copied into a frozen, request-owned snapshot of the validated claims before it is attached to `req.auth`: the transport reads that context only after the body arrives, so a verifier that reuses or mutates its own `AuthInfo` cannot change which account an earlier request was authenticated as. The snapshot reaches the tool only as the SDK's per-request `ctx.http.authInfo`, read inside each invocation; an `accountId` argument is dropped. An optional `status` filter is the only declared argument, and it cannot name an account. There is no shared current-user state.
- `mcp/dev-auth.ts`: **development-only** verifier with fixed public tokens (`DEV_TOKENS`). It throws when `NODE_ENV=production`, is imported only by `mcp/serve.ts` (the loopback demo) and tests, and is kept out of the browser bundles (checked by `e2e/view-bundle.spec.ts`). A remote host must pass its own configured `verifier` to `startEpisodeListener({ subscriptions })`; the listener has no default.
- `mcp/subscriptions.ts`, `mcp/subscriptions-server.ts`: strict, bounded zod projection. Each field is copied from the backend record explicitly (no spreading) and the result is validated before serialization; a record that breaks the contract yields a generic tool error. Canary private fields never reach the wire.
- View session: the result carries an opaque label (`vs_` + 22 characters, an HMAC of the sign-in id under a per-process key). `mcp/subscriptions-view.ts` pins the opening host delivery; a different label, an unknown shape, or an error clears the private view. A `toolinput` notification does not authenticate the next `toolresult` — those notifications are not correlated. When the host proxies server tool calls, a new input starts `App.callServerTool`, and only that response may establish or recover the pin. That read carries the declared `status` filter from the input's business arguments, so a filtered read stays filtered: an undeclared field such as `accountId` is dropped, and a status the tool does not support clears the view instead of widening the read. A finished read does not recycle its identity, so an older in-flight response cannot satisfy a later read or restore private rendering after a later refusal. An unsolicited notification cannot open private rendering, but an error, a changed label, or an unknown shape still clears the view while a correlated read is in flight and retires reads that started before that loss. Only a correlated read started after the loss may recover. A refusal of the proxied call (the listener's HTTP 401/403, before any tool handler) keeps the view cleared. The label controls freshness only; the server authorizes every call.
- `subscriptions.html`, `src/subscriptions-main.ts`: the view, built to `dist/subscriptions-view/subscriptions.html`. States: subscriptions, empty, sign-in required, retry, problem. Values are written with `textContent`.
- `runToolResultView` (view lifetime) is the `@saga-a2ui/mcp/view` export that the episode, subscriptions, answer and playback views share.

Try it locally (`npm run build` first): `curl -s -X POST http://127.0.0.1:3001/subscriptions/mcp -H 'authorization: Bearer dev-only-token-alice' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_subscriptions","arguments":{}}}'`.

### Recovering from a failed subscription read (BROWSE2)

Install and run the same way as the rest of the app: `nvm use`, `npm ci`, `npm run build`, then `npm run serve:mcp`. The protected path is `POST /subscriptions/mcp`. Sign in with a bearer token the configured verifier accepts. The loopback demo accepts only the development tokens printed in `mcp/dev-auth.ts`; it refuses to start that verifier when `NODE_ENV=production`. A remote host passes its own `OAuthTokenVerifier` and the endpoint's canonical `resource` URL to `startEpisodeListener({ subscriptions })`. The development verifier stamps every credential with the one resource it was constructed for (`createDevelopmentVerifier(resource)`), as an identity provider's audience would. There is no separate diagnostic command.

Read the HTTP status before the JSON-RPC body. They are different failures, and none of them forwards a backend status or a raw `Error.message`.

| What you see | Class | Meaning |
| --- | --- | --- |
| `401` or `403`, `WWW-Authenticate: Bearer ...`, body `{ "error": "..." }` and no `jsonrpc` | Authorization | The credential is missing, invalid, expired, or not a user. The tool did not run. Sign in again. `insufficient_scope` means the credential is not a user sign-in. |
| `413`, `406` or `415`, body `{ "error": "..." }` and no `jsonrpc` | Transport | The body is over the browse limit, or `Content-Type` / `Accept` is missing. The tool did not run. Fix the request. A chunked body with no `Content-Length` is the same 413, sent before the connection is closed. |
| `400` or `200` with `jsonrpc`, `id` and `error`, and no `result` | Protocol | Malformed JSON (`id` is `null` when none can be read), a malformed call, unknown tool, or an argument over the input limit. A JSON-RPC batch is classified the same way before any element runs: a one-element batch keeps that element's error and id; a rejected longer batch is one invalid request and does not run the other elements. The tool name is not copied into the error. The `id` matches the request when one was present. The tool did not run. |
| `200` with `result.isError` and a fixed sentence | Tool failure | The known tool ran, or rejected its own business input, and returned a safe sentence. A backend read that does not finish within five seconds, or whose request is cancelled, is this failure (`Subscriptions are unavailable.`); a later resolution is not sent. An empty `subscriptions` array is not this: it is a successful read. |

The view then shows one of three subscriber states, and never the backend text:

- **Empty** (`data-state="empty"`): the read succeeded and there are no rows. Try again refreshes that same read.
- **Retry** (`data-state="retry"`): the read could not be completed. Private rows and the selection are cleared. Try again calls `list_subscriptions` with no arguments; it does not resend the failed input.
- **Cleared** (`data-state="problem"`): the result was not a subscriptions result, the projected output was invalid, or the business input was rejected. Private values are cleared. Try again is still only the safe read.

A selection stays only when the next successful read still contains that subscription id. A host refusal of the proxied call (HTTP 401/403, before the tool handler) keeps the sign-in-required state; a delayed copy of an earlier result cannot restore it.

Tests: `src/mcp/subscriptions.test.ts` (wire classes, limits, batch classification, chunked 413, a bounded backend read that does not emit late, and the failure fixture), `src/mcp/subscriptions-view.test.ts` (empty, retry, cleared, selection, the declared status filter through a real `App`/`AppBridge`, and a bounded read that does not emit late), `e2e/subscriptions-view.spec.ts` (the same wire results in the sandboxed view).

Tests: `src/mcp/subscriptions.test.ts` (real listener and bearer credentials over HTTP: concurrent users, forged account argument, canaries, bad backend data, every credential failure and its status/challenge, and a paused request whose verifier reuses one mutable `AuthInfo`), `src/mcp/subscriptions-view.test.ts` (session pinning, clearing, recovery only through the correlated `callServerTool` response, an older in-flight read that cannot reuse a later read's identity after a refusal, and session loss that clears while a read is pending), `e2e/subscriptions-view.spec.ts` (built view in the sandboxed host fixture: authorized, changed sign-in, a proxied tools/call whose listener 401 clears the view, a delayed prior result, and recovery from that call's response).

### Play an episode only after a fresh entitlement check (PLAY1)

A third protected MCP endpoint, `POST /playback/mcp`, lets the signed-in synthetic subscriber press Play in an embedded Lit view and hear a protected episode. It uses synthetic accounts and a generated tone. One new runtime dependency: `jose` 6.2.12 (MIT) for JWT proofs and RFC 7638 key thumbprints; no MCP-UI, CopilotKit, AG-UI or Ora package is used. The [v0.1.0 playback walkthrough](../docs/authorized-playback.md) shows the current SDK/application split, Play sequence, media checks, player states and teardown behavior.

    npm run build && npm run serve:mcp   # also prints the playback URL; dev tokens only (see mcp/dev-auth.ts)

Mechanisms chosen for the Blueprint's open decisions (the evidence is the tests named below, run through the real listener and the built view):

- **Recipient binding (decision 1): proof of possession.** The view creates a non-extractable ECDSA P-256 key and sends only its public half in the Play call's `_meta` (`saga-a2ui/recipient-key`); the arguments stay `{ episodeId }`. The media service binds the issued capability to the verified account, the episode and that key's thumbprint. A media request must carry the capability **and** a fresh ES256 proof signed by that key naming the exact URL, method and capability; each proof is single-use. A copied capability, another user, another episode, a missing, stale, replayed or mis-targeted proof and an expired capability each get the same `403` with a fixed `{"error":"forbidden"}` body and no protected read (`playback/media.test.ts`, `e2e/playback-view.spec.ts`). A bearer URL alone is never enough.
- **App-only declaration and private result channel (decision 3).** `play_episode` declares `_meta.ui.visibility: ['app']`; the only model-visible tool is `get_playable_episode`, which mounts the view and checks no access. A successful Play puts the capability **only** in `result._meta['saga-a2ui/playback']` (MCP Apps documents `_meta` as not intended for model context); `content` is a fixed sentence and there is no `structuredContent`. Both projections are strict, bounded zod schemas parsed before serialization. The static view resource is identical for every caller.
- **User gesture (decision 4).** The press calls `player.prepare()` synchronously (creating and resuming the `AudioContext` inside the activation), then authorizes asynchronously. If the browser still holds audio back, the view shows `gesture-needed` and a second explicit press plays; it never autoplays. Audio is fetched with `fetch` and decoded with Web Audio, so the view needs only `connect-src` for the media origin and no media element, URL or `media-src`.
- **Playing means the audio clock advanced.** The view reports `playing` only after that signal; `denied`, `expired`, `unsupported`, `unavailable`, `media-failed` and `gesture-needed` are distinct states, and pending work is retired so a late success cannot restore cleared media. PLAY1 did this with a generation number and an `attemptLimitMs` bound inside the controller; CORE2 replaced both with the shared action runtime: a changed `subject` and the action's work deadline (30,000 ms by default) retire the press, and one deadline covers every client stage until audio advances. See "Bounded requests and playback (STATE2)" below.
- **Pause, Resume and a short episode tell the truth.** `pause()` and `resume()` return promises, so the view shows `paused` or `playing` only once the audio did that. A Resume the browser withholds (`NotAllowedError`, or a clock that does not advance) shows `resume-blocked`, keeps the position, and the next explicit press retries it without a new authorization. A Pause or Resume the player cannot perform is `media-failed`. Audio that ends before the start is confirmed shows `ended`: the end is remembered for the request that was waiting, and the late `started` result cannot replace it, while a retired request still cannot restore anything.

Wire mapping, verified against `@modelcontextprotocol/server` 2.4.0 and `ext-apps` 2.0.3 (see the MCPV2 recipe below):

| Condition | Result |
| --- | --- |
| Missing, invalid, expired credential | HTTP `401` + `WWW-Authenticate`, before any tool |
| Service-only credential | HTTP `403 insufficient_scope` |
| Malformed call, unknown tool, oversized argument | JSON-RPC error from the request gate (`protected-request.ts`), tool not run |
| Known tool, invalid input (incl. a forged `accountId`) | `isError` result with a fixed sentence; the rejected key and value are not echoed |
| Denial, unknown episode | `isError`, "Playback denied: this account does not have access to this episode." (identical for both) |
| No usable recipient key (host dropped `_meta`) | `isError`, "Playback is not supported here."; zero entitlement checks, zero media reads |
| Backend failure, projection that breaks its contract | `isError` with a different fixed sentence; no capability, no backend text, nothing in logs |

Implementation notes:

- The MCP server package maps **any** handler failure to an `isError` result (and copies the thrown message into it, which is why handlers catch everything and return fixed sentences); it has no JSON-RPC internal-error path for a registered tool. The ticket's "sanitized internal error" is therefore an `isError` result with a fixed sentence and no success data.
- Play's input is a strict object, so a forged `accountId` is rejected instead of dropped. MCP Apps 2 accepts that schema in `registerAppTool`, which also writes the legacy flat `ui/resourceUri` key, so Play and its opener use the helper like every other app tool.
- **Host requirements.** Recipient binding needs the host to forward `_meta` on the view's proxied `tools/call` and to let a sandboxed iframe `fetch` the media origin with custom headers. The local host fixture shows the binding working when the host does both, and Play failing closed (`unsupported`, no protected fetch) when it does not. The binding is never weakened for a host that cannot carry it.
- The media origin answers any origin (`Access-Control-Allow-Origin: *`, no credentials) because a sandboxed iframe sends `Origin: null`. That is safe only because no cookie or ambient header authorizes media; the capability and proof decide every request.
- Expiry, revocation, ranges, redirects, origins and caches are decided together in PLAY2 below. [Request and view lifetimes](../blueprints/features/request_view_lifetimes.blueprint.md) proposes STATE1/STATE2 scope for selection races, teardown, cancellation and bounded request completion, replacing the [rejected account/session proposal](../blueprints/features/account_session_isolation.blueprint.md).
- In headless Chromium, playback is checked by the audio clock advancing.

Tests: `src/playback/playback.test.ts` (wire contract through the real listener: declaration, entitled/denied/unsupported/forged/replay, every credential failure, projections, fault mapping with log capture, CORS/CSP), `src/playback/media.test.ts` (recipient binding, replay, expiry, preflight), `src/playback/playback-view.test.ts` (the controller through a real `App`/`AppBridge` whose host forwards to the real listener), `e2e/playback-view.spec.ts` (built view in the sandboxed fixture with real Web Audio: playing, keyboard, denial, sign-in recovery, unsupported, replay after revocation, expiry, recipient binding, pending, live region, 320px reflow with 200% text), and `e2e/view-bundle.spec.ts` (no server code, credential or media element in the built view).

### Protected media expiry and delivery constraints (PLAY2)

The same example media service and foreground player, no new dependency and no general media proxy. The rules below are decided together and each one is pinned by a test named after the behavior. The media checks are drawn in [How authorized playback works](../docs/authorized-playback.md#what-the-media-service-checks). They build on PLAY1's recipient binding (capability plus a fresh single-use proof from the bound key); none of them weakens it.

Every acquisition, whole body or byte range, runs the same checks in this order and stops at the first failure with the same `403` (fixed body `{"error":"forbidden"}`) and no read of protected storage: capability known and unexpired on the **service's** clock, episode scope, proof from the bound recipient key (single-use, so a range needs its own proof), then **current entitlement**. Only then is storage read and the `Range` header interpreted.

| Rule | Decision |
| --- | --- |
| Retained state | The service keeps at most 1,024 capabilities and 4,096 spent proof identifiers, so memory does not grow with traffic. A full capability table forgets expired entries first and then the oldest issue (its holder plays again). A full proof table refuses a new proof until the oldest identifiers age out rather than forget one that still makes its proof single-use. A spent identifier is held until the last second its proof could still be accepted (its `iat` plus 65 seconds, inclusive, so up to 71 seconds after first use for a proof dated the full 5 seconds ahead). A capability is 43 base64url characters, a proof identifier 1–64 URL-safe characters, a proof at most 4,096 characters, an account identifier at most 256 bytes; anything else is refused before it is parsed or kept. `capabilityTtlSeconds` must be a whole number from 1 to 3,600 (the listener refuses to start otherwise), and a clock that returns a non-finite time is a fault: nothing is issued or accepted on it. The tables are per listener and shared by every principal it serves; a deployment that shares them across principals or faces the network needs per-account limits. |
| Lifetime | 60 seconds from issue (`capabilityTtlSeconds` overrides). Usable while `now < expiresAt`; the view is told that same `expiresAt`. Using a capability does not extend it. A new Play issues a new capability. |
| Revocation lookup | The application's own `checkEntitlement`, asked again on every acquisition for the account and episode the capability was issued for. A denial refuses the request **and drops the capability**, so access granted again later is reached only through a new Play, never by reviving an old copy. |
| Lookup or storage fault | Not a refusal and never a grant: a `503` with the fixed body `{"error":"unavailable"}` and no dependency text on the wire or in logs, distinct from the `403` that means expired, revoked or misused. A fault does not revoke the capability. |
| In-flight response | A response that already passed every check is not tracked or cancelled and finishes. Every acquisition that **starts** after the revocation or expiry, including a range request issued while the first is still running, gets no bytes. |
| Bytes already delivered | Cannot be retracted. Stopping and clearing the player reduces continued use of held media; it does not erase what the browser or the host already buffered or downloaded. |
| Ranges | One `bytes=` range (`a-b`, `a-`, `-n`) is answered `206` with `Content-Range` and `Content-Length`; `Accept-Ranges: bytes` is sent on whole answers. A `bytes=` range the service cannot serve as one slice (past the end, reversed, `-0`, `-`, several ranges, non-numeric) is `416` with `Content-Range: bytes */<length>` and no body, sent **only to a caller who passed every check**, so the length is not a probe. A range in another unit is ignored and the whole body is sent (RFC 9110). |
| Cache | Every answer that can carry bytes or a status (`200`, `206`, `403`, `416`, `503`) is `Cache-Control: private, no-store` with `Vary: Origin, Range, x-saga-capability, x-saga-proof`, so neither a shared cache nor the browser keeps it and a cache that ignores `no-store` still cannot answer one user with another's bytes. The player also fetches with `cache: 'no-store'`. |
| Origins | The only origin the view may reach is the listener's own, which the application writes into the served player document (`<meta name="saga-media-origin">`) and also declares in `connect-src`. The view refuses, before signing a proof or sending a request, any grant whose media URL is not exactly that origin plus `/playback/media/<episodeId>` (another scheme, host or port, credentials, a query, a fragment or a path variant all fail), and a document with no usable origin admits nothing. The refusal does not depend on the host enforcing the resource's CSP; the declared `connect-src` remains as a second control. The player then shows `unavailable` with an unknown request outcome, because the server issued a capability that was never used. |
| Redirects | The media service never redirects. The player fetches with `redirect: 'error'`, so a redirect is a failed acquisition and the capability and proof headers never follow it to a destination the application did not declare. |

Recovery in the view: expiry or revocation between grant and fetch shows `expired`; any other failure of the media request (network, `5xx`, a redirect, undecodable bytes, a blocked origin) shows `media-failed`. Both stop the player, clear the source and offer one explicit press. That press is a brand-new Play (fresh authentication, a fresh entitlement check, then a fresh capability) and ends in playing or the safe denial. Nothing refreshes a capability from saved view state, nothing retries on its own, and no public MP3 or chat URL is ever substituted. The status line is the polite live region and the control keeps keyboard focus through `expired`.

Implementation notes:

- The built player fetches the whole body with one request. Range behavior is exercised at the service's HTTP edge (real listener, real proofs).
- The admitted origin comes from the document the application served, so it binds the destination to the application's configuration. It is exact origin admission: a deployment that needs DNS rebinding resistance should use a stable application-controlled hostname.
- The redirect rule is exercised in the headless controller test against a real redirecting origin.
- The synthetic entitlement lookup and storage are in-memory seams. A real application owns revocation latency; this service asks on every acquisition.
- `Access-Control-Allow-Origin: *` remains (see PLAY1): a sandboxed iframe sends `Origin: null`. Nothing ambient authorizes media, so this discloses nothing to a page without the capability and a proof from the bound key.

Tests: `src/playback/media.test.ts` (revocation of an issued capability, sticky revocation, fault versus revocation, in-flight characterization, lifetime boundaries, every range case, `416`, `503`, cache and `Vary` headers, log capture), `src/playback/playback-view.test.ts` (redirect not followed, expiry versus media failure, retry as a new Play, no automatic loop, only the declared origin fetched), and `e2e/playback-view.spec.ts` (the same behavior in the built view: revoked mid-Play with keyboard focus kept and announced recovery, media-service outage, no self-retry, an undeclared origin receiving nothing, headers sent only to the declared origin, no media request after a denied Play, no capability in model-visible fields or the static resource).

### View teardown and acquisition-scoped cleanup (STATE1, partial)

This slice implements the teardown part of [Request and view lifetimes](../blueprints/features/request_view_lifetimes.blueprint.md). It adds no dependency and changes no server code. It covers teardown of the subscriptions and playback views, the action-view label-loss policy and acquisition-scoped start cleanup.

What changed:

- **Subscriptions view.** The controller registers `onTeardown`. Teardown retires the read in flight, stops its timer and drops the private rows and selection. A late answer, a late rejection or the read bound then presents nothing, and `retry()` and `select()` do nothing and start no read. Teardown is not disposal: the bridge connection stays open until `dispose()`, which closes it once. The correlated-recovery rule is unchanged (an unsolicited positive result cannot recover label loss; a correlated read started after the loss can).
- **Playback view.** Teardown still releases the player and aborts the byte request, and now also retires the controller: Play, Pause and Resume, the player's end event and every asynchronous continuation of an earlier press present nothing, prepare no audio and send no request. This `tornDown` state is separate from `disposed`, which makes `dispose()` return before it reaches the bridge. Host teardown does not call the connection's `dispose()`, and a later `dispose()` closes it once.
- **Action-view label loss (decided 2026-10-19, [#105](https://github.com/MachineWisdomAI/saga-a2ui/issues/105)).** The playback controller pins the sign-in label of its first opener. An opener or a grant under a different label ends the view for good: it clears the selection, stops the player and shows `session-changed` ("Your session changed. Open a new view or reload to continue.", with no control). From then on every opener is ignored whether it carries the old label, the new label or is unreadable, and Play, Pause and Resume send no request, prepare no audio and acquire no media. A new view or a reload pins its own label and bootstraps normally. A same-label opener for another item before any loss still replaces the selection. The controller tests (`playback-view.test.ts`, "final loss of the pinned sign-in label") and the built-page tests (`playback-view.spec.ts`, "after the sign-in label is lost") pin this. The label is freshness only; the server still authorizes every Play and media request.
- **Late `start` cleanup.** A start that settles for a retired Play releases the player only while no later Play has taken it over; it never stops or otherwise touches a newer Play's audio. The release for the latest retired Play is kept, because a player that does not reject a pending start on `stop()` would otherwise leave audio running.

Real-player ordering (Chromium, Web Audio player, `e2e/web-audio-player.spec.ts`): `stop()` rejects a start that is decoding or waiting for the audio clock, and a start made before the next `prepare()` is rejected by that `prepare()` and cannot end the newer start. The whole-player `AudioPlayer` seam stays: with a player that honors that contract, a stale start never resolves, so the controller's guard matters only for a player that does not. *Current reading: that per-lease owner now exists (`apps/lit-host/src/playback/player-owner.ts`, delivered with CORE2); this paragraph records STATE1's own behavior.*

The view takes the last opener delivered; the server authorizes every request. Content consent is unchanged: replacement, error, invalidation, teardown and disposal revoke or retire it (`packages/components/src/faithful-card/image-consent.test.ts`, `e2e/description-strict.spec.ts`).

Tests: `src/mcp/subscriptions-view.test.ts` ("host teardown of the subscriptions view"), `src/playback/playback-view.test.ts` ("host teardown of the playback view", "late player-start cleanup is scoped to its own acquisition"), `e2e/playback-view.spec.ts` ("the built player after host teardown") and `e2e/web-audio-player.spec.ts`.

### Standard descriptions (POL1)

Episode descriptions are read as Markdown under one trusted, immutable content policy chosen by the application. This section is Standard (POL1); Strict and the reader's Show images control follow in [POL2](#strict-descriptions-and-show-images-pol2). One new runtime dependency: `markdown-it` 15.0.3 (MIT; notices in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md)). No MCP-UI, CopilotKit, AG-UI or Ora package is used. A2UI's optional `@a2ui/markdown-it` peer stays uninstalled; SAGA uses `markdown-it` directly so it controls the token set.

    npm run build && npm run serve:mcp   # the default policy; PORT=… overrides the port

Decisions made here (the Blueprint left them open):

- **Parser and dialect.** `markdown-it`'s `commonmark` preset with linkify, typographer, tables and strikethrough off. Supported: paragraphs, headings, block quotes, bullet and ordered lists, fenced and indented code, rules, emphasis, strong, inline code, soft and hard breaks, links and images. Everything else, including raw HTML (`<b>x</b>`), stays as the characters written. The parser recognises raw HTML only so POL2 can tell it from prose: its tags, comments and blocks become `raw-html` and `raw-html-block` nodes that carry their characters and are rendered as text, never as elements.
- **Input bound.** 2000 UTF-16 code units (`EPISODE_CARD_SETTINGS.maxLength`, the episode consumer's trusted setting; see the FaithfulCard section). Longer input is an explicit "too long" alert, never truncated. The MCP tool contract (`mcp/episode.ts`) is stricter, at 500; the renderer bound covers other data sources too.
- **Nesting bound.** `markdown-it` silently stops reading once open block containers reach its ceiling, which would drop the rest of the text. The ceiling is fixed explicitly (`MAX_NESTING_LEVEL`, 20; a block quote counts one level, a list item two) and a description that reaches it is refused with an explicit "nested too deeply" alert, never partly rendered. Inline nesting (brackets, emphasis) does not drop text and is not limited.
- **Restricted tokens.** `@saga-a2ui/components/faithful-card` (`markdown.ts`) turns the parser's tokens into a closed, deeply frozen set of nodes in source order (`ParsedMarkdown.source` keeps the original string). `@saga-a2ui/lit/faithful-card` renders each node with a fixed template and text bindings; no `unsafeHTML`, `innerHTML` or parser-generated HTML exists.
- **Policy.** `@saga-a2ui/components/faithful-card` (`policy.ts`, `createContentPolicy`) validates `{ level?, imageHosts?, blockedPresentation? }` (see POL2) and returns a frozen policy or an explicit failure; it accepts only canonical lowercase DNS hostnames (labels of letters, digits and interior hyphens, which also covers canonical dotted IPv4) and rejects wildcards, schemes, ports, paths, credentials, uppercase or non-canonical hosts, any character that is a delimiter in a Content-Security-Policy (such as `;`, `,`, `'`, spaces) and bracketed IPv6 literals, more than 32 hosts and unknown settings, and never falls back to something looser. `imageHosts` defaults to empty; `fontOrigins` is a separate trusted list (see "Trusted artwork and fonts"). Link decisions allow only absolute HTTPS without credentials. Image decisions additionally need an exact `https://host` origin match (so suffix tricks, unlisted subdomains, other ports and credentials fail) and demonstrated enforcement.
- **Links.** A link is a button whose accessible name includes the parsed hostname (shown as `(docs.example.com)`; internationalized names appear in ASCII). Activation calls only `HostLinks.open`, backed by the pinned upstream `App.openLink` (`ui/open-link`) when the host advertised `openLinks` (`mcp/host-links.ts`). Denial, failure or a missing capability shows a polite status with the destination as text. There is no `window.open`, anchor or navigation fallback. A result that arrives after the description changed is ignored.
- **Resource restrictions.** MCP Apps `resourceDomains` is one broad permission (scripts, styles, fonts, media and images). The server therefore inserts a second `<meta http-equiv="Content-Security-Policy">` derived from the same policy into the served document (`embedContentPolicy` from `@saga-a2ui/components/faithful-card`, composed by `mcp/content-resource.ts`): `default-src 'none'`, `script-src`/`style-src` `'unsafe-inline'` only (the single-file view), `img-src` and `font-src` (each the mode's embedded baseline plus its own exact origins, see "Trusted artwork and fonts" below), and `media-src`, `connect-src`, `frame-src`, `object-src` `'none'`. A document must satisfy the host's policy and this one, so a listed origin gains nothing but its own resource type. Redirects are checked against the same `img-src`, so a redirect to an unlisted origin is not followed.
- **Enforcement gate.** The view rebuilds the policy from the JSON embedded in its own resource (an invalid one stops the view before anything is mounted) and treats images as enforced only when the document carries exactly the restrictions that policy derives (`establishImageEnforcement`). Without them every image stays inert, even from a listed host. The host fixture shows the effect with a host policy as broad as the spec describes.
- **Identity.** The episode view is served as `ui://views/view.<16 hex digits>.v1.html`: the hex digits are a digest of the embedded policy, and `v1` is the contract major of the view (`EPISODE_VIEW_MAJOR`), with the image origins and font origins as the only `resourceDomains`. A rebuild of the application code, CSS, fonts or artwork keeps the URI, so a host holding an earlier tool descriptor still reads a document that is served; a change to the policy is a new resource. A Strict policy never shares a URI with a Standard policy that declares the same origins, although both declare identical host metadata, because the embedded configuration differs. `createEpisodeServer` and `startEpisodeListener` take the policy explicitly (the listener defaults to Standard with no image host); the view receives its own policy and `HostLinks` through its `saga-app`, never through module state.
- **Authored Play is separate.** The playback resource and its capability, origin and entitlement rules are unchanged; a content image host is never added to them, and choosing one does not change Play's authorization (`playback/content-policy-separation.test.ts`).

Implementation notes:

- A host that rewrote the document's policy away makes the view treat every image as inert, because the derived restrictions are missing (covered by the stripped-policy browser test).
- Image-only enforcement is shown in the local host fixture's sandboxed iframe in Chromium, through the `securitypolicyviolation` directives and the absence of requests at the network boundary.

Tests: `packages/components/src/faithful-card/policy.test.ts` (configuration failures, link and image decisions, derived restrictions, immutability, enforcement), `packages/components/src/faithful-card/markdown.test.ts` (order, preservation, inert HTML and unsupported syntax, the bound), `src/mcp/content-resource.test.ts` and `src/mcp/server.test.ts` (identity, declared origins, embedded configuration), `src/mcp/host-links.test.ts` (a real `App`/`AppBridge`: opened, denied, failed, no capability), and `e2e/description.spec.ts` (the built view in the sandboxed fixture with real `ui/open-link`: order and formatting, hostile input, hostname disclosure, keyboard activation, denial and missing capability without navigation, inert links, stale results, empty and exact-host allowlists, suffix/subdomain/credential/port/non-HTTPS images, redirect, the missing-restriction fallback, a no-restriction control proving scripts, styles, fonts and media would otherwise load, and invalid embedded configuration).

### Strict descriptions and Show images (POL2)

Strict is chosen by the application, like Standard: `createContentPolicy({ level: 'strict', imageHosts?, blockedPresentation? })`, where `blockedPresentation` is `placeholder` (the default) or `inert-text` and is rejected for Standard. The same policy value drives the resource restrictions and the view's decisions. No new dependency.

    const created = createContentPolicy({ level: 'strict', imageHosts: ['images.example.com'] });
    if (!created.ok) throw new Error(created.failure.message); // never mount on a guessed policy
    await startEpisodeListener({ viewHtml, catalog, contentPolicy: created.policy, port });

Behavior (`packages/components/src/faithful-card/policy.ts` and `image-consent.ts`, `packages/lit/src/faithful-card/faithful-card-element.ts` and `blocked-fragment.ts`):

- **Blocked fragments.** Under Strict every link, image reference and piece of raw HTML is a blocked fragment. By default each appears as readable placeholder text in its original position (`[Link blocked]` after the link's label, `[Image blocked: alt]`, `[Markup blocked]`); surrounding prose, order and formatting are unchanged. With `inert-text` the source is shown from the start. In either case a keyboard-operable **Reveal source / Hide source** button switches between the two. It changes visibility only: nothing revealed can execute, navigate or fetch. Revealed source is reconstructed from the parsed fragment (`[label](destination)`, `![alt](source)`, the HTML's own characters), not copied byte for byte; `ParsedDescription.source` still holds the supplied string. A description with nothing to block gets no button.
- **Links stay inert.** `decideLink` refuses every destination under Strict, valid HTTPS included, and image consent does not change that.
- **Show images.** Before consent, including after source reveal, no image request is made (`decideImage` answers `consent-required` for an image that otherwise qualifies). **Show images** is enabled only when `offerImages` finds an image that would qualify now: an exactly listed HTTPS host and demonstrated enforcement, the same test as Standard. It cannot widen the allowlist or relax the document's restrictions, which Strict declares before mounting exactly as Standard does. When no image qualifies the button is disabled and a polite message says images cannot be shown; a description with no image has no button. Under Strict the images load eagerly once consented, rather than lazily, so consent and request are one observable step. **Hide images** removes them and revokes consent; it cannot undo a request already sent.
- **Consent is separate, revocable view state.** `createImageConsentScope()` creates one scope per view (`contentViewFromDocument`); a grant is live until revoked and is never restored, so a later Show images is a new grant. The description element revokes its grant on Hide images, when its description changes, when its view's scope is revoked, and on disconnection, and ignores image load results from before. The view revokes the scope before it applies any delivered tool result (a new result is a new selection even when its description is identical, which also means a repeated identical result needs fresh consent; the view is still live, so the reader can consent again, `mcp/view.ts`, `revokeImageConsent`). When the host asks it to tear down, and when its connection is disposed, the view retires the scope instead (`retireImageConsent`, `ImageConsentScope.retire()`): that is terminal, every later `grant()` is already dead, and the Show images control is disabled with a "view ended" notice. Show/Hide images controls are also bound to the description revision they were rendered for, so a control kept from a replaced description (or from before a disconnect) does nothing when invoked. A new view replacing an old one, or a second view, starts with no consent and cannot inherit it. The scope's `revokeAll` revokes every grant in the view at once.
- **Identity.** See POL1: the Strict configuration is part of the resource URI and is embedded in the document, so Standard and Strict resources are never confused. `npm run candidate:identity -- --level strict [--blocked-presentation inert-text] --image-host HOST` reports the Strict resource's URI, bytes and SHA-256.
- **Authored Play is unchanged in both modes.** The player resource, capability, origin and entitlement rules are untouched; `playback/content-policy-separation.test.ts` runs its cases under Standard and Strict.

Dialect notes:

- Only raw HTML is treated as "unsupported markup". Other syntax the episode's CommonMark dialect does not support (strikethrough, tables) is ordinary text and stays visible under Strict; the answer dialect reads both.
- HTML blocks follow CommonMark: a line that starts an HTML block keeps the rest of that block as raw source, so Markdown inside it is no longer interpreted (Standard shows it as text too).

Tests: `packages/components/src/faithful-card/policy-strict.test.ts` (configuration, link and image decisions, Show images offers), `packages/components/src/faithful-card/image-consent.test.ts` (grant, revoke, view-wide revoke, isolation between views), `packages/components/src/faithful-card/markdown.test.ts` (raw HTML nodes, fragment inventory), `src/mcp/content-resource.test.ts` (Strict identity and embedded configuration), `src/mcp/view.test.ts` (revocation before each result, on teardown and dispose), `src/playback/content-policy-separation.test.ts` (Play under both levels), `scripts/candidate-identity.test.ts`, and `e2e/description-strict.spec.ts` against the built resource in the sandboxed fixture (placeholders, keyboard reveal and hide, hostile input before and after reveal and consent, zero requests before consent, only the permitted image after, disabled states, redirects, Hide images, late results, description change, new selection, teardown, view replacement, failure results, two concurrent views and interleaved Standard and Strict views, resource identity and restrictions). Helpers shared with `e2e/description.spec.ts` live in `e2e/description-harness.ts`.

### Trusted artwork and fonts (REACT3-RESOURCES)

Design: [content safety and resource permissions](../blueprints/features/content_safety_levels.blueprint.md#trusted-embedded-artwork). This slice changes only the shared resource policy (`@saga-a2ui/components/faithful-card`, `policy.ts`) and its owned consumers; it adds no package, dependency, registry or configuration flag, and no React code.

- **Baseline.** The document's `img-src` and `font-src` each start with the mode's embedded schemes: `data:` and `blob:` in Standard, `data:` only in Strict. They fetch nothing from the network and are not origins. Trusted template or CSS can therefore embed artwork and fonts as data URLs at either level, and use an application-owned object URL in Standard. Strict never has `blob:`, whatever else is configured. There is no embedded-asset opt-in.
- **One directive per type.** `img-src` is the baseline plus the exact image origins, `font-src` the baseline plus the exact font origins; an empty, single or multiple list extends the baseline and never replaces it (no `'none'` remains in either directive). `script-src`, `style-src`, `media-src`, `connect-src`, `frame-src`, `object-src` are unchanged.
- **`fontOrigins`.** A separate trusted list, default empty: `createContentPolicy({ fontOrigins: ['https://fonts.example.com', 'https://assets.example.org:8443'] })`. Each entry is validated and normalized (lowercase ASCII host, the default port dropped, any other port kept), then deduplicated and sorted. A wildcard, plain HTTP, credentials, a path other than `/`, a query, a fragment, whitespace, a CSP delimiter or a bracketed IPv6 literal is an explicit `invalid-font-origin` failure, never dropped. The host rule is the image-host rule, so a canonical dotted IPv4 address is accepted as an exact host. The list is part of `policy.configuration`, so `createContentPolicy(policy.configuration)` and the embedded copy rebuild an equal policy; the baseline follows from the level.
- **Separation.** An image host never authorizes a font and a font origin never authorizes an image: they are different directives. The resource declares the union of both lists once as `resourceDomains` (the host permission is not per type); the document's own policy keeps each origin to its type, and a font origin gets no script, stylesheet, image, media, frame or connection access. A remote font stylesheet is a stylesheet request and is not authorized by its font origin.
- **Unchanged.** `decideImage`, `offerImages`, Strict consent, link rules and `establishImageEnforcement` (which still requires the exact derived document policy) are untouched. Content images still need an absolute HTTPS URL on an exact image host; Markdown `data:` and `blob:` images stay rejected, with or without consent. The content wire contract is still `contractVersion` and `markdown`; an answer cannot select assets, CSS, templates or policy.
- **Font URLs are trusted authored inputs.** Font requests carry ordinary network metadata, and `unicode-range` can reveal which subsets were needed, so an application never builds a font URL from answer text, credentials or private data. A static asset-version parameter is fine; an origin allowlist does not validate a URL's content.
- **Identity.** `contentResource` builds its view with `operationViewFromHtml` (`@saga-a2ui/mcp/server`) at major 1, with a digest of the embedded policy in the filename, so a change to the policy (including `fontOrigins`) is a new resource, a rebuild of code, CSS, font or artwork keeps the URI, and a new answer reuses it. Runtime assets stay embedded in the self-contained document.
- **Candidate report.** `npm run candidate:identity` accepts `--font-origin ORIGIN` (repeatable) beside `--image-host`.

Evidence (this change; Node 26.7.0, Chromium 1248 through Playwright 1.64.0):

- `packages/components/src/faithful-card/policy-resources.test.ts`: baseline and composition for both modes with empty, single and multiple lists; font origin validation, normalization, ports and rejection of each forbidden form; separation of image and font permissions; round-trip of the configuration; unchanged content decisions. Mutating Strict to carry `blob:` fails 10 of these and 6 browser cases.
- `apps/lit-host/e2e/trusted-assets.spec.ts` drives the built episode view in the sandboxed host fixture, in both modes and with empty and nonempty lists. The document carries exactly the derived `img-src` and `font-src`. A trusted data image and data font written into the served document load (measured natural size and font advance, no network request); a blob image and a blob font load in Standard and are blocked in Strict (security-policy violation, readable fallback text). Remote fonts: a declared origin and an explicit port load with CORS and without Show images consent; an unlisted origin, port, subdomain or scheme is blocked before any request; a response that denies this origin through CORS fails and falls back; a redirect to an undeclared origin is blocked and never requested; a declared font origin gives no image, script, stylesheet, media, frame or connection access, and an image host no font access. Hostile descriptions (data and blob images, raw `<style>`/`@font-face`, links and font URLs) sent through the real MCP tool result and A2UI binding, with Show images given in Strict, produce no data or blob image, style, font face, font request or link.
- The test host fixture (`host-fixture/csp.ts`) now models a host that allows `data:` and `blob:` for images and fonts; its own policy and the document's must both be satisfied.

The built episode view carries no artwork or font of its own: the specs write a trusted data image, data font and object URLs into the served document or the mounted frame to stand in for a trusted template. CORS denial is exercised with a fulfilled response that names another origin (Playwright otherwise adds a permissive header). The font fixture is a hand-built two-glyph font. The React card's content boundary and its installed combined resource are covered in REACT3-TEXT and REACT3-PACKED.

### Reusable MCP connector (CORE1)

`packages/mcp` (`@saga-a2ui/mcp`) takes over MCP delivery from the application. At this slice it was a workspace package with no version, so the version policy had nothing to enroll. The Lit application consumes it through its package name and its three separate subpath exports. This is a preparation slice: the interfaces may change until CORE3, and owned callers migrate together.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/mcp/server` | `registerPublicOperation`, `registerProtectedOperation`, `operationViewFromHtml`, `viewUriForMajor`, `viewUriForHtml`, `OperationConfigurationError`, the request-budget seam (`createServerBudgets`, `RequestLifetime`, `LifetimeCause`, `StageFailure`), `attachRequestLifetime` (with `RequestLifetimeAttachmentError`) and the declaration types | MCP server and MCP Apps server helpers, Zod; no renderer, no view code |
| `@saga-a2ui/mcp/view` | `runToolResultView` (view lifetime: handlers installed before connect, early results held, host context applied before the first result, teardown before the connection ends, disposal, callback failures reported), `ViewStartFailure`, `hostLinksFromApp`, `conversationFromApp`, `startOwnSizing`, `readingProfile`, `deliveredResultFromToolResult` (maps a tool result onto the neutral `DeliveredResult` and interprets nothing), `DEFAULT_TOOL_RESULT_LIMITS` and `ToolResultRefused` (the admission budget for a delivered result or input) | types only (the host link contract and `DeliveredResult` are types from `@saga-a2ui/core/host-links` and `@saga-a2ui/core/delivered-result`); no server module, no Node built-in, no renderer |
| `@saga-a2ui/mcp/policy` | `ViewCsp`, `CLOSED_VIEW_CSP`, `DEFAULT_OPERATION_MS`, `DEFAULT_REQUEST_MS`, `startBoundedTimer` | nothing |

`packages/mcp/src/exports.test.ts` imports each subpath by name and bundles its module graph (dependencies included) to show a server consumer pulls in no renderer and a view consumer pulls in no server module; `e2e/view-bundle.spec.ts` repeats the check on the built views.

**What the application keeps.** The listener (`mcp/listener.ts`: hosting, Host-header protection, body bounds), authentication (`mcp/request-auth.ts`), request classification (`mcp/protected-request.ts`), domain authorization (which subscriptions belong to the verified account), backend calls and the renderer. The connector never reads a credential: for a protected operation the application supplies `identity(authInfo)`, which turns the transport's per-request verified context into its own immutable value.

**What the connector does** for each declared operation, in this order:

1. *Registers* the tool and its `ui://` view resource on the application's `McpServer`. Protected registration without an identity resolver, sign-in failure text, projection, view or output contract throws `OperationConfigurationError` naming the missing requirement, before anything is served. A non-finite bound is refused the same way.
2. *Validates input* with the declared Zod contract before the handler runs. Undeclared fields (for example an `accountId`) are dropped; the handler never sees them and a protected operation takes its identity only from the verified context.
3. *Resolves identity* (protected only). No acceptable identity gives the declared sign-in text and the handler does not run. A public operation resolves nothing and hands its handler no identity.
4. *Waits for the handler and its projection* as one bounded `handler` operation of the request's lifetime (see "Bounded requests and playback (STATE2)"): the operation limit (`boundMs`, else the route's or SDK instance's limit, else 3 s), what the request has left, and the caller's cancellation signal. A result that loses that race is ignored; a handler that throws or rejects gives the declared `unavailable` text with no message. A call whose request already ended, or that was cancelled before it began, never starts the handler.
5. *Projects explicitly*: `project(record)` builds the model-facing text and the structured data field by field; the connector validates the data against the strict output contract before serialization. A violation gives the declared `invalidOutput` text, not the validator's message.
   The connector also bounds the result's size and shape (`packages/mcp/src/server/output-budget.ts`), whatever the contract allows. One budget covers the whole result envelope: the JSON the transport writes for `content` and `structuredContent`, in UTF-8 bytes with string escapes counted (a NUL is six bytes, not one). The default is 1 MiB, 32 levels of nesting and 100,000 values. The `_meta` that links the declared view is outside the budget; it comes from the trusted declaration. The connector reads the projection's `text` and `data` once, and copies the data into plain accessor-free values while it measures them. The contract parses that copy; a second copy of the parsed data (a contract may transform what it accepts) is measured again and is exactly what the transport receives, so a getter, a changing `toJSON` or a later mutation of the application's own objects cannot change what was admitted. `Date` values are copied by time and written as ISO strings, as JSON does. The walk stops at the first limit crossed: a string longer than what is left, or an array or object with more members than the node limit allows, is refused before its contents are read or escaped (listing an object's own keys costs memory in proportion to that object, which the application already holds). A value that is cyclic, holds a `bigint` or a `toJSON` method (other than `Date`), or throws when read is refused too. An operation may declare `outputLimits: { maxBytes, maxDepth, maxNodes }` (positive integers, validated at registration) to tighten or raise a limit for its own legitimate results. Over the budget gives the declared `invalidOutput` text and no data. `operation-output.test.ts` pins this, with exact-boundary, escaping, getter, transform and wide-object cases and a control for a large result that still passes. The budget bounds one result; the memory a handler or projection uses to build it, and transport metering, belong to the application.

6. *Links the result to its view.* Every result the operation returns, success or fixed-text failure (absent, refused, unavailable, invalid output, sign-in required), carries `_meta.ui.resourceUri` set to the declared `view.uri`, so a host can mount the view from the result alone and not only from tool discovery. The value comes from the trusted declaration after the result is built; a tool argument, the handler's record or the projection cannot select another resource, and `content`, `structuredContent`, the resource's MIME type and its CSP are unchanged. A request the server rejects before the operation runs (for example an input that fails its contract) is answered by the MCP server itself, not by the operation, and is not stamped.

The handler returns `record`, `absent` (declared text) or `refused` (a fixed safe text for well-formed but unaccepted business input). Projections are the model-visible `content` text and the validated `structuredContent`. Play's app-only visibility and `_meta` payload stay in `playback/` until CORE2.

### Bounded requests and playback (STATE2)

Implements the server-budget amendment of [Request and view lifetimes](../blueprints/features/request_view_lifetimes.blueprint.md) (contract revision `c674060`). Reference-application limits and wording below are implementation choices within that contract.

**Configuration.** Two independent limits: an **operation limit** (3,000 ms, `DEFAULT_OPERATION_MS`) and a **request limit** (10,000 ms, `DEFAULT_REQUEST_MS`). Each field resolves as per-operation or per-route override, then SDK-instance setting, then the default, and an omitted field never changes the other. `createServerBudgets({ operationMs, requestMs })` is an SDK instance; `forRoute(...)` layers a route's overrides; the listener takes `budgets` (instance) and a `budgets` on each endpoint (route). `boundMs` on an operation declaration (and the listener's `readBoundMs` and `answerBoundMs`) is the per-operation override of the operation limit, not a second timer. Every supplied value must be a finite positive number; zero, negative, `NaN`, infinite and non-number values, including values a more specific setting would shadow, are refused when the SDK instance, route, listener or operation is configured, before a callback or port is opened. Settings are copied when created; instances share no timer or mutable default.

**One request lifetime** (`packages/mcp/src/server/lifetime.ts`, portable, no HTTP types). The Node listener starts it when it admits the request, before the first credential, header or body wait. The request deadline is monotonic and absolute. Authentication, body ingestion, the complete handler with its projection, an authorization lookup, a storage read and a media acquisition are each a bounded stage whose wait is the least of its own limit, every enclosing operation's remainder and the request's remainder. Progress, retries, callbacks and revisited stages never renew a deadline. A timer is not the only witness of a deadline: a result is checked against the absolute deadlines when work returns and when it settles, so work that blocked the thread past its limit is refused even though its continuation ran before the timer (JavaScript is not preempted; the result is dropped and nothing later starts). Every wait uses `startBoundedTimer`, which segments delays so an accepted finite limit above the platform timer maximum (2^31-1 ms) is honored instead of expiring at once. A handler's nested work goes through `request.within(stage, work)`, which shares the handler's aggregate budget and hands the work a signal. Racing is the guarantee and the signal asks for cooperation: an uncooperative verifier, lookup or storage read cannot hold the request open, its late result is dropped (an application's token verifier additionally runs under `boundVerifier`, whose cap counts calls until they settle: a verifier that ignores its signal and never settles keeps its slot, so enough of them refuse every credential with the unavailable-dependency answer until the process restarts), and the gate is checked before later stages (no server is built, no authorization snapshot taken, no capability issued, no storage read started and no grant deleted after it closes). Untrusted input cannot choose these settings: the route is chosen from the path.

| Before the response is committed | Answer |
| --- | --- |
| Verifier or admission wait expires | `500 server_error`, never `401` for a wait that merely expired. A late valid identity is dropped |
| Body never completes | `408 request_timeout`, then the incomplete request is closed |
| Tool handler, authorization or storage | the tool's fixed unavailable `isError` result |
| Media lookup or storage | `503 unavailable` with the existing safe headers |
| Caller disconnects | nothing is written |

Real credential refusals keep their `401`/`403` and challenge. An expired request may attempt one immediate safe answer and gets no extra delivery time; a committed response is never given a replacement status. Causes are typed and inspectable (`operation-timeout`, `request-timeout`, `cancelled`, `disconnected`, `auth-refused`, `dependency-failure`, each with a stage and whether an effect is possible); they may hold the original error, so the listener hands them only to the application's `observe` callback and never to a caller. After a timeout, a possibly completed write is reported as unknown and is never offered a retry.

**Bounding tool input structure.** The official `McpServer` (2.4.0) counts the array elements and object members of one `tools/call` `arguments` payload only when it is built with `maxToolInputElements`; without it nothing but the transport's byte limit stops a small body that is wide or deeply nested from being parsed and validated, and the tool's own schema runs afterwards. `DEFAULT_MAX_TOOL_INPUT_ELEMENTS` (256) is exported from `@saga-a2ui/mcp/server` and both stacks' `/server` entries, and every maintained server passes it as `new McpServer(info, { maxToolInputElements: DEFAULT_MAX_TOOL_INPUT_ELEMENTS })`: the host application's servers, the templates, the examples and the packed qualification consumers. The listeners and `createMcpFetchApp` receive a server from the application's callback and cannot set the option on it, so the option belongs where the server is built. A larger finite number is the application's decision when its tools really take larger structured input. `packages/mcp/src/server/tool-input-limit.test.ts` calls a real server over Streamable HTTP: a legitimate call and the largest payload that fits succeed, one element more is refused before the tool runs, and the same payload succeeds against a server built without the option. `scripts/mcp-server-input-limit.test.ts` reads every `McpServer` construction in the maintained servers and guides and fails, naming the line, when one omits it. The tutorial under `docs/tic-tac-toe/` quotes an external application at a pinned revision and installs published packages, so it moves with that application and is excluded from the scan.

**Ending the lifetime with a per-request server.** A stateless `createMcpHandler` factory builds one `McpServer` per request, and the request's lifetime has to end when that server does; otherwise its request timer runs on. A server ends in two ways: its transport closes (the server's `onclose` fires), or the handler closes it before any transport was connected, for example when it answers `subscriptions/listen` or rejects a request (no `onclose` fires). `attachRequestLifetime(server, lifetime)` from `@saga-a2ui/mcp/server` covers both, so an application does not subclass `McpServer` to call `lifetime.finish()`:

    const server = new McpServer(
      { name: 'status', version: '1.0.0' },
      { maxToolInputElements: DEFAULT_MAX_TOOL_INPUT_ELEMENTS },
    );
    attachRequestLifetime(server, lifetime);   // before the factory returns it
    registerPublicOperation(server, operation, { lifetime });
    return server;

`lifetime.finish()` is called exactly once per server, on transport close, on `close()` with or without a transport, on a repeated `close()`, and when the upstream `close()` throws (the failure still reaches the caller). A close callback already set on `server.server.onclose` keeps running first; attach after installing your own. The upstream handler chains to the attached callback in the same way. Attaching the same lifetime twice changes nothing; a different lifetime throws `RequestLifetimeAttachmentError` and leaves both untouched, because it could never be finished. This binds a lifetime to closure only: the application still starts the lifetime at admission and passes it to the operations. `packages/mcp/src/server/request-closure.test.ts` covers each case, and runs a stateless `createMcpHandler` factory under fake timers to show the request timer released with no transport ever connected. No template or example subclasses `McpServer`, so none needed migrating.

**Finite delivery.** JSON and media responses are bounded through the transport's `finish`, not through the result being ready. A reader that stops reading is closed at the original request deadline; bytes already buffered are not recalled. Destroying a response can itself emit `finish` (with `writableFinished` and `destroyed` both true) before `close`, so only a `finish` on a response nobody destroyed counts as delivery; the listener's `observe` reports `finished: false` for a response the deadline closed. Finish, deadline and disconnect settle once. Media grants keep their own expiry, a spent proof stays spent, an acquisition is a new request with a new deadline, and a denial that arrives after the request ended does not delete the grant (the next acquisition asks the lookup again).

**Streaming.** The request deadline bounds setup up to the established `text/event-stream` response. An established stream may live as long as the transport keeps accepting its bytes: `answer.streaming.idleMs` (default `DEFAULT_STREAM_IDLE_MS`, 30,000 ms, validated before streaming is enabled) closes a stream that goes idle or backs up. Only bytes the transport actually accepts reset it; progress the application reported but never delivered does not. Each later finite operation keeps its operation limit.

**Playback controller.** Play is one server action built with `Action.server('play', transport)` and bound directly to the rendered control (mapping A, CORE2): one work interval spans every pending stage. The synchronous prefix (`input`, `atActivation`) selects the item, takes a lease from the application's player owner and unlocks audio inside the click. Two prerequisites run in order before the handler, the host-capability check and recipient-key creation, so a failure of either is `unsupported` and a stall in either is plain `unavailable`, with the protected request never sent. The handler makes the host call, validates the grant, signs the proof, acquires the body, decodes and starts the player, and on a confirmed start transfers the lease to the owner with nothing awaited between. The shared runtime's work deadline (30,000 ms by default; override through the action host's `limits`) therefore bounds key creation through the start of audio. Progress never extends it, a successful start ends it without stopping the audio, and a continuation delivered after it passed but before its timer is dropped. The success hook that presents `playing` is under the hook budget (5,000 ms). `App.callServerTool` gets the invocation's signal, a timeout no wider than what remains or the 60,000 ms transport safeguard, `resetTimeoutOnProgress: false`, and the recipient public key as request `_meta` through `call(name, args, { meta })`, never in the arguments. A rejected, timed-out or aborted host call is `unavailable` with `requestOutcome: 'unknown'` (never "sign in" or "denied"): a capability may have been issued, so no retry is invited and the status asks the user to open the episode again, with focus moved to the status. A host call that resolves is classified before anything decides expiry or recovery: only the server's two fixed early refusals (denied, unsupported, both made before a capability exists) and a valid grant for the selected episode and pinned sign-in establish a known result. Any other answer is unknown, with the same unconfirmed presentation: a generic `isError` result (the server issues the capability before it labels and validates the response, so an error can follow issuance) and a success with missing, malformed or mismatched private grant metadata. This does not depend on the error's wording or the host, and it holds when the answer arrives after the deadline but before its timer. A valid grant under another sign-in label still ends the view for good. An expiry before anything was sent, or a proof, media, decode or start failure or expiry after a valid matching grant, is plain `unavailable` or the matching state with its permitted manual recovery. No attempt retries itself. Pause and Resume are local actions that call the player inside the click and present what it reports for the lease it still holds. Pending is presented by the invocation's own prefix and replaced by exactly one of its outcome hooks, so it is shown while the Play binding runs and the binding is idle again once audio plays; Play being unavailable while audio plays is application state, not binding busy state. A changed selection is a changed subject (the binding cancels an undecided Play at its next checkpoint), and every opener, valid or not, replaces the subject's identity, so a malformed opener that keeps the selected item still retires an undecided Play and its late grant fetches nothing, while the unchanged selection keeps its manual Play. The protected media request is preceded by the invocation's own `current()` checkpoint (which reads the work deadline's clock), so an overdue proof or a retired Play dispatches nothing. A Play whose control was retired or replaced while it was pending is not left pending: the view shows `ready` when nothing was sent, plain `unavailable` after a known grant, and `unavailable` with `requestOutcome: 'unknown'` once the request was sent (no blind retry is invited; a replacement control's deliberate press starts a new Play). A lost label, a host teardown and a disposal dispose the bindings and stop the audio through the owner. Late cleanup is scoped to its own lease: an old acquisition's release or start cannot stop a newer player. The former controller-local attempt timer, generation counter and abort controller are gone, and `attemptLimitMs`, `PLAYBACK_ATTEMPT_LIMIT_MS` and `PlaybackConfigurationError` no longer exist.

Tests: `packages/mcp/src/server/lifetime.test.ts` and `lifetime-deadline.test.ts` (defaults, independent overrides, invalid and shadowed values, isolation, absolute deadlines, deadlines noticed at settlement, nested defaults, large finite limits, aggregate budgets, retirement, pre-aborted calls), `packages/mcp/src/server/operation.test.ts` (the handler under instance, operation and request limits), `src/mcp/request-budgets.test.ts` (listener over real sockets: verifier and body stalls, mid-body disconnect, unaffected concurrent requests, handler expiry, streaming setup versus idle), `src/playback/playback-budgets.test.ts` (lookup and storage stalls, late denial, no capability after the gate closes, slow-reader delivery), `src/playback/playback-view.test.ts` (every client stage under the action work deadline, Play as one action on the rendered control) and `src/playback/player-owner.test.ts` (lease-scoped release and hand-over) and `e2e/playback-view.spec.ts` (announcements, recovery, focus, 320 px, 200% text and a long title).

#### Identity of a served view (`operationViewFromHtml`, `viewUriForMajor`)

The address of a view names its compatibility line: `ui://views/answer.v1.html` for `answer.html` on major 1. The application states the major version of the contract between the application's tools and its view (what the view reads from a result and what its actions send and expect back), and `operationViewFromHtml` from `@saga-a2ui/mcp/server` builds the whole `OperationView` from the final HTML:

    const html = fs.readFileSync('dist/answer.html', 'utf8');   // the final, built document, release stamp included
    const view = operationViewFromHtml({ html, filename: 'answer.html', major: 1, title: 'Answer' });
    registerPublicOperation(server, { ...declaration, view });

- Every compatible rebuild keeps the address: a fix, an addition, a restyle, an SDK upgrade, a new build stamp. A host that kept a tool descriptor from before a deploy therefore still reads a document that is served, and receives the current one. Raise `major` only for an incompatible change; every tool that names the view then moves to the new address in the same deploy. A change to what the view reads, what an action means, or which host capabilities or content-security origins the view needs can be incompatible even when the JSON shape is not.
- Every build on one major must handle current results and actions: during a rolling deploy two builds may serve one address, and a host may keep showing a document it cached under it.
- A build stamp the application writes into the HTML stays in the served document, where it identifies the build that rendered. It has no effect on the address.
- `major` must be a safe integer of at least 1 (version 1 is the first line); anything else throws `TypeError`, as does a filename that is not a relative `.html` file. `csp` starts from `CLOSED_VIEW_CSP` and takes only the host permission arrays the caller names. Its `csp` is structural, so a content policy supplies it through `resourcePermissionsOf(policy)` (`@saga-a2ui/components/faithful-card`) without either package importing the other.
- `major` is required; a missing one throws `TypeError`.
- `viewUriForMajor(filename, major)` returns the same address for an application that builds its `OperationView` by hand.
- Two different documents on one server need two filenames: registering a second view at an address already registered on that server throws at startup.
- `viewUriForHtml(html, filename)` remains a content digest, `ui://views/answer.<32 hex digits>.html` from the SHA-256 of the exact bytes (a string is hashed as UTF-8; one with an unpaired surrogate throws `RangeError`). Use it to check which build a deployment serves, not to name a view whose document carries a per-release stamp.
- A content policy travels in the same document: `embedContentPolicy(html, policy)` writes the policy-derived `Content-Security-Policy` meta and a configuration script (every `<` written as `\u003c`, so no value can close the element), and `contentPolicyFromEmbedded(text)` rebuilds and re-validates the policy from that script's text (`null` is the default Standard policy; anything invalid fails with the policy's own failure kinds). Both are string operations, so a server calls them without a DOM. The insertion is immediately after `<head …>`, or after a `<meta charset>` only when that is head's first element. `embedContentPolicy` throws, and nothing is served, when the document has no `<head>`, has a `<script` or a comment before the insertion point, declares its charset anywhere but as head's first element, or when the policy's CSP contains a `"`. Reading the element from a document is the renderer side's job (`content-view.ts` in the consumers).
- It is a pure function: no registry, global state or cache, and no action API. It identifies the document's bytes; the CSP declared beside it is separate. A host that already cached a URI keeps that copy, so serve a changed document under its new URI.
- The synthetic `examples/answer-consumer` shows both pieces from the installed packages alone (`server/answer-server.ts`). It serves `mcp.html`, a small embedded entry (`src/mcp-main.ts`) that the Lit stack starts from one card application definition (`startFaithfulCardApp`) and that shows each delivered result in the same FaithfulCard the standalone `index.html` shows through the card surface (`openFaithfulCardSurface`, in `src/answer-app.ts`), with no form and no answer function of its own. `scripts/answer-consumer.test.ts` builds that page, serves it through the packed `@saga-a2ui/mcp`, and checks over JSON and server-sent events that results, tool discovery and the resource read agree, that hostile question text does not change the link, and that a changed page gets a different URI. `apps/lit-host/e2e/answer-consumer-mcp.spec.ts` then mounts the page the consumer's own server actually serves in the sandboxed host fixture and delivers real tool results over the bridge: initialization, the first result, replacement, failure and recovery, host teardown with a late delivery, remount, and a link that leaves only as a request to the host. It counts the server's answers to show the page makes no provider call of its own.

Browse (`mcp/subscriptions-server.ts`) is the protected consumer: the existing `list_subscriptions` behavior, including the declared `status` filter, the opaque view-session label, concurrent principals, forged-account rejection, and the empty/denied/failed outcomes, passes its unchanged `subscriptions.test.ts` and `e2e/subscriptions-view.spec.ts`. The episode tool (`mcp/server.ts`) is the first public consumer.

#### Public answer operation

`POST /answer/mcp` (`startEpisodeListener({ answer })`, off unless configured) is a synthetic, explicitly public question-and-answer tool, `answer_question`, with its own built view (`dist/answer-view/answer.html`). No credential is read, none is fabricated, and a presented `Authorization` header is not treated as an identity. `responseMode` is `json` (one body when the answer is ready) or `event-stream` (progress notifications, then the answer, as server-sent events).

- *Binding.* The result repeats the question exactly as asked (`{ question, answer }`, strict, bounded to 500 and 2000 characters). The view shows that pair. If the host also announced the question (`toolinput`), a result is shown only when its question is identical (no trimming or case folding); a result for another question, such as a late copy of an earlier answer, is ignored and the view keeps waiting.
- *Early, repeated, late.* A result before any input is shown with its own question; an input for the question already answered keeps the answer; the same answer again is not shown again; a different answer to the same question replaces it. After host teardown or dispose nothing is delivered. An error, a malformed or undeclared-field result, or an unreadable input clears the answer and shows a problem; only the server's three known safe texts are shown verbatim.
- *One handler call, progress, delay.* The handler runs once per call. `request.reportProgress` sends `notifications/progress` only to a caller that supplied a progress token and only while the operation is live; it is a quiet no-op after the operation finished, was cancelled or timed out. In `json` mode progress is not delivered but the delayed answer completes the one request.
- *Bounds and cancellation.* The wait is one operation of the request (`answerBoundMs` overrides the operation limit for this answer; the default is 3 s) and a dropped HTTP request aborts the handler's signal; a late answer has nowhere to go. STATE2 adds the whole-request deadline and finite-delivery bound above; CORE3 records the full matrix (see "The server request contract and its failure paths (CORE3)" below). The application cleans up work it cannot interrupt.
- *No logging of questions.* Neither the connector nor the listener logs the question or answer.

Run it: `npm run build && npm run serve:mcp` (the demo answers two fixed questions with a short delay and progress, streaming). Tests: `packages/mcp/src/server/operation.test.ts` (the connector over real Streamable HTTP and a real MCP client: projection, refusal, absent, failure, bound, disconnect, progress in both modes, concurrent principals, forged account, registration failures), `packages/mcp/src/view/view.test.ts` (bridge lifetime), `packages/mcp/src/exports.test.ts`, `src/mcp/answer.test.ts` (the real listener in both modes), `src/mcp/answer-view.test.ts` (delivery rules over a real `App`/`AppBridge`), and `e2e/answer-view.spec.ts` (real listener, real client, the built view in the sandboxed host fixture).

At this slice the packages are installed through the npm workspace link; PACK1 and PACK2 cover packed and public installation.

### The server request contract and its failure paths (CORE3)

CORE3 qualifies the request pipeline that CORE1 extracted and STATE2 bounded, through the installed server export, the real listener and the built answer view, and records what an application can rely on. The connector owns server request execution and the callbacks below. It does not own authentication, hosting, domain authorization or the client-side action runtime: an action's `before`, hooks and busy policy are not a request deadline, and a client prerequisite never authorizes a protected handler.

**Callback contract** (`@saga-a2ui/mcp/server`). An operation's `handle(input[, identity], request)` receives an `OperationRequest`: `signal` (aborts on caller disconnection, a cancellation that reaches the request, the handler's budget, the request deadline, or once the operation has finished), `within(stage, work, { limitMs })` for nested work inside the same aggregate budget (rejects with `StageFailure` carrying the typed cause), and `reportProgress(update)`, a quiet no-op after the operation ended. `handle` returns `record`, `absent` or `refused` (with a non-empty text); anything else it returns, including an unknown kind or a refusal without text, is answered with the declared `invalidOutput` text before the projection runs, and anything else it does is a failure. `project(record[, identity])` synchronously returns `{ text, data }`; a returned promise is refused with the declared `invalidOutput` text without being awaited because projection is a synchronous callback contract (any supported awaited work would still spend the same enclosing budget) and its rejection is consumed so it cannot surface unhandled. The connector runs the complete handler and projection as one `handler` operation of the request's lifetime, so identity, authorization, handler and projection spend one budget; progress and a delayed JSON or SSE completion do not renew it. Decisions: the declared Zod input and output contracts own every size, item and string bound (the connector adds none and never truncates), `Projection.text` is checked for being a string and nothing else (bound it in `project`), and the identity resolver is synchronous: a promise, or a result whose `then` cannot be inspected without throwing, is answered with the declared unavailable text and kept as the typed `authentication` cause.

**Failure map.** Each observation is separate: the HTTP status and challenge, the JSON-RPC error, and the tool result's `isError`.

| Trigger | HTTP | JSON-RPC | `isError` | Internal cause (for `observe`, never sent) |
| --- | --- | --- | --- | --- |
| No, malformed, unknown or expired credential | 401 + `WWW-Authenticate` | none | n/a | `auth-refused` 401 |
| Service-only credential or missing scope | 403 `insufficient_scope` + challenge | none | n/a | `auth-refused` 403 |
| Verifier throws, or its wait expires | 500 `server_error`, no challenge | none | n/a | `dependency-failure` / `operation-timeout`, stage `authentication` |
| Body over the limit, never completes, wrong `Accept` | 413, 408 (then closed), 406 | none | n/a | `request-timeout` for the 408 |
| Body is not JSON | 400 | `-32700`, id `null` | n/a | none |
| Malformed MCP call | 400 | `-32600` | n/a | none |
| Unknown tool | 200 | `-32602` | n/a | none |
| Business input refused, record absent | 200 | none | `true`, declared text | none |
| Handler throws, rejects, stalls or is cancelled; projection throws; identity resolver throws or returns a promise | 200 | none | `true`, declared `unavailable` text | `dependency-failure`, `operation-timeout`, `request-timeout` or `cancelled` with the stage |
| Projection is not `{ text: string, data }`, `data` breaks the output contract, or is oversized | 200 | none | `true`, declared `invalidOutput` text, no `structuredContent` | none |
| Backend answers 401, 429 or 503 | 200 | none | `true`, declared `unavailable` text; no backend status, `Retry-After` or challenge | `dependency-failure` with the original error |
| Request deadline passes before anything is committed | the owned stage's answer above, once | | | `request-timeout` |
| Caller disconnects or cancels | nothing is written | | | `disconnected` or `cancelled` |

A cause says whether an effect is possible: a stage that never started (a request already cancelled when its callback was reached) is `effect: 'none'`; anything that began is `'unknown'`. Success output schemas stay strict and a failure never weakens them.

**Cancellation, disconnection and resume are different facts.**

- *The same request's disconnection* aborts the handler's `signal` and drops everything after it; the transport receives no write. Verified by observing every `write`, `end` and `writeHead` made on a response that was already destroyed or ended, in both response modes and after deadline expiry; the transport's own idempotent bare `end()` on a closed response carries nothing and is not counted.
- *A `notifications/cancelled` in the POST that carried the call* is processed before the SDK reaches the tool callback, and **the pinned SDK (server 2.4.0) then invokes the callback with an already-aborted signal**. The connector does not start the handler (or resolve an identity) and no JSON-RPC response is sent for the cancelled call, as the protocol prescribes; the exchange then ends at the request deadline (JSON) or the stream idle policy (SSE). Since the STATE2 lifetime, `execute` runs the handler only inside `lifetime.run`, which refuses an already-aborted signal first, so entry is prevented rather than only its result discarded.
- *A separately posted `notifications/cancelled`* names no running request on a stateless endpoint (each POST has its own server and transport, and the connector keeps no process-wide request or action registry): it is acknowledged `202` and the running handler's signal stays unaborted. Cancellation in this design therefore reaches a handler only by closing its own HTTP request.
- *Resume and replay.* Endpoints are stateless: `GET` (with `Last-Event-ID`) and `DELETE` are refused `405`, the abandoned handler is not run again, and a client's retry is a new request with its own handler run and budget.

**Cleanup responsibilities.** The connector stops waiting, ends the signal, drops late results and progress and refuses to start later stages. The application stops work it can on `request.signal` and `within`'s signal, owns idempotency and compensation for work it cannot interrupt (a timed-out write may have completed; nothing is retried or rolled back for it), keeps per-request state in the request, and, as the listener, starts a lifetime per request, reports disconnects and `finish` to it, and closes the transport and server when the response closes.

**Evidence.** Hosted by Node 26 `http` with the MCP SDK's Streamable HTTP server transport and client, in JSON and server-sent events, against exact tarballs of the workspace package; the packed test checks contents and declared dependencies. The installed-export test hosts the packed server export on the test host; the application listener (`apps/lit-host`) is exercised from the workspace.

Tests: `packages/mcp/src/server/request-lifecycle.test.ts` (cancellation before start, same-request versus separate cancellation, every callback that stalls, throws or misreports, writes after closure, over a real transport and client in both modes), `apps/lit-host/src/mcp/request-pipeline.test.ts` (real listener: which layer reports each failure including backend 401/429/503 and verifier faults, canary disclosure across results, discovery, resources, errors, headers, logs and diagnostics, disconnect/resume/deadline, concurrent principals and progress isolation, claims that authorize nothing), `scripts/request-consumer.test.ts` (the same contract from the packed `@saga-a2ui/mcp`) and `apps/lit-host/e2e/request-pipeline-view.spec.ts` (stalled, oversized and failing answers reach the built view only as the declared safe text, and a late answer changes nothing).

### Core and Lit packages (VIEW1)

`packages/core` (`@saga-a2ui/core`) and `packages/lit` (`@saga-a2ui/lit`) take renderer-independent A2UI processing and Lit binding out of the application. At this slice both were workspace packages with no version, like `@saga-a2ui/mcp`. This is a preparation slice: the interfaces may change until the combined CORE3/VIEW2 qualification, and owned callers migrate together. The application keeps its catalogs, components, content policy and its existing Play operation.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/core/protocols/a2ui/v0_9` | `a2uiV0_9Decoder` (the `MessageDecoder` strategy; `createA2uiV0_9Decoder` for non-default input limits), validated message cases with `A2uiMessageVisitor`, `createMessageSession` and the ingest result types, and `defineSurface` with `SurfaceLayout` (surface authoring, below) | upstream `@a2ui/web_core` and Zod 3; no DOM, MCP or renderer (its `tsconfig` loads neither the DOM nor Node typings) |
| `@saga-a2ui/core/protocols/a2ui/zod3` | `z`, the Zod 3 copy upstream A2UI builds on, for authoring catalog component schemas | `zod3` |
| `@saga-a2ui/lit` | `createA2uiAppElement` (mounts one `SurfaceLayout` from a session, owns its lifecycle and exposes `updateData`) and `defineElements` (explicit custom-element setup) | `lit`, upstream `@a2ui/lit`, the core types; no MCP, no Markdown parser, no optional components |
| `@saga-a2ui/core/actions`, `@saga-a2ui/lit/actions` | Added by ACT1: see "Direct action attachment (ACT1)" | as listed there |

**What the application keeps.** Its catalog (`saga-panel/` and `lit/integration.ts` for browse, descriptions and Play; `answer-card/` and `lit/answer-card.ts` for answers), the component implementations, the trusted content policy, host links, the Play operation, and the composition roots (`main.ts`, `view-main.ts`, `answer-main.ts`) that choose the catalog and layout. Raw wire parsing exists only in core: renderer code receives validated messages.

**Surface authoring (view composition, layer A).** No consumer writes A2UI wire messages. `defineSurface({surfaceId, catalogId, data, root, components?, initial})` in the v0.9 protocol module (the one place the version literal and message names live) returns a `SurfaceLayout<TData>`: `opening` (`createSurface`, `updateComponents` and the first `updateDataModel`, as decoder input) and `update(data)`, which returns the one `updateDataModel` that replaces the whole data model, or `{ ok: false, failure }`. `data` is a Zod 3 object schema (`z` from `@saga-a2ui/core/protocols/a2ui/zod3`) and `TData` is inferred from it. The schema is applied strictly and the result must equal the input, so `update` refuses an unknown or missing field at any depth, and a default, coercion or transform that would change a value, instead of dropping, filling or converting it. The scope is one root component over a flat data model plus an explicit list of other components passed through unchanged; `root.bind` maps a root property to a data field as a path binding and `root.props` supplies plain values. It is not a binding engine and it does not decide catalog support: every generated message still passes through `a2uiV0_9Decoder` and the upstream processor, so a root the catalog lacks fails when the surface is opened. `defineSurface` throws at definition time, naming the field, for an `initial` that fails the schema, a binding to an undefined field, a property both bound and valued, a property the layout owns (`id`, `component`), or repeated component ids. A one-field write in a nested data scope (for example a row's status line) is not a whole-model replacement; an application that needs one writes that protocol message itself and relays it (`examples/pack1-consumer` shows this for the Lit view).

**Input and retained-state limits.** The upstream A2UI schemas are built on Zod 3, which accepts arrays and nesting of any size, so SAGA bounds untrusted input itself, before Zod parses it and before anything is copied. `a2uiV0_9Decoder` reads the whole input once, iteratively (depth costs no stack, an array's length is checked before its items are read, and an object's keys are visited one at a time, so no list of them is built and a wide object is abandoned at the first limit), into a snapshot of plain data; everything after that, including Zod and the copy, works on the snapshot, so a getter or proxy is read once and the value measured is the value used. A `Map`, `Set`, `Date` or class instance is refused as not plain data, because its content cannot be measured by reading properties. Primitives are an explicit allowlist (strings, finite numbers, booleans and `null`): a `bigint`, a symbol, a function, `undefined`, `NaN` or an infinite number is refused the same way, because a `bigint` of millions of bits would otherwise be charged as one value and no bytes. It refuses input as `malformed`, naming the limit, when it has more than 1000 messages, 4 MiB of string, property-name and binary data, 200000 values (a shared value or a cycle counts each time it is reached), 64 levels of nesting, or an array of more than 10000 items (the upstream data model's own index ceiling). The count of messages is part of that one read: the length of the root list, or of the envelope's `messages`, is the length admission reads before its items, so nothing is read before or beside it. An `updateDataModel` path of more than 64 segments is refused too, because each segment creates a level of retained state. `createA2uiV0_9Decoder({ maxMessages, maxBytes, maxNodes, maxDepth, maxArrayItems })` chooses other positive-integer limits for an application whose legitimate payloads are larger. The session adds a second bound on what it keeps: `createMessageSession` accepts `retainedLimits: { maxNodes, maxBytes }` (defaults 500000 values and 16 MiB) and refuses with `kind: 'rejected'`, before the message is copied into the upstream processor, a batch that would take surface data, component properties, themes and metadata past them. It counts cheaply (an upper bound of what each validated batch can add, reading no state) and measures the real state only when that count would cross a limit. It then charges the batch what it would really add to that state, taking its messages in order against the state the earlier ones leave: a value written over an existing one, or deleted, is credited once, and a data path is charged only for the containers it does not already have (one value and the name for an object key, the growth in length for an array index). The second write to a surface's data in a batch is read against a copy of that data on which the earlier writes were set with the upstream data model, so a batch is charged what the same messages sent one by one would be: a path written twice in one batch costs what it costs once, and so does one that is written, deleted and written again, while a path of new containers is refused. The answer is the most the state can hold above where it is now at any point of the batch, since a later message may fail upstream and the messages before it stay applied. A batch that only deletes surfaces is always accepted, and a deleted surface is not credited for what it held. A custom `MessageDecoder` keeps the `DecodeResult` shape it always had, and its output is bounded by the retained limits too: the session reads each message it supplies exactly once, through the same bounded plain-data admission (at most twice the retained limits for one message), and then measures, replays and applies only that snapshot, so what is measured is what is kept. A getter or proxy is read once; an array contributes only its items, so an extra own property on an array is not kept; and a value that is not plain data (a `Map`, `Set`, `Date` or class instance, or a primitive outside the allowlist above such as a `bigint`, anywhere in a message) has no measurable content, so the message that holds it, like a getter that throws or a message over the ceiling, is refused as `rejected` before anything is applied. These are availability limits on the supported ingestion paths. The admission walk reads one key at a time (`for...in`) and builds no list of its own. The Zod 3 line stays pinned to upstream; revisit the limits when A2UI supports a fixed validator line or a compatible fixed Zod 3 release appears.

**Data updates.** The element's `updateData(data)` validates against the layout and applies the replacement in place. The mounted controls, their action bindings and focus survive because nothing remounts; a rejected update (invalid data, an element that is not connected, a disposed session) returns `{ ok: false, failure }` and changes nothing. The method is `updateData` rather than `update` because Lit's `ReactiveElement.update` is the render lifecycle method of every element built on it. The element has no selection concept. `ingest(input)` is no longer part of the consumer contract: it remains a protected member of the element for a subclass that relays protocol input it did not author (the lit-host `window.sagaSend` hook, the notes row status line).

**Rejection.** `ingest(input)` never throws for bad input. When the current input is rejected (unsupported version, malformed envelope, or an upstream refusal of a component or update), the element clears the surface and shows a safe fallback (`role="alert"`, inert text). Messages of a rejected batch that were applied before the refusal stay applied in the session. The next input the session accepts removes the fallback and shows the surface again. An application that wants a fresh surface sends `deleteSurface` and creates it again, as the episode view does.

**Registration.** `defineElements` defines tags that are free, leaves a tag bound to the very same constructor alone (so repeating setup, or two catalogs sharing a component, is harmless), and fails with `ElementConflictError` for a different constructor on an existing tag. The first definition is kept, and a failing call defines nothing. Nothing registers at import time.

**Lifecycle.** Connecting creates a session, subscribes to the surface and opens the layout. Disconnecting unsubscribes and disposes the session; a late `updateData` or `ingest` on a retired element is refused with an explicit failure rather than a throw, and a reconnected element opens the layout afresh on a new session.

**Answer view.** `answer-main.ts` now renders the public answer through these packages with its own `AnswerCard` catalog: the view still decides which question and answer to show (`mcp/answer-view.ts`, unchanged), and each state is delivered through `updateData` as one replacement of the whole card, so a previous question, answer or problem cannot remain beside a new state. The answer view bundle contains neither the panel catalog nor the Markdown policy.

Tests: `packages/core/src/protocols/a2ui/v0_9/protocol.test.ts` (decoding, message cases, field preservation, partial updates, rejections, session lifetime, no DOM), `packages/core/src/exports.test.ts` (supported names; the bundled graph holds no renderer, MCP or DOM runtime), `packages/core/src/protocols/a2ui/v0_9/surface-layout.test.ts` and `packages/components/src/faithful-card/surface-layout.test.ts` (opening messages for the starter layout and a FaithfulCard root accepted by the decoder and the upstream processor without a DOM; strict whole-model updates; definition-time failures), `packages/lit/src/a2ui/app-element.test.ts` (identity-preserving `updateData`, rejected updates, disposal and fallback), `packages/lit/src/element-registration.test.ts` (the tag rule), `e2e/fixture.spec.ts` and `e2e/lifecycle.spec.ts` (rendering, rejection clears and recovers, partial application, mount and unmount), `e2e/catalog-isolation.spec.ts` (the panel and answer catalogs in one page and one registry: independent data, rejections and disposal; conflicting tag fails and keeps the first), `e2e/answer-view.spec.ts` (early, repeated and late delivery, binding, markup, teardown through the built view), `e2e/own-catalog-consumer/packed-consumer.test.ts` (an application with its own catalog built from the packed core and Lit tarballs, without optional components, FaithfulCard, a Markdown parser or server code), and `e2e/view-bundle.spec.ts` (built artifacts).

The packed-consumer test packs a copy that carries a throwaway version (`npm pack` refuses an unversioned package) and checks the package contents and declared dependencies. At this slice Play ran through the application's own operation. *Current reading (ACT7): CORE2 has since moved Play onto the reusable action contract (see "Direct action attachment (ACT1)" and "The action contract across the current codebase (ACT7)"); the Lynx delivery chain is retired.*

### Qualifying the application through the installed packages (VIEW2)

The Lit application's browser pages are also built the way an application outside this repository receives SAGA, and the existing browser specs run against that build. `npm run build:installed-lit-host` (part of `npm run build`) packs `core`, `lit`, `components`, `mcp`, `react` and the two card stacks (`lit-mcp-stack`, `react-mcp-stack`) with `npm pack`, unpacks the tarballs into a clean directory outside the repository as installed dependencies, copies the application's page sources there and builds the application page, the episode, subscriptions, answer and player views, the test host fixture, the catalog-isolation page, the synthetic action consumer and the two card application stack probes (`vite.card-app-stack.config.ts`, built once per `STACK`) with the application's own Vite configurations. The result is `apps/lit-host/dist-installed` (ignored) with an `identity.json` naming the source commit (and whether tracked files were dirty), the Node and npm versions, each packed tarball's SHA-256, each built file's SHA-256 and, per page, every installed SDK module it contains. The build fails if any module comes from a workspace package or application file instead of an installed copy. The packed copies are a local qualification artifact.

    npm run build                                   # builds dist and dist-installed
    npm run test:browser:installed -w @saga-a2ui/lit-host-app   # the specs below, served from dist-installed

`SAGA_BUILT_DIR=dist-installed` selects the installed build for the specs and for the preview server (`e2e/built-artifacts.ts`, `playwright.config.ts`); the specs' assertions are unchanged (they only read the built page from that directory). `npm run test:browser` runs every spec on `dist` and then the installed set. That set is the Lit adapter lifecycle (`app-element-lifecycle`: session and listener release, retired delivery, control movement, discovery failure, rejection while work is pending), the local, asynchronous, reusable-prerequisite and Archive server action cases (`action-binding`, `async-action-binding`, `resource-action-binding`, `server-action-binding`), the application and catalog-isolation pages (`fixture`, `lifecycle`, `catalog-isolation`), the read, content and protected views (`mcp-view`, `answer-view`, `subscriptions-view`, `playback-view`: early, repeated, late and reversed delivery, invalid-result clearing with valid recovery, sign-in label loss, refused and unknown outcomes, teardown) the two card application stacks (`card-app-stack`: the whole-result matrix of the definition-owned reader, including rejection, clearing, a reader that throws after image consent, and recovery by the next valid result, runs unchanged against the probes built from the packed `lit-mcp-stack` and `react-mcp-stack`) and the bundle guard (`view-bundle`: no server module or credential in a built artifact). `scripts/installed-lit-host.test.ts` (headless) checks the build itself: where every module came from, that the action consumer needs only `core` and `lit`, that the pages without a FaithfulCard carry neither the optional components, a Markdown parser nor React, that no page contains a delivery server module, that each card stack probe loads its own stack, renderer package and neutral result contract from installed copies only (the React probe no Lit package, the Lit probe no React package), and that the recorded digests match the bytes written. The React card probe is a development build whose JSX source information names its temporary build directory, so its bytes differ between builds in different directories; the symlinked-root check compares it with that directory name removed. The application-owned catalogs, policies and authentication stay in the application; the specs' MCP listener, development verifier and backend are application code and run from the workspace (see Scope below).

**Scope.** The browser pages are built from the packed copies; the MCP listener, authentication, media service and backends the specs start in the Playwright process are the application's server code, which imports the workspace `@saga-a2ui/mcp` and `@saga-a2ui/core` server exports. The installed set reuses the specs unchanged, and the package boundary satisfied each case without a source repair. The action-consumer and view pages are synthetic local fixtures. The playback controller and its migration (#15) are consumed as they are.

### The passive FaithfulCard and an installed second consumer (CARD-PREP)

At this slice `@saga-a2ui/components` was an unversioned workspace package like the other SDK packages. It holds one optional export, `@saga-a2ui/components/faithful-card`, and the Lit element that shows it is the optional `@saga-a2ui/lit/faithful-card` export. This is the **passive preparation slice** of CARD1 ([#19](https://github.com/MachineWisdomAI/saga-a2ui/issues/19), delivered under [#99](https://github.com/MachineWisdomAI/saga-a2ui/issues/99)): it extracts the proven description behavior (POL1, POL2) so a second application can install and reuse it.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/components/faithful-card` | The versioned content contract and its reader (`createFaithfulCardReader`, `describeContentFailure`), Markdown interpretation into restricted nodes, the trusted content policy (`createContentPolicy`, `establishImageEnforcement`), image consent scopes (`createImageConsentScope`) and the A2UI catalog contract (`FaithfulCardApi`) | `markdown-it`, `zod`, upstream `@a2ui/web_core` and `@saga-a2ui/core` for the catalog schema; no MCP, no renderer, no DOM or server API (checked on the bundled graph) |
| `@saga-a2ui/lit/faithful-card` | `FaithfulCardContentElement` (`<saga-faithful-card-content>`), the catalog entry `faithfulCardEntry` (`<saga-faithful-card>`), `registerFaithfulCard`, and the view seam (`ContentView`, `provideContentView`; the document's own policy values are read by `documentContentSecurityPolicies` of `@saga-a2ui/lit-mcp-stack/faithful-card`; `HostLinks`, `LinkOpenOutcome`, `NO_HOST_LINKS` and `describeLinkOutcome` are in `@saga-a2ui/core/host-links`, shared with the React card and with MCP delivery) | `lit`, upstream `@a2ui/lit`, `@saga-a2ui/components` (an **optional peer**: an application that never imports this export does not install it) |

**Use.** An application builds its trusted settings once and answers the cards inside an element with them:

    const policy = createContentPolicy({ level: 'standard', imageHosts: ['images.example.com'] });
    // documentContentSecurityPolicies comes from '@saga-a2ui/lit-mcp-stack/faithful-card'
    const view: ContentView = createFaithfulCardView({ dialect: 'commonmark-tables-strikethrough', maxLength: 50_000, policy: policy.policy, contentSecurityPolicies: documentContentSecurityPolicies(document), hostLinks });
    provideContentView(app, view);        // the cards inside `app` receive this view when they connect
    registerFaithfulCard();               // explicit; importing the package registers nothing

and lists `faithfulCardEntry` in its own catalog. The card's two A2UI properties are `contractVersion` and `markdown`; both are bindable, and the schema is strict, so a layout cannot supply an action, a handler name, a dialect or a bound. `examples/answer-consumer` is a complete application built this way.

**Composing the card (layer C).** Both renderers export `createFaithfulCardView({ dialect, maxLength, policy, contentSecurityPolicies, hostLinks })`, which replaces the `createContentView` copies the consumers used to carry: it builds the reader (an unsupported dialect or a non-finite bound throws, naming `dialect` or `maxLength`, and builds nothing), establishes image enforcement from the Content-Security-Policy values it is given and takes no document (a caller that has one reads the values, for example with `documentContentSecurityPolicies`, and passes them in), and gives each view a fresh consent scope. `openFaithfulCardSurface()` returns a `CardSurface` with `present(content)` and `clear()`: `present` is the one selection operation. It revokes the view's image consent, retires the previous presentation's late link and image answers and mounts a fresh card, even for equal text, and content the surface refuses leaves the shown presentation in place; an ordinary data update of an own-catalog surface (`BoundSurface.update`, `updateData`) is a different operation and keeps the mounted content's identity. React mounts it with `<FaithfulCardSurface of={surface} />` under `FaithfulCardProvider`; Lit's `surface.element` goes inside the element that calls `provideContentView`. `useHostLink(url)` (React) and `bindHostLink(element, url)` (Lit) give a link the application renders itself the card's own rules: the view's policy decides at activation (Strict allows nothing), the host is asked once per activation through `requestLinkOpen`, the outcome is worded by `describeLinkOutcome`, and an answer arriving after the link, the view's selection or the element has changed is dropped; outside a view nothing is allowed and nothing throws. The styling surface the two renderers share, including the structural `data-saga-closing="paragraph"` marker, is documented in [faithful-card-styling.md](faithful-card-styling.md) and qualified at the card-surface level by rendering a branded stylesheet in both (`apps/lit-host/e2e/card-styling.spec.ts`). The stack-level result, through each stack's `startFaithfulCardApp`, is recorded separately in `apps/lit-host/e2e/card-app-stack.spec.ts`; see the styling guide's [Through the stack's start](faithful-card-styling.md#through-the-stacks-start). The consumers pass the CSP values from their own copy of the lookup or the Lit export.

**Content contract.** Content is untrusted: `{ contractVersion: 1, markdown: string }`. The reader refuses anything else with an explicit failure kind and never repeats the content: `invalid` (not that shape, or an unknown field), `unsupported-version`, `too-long` and `too-nested`. The element then shows an alert and none of the earlier content, and the next valid value recovers. A card with no enclosing view shows nothing of its content.

**Trusted settings, never content.** The reader is created from `{ dialect, maxLength }`, validated on its own (an unknown dialect, or a missing, fractional, non-positive, infinite or non-numeric bound, fails with `invalid-dialect`, `invalid-limit` or `invalid-config`) and with no defaults. `maxLength` counts UTF-16 code units, is the application's finite bound, and is independent of every other consumer's: the episode view keeps its 2,000-unit CommonMark settings (`EPISODE_CARD_SETTINGS` in `apps/lit-host/src/lit/content-view.ts`), and the answer example accepts 50,000 without changing that. The nesting safeguard (`MAX_NESTING_LEVEL`, 20) applies to both.

**Dialects.** `commonmark` is markdown-it's preset with linkify, typographer, tables and strikethrough off; pipe tables and `~~tildes~~` stay readable text. `commonmark-tables-strikethrough` enables the parser's own maintained `table` and `strikethrough` rules and nothing else. Both go through the one implementation. The parser's table rule drops body cells beyond the header's column count, so the reader splits each body row's source line the way the rule does and keeps the dropped cells after the parsed ones; nothing written is lost. Raw HTML, footnote syntax, task-list markers and the like stay as the characters written. A link reference definition is CommonMark syntax that the parser consumes to resolve the links that use it, so a definition nothing uses is not shown. The card never rewrites, translates, summarises, moves attribution, numbers headings or truncates: numbered headings, attribution-like lines and a footer appear as supplied and in place.

**Presentation.** The element renders into the light DOM with fixed templates and text bindings, and reads `--saga-card-font-family`, `--saga-card-line-height`, `--saga-card-text-color`, `--saga-card-accent-color`, `--saga-card-muted-color`, `--saga-card-border-color` and `--saga-card-code-background` (each with a neutral fallback). Block elements use `dir="auto"` so Arabic text reads right to left where the text does, headings start at `h3` (the surrounding page owns the levels above), and a table scrolls inside its own keyboard-focusable region so a narrow screen does not scroll the page sideways. The application owns the question, the status text, branding, fonts and any footer or attribution semantics.

**Policy and consent are unchanged in behavior.** Standard and Strict, exact-host images, the enforcement gate, Show/Hide images and revocation work as described in POL1 and POL2; the code moved and its owners did not. Policy and consent live in the components package without any transport; the host callback and every DOM interaction live in the Lit element, and each card gets them through its own view, so two cards on one page keep separate policy, callbacks and consent. Consent is revoked by new content, by the view's `revokeAll` and `retire`, by Hide images, and by disconnecting the card, and a control kept from earlier content or from before a disconnect does nothing. A reconnected card starts fresh.

**Installed, not aliased.** `scripts/build-answer-consumer.ts` packs the core, Lit, components and mcp packages (the browser page uses the first three; the mcp package serves it, see "Content identity for a served view"), unpacks them as installed dependencies of a clean directory outside the repository, links only the third-party packages their manifests declare, and builds `examples/answer-consumer` against those copies: the standalone page, the `mcp.html` page an MCP host mounts, and the consumer's MCP server (`apps/lit-host/dist/answer-consumer-server/server.mjs`, which the browser test connects to). It records the source commit, runtime, tarball digests and each built artifact's digest in `apps/lit-host/dist/answer-consumer/identity.json` (ignored). Reproduce it from a clean checkout:

    nvm use && npm ci
    npx playwright install chromium
    npm run build                                     # includes npm run build:answer-consumer
    npx vitest run --config vitest.config.ts scripts/answer-consumer.test.ts apps/lit-host/e2e/own-catalog-consumer
    npm run test:browser -w @saga-a2ui/lit-host-app -- e2e/answer-consumer.spec.ts e2e/answer-consumer-mcp.spec.ts e2e/faithful-card.spec.ts

An application with its own catalog installs only core and Lit; `e2e/own-catalog-consumer/packed-consumer.test.ts` shows its build holds no components package, `markdown-it`, FaithfulCard element or delivery code, and that the Lit manifest names the components package only as an optional peer. Building the consumer in a browser found that decorator syntax in `@saga-a2ui/lit` sources is not transformed under a consumer's own toolchain, so `createA2uiAppElement` and the card now declare reactive state with `static properties` and `declare`.

Tests: `packages/components/src/faithful-card/reader.test.ts` (settings validation, bound at and over the limit, versions, shapes, no content leakage), `dialects.test.ts` (tables, alignment, dropped cells, strikethrough, CommonMark's readable source, order, numbered headings, attribution, Arabic, long content), `markdown.test.ts`, `policy*.test.ts` and `image-consent.test.ts` (moved with the code; they characterise the extraction), `packages/components/src/exports.test.ts` (supported names and a bundled graph with no renderer, MCP or DOM), `scripts/answer-consumer.test.ts` (the installed consumer's imports, tarballs, manifests and graph), `e2e/faithful-card.spec.ts` (catalog setup, repeated and conflicting registration, dialects, failure and recovery, Standard and Strict effects at the network and callback boundary, two cards interleaved with replacement and disposal, retirement signals, reconnection, keyboard, status and a 320-pixel layout), `e2e/answer-consumer.spec.ts` (the built external page) and the existing `e2e/description*.spec.ts` (the migrated episode consumer).

The installed set and an authored protected control beside the card are recorded in "The FaithfulCard beside an authored control (CARD1)" below. The packed test uses a throwaway version and checks contents and declared dependencies. The external consumer's link callback reports that the open request was made. Image loading is observed in Chromium.

### The FaithfulCard beside an authored control (CARD1)

This fixture slice qualifies the card composed with an authored control; the real protected-player integration is recorded in the next section. It adds no component code, no export and no dependency: the card, its policy and consent, `ActionButton`, `createLitActions` and `Action.server` are used as delivered. What it adds is evidence that they compose, and that the card pages are part of the installed-package qualification (VIEW2).

**The composition.** `apps/lit-host/e2e/card-workflow/` is a test-only page, not an application: one A2UI surface whose list rows each render a title, a `FaithfulCard` for the row's `description` and an `ActionButton`. The catalog lists upstream `Text`, `Column` and `List` with `faithfulCardEntry` and `actionButtonEntry`. The application, not the card, binds the Archive server action of the Blueprint to the control with `watchById('row-archive', ActionButton, …)` and `subject: () => handle.read('id')`; the note identifier comes from the row's data scope. Two rows repeat the same component ids. The page's single view gives the cards a Strict policy with one image host and a consent scope.

**What the specs show** (`e2e/card-workflow.spec.ts`, real clicks, the real data model, Chromium):

- Each row's card shows its own description and each control archives its own row's note, one protected request per press, with the prerequisites counted apart from the request. The control is a direct attachment: the surface dispatches no protocol action.
- Supplied Markdown is only text. Text that looks like a control, an action name, a handler choice, a grant or an `onclick` is shown as blocked markup, an inert link or the characters written; clicking it sends no request and runs no prerequisite, opens no link and dispatches no action. The only buttons are the two authored controls, and the real control still sends the note its own row shows, not the one the Markdown names. A layout that gives `ActionButton` or `FaithfulCard` an `action`, or the card a `dialect`, is rejected whole.
- Image consent and the control have separate lifetimes. Replacing a description revokes only that card's consent and does not touch the same row's pending archive; a row that leaves the list retires its card and aborts its pending request, and the application's cancellation hook then says only that the status is unknown; disconnecting the application ends both, and a reconnected presentation runs `attach` again and starts without consent.
- A refusing session prerequisite is shown by the application and does not change the card. The application, which observed the sign-in change, ends the reader's consent by calling `view.consent.revokeAll()`.
- An unsupported `contractVersion` shows an alert and none of the private text, leaves the other card and the row's control working, and the next valid value recovers.

**Installed set.** `vite.faithful-card.config.ts` and `vite.card-workflow.config.ts` are now in the pages `npm run build:installed-lit-host` builds from the packed `core`, `lit`, `components` and `mcp` tarballs, and `e2e/faithful-card.spec.ts` and `e2e/card-workflow.spec.ts` are in `npm run test:browser:installed`. `scripts/installed-lit-host.test.ts` checks that both pages load the components package, the card element, `ActionButton` and the server action from installed copies and that no module came from a workspace.

Run it:

    npm ci && npx playwright install chromium
    npm run build
    npm run test:browser -w @saga-a2ui/lit-host-app -- e2e/card-workflow.spec.ts e2e/faithful-card.spec.ts
    npx vitest run --config vitest.config.ts scripts/installed-lit-host.test.ts

**Test doubles and mutation checks.** The transport, session, confirmation and audit are the page's test doubles (the Archive fixture of ACT6); the card in the protected player is the next section. Mutations of the source that the new spec catches (each reverted): dropping the card's consent revocation on new content (the replacement case fails), and loosening the card's strict catalog schema so a layout may add properties (the rejected-layout case fails). `THIRD_PARTY_NOTICES.md` is unchanged (`markdown-it` was already covered).

### The description card in the protected player (CARD1)

The optional Lit FaithfulCard sits beside the authored, directly bound Play control in the real protected player (`playback.html` / `playback-main.ts`), not in a test-only page. It adds no component, export, dependency or action runtime; the card, `contentViewFromDocument`, `createAppHostLinks` (since replaced by `hostLinksFromApp` in `@saga-a2ui/mcp/view`), the image consent scope, `connectPlaybackView` and the CORE2 Play action are used as delivered.

**The composition.** The player's opener result (`get_playable_episode`) already carried the episode's public `description` and the sign-in label. The page now shows that description with `<saga-faithful-card-content>` (public `@saga-a2ui/lit/faithful-card`, contract `FAITHFUL_CARD_CONTRACT_VERSION` from `@saga-a2ui/components/faithful-card`) between the title and Play. No subscriber field was invented and no card is required of other views: the subscriptions list stays a separate view, and the selection here is the opener result. The page builds one `ContentView` from its own document (`contentViewFromDocument`) and answers the card with `provideContentView`; the description supplies no policy, handler, subject or permission.

- **Authored control, trusted inputs.** Play is unchanged: bound to its own rendered instance, with the subject and `episodeId` taken from the selected opener, never from the Markdown. Text that names an episode, imitates a button, carries `javascript:` or a raw `onclick` is only text; pressing it sends no request.
- **Consent has one owner and its own lifetime.** `PlaybackViewDependencies.contentConsent` (optional; a standalone player passes none) is the page's `view.consent` scope. The controller revokes it before every opener is presented (an unchanged description is still a new selection), and retires it for good on label loss, host teardown and disposal. A press, a Play in flight and its outcome never touch consent, and consent ending never touches a Play. The card element removes the private text when a state has no episode (label loss, no selection), so nothing is shown beside a retired control.
- **Terminal retirement ends the card, not only its consent.** The same one-time retirement call also removes the card from the page (`playback-main.ts` wraps the scope's `retire`; no second consent owner and no new controller state). A card left mounted would keep its revision current, so a safe link kept from before teardown would still ask the host to open it and a host answer still pending would still be shown. The removed element invalidates its link results and consent itself, and the page mounts no card again once the view is over. Image Hide, a content-only change and an unrelated live Play stay as they were.
- **Policy.** The player resource is served verbatim and may connect only to the media origin. An embedded content policy carries `connect-src 'none'`, which would block the media fetch, so the deployed player embeds none: the card runs the default Standard policy with an empty image allowlist. It loads no image, and a link opens only through the host's `ui/open-link`. The page still honours an embedded policy, which is how the specs exercise Strict Show/Hide images, replacement, teardown and label loss.
- **Contract version.** The card's contract version is a page constant, so a server cannot induce an unsupported contract here; version failure, recovery and no partial display are the accepted `faithful-card.spec.ts` and `card-workflow.spec.ts` cases and are not repeated. The Archive page of PR143 is untouched.

**Tests.** `src/playback/playback-view.test.ts` (consent revoked before each opener and the unreadable one, untouched by play/pause/resume and a pending Play, retired on label loss, teardown and disposal, once); `e2e/playback-view.spec.ts` against the built page (order and inertness, hostile Markdown cannot play or change the episode, no image request and host-only links, replacement with a late grant for the old selection, label loss, teardown with a retained link click and a host link answer pending across it, and the Strict consent boundary). `scripts/installed-lit-host.test.ts` now expects the player page to load the installed card, components and `markdown-it`; `e2e/view-bundle.spec.ts` checks the player's markup and element construction instead of every character of its script.

**Bundle size and evidence.** The player resource grew from about 305 kB to 818 kB (84 kB to 236 kB gzipped): the card's single export also loads the catalog entry and so the upstream A2UI Lit renderer, whose media templates are why the bundle check changed. Image consent is exercised with an embedded Strict policy; the deployed player has no image host. The specs written for the page's behavior were red before `playback.html` carried the card (the browser specs failed on the missing description element, the controller tests on the missing consent hook) and green after; the Strict specs passed on first run and were checked by mutation (removing the consent wiring fails two; not clearing the card on label loss fails two). Those worker checks establish source, installed and browser evidence. The subsequent [bounded ChatGPT/Claude receipt](https://github.com/MachineWisdomAI/saga-a2ui/issues/146#issuecomment-6278612238) verifies the composed description and protected dispatch, observed retirement/remount and fresh recovery at the reviewed installed resource. [The lifecycle record](../blueprints/features/reusable_lit_adapter.blueprint.md#status) maps actual merge `11ce39d6d413a3a9a051b4cd8d2303f00883763e` and independent repaired-head validation.

### Reading the FaithfulCard accessibly in the Lit flow (CARD2)

This qualifies the optional Lit FaithfulCard for long, multilingual and hostile descriptions in the subscriber flow ([#20](https://github.com/MachineWisdomAI/saga-a2ui/issues/20)). It adds no export, dependency, action runtime or card property; it reuses the extraction, policy, consent and protected-player work above and adds reading cases.

**Shared, renderer-neutral fixtures.** `packages/components/src/faithful-card/description-fixtures.test-support.ts` is plain data with no imports and no DOM: four valid descriptions (long mixed-script notes, a table with code and strikethrough, a hostile description of refused links, images and markup, and long unbroken tokens) and six refused results (a later version, a version given as text, a non-string, a missing value, one unit over the bound, nested too deeply). Each valid fixture states the top-level block kinds the reader finds and pieces of text that must appear in order, not how any renderer draws them. The package manifest leaves it out of the published files and the type-checked source. `description-fixtures.test.ts` reads every fixture through the production reader and policy (and checks the file imports nothing), so a fixture cannot describe something the component does not do. Another renderer can import it the same way.

**Two defects the fixtures found, fixed in the Lit element** (`packages/lit/src/faithful-card/`):

- A list with a right-to-left item inside a left-to-right page put that item's marker outside the card, so the page scrolled sideways at desktop width. Lists now take no padding of their own and each item keeps `margin-inline-start: 2.5em` on the side its own text starts from.
- The card's own wording was not told apart from supplied text: Strict italicized a blocked link's label together with its `[Link blocked]` placeholder, and nothing marked the words at all. The card's wording is now an element with `data-annotation` (`link-blocked`, `image-blocked`, `markup-blocked`, `image-not-loaded` and the hostname `link-host`), italic except the hostname. Supplied labels, destinations, alt text, revealed source and text that merely spells `[Link blocked]` are never marked. The visible words and `data-testid`/`data-reason` hooks are unchanged, so the React card's wording stays aligned.

**What the new specs show** (Chromium through Playwright, the built pages):

- `e2e/faithful-card-reading.spec.ts`: each valid fixture under Standard and Strict keeps its structure and order and never scrolls the page sideways; each refused result shows an alert (a card on the mounted page and the A2UI catalog binding) with neither the old nor the refused text, and a valid value recovers; refused links and images stay readable (Standard shows a refused link's destination as text and names a refused image, Strict shows placeholders and, on Reveal source, the source), nothing refused is fetched or opened, and annotations are distinguishable from supplied text that imitates them.
- `e2e/faithful-card-view-results.spec.ts`: the fixtures are what the installed answer consumer's MCP server returns from real `tools/call` requests, delivered to the built page over the host fixture's real AppBridge; each replaces the last, an over-bound description is refused by the card, and results outside the contract clear the card and recover.
- `e2e/faithful-card-access.spec.ts`: light and dark follow the host's `prefers-color-scheme` and tokens (WCAG contrast of the card's readable text, with and without the card's tokens, and no fixed card colours); keyboard focus indicators for links, table regions and Strict controls; keyboard order and focus that stays on the control the reader used; status regions that exist before they speak and failures that are alerts; the accessibility tree of a structured description; every fixture at 320 CSS pixels and at 200% (a 320-pixel layout at twice the density with doubled text) without clipping or sideways page scroll, with wide tables and code scrolling inside their own focusable region; no animation, transition or smooth scroll under either motion preference.
- `e2e/faithful-card-instances.spec.ts`: a Standard and a Strict card interleaved while one description is updated and one view is disposed; consent, host callbacks, pending host answers and controls stay with their own instance, and a control kept from an earlier render cannot open a link, load an image or restore old content. Consent still has one owner, the view's image-consent scope.
- `e2e/card-instances.spec.ts` (the built `card-workflow` page, now able to mount further instances, each with its own policy, consent scope, host callback and Archive environment): the authored Archive control binds to its own rendered instances; interleaving an update and the end of one instance keeps the other's image, pending request and callback, aborts only the ended instance's request, and leaves kept controls of the ended instance inert; the card's source and consent controls send no protected request and Archive changes no content setting; and the server's decision stays apart from the client's (a Standard card with a listed image does not authorize Archive, and a Strict card without consent does not block it).

**Method.** The accessibility and zoom cases passed on their first complete run apart from fixture assumptions; the fixture-found defects above were red first (the multilingual fixture scrolled the page sideways and the annotation cases failed) and green after the fix. Mutations of the source that the specs catch (each reverted): a fixed `#888` hostname colour fails the light-scheme contrast cases, a transition on the hostname fails the Standard motion cases, and not revoking consent on new content fails the interleaving cases.

**Method notes.** Contrast is computed from the card's own computed colours against the colours behind them; native control colours follow the browser. Zoom is emulated by viewport width, device density and text size. The specs check roles, names, live regions and the accessibility-tree snapshot as the browser exposes them. Standard shows the alt text of a refused image (the wording is shared with the React card); Strict can reveal its address. A `javascript:` destination is not a link to the parser and stays the characters written. The subsequent [bounded ChatGPT/Claude differential](https://github.com/MachineWisdomAI/saga-a2ui/issues/20#issuecomment-6280435005) observed the changed mixed-direction lists, readable annotations and visible keyboard focus at the available host viewports. [The lifecycle record](../blueprints/features/content_safety_levels.blueprint.md#status) maps actual code `299e396c5c55a92eddcd2a12f0bf85bacd8e9bde` and independent 63 browser/seven fixture checks.

Run it:

    npm ci && npx playwright install chromium
    npm run build
    npx vitest run --config vitest.config.ts packages/components/src/faithful-card/description-fixtures.test.ts
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/faithful-card-reading.spec.ts e2e/faithful-card-access.spec.ts e2e/faithful-card-instances.spec.ts e2e/card-instances.spec.ts e2e/faithful-card-view-results.spec.ts

### Direct action attachment (ACT1)

ACT1 is the first slice of the [action binding](../blueprints/modules/action_binding.blueprint.md) design (design revision `c6506adccdeb71ac65fb10c793208d127eea7914`, approved 2026-10-17). It builds a synchronous local action fluently and attaches it directly to the exact rendered Lit control that fires it. ACT2 (React) and ACT3 (Lynx) qualified its shared seam before ACT4 built on it.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/core/actions` | `Action.local(label)`, `componentKind`, `createInstanceHost` and their types | nothing outside core: no Lit, no DOM, no MCP, no third-party module |
| `@saga-a2ui/core/actions/action-button-schema` | `ActionButtonApi`, the renderer-neutral contract of the opt-in control (moved here by ACT2 so the Lit and React controls share it) | upstream `@a2ui/web_core` and core's Zod 3 export; no renderer |
| `@saga-a2ui/lit/actions` | `ActionButton` (the kind token for setup code), `actionButtonEntry` and `ActionButtonElement` (the opt-in control), `createLitActions` | `lit`, upstream `@a2ui/lit`, core; imported by nothing in the main `@saga-a2ui/lit` entry |

Application code follows three steps; the rest is the SDK's:

```ts
// 1. Layout names the control by ID and type. It carries no action and no handler name.
{ id: 'save', component: 'ActionButton', child: 'save-label' }

// 2. Build the action once. Immutable; one definition serves any number of controls.
const save = Action.local<ActionButtonActivation>('save')
  .input((event) => ({ noteId: String(event.read('id')) })) // optional; copies what the handler needs
  .run(({ params }) => saveNote(params.noteId))             // synchronous
  .build();

// 3. Opt in once: list the entry in the catalog, define the element, and give the app element its setup.
createA2uiAppElement({
  /* catalog, layout */
  actions: createLitActions({
    attach: (view) => view.watchById('save', ActionButton, (handle) => handle.bindAction('activate', save)),
    onSetupError: reportSetupProblem,
  }),
});
```

- **Discovery and routing.** IDs select handles during setup only: `getById` for exactly one instance (it throws for none or several, naming the ID) and `watchById` for every present and later instance, such as each row of a template. An activation never looks anything up: the control's own click calls the callable installed in that instance's own slot. A slot belongs to one instance and is keyed by the event names its kind declares; there is no registry, no handler-name table and no action bus.
- **Binding rules.** One instance and event admit one live binding, so a second `bindAction` throws. `dispose()` is idempotent and detaches only its own installation; the same live handle can then bind again. Binding an event the instance does not offer, or through a handle whose instance was retired or whose setup ended, throws. A recreated component is a new instance that starts unbound and idle; handles for the old one are stale.
- **Execution.** A press runs `input` then the handler once, in the click's own call stack. Binding state passes `running` and `settling` and is `idle` again before the click handler returns, with a listener call for each change. A press that arrives while the same binding is still running (the handler caused it) is dropped, the default `ignore` policy. A handler or `input` that throws, or returns a promise the types did not show, ends the invocation, returns the binding to `idle`, and then rethrows to the event caller: this slice has no failure hook, and a failure must not disappear. `event.read(path)` reads the pressing instance's own data scope and answers only during delivery.
- **Ownership (Lit).** `createLitActions` makes the app element give each presented surface its own host. It starts before the surface first renders, so every `watchById` is registered before any control opens an instance, and it ends, disposing every binding and discovery subscription, when the surface is deleted or replaced, when setup fails, and when the element disconnects (before the session is disposed). A reconnected element presents a new surface and so gets a new host and a fresh `attach`. Unsubscribing a `watchById` stops later handles only; it disposes no binding. A setup that throws leaves nothing bound and the element shows its safe fallback; a discovery callback that throws loses only the bindings it made and reports to `onSetupError`.
- **Which mount owns a control.** `ActionButtonElement` finds its host from its place in the DOM, not from the surface object: the walk crosses shadow roots outward and accepts only an app element whose own `<a2ui-surface>` is the nearest surface above the control. A second `<a2ui-surface>` for the same model, outside any app element or inside an app element's own shadow tree, leaves its controls unbound. A control in light DOM or slotted content outside the app element's shadow tree finds no host and is unsupported.
- **Strict opt-in control.** `ActionButton` has a strict schema with `child` and optional `checks` and no `action`, so a layout that adds an upstream action, a `functionCall` or a handler name is rejected when it is ingested, before any property is resolved or any function runs. The element is the only click site (do not add a click listener to a rendered button as a shortcut). A control with no attached action does nothing, and a failing `checks` rule disables it as it does the upstream Button. Upstream `Button`s and their `event`/`functionCall` actions are untouched and deliver exactly once.
- **Lit seam.** The element uses upstream's overridable `createController()` and `isConnected`, the model registry and the data path, never `element.node`, which stays unset on the default `a2ui-surface` path. The existing rejection/recovery (`ingest` clears the surface and shows a fallback; the next accepted input recovers it) and `ElementConflictError` behavior are unchanged; a control that returns after a recovery is bound again by the same host without running `attach` a second time.
- **Own-catalog consumers.** The main `@saga-a2ui/lit` entry defines only the `A2uiActions` seam type and imports nothing from the action module, so an application that does not opt in bundles none of it. `packed-consumer.test.ts` builds both kinds of consumer from the packed tarballs.

Implemented in ACT1: immutable `Action.local(...).input(...).run(...).build()` with synchronous input and handler, binding state and subscription, direct attachment through `bindAction(event, definition)`, `getById`/`watchById`, ownership of setup, and the Lit control. ACT1 declares nothing beyond that (no placeholder methods, no ignored options). Later slices add the rest of the contract: React qualification (ACT2), Lynx qualification (ACT3), asynchronous local actions (ACT4), resource scopes (ACT5) and server actions with the joined contract (ACT6); CORE2 moved Play onto it. Controller safeguards in the Play and subscriptions views are untouched. The ACT3 repair added two members to the adapter-facing `OpenInstance` (`attached(event)` and `subscribe(listener)`), so an adapter can capture the attached binding by reference and learn when it changes; see the ACT3 section.

Tests: `packages/core/src/actions/actions.test.ts` (through the public interface with a renderer-free fake adapter, plus the type-level cases checked by `npm run typecheck`), `packages/core/src/exports.test.ts` (supported names; the bundled graph has no renderer, MCP or DOM runtime and no dependency at all), `apps/lit-host/e2e/action-binding.spec.ts` against the built consumer `dist/action-consumer` (a catalog of upstream Column, Row, List, Text and Button plus `ActionButton`, two app elements, repeated IDs and data paths, later rows, replacement, stale events, two mounts, a second surface mount, setup failure, surface deletion, disconnect and reconnect, rejection and recovery), and `packed-consumer.test.ts` (both consumers from the packed packages). The browser run is local Chromium through Playwright.

### Qualifying the shared action seam in React (ACT2)

ACT2 gives ACT1's shared runtime a second, real renderer before ACT4 builds on it. `packages/react` (`@saga-a2ui/react`, unversioned at this slice like the other SDK packages) has one export, `@saga-a2ui/react/actions`, and it is the smallest React A2UI consumer of the common seam, with its fixtures kept for REACT1/REACT2 to adopt; REACT1, REACT2 and the REACT3 slices add the workflow and the FaithfulCard.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/react/actions` | `ActionButton` (kind token), `ActionButtonEntry` (the opt-in catalog entry), `InstanceHostProvider`, `useActionSetup` and the activation types | React, upstream `@a2ui/react` 0.13.0 and `@a2ui/web_core`, `@saga-a2ui/core` (actions and the shared control contract); no Lit, no MCP |

The application writes the same three steps as for Lit; only the third differs:

```tsx
// 3. List ActionButtonEntry in the catalog, mount one provider per rendered surface, and run setup under it.
function SaveActions() {
  useActionSetup(setup); // `setup` has a stable identity, e.g. a module constant or useCallback
  return null;
}
const setup = (view: InstanceView) =>
  view.watchById('save', ActionButton, (handle) => handle.bindAction('activate', save));

<InstanceHostProvider onSetupError={reportSetupProblem}>
  <SaveActions />
  <A2uiSurface surface={surface} />
</InstanceHostProvider>
```

- **What an instance is.** The component function is not the instance: React may re-run it, discard a render before it commits, or mount a second copy. The instance is the span of one layout effect for one committed `(host, node)` pair of the control's boundary (a wrapper around the entry's generated `view`). A render React never commits publishes nothing. The press handler reads the committed instance at press time and calls its installed callable directly: no handler name, registry or lookup, and nothing from Lit.
- **Retirement.** An instance retires through the layout effect's cleanup (host or node change, unmount), through `node.addCleanup` (the upstream resolver disposes a node synchronously, before React has updated the screen) and through the host's `close()`. Each path is idempotent and disposes the instance's bindings, so a retired handle cannot bind and an old cleanup cannot detach a newer installation. The adapter's liveness pull is `!node.disposed`; retirement is the commit-time signal, which is why a separate "committed entry" check in the proposal's sketch was dropped (no test could tell it apart, because retirement already covers it).
- **Provider and setup.** `InstanceHostProvider` creates its host in an effect and closes it in the cleanup, so Strict Mode's simulated unmount closes the first host and the second effect makes another; children render only once a host exists (one extra render). Closing is terminal: a reference kept to a closed host can neither register a setup nor open an instance. `useActionSetup` registers `setup` per `(host, setup)` pair and ends the registration in its cleanup, disposing the bindings made through it, so changing the definition disposes the old binding before the new one binds. A setup that throws reports to `onSetupError` and then propagates to the nearest error boundary (the React counterpart of Lit's safe fallback), leaving nothing bound. A discovery callback that throws loses only its own bindings and reports to `onSetupError` alone.
- **Discovery timing in the published runtime.** `A2uiSurface` 0.13.0 renders its loading placeholder in the first commit and creates its resolver only when the store subscribes, so no instance exists while the first setup effect runs. `getById` at that moment finds none; use `watchById`, which delivers present and later instances (and call `getById` later, from a retained view, for a unique ID). A new `surface` prop passes through the placeholder again, so the root boundary remounts rather than receiving a new `node` prop; the effect still depends on `node`.
- **Data scopes.** Repeated IDs give separate instances with separate `dataPath`s. The event's `read(path)` answers only during delivery and `handle.read(path)` is the live reader (`undefined` once retired). Replacing the item at a position keeps the instance and its binding, and the next press and the reader see the new item.
- **Upstream Button.** `@a2ui/react` 0.13.0 ships no basic catalog. The test catalog builds Column, Row, List, Text and Button the way an application does, from `createComponentImplementation` over the upstream `@a2ui/web_core` component contracts; its Button calls the resolved `action`, which dispatches on the surface exactly as an upstream renderer's Button does. An `ActionButton` press dispatches nothing upstream, and an upstream Button press runs no attached definition.

**Exact identities the fixtures ran on** (asserted by `runtime-identity.test.ts`, not just printed): `@a2ui/react` 0.13.0 (the published package, not the 0.14.0 commit `45633b9` that the proposal inspected), one shared `@a2ui/web_core` 0.13.0 copy for the renderer, core and this package, React and React DOM 19.3.1, `@types/react` and `@types/react-dom` 19.3.0, jsdom 28.1.0 for the DOM, and Vitest 5.0.4, run on the repository's pinned Node 22.12.0 with npm 10.9.0 (the lockfile is written by npm 12.0.2 and installs cleanly with `npm ci` on 22.12.0). jsdom 28.1.0 is the newest release whose `engines` accept Node 22.12.0: 29.0.0 needs `^22.13.0` and 30.1.3 needs `^22.22.2`, and 30.1.3's `undici` 8 does not load on 22.12.0 (`createZstdDecompress` is absent). jsdom is a root `devDependency` as well as this package's, so the single root Vitest resolves the same copy. Resolved tarball integrity is in `package-lock.json`. Installing `@a2ui/react` pulled `@a2ui/markdown-it` 0.2.2 at its newest allowed range, whose peer `@a2ui/web_core ^0.14.0` installed a second, hoisted `web_core` 0.14.0 above every package's pinned 0.13.0. The root `package.json` therefore overrides `@a2ui/markdown-it` to 0.2.1 (the release in the `^0.2.1` range whose peer is `^0.13.0`).

Tests: `packages/react/src/actions/actions.test.ts` runs a real React 19 root in jsdom with Strict Mode on by default, a real `A2uiSurface` and real message sessions from core, and presses real DOM controls. It covers two instances each running only their own definition once, an unbound control and an upstream Button, a failing `checks` rule, Strict Mode, a transition that is held and then discarded, keyed-child replacement, surface swap, synchronous resolver disposal before React updates the screen, a host that changes under a node that stays, unmount and provider closing, repeated IDs, later and removed rows, same-position data replacement, the delivery-only event reader, setup and discovery failure, duplicate attachment, dispose and rebind, and a changed definition. `runtime-identity.test.ts` pins the versions above. `packages/core/src/exports.test.ts` also checks the shared contract's export.

Browser tests: `apps/lit-host/e2e/react-action-binding.spec.ts` (14 tests, `npm run test:browser`) drives a built React consumer, `dist/react-action-consumer`, produced by `vite.react-action-consumer.config.ts` as the last step of `npm run build`. The page is a real React 19.3.1 root, wrapped in Strict Mode, over the published `A2uiSurface` from `@a2ui/react` 0.13.0, with its own catalog (upstream-contract Column, Row, List, Text and Button plus `ActionButtonEntry`) and the public `@saga-a2ui/react/actions` exports (`InstanceHostProvider`, `useActionSetup`, `ActionButton`). React is built as its development build on purpose: Strict Mode's extra setup and cleanup exist only there, and the spec asserts that discarded first-pass bindings exist and that exactly one binding per control is live. It covers an attached control, an unbound control and the upstream protocol Button (each runs only its own path), the strict schema and a failing `checks` rule, repeated IDs with per-row data, a later row, a removed row and same-position replacement, synchronous resolver disposal while the old element is still in the document, a stale handle and a stale button event, surface swap, unmount and a fresh remount, a setup that throws (provider sink, error boundary, nothing bound, recovery) and a discovery callback that throws. It repeats the jsdom file's behavioral assertions through a real browser; it adds no second adapter and no new runtime. The spec prints and attaches the identities the bundle was built from (`@a2ui/react`, `@a2ui/web_core`, React and React DOM from the lockfile's installed copies, Vite, the browser and Playwright versions) and asserts the dependency ones. The recorded run: Chromium 156.0.8078.4 (headless shell, Playwright 1.64.0), Vite 8.3.4, `@a2ui/react` 0.13.0, `@a2ui/web_core` 0.13.0, React and React DOM 19.3.1. Hand mutations of the adapter that the browser spec catches: a layout cleanup that does not retire the instance (5 failures) and no synchronous cleanup on resolver disposal (1 failure). The jsdom tests catch two more: a passive instead of layout effect, and a host change under a node that stays. These mutation checks (breaking one lifecycle rule at a time and watching tests fail) were run by hand and are recorded in the pull request.

**Scope.** The jsdom tests cover React's lifecycle and event system; the browser spec covers the same behavior in local Chromium on React 19.3.1. The shared contract needed no change beyond sharing the control's schema. Asynchronous work, cancellation, hooks and subjects arrive in ACT4.

### Rendering the FaithfulCard in React (REACT3-TEXT)

[#117](https://github.com/MachineWisdomAI/saga-a2ui/issues/117) gives React consumers the passive FaithfulCard text and safe links through a second optional export of `@saga-a2ui/react`. It is the text and lifecycle slice of REACT3, bounded by the [approved design](../blueprints/features/content_safety_levels.blueprint.md). Image loading and consent are the next slice, described in the section after this one.

| Export | Holds | Imports |
| --- | --- | --- |
| `@saga-a2ui/react/faithful-card` | `FaithfulCard`, `faithfulCardEntry` (the catalog entry) and `FaithfulCardProvider` with its `FaithfulCardView` | React, upstream `@a2ui/react` 0.13.0, `@saga-a2ui/components` (an **optional peer**) |
| `@saga-a2ui/react/faithful-card.css` | The scoped presentation, imported explicitly | nothing |

An application with its own catalog that lists none of this carries none of it: the `@saga-a2ui/react/actions` graph holds no card, no components package and no Markdown parser (`exports.test.ts` bundles it to show so). The card is used the way the Lit card is, with the trusted settings supplied once and the content supplied by A2UI binding:

    const policy = createContentPolicy({ level: 'standard' });
    const view = createFaithfulCardView({ dialect: 'commonmark-tables-strikethrough', maxLength: 50_000, policy: policy.policy, contentSecurityPolicies, hostLinks });
    <FaithfulCardProvider view={view}><A2uiSurface surface={surface} /></FaithfulCardProvider>   // catalog lists faithfulCardEntry

- **One interpretation.** The card renders the typed nodes the components package already produces: the shared reader, the one maintained parser and the unchanged `{ contractVersion: 1, markdown }` wire contract. Every node case is a fixed element with text children (React escapes the strings; no raw-HTML escape hatch exists), and both `switch` statements over the node types end in an exhaustiveness check, so a new case does not compile until it is rendered. Order, Unicode and right-to-left text (`dir="auto"`), tables (a keyboard-focusable scrolling region) and the content bound's failures (`too-long`, `too-nested`, `unsupported-version`, `invalid`) behave as in Lit, and the failure sentences now have one owner, `describeContentFailure` in the components package. Without a provider the card shows an explicit, inert alert (`data-reason="no-view"`) and interprets, shows and requests nothing. The catalog schema stays strict, so a layout cannot supply a dialect, bound, action or handler.
- **Links.** `HostLinks` and `LinkOpenOutcome` moved to `@saga-a2ui/components/faithful-card` (later moved again, to `@saga-a2ui/core/host-links`, so MCP delivery can return them without importing components), together with `NO_HOST_LINKS` and the reader-facing outcome text (`describeLinkOutcome`); the Lit element, the Lit application, the MCP link adapter, the example consumer and the tests were migrated in the same change and the Lit export no longer carries them (no alias). Under Standard a validated HTTPS link is a button whose accessible name includes the parsed hostname, pressing it makes one request through `HostLinks.open`, and a denied, unavailable or failed answer leaves readable inert text with the destination and no navigation fallback (there is no `href`). Strict keeps every link inert behind a placeholder; Reveal source shows it as text and changes visibility only.
- **Images.** This slice fetched none. The image-consent slice below extends the provider's view with enforcement and a consent scope.
- **Lifecycle.** The card's state belongs to a content revision and starts over when the content, or the application's trusted view, changes: source visibility, link outcomes and every control from before. Rendering derives values only (state reset follows React's render-phase derivation rule) and runs no effect; the host is asked only from a press. A control applies to the revision it was rendered for, a late host answer for replaced content is not shown, an answer after unmount is dropped without a React warning, and a card asks its A2UI node whether it still stands before it asks the host for anything, so a node that A2UI disposed but React has not yet unmounted is already inert. Writing the Strict Mode tests found one real defect before the first green run: the per-render link and table counters lived outside the component that used them, so Strict Mode's second render of the same props continued numbering where the first stopped; they now belong to the one render, and the table-numbering test failed first.
- **Styles.** Templates (`nodes.tsx`), lifecycle (`lifecycle.ts`) and the stylesheet are separate. Every rule is scoped under `.saga-card`. The seven existing tokens keep their names and fallbacks (`--saga-card-font-family`, `-line-height`, `-text-color`, `-accent-color`, `-muted-color`, `-border-color`, `-code-background`), and `--saga-card-font-size` and `--saga-card-reading-width` (default `70ch`, following the card's own font) are new. The semantic classes (`.saga-card`, `-content`, `-failure`, `-controls`, `-link`, `-link-host`, `-link-status`, `-link-inert`, `-link-destination`, `-blocked`, `-source`, `-placeholder`, `-table-scroll`) are documented in the stylesheet's header, and `styles.test.ts` fails if the card renders one that is not documented. The Lit card's own inline styles are unchanged.
- **Supported versions.** The supported React and React DOM are exactly **19.3.1** (narrowed from the earlier `^18.0.0 || ^19.0.0` peers) with upstream `@a2ui/react` and `@a2ui/web_core` exactly **0.13.0**, which stay exact dependencies. `qualification.test.ts` fails when an installed copy, a manifest pin or the consuming application's pin drifts apart, and every rendering suite below ran on those copies.

Tests (run `npm run test:headless`, then `npm run build` and `npm run test:browser -w @saga-a2ui/lit-host-app -- e2e/react-faithful-card.spec.ts`):

- `packages/react/src/faithful-card/card.test.ts` (43 tests when REACT3-TEXT landed, 55 now; jsdom 28.1.0, React 19.3.1, Strict Mode): the card exported for direct use. Formatting and order, hostile markup kept as text (no element, no script run), direction and tables, every refusal with recovery, no provider, Standard link disclosure and each host answer including a rejecting adapter, inert non-HTTPS destinations, Strict placeholders and source reveal with nothing requested, image references, no host request during render, late answers, a replaced trusted view, an equal view that keeps state, and independent cards.
- `surface.test.ts` (11 tests): the same through a real message session, the published `A2uiSurface` and an application catalog. Data-model replacement, refusal and recovery, a layout that tries to choose its own settings, a surface without a provider, component replacement, unmounting, a node disposed before React unmounts it, a late answer after replacement, several cards, Strict and plain roots.
- `exports.test.ts` (3), `qualification.test.ts` (3), `styles.test.ts` (3) and, in the components package, `host-links.test.ts` (3) and two `describeContentFailure` cases in `reader.test.ts`.
- `apps/lit-host/e2e/react-faithful-card.spec.ts` (19 browser tests when REACT3-TEXT landed, one of which, on inert images, the image section replaced; Chromium through Playwright, the built `dist/react-faithful-card` from `vite.react-faithful-card.config.ts`, React's development build under Strict Mode): the recorded runtime identities; computed typography with and without tokens, colours from the existing tokens, the reading width and its token, a 320-pixel layout in which only the table region scrolls, and isolation (the same element types outside the card keep their browser and page styling, and a token set on the card does not reach the page); link disclosure, one request, `denied`, `unavailable` and `failed` answers with no navigation, popup or `href`; Tab, Enter, Space and arrow-key scrolling; Strict reveal and keyboard use; and A2UI replacement, refusal, recovery, independent cards, a late answer for replaced content, component replacement, unmount and remount, and a card that tries to supply its own settings.
- Hand mutations of the lifecycle that the suites catch (each reverted): applying a state change without checking that its revision is still current (3 failures) and not asking the A2UI node whether it still stands (1). An earlier committed-revision guard was removed because no test could distinguish it from the revision check.

**Scope.** Source and Chromium coverage of the React card on one pinned React and upstream pair, with a fixture host link adapter on the browser page. Image loading and consent are the next section; the installed-package join is [#120](https://github.com/MachineWisdomAI/saga-a2ui/issues/120) (REACT3-PACKED) and the shared resource-policy derivation [#119](https://github.com/MachineWisdomAI/saga-a2ui/issues/119).

### Image consent in React (REACT3-IMAGES)

[#118](https://github.com/MachineWisdomAI/saga-a2ui/issues/118) lets the React card show the images its content policy permits, and lets a reader Show and Hide them under Strict, without stale consent, effects across views or any way around the policy. It consumes the existing shared policy (`decideImage`, `offerImages`, `establishImageEnforcement`) and the application-owned `ImageConsentScope`; it adds no policy rule, no action runtime and no server call, and it does not touch the resource-policy derivation of [#119](https://github.com/MachineWisdomAI/saga-a2ui/issues/119).

`FaithfulCardView` gains two members, both supplied by the application and trusted like the rest: `imageEnforcement` (`establishImageEnforcement(policy, <the Content-Security-Policy values the document carries>)`; anything else keeps every image inert) and `consent`, this view's own scope. The scope is the **sole owner of view-wide revocation**: the application calls `consent.revokeAll()` when its selection changes or it observes another retirement signal, and `consent.retire()` when the view ends. A card asks the scope for grants and gives back only its own; it never calls `revokeAll` or `retire`.

- **What shows.** Standard shows an image from an exactly listed HTTPS origin (same scheme, host and port) with no consent. Strict shows it only while this card holds a live grant, made by pressing Show images. Everything else (an unlisted host or port, `http:`, credentials, a relative address, a `data:` or `blob:` Markdown reference, and every image when enforcement is not established) stays text in its original position with a `data-reason` (`host-not-allowed`, `not-https`, `credentials`, `malformed`, `enforcement-unestablished`, `consent-required`), and Strict can reveal it as source. Show images is offered only when at least one image would load once consent is given, and says why when it is not. An image the browser fails to load becomes the same text with `data-reason="load-failed"`. The document's derived `img-src` now carries the embedded baseline for the application's own trusted artwork (`data:`, and `blob:` in Standard); that does not reach Markdown, because the content decision refuses a `data:` or `blob:` reference before an element exists, and the browser spec checks it against the built policy.
- **Committed requests only.** React creates and fills in the elements of a render before it knows the render will be kept, and a browser requests an image as soon as an element has an address. The image element therefore receives its address in a layout effect (`image.tsx`), after the commit, so a render that is discarded or whose consent ended cannot start a request. Strict Mode's replay finds the address already set and sends nothing more. Consent can also end between render and that effect: the application owns the scope and may revoke or retire it from an earlier effect of the same commit, which React answers with a later render that is too late to take back a request. So the effect asks the shared policy again, through the card's lifecycle, with the render's owner and grant as they are at that moment (`imageStillPermitted`), and gives no address if it no longer agrees. The scope stays the only owner of consent; the element holds none.
- **Grants and subscriptions stay out of render.** A grant is made only by the reader's press. The card learns of `revokeAll` and `retire` through `useSyncExternalStore`, which subscribes after commit, removes the subscription on unmount and re-reads the state once subscribed, so a revocation between render and commit is not missed. The cleanup of a committed revision revokes the grants that card made and nothing else: during Strict Mode's replay of a mount it finds no grant and the scope stays live, and unmounting one card leaves a sibling's images showing.
- **What ends consent.** Hide images; new content or a replaced trusted view (a new revision); the component being replaced or the surface unmounted (a card's disposal); `revokeAll` and `retire` from the application. The control of a revision that has ended, or of a node A2UI has disposed but React has not yet unmounted, does nothing, and a load or error event for an image that is gone cannot restore consent, because only a press makes a grant and only a live grant shows images. A new press is a new grant.
- **Raw source.** Reveal source changes visibility only: it makes no grant, loads no image and asks the host for nothing.

Tests (run `npm run test:headless`, then `npm run build` and `npm run test:browser -w @saga-a2ui/lit-host-app -- e2e/react-faithful-card.spec.ts`):

- `packages/react/src/faithful-card/card.test.ts` (55 tests; the image cases replace the former inert-image cases) and `image-consent.test.ts` (23 tests, jsdom 28.1.0, React 19.3.1, Strict Mode): the card and the A2UI catalog entry under a scope the test plays the application of, recording what the card asks of it. Listed, unlisted, port, subdomain, `http:`, credentialed, relative, `data:` and `blob:` references; Show and Hide; no grant and one subscription after a Strict Mode render and mount; unsubscribed on unmount with no `revokeAll` or `retire`; a sibling unaffected by another card's unmount, Hide or new content; new content and a replaced view ending the grant; `revokeAll` and `retire` across several cards and two views; a card mounted after the view ended; stale controls; late load and error events; the address set once, after the commit; a data-model replacement, a replaced component, a node disposed before unmount, and an unmounted surface.
- `apps/lit-host/e2e/react-faithful-card.spec.ts` (33 browser tests, 15 of them new for this slice). The consumer page puts the policy's derived Content-Security-Policy in the document before rendering, establishes enforcement from it, answers every HTTPS request itself and records what the browser actually sent. It observes: the document carries exactly the derived policy; Standard requests only the listed images and none of the inert references; a listed image that redirects to an unlisted host is stopped by the browser before the redirect is followed (the target is never requested and the card shows text); an image injected outside the card is refused by the browser itself; with the policy absent every image stays inert; in Strict no request before consent, one after Show images, none for the other card, and Hide images removes it; the keyboard; data, blob, unlisted and plain-`http:` references never requested even with consent; Reveal source granting nothing; new content, a replaced component, unmount and remount, `revokeAll` and `retire` ending consent with a stale control unable to restore it; and two views, one revoked or retired while the other keeps its images.
- Hand mutations that the suites catch (each reverted): not giving back a card's grants on cleanup (6 failures), not subscribing to the scope (5), a card retiring the shared scope on cleanup (19), and giving the image its address while rendering (1). A guard that tied a late load failure to its grant was removed because no test could distinguish it, since React already drops events for an element that is gone.

**Scope.** Source and Chromium coverage on the pinned React and upstream pair, with a fixture page that answers image requests itself. The installed-package join and React asset isolation are [#120](https://github.com/MachineWisdomAI/saga-a2ui/issues/120). `documentContentSecurityPolicies`, which reads the document's policy values, is in the Lit export; a React application reads the values itself, as the React page does.

### The installed React card as one self-contained resource (REACT3-PACKED)

[#120](https://github.com/MachineWisdomAI/saga-a2ui/issues/120) joins [#117](https://github.com/MachineWisdomAI/saga-a2ui/issues/117) (React text and links), [#118](https://github.com/MachineWisdomAI/saga-a2ui/issues/118) (image consent) and [#119](https://github.com/MachineWisdomAI/saga-a2ui/issues/119) (the shared resource policy) through the packed packages: a clean consumer outside this repository installs `@saga-a2ui/core`, `components`, `mcp` and `react` as tarballs and shows tool-result answers in the optional React FaithfulCard from one immutable HTML resource. It is the minimal passive card: it adds no package, dependency, flag or SDK code.

`examples/react-card-consumer` is that application (not an npm workspace):

| File | Holds |
| --- | --- |
| `src/card-view.tsx` | The application: a card application definition (`FaithfulCardApp.define(...)`, the reader, the policy source and the parse of a result) started with `startFaithfulCardApp` from `@saga-a2ui/react-mcp-stack/faithful-card`, and the frame the application puts around the card (brand, status line). The stack connects to the host, holds early results, reads the document's embedded policy and ends the view with the page; this file imports no bridge and writes no A2UI message |
| *(no consumer file)* | The content policy still travels in the served document (the policy-derived `Content-Security-Policy` and the policy configuration, written by the server with `embedContentPolicy` and read and validated again by the stack with `contentPolicyFromEmbedded`, both from `@saga-a2ui/components/faithful-card`). The consumer's former `content-view.ts` and `embedded-policy.ts` copies are deleted: the stack owns the document lookup |
| *(no consumer file)* | The card's A2UI surface and data updates are the React package's (`createFaithfulCardView`, `openFaithfulCardSurface`); a result that is an error or outside the application's output clears the card and shows the application's problem text. The consumer's former `answer-surface.ts` is deleted |
| `src/main-neutral.tsx`, `src/main-harbor.tsx`, `src/brands/*.css`, `assets/` | Two composition roots of the one implementation: a neutral brand (no token set, so every card token keeps its fallback) and a differently branded one (all the card tokens, its own artwork and font). Each brand embeds its own SVG artwork (template `<img>` and stylesheet `background-image`) and WOFF2 font (`@font-face`) as bytes |
| `server/card-server.ts` | The consumer's MCP server, from `@saga-a2ui/mcp/server` alone: `createCardServer(builtHtml, { filename, policyConfiguration, answer })` embeds the policy (`embedContentPolicy`), builds the view with `operationViewFromHtml` (the actual filename and major 1 in the resource URI, `resourcePermissionsOf` supplying the configured origins as the only `resourceDomains`) |

**Build and reproduce.** `scripts/build-react-card-consumer.ts` (`npm run build:react-card-consumer`, part of `npm run build`) packs the four packages, unpacks them as the installed dependencies of a clean directory outside the repository, links in only the third-party packages their manifests declare (plus the consumer's own), and builds each brand with `vite-plugin-singlefile` into one HTML document with the runtime, stylesheet, artwork and font inlined, and the server into `apps/lit-host/dist/react-card-consumer-server/server.mjs`. `apps/lit-host/dist/react-card-consumer/identity.json` (ignored) records the source commit, runtime, tarball digests, the installed versions the pages were built with and each artifact's digest.

    nvm use && npm ci
    npx playwright install chromium
    npm run build                                     # includes npm run build:react-card-consumer
    npx vitest run --config vitest.config.ts scripts/react-card-consumer.test.ts
    cd apps/lit-host && npx playwright test e2e/react-card-consumer.spec.ts   # the whole suite is npm run test:browser

**What the headless checks show** (`scripts/react-card-consumer.test.ts`, 15 tests, on the packed tarballs and built graphs, never on source imports). The consumer imports only public exports and its own files. Each package ships source and manifest only (no tests), every export the React manifest names (`./actions`, `./faithful-card`, `./faithful-card.css`) resolves to a file the tarball carries, and the manifests keep the components package an optional peer (`@saga-a2ui/react` depends on no components, parser, Lit or delivery package). An application with its own catalog and the `actions` export builds a graph with no card, no `@saga-a2ui/components`, no `markdown-it` and no MCP code (`apps/lit-host/e2e/react-own-catalog-consumer`); the card consumer's graph holds the installed card, reader, parser, session and view connection and nothing from the workspace, a server or a second renderer. The two brands' graphs differ only in their composition root, stylesheet and artwork, so they are one implementation. Each built page has no `<link>`, script source, chunk, import or non-`data:` `url()`, is a production React build, holds no canned answer and carries the committed font bytes; the font fixtures equal the generator the policy specs use. Served over a real MCP connection the resource URI is the SHA-256 of the served bytes, every result of distinct answers links to it, a change to level, either origin list, brand or a single byte is a different resource, an answer is never part of it, and an invalid policy configuration is refused before serving.

**What the browser checks show** (`apps/lit-host/e2e/react-card-consumer.spec.ts`, 40 tests; Chromium through Playwright, the built pages served by the consumer's server and mounted in the sandboxed iframe of the local host fixture, results delivered over its real `AppBridge`):

- *Self-contained.* With every request but the fixture's own refused, each brand mounts, shows its neutral initial state, decodes its template and stylesheet artwork from embedded bytes, loads its embedded font (a measured advance, not an assumption), and renders an answer, with no request from the view frame and no page error.
- *Answers.* Three distinct answers from three tool calls reuse the one resource, in the same document and React tree, with replacement leaving nothing of the earlier answer; an error result, a wrong contract version, a wrongly typed field and a result with no structured content each clear the answer, say so and recover; after a host reload only the one complete delivered result is needed and nothing carries over; a host teardown stops delivery; `pagehide` unmounts the card; the server is asked exactly once per tool call.
- *Typography and brands.* Computed font family, size, line height, colours, reading width, link, table and code colours equal the tokens set (harbor) or the documented fallbacks (neutral), the brand's own font is applied to the title, and the card's stylesheet leaves the application's own elements alone.
- *Resource policy.* In both modes with empty and with configured origin lists, the mounted document carries the derived `img-src` and `font-src` exactly (Standard `data: blob:`, Strict `data:`, each plus only its own origins; Strict never regains `blob:`), the host declaration lists each configured origin once and no scheme, trusted data artwork and a data font load with no request, a blob image and a blob font load in Standard and are blocked in Strict with a security-policy violation and readable fallback text, a declared font origin loads with CORS (explicit port included) while an undeclared origin, port, subdomain or scheme is blocked before any request, and neither an image host nor a font origin authorizes the other. Content images follow the mode and the lists through the installed card (Standard shows a listed image without consent, Strict only after Show images, unlisted, `data:` and `blob:` references stay text).
- *Isolation.* A hostile answer (data and blob images, raw `<img>`, `<style>` and `@font-face`, links to data, blob and font URLs, and the application's own artwork address offered back as an image, a link and markup) sent through the real tool result and A2UI binding, with Show images given in Strict, leaves the template artwork address, every CSS rule, the style elements, the document's font faces and its image count as they were, converts nothing into an object URL or a `FontFace` (counted in the page), asks the font origin for nothing and activates no link. Extra fields in a result (an artwork address, a font URL, CSS, a brand, a policy, a template) select nothing, in either mode.
- *Consent and links.* Strict image consent ends when the host tears the view down and when a new tool result replaces the selection (the application revokes the view's consent scope before applying each result, a failure included), even when two distinct questions return equal Markdown; a fresh press grants again. A link leaves only as a request to the host.
- *Identities.* The served document is the built page plus exactly the policy-derived `Content-Security-Policy` and configuration; its digest, the resource URI, the recorded packed-tarball digests and the installed React 19.3.1, React DOM 19.3.1, `@a2ui/react` 0.13.0 and `@a2ui/web_core` 0.13.0 match what was built (attached to the Playwright report per brand).
- Hand mutations the suites catch (each reverted): `blob:` added to the Strict baseline (4 browser and 2 headless failures in these suites), the artwork address taken from a result field (4), not retiring the consent scope on host teardown (1), and not revoking it when a new result replaces the selection (1).

**Scope.** Installed-package, built-resource and local Chromium coverage on one pinned React and upstream pair, using packed tarballs, with the local host fixture answering requests. The embedded font is a hand-built two-glyph probe face (so a measured advance shows that it, and not a fallback, was used); it is applied to the title with a readable fallback stack, and the card's own text uses the brand's system font tokens. Standard defers an image the browser considers far from the viewport (`loading="lazy"`), so the Standard image check brings it into view. Playwright was run through `worker-browser-prereqs` against the shared browser cache.

### Lynx action attachment qualification (ACT3)

ACT3 challenges ACT1's shared action seam on a real ReactLynx renderer before ACT4 broadens it. `apps/lynx-fixture` (`@saga-a2ui/lynx-fixture-app`, private, unversioned) is a **retained qualification fixture, not an adapter**: it consumes `@saga-a2ui/core/actions` (with the one binding-identity addition described under *Seam repair* below), builds no second action runtime, and declares no supported `@saga-a2ui/lynx` package. Its control, slot and admission store live under `src/adapter/` only so that the shared seam can be exercised, and they are not exported.

**What ran.** The Lynx **Web** target, in Chromium. Exact identities are pinned in `apps/lynx-fixture/package.json` and its own lockfile, and `e2e/identity.spec.ts` asserts them and prints the report for the run:

| Part | Version |
| --- | --- |
| `@lynx-js/genui` (renderer, its own A2UI processor) | 0.7.0 |
| `@lynx-js/react` (ReactLynx) | 0.128.0 |
| `@lynx-js/react-rsbuild-plugin` (compiler) / `@lynx-js/rspeedy` (build) | 0.21.0 / 0.18.2 |
| `@lynx-js/web-core` (Web runtime) / `@lynx-js/types` | 0.26.4 / 4.3.0 |
| `@lynx-js/lynx-ui` (needed to bundle GenUI's catalog index) | 3.140.0 |
| `@a2ui/web_core` seen by GenUI / by SAGA core | 0.10.6 / 0.13.0 |
| Chromium (Playwright's headless shell) / Node | 156.0.8078.4 / 26.7.0 |

ReactLynx 0.128.0, not the 0.121.0 the design reported, because `@lynx-js/react-rsbuild-plugin` 0.21.0 (a GenUI dependency) requires `^0.128.0`; npm refuses 0.121.0 with it. GenUI's all-in-one `<A2UI>` interprets the protocol with its own 0.10.6 processor. The fixture adds no validation path of its own and weakens none; the layouts it is driven with are also decoded by SAGA's 0.13.0 core decoder in `src/adapter/admission.test.ts`, which accepts them; the admission store on the GenUI path refuses an `action` on the bound control.

**A separate project.** The fixture is not in the SDK npm workspace (`workspaces` lists `packages/*` and `apps/lit-host`) and has its own `package-lock.json`. Adding GenUI's tree to the workspace made npm hoist `zod-to-json-schema` to the root, where its Zod peer resolves to Zod 4: the placement the Zod-boundary note above says must not happen, which `npm run candidate:identity` correctly refused. Overriding GenUI's own `@a2ui/web_core` would have changed what is qualified, so the fixture is installed on its own: `npm ci && npm ci --prefix apps/lynx-fixture` (CI does both). It resolves `@saga-a2ui/core` through the workspace link, and TypeScript, Playwright, `tsx` and `@types/node` from the root install.

    npm ci --prefix apps/lynx-fixture   # the fixture's own lockfile
    npm run build                       # also builds apps/lynx-fixture/dist (rspeedy web bundle + the web-core runtime)
    npm run test:browser                # includes the 51 Lynx Web specs (port 4174)

**Findings, by claim.** Each is a browser spec under `apps/lynx-fixture/e2e` unless it says otherwise.

- *Direct attachment* (`attachment.spec.ts`). One catalog component type serves every instance; setup discovers instances by the layout's own ID with `watchById` and binds a definition to the exact handle. Two definitions on one control kind each run once per tap in the background thread, `input` before the handler. An unbound control and a control whose setup bound and then threw (ACT1 disposes what that callback bound and reports it) refuse every tap. A second bind throws; dispose then rebind runs the new definition on the same mounted instance with no remount. A handler failure reaches the adapter, returns the binding to `idle`, and does not reach the renderer. A protocol `action` on the bound control is rejected whole by the admission store before the processor sees it, so a `functionCall` in it never runs; the same call on an upstream `Button`'s `action` runs during prop resolution, before any tap (the hazard the guard is for), and unrelated function calls and the upstream `onAction` path are untouched. The guard applies to that one property of that control kind.
- **Seam repair: a queued tap is bound to the binding its render showed.** The first revision of this slice found that a tap closure queued before a dispose, after a second binding was attached on the same handle, ran the replacement definition, because ACT1's `OpenInstance` never exposed the attached binding. The approved tap-admission contract requires the opposite. The repair is in the shared owner, `@saga-a2ui/core/actions`, and adds no registry and no second runtime: `OpenInstance.attached(event)` returns the binding now attached to an event of that instance by reference (`undefined` while none is, never a disposed binding), and `OpenInstance.subscribe(listener)` calls back synchronously after an attach, a detach and once at retirement, with the change already visible through `attached`. The adapter publishes the attached binding in the snapshot a render reads, so each render's tap token carries it, and `activate` checks in order: installation live and the token's, the observed-key epoch, a binding attached (`unbound` otherwise), the token's binding being the attached one by reference (`stale` otherwise), and the live key. A closure queued before a dispose is `unbound` while nothing is attached and `stale` after the replacement, which is not started; a render after the rebind carries the replacement and its tap delivers. Lit and React keep their calls to `activate` unchanged. Browser specs: `an old queued tap is unbound after dispose and stale after rebind...` and `a closure captured while a binding was attached stays stale across two rebinds...`; core tests under *the binding an instance exposes to its adapter*. Recorded red before the repair, on the real Lynx Web target: the old adapter returned `delivered` for the stale closure (both specs failed at that assertion).
- *Checks and `isValid`* (`checks.spec.ts`). The control calls GenUI's exported `useChecks`, the hook the published `Button` uses, and binds `bindtap` only when `isValid` is not `false` and every check passes; the first failure's message is shown. No expression interpreter is added. **The hook is given the component's stored rules** (`surface.components`, with the component's resource as the update notification), not the props GenUI has already resolved. Resolved props turn a `{ path }` condition into its current value, which `useChecks` does not recognise and counts as passing; the repair in this revision found that on the first revision (a tap on a control with `condition: { path: '/approved' }` and `approved: false` ran its definition once, expected zero). Covered on the real renderer, each as a failing-then-passing sequence on one binding: a false model-bound condition (message shown, a tap runs nothing), then the same model value changed to true (message gone, exactly one invocation), to false again (message back, no further invocation) and true again, with one `opened` probe record and no rebind, on the `ordersLayout` surface; a relative `{ path: 'approved' }` condition in a template row, each row reading its own value; a replaced condition path re-evaluated against the new value; an `equals` function-call condition (the A2UI basic functions are registered by the fixture root, through GenUI's own `registerBasicFunctions`) following the model; plus the earlier cases: a failing literal check, a passing check, the first of several failures, `isValid: false` with passing checks, a replaced literal rule list followed in both directions on one instance. Recorded red before the repair, on the real Lynx Web target: four of these specs failed against the previous control (the model-bound, relative, changed-source and published-Button-comparison ones), and passed after; the function-call spec passed both before and after, because a boolean result survives GenUI's early resolution. **Upstream behavior, pinned:** the published `Button` at GenUI 0.7.0 hands `useChecks` the resolved props; the first spec asserts that beside the control's own enforcement of the model-bound condition. A rule's message is shown when it is a string. Checks gate the interface and authorize nothing. `useChecks` needs `<A2UI>`'s context, so the empty first screen, which `<A2UI>` draws outside it, renders a separate `firstScreenProbe` that shares the slot machinery with the control but not the checks gate.
- *Freshness* (`freshness.spec.ts`). Rows of a template share the layout ID, have distinct expanded IDs (`row-archive:0`), and read their own relative `noteId`; the adapter's `sagaSourceId` annotation survives GenUI's clone and reaches the control. A same-position replacement and a reorder keep each instance (no open or close) and move what it shows; the live reader agrees with GenUI's resolved prop for a literal, an absolute path and a relative path, and returns `undefined` without executing a function-call binding. **Observed notification order on the Web runtime** for `updateDataModel`: the signal callback runs synchronously inside the processor's batched update, first, only for the key that changed; the Resource callbacks of every template row follow; the render comes last. For `updateComponents` replacing `{ path: '/old' }` with `{ path: '/new' }`, the Resource callback moves the watch to the new signal and the new signal's first value is compared with the last seen; a change at the retired path is ignored and the same key at another path does not count. *Checkpoint freshness versus the observed A–B–A count:* the live key comparison at the tap refuses a closure whose key no longer matches, with no notification involved; an observed A, B, A makes the key equal again and only the count of observed changes then refuses the old closure. Within one signal batch a value set and reverted is a single observation, so the old closure is admitted, as designed; two update messages are two batches and both count.
- *Partition and locality* (`partition.spec.ts`). The template has one background chunk and one main-thread chunk. A `'background only'` function body (the setup) is absent from the main-thread chunk; ordinary module code, including the shared runtime, the adapter and the definitions, is in **both**. What matters is what ran: the main thread rendered the application root and an inert first-screen probe (the control's slot machinery without its checks gate, see above) once for `<A2UI>`'s empty first screen (a slot constructed, no token captured, nothing opened or closed) and then rendered nothing further, because `<A2UI>` builds surfaces from messages in a background effect. Effects, setup, `bindtap`, `input` and the handler all ran in the background Web Worker (`document` undefined, `WorkerGlobalScope`). No binding or function reference was transferred: nothing binding-related existed on the main thread. The built template is read when a test runs, not while Playwright discovers tests, so `npx playwright test --list` works on a fresh checkout before `npm run build`.
- *Cancellation primitive.* `AbortController` exists in the background worker and delivers abort once; separately, `fetch` there honors the signal and the server saw its connection dropped. These are Web Worker observations.
- *Lifecycle* (`lifecycle.spec.ts`). A keyed session reset (new `key`, new admitting store, new host) closes every instance, disposes every binding, refuses an old closure and starts the new mount unbound until its own setup runs; clearing the store without changing the key is not a reset. Replacing a control with another component type, or deleting the surface, retires its instances; an ID merely omitted from a later update does not. Scrolling the Web `x-list` neither opens nor closes an instance and a row tapped afterwards keeps its item. The Web list keeps every row's element. Removal versus cleanup, three samples: cleanup was recorded 2 to 5 ms *before* the page observed the element's removal. The retirement-tolerant contract holds: presentation is written to state keyed by the business item, and `current()` is not used as proof of native presence (ACT4 owns it).

**Mutation checks.** The six guard mutations in `src/adapter` from the first revision were each removed once and the named spec failed for five of them (epoch check, live key comparison, retirement at cleanup, admission, watch following a replaced binding); the sixth, the installation-identity check at tap, is defensive, since a slot is opened once here. The binding-identity check and the snapshot subscription added in the repair are covered by the two attachment specs above.

### Asynchronous local actions (ACT4)

ACT4 extends the one shared action runtime in `@saga-a2ui/core/actions` (no second runtime, no registry, no alternative combinator model) so a directly bound local action can wait for reusable prerequisites, do asynchronous local work and reach the correct outcome without leaving its control busy forever. The fluent interface is the approved one:

```ts
const requireSession = prerequisite('session', async ({ signal }) => (await currentSession(signal)) ? proceed({ user }) : refuse('sign-in-required'));

const save = Action.local<ActionButtonActivation>('save-draft')
  .input((event) => ({ text: String(event.read('/draft')) }))
  .before(requireSession)                      // in the order written; each adds provided values
  .run(({ params, provided, signal }) => saveLocally(provided.user, params.text, signal))
  .limits({ deadlineMs: 10_000 })              // optional: overrides the work deadline for this action only
  .onSuccess(({ result, current }) => { if (current()) showSavedAt(result.savedAt); })
  .onFailure((context) => { /* context.stage and context.failure say what is known */ })
  .whenBusy('ignore')
  .build();

handle.bindAction('activate', save, { subject: () => handle.read('id') });
```

- **Prerequisites** are application work before the handler, not authorization and not pending UI. They run strictly in order, may answer synchronously or with a promise, and see `provided`, `params`, `signal` and their own `current()`. `refuse(reason)` ends the invocation as `failed` in the `prerequisites` stage and the handler never runs; a throw is `prerequisite-error`; a key two prerequisites both provide, or an answer that is neither `proceed` nor `refuse`, is `prerequisite-error` too. An action built only from synchronous pieces still reaches `idle` before the event handler returns, and a local action makes no MCP request.
- **Bounds.** `deadlineMs` covers the prerequisites and the handler together; `hookMs` is a separate budget for each of `onSuccess`, the outcome hook, each resource release and `onFinally`. Neither needs to be declared: each resolves on its own from the action's `limits` override, then the owning SDK instance's configuration, then the default of 30,000 ms and 5,000 ms (see [Configurable action defaults](#configurable-action-defaults-and-error-categories)). There is no whole-invocation timer. A timer is armed only when a step returns a promise. `onSuccess` is awaited before success is decided: its exception or overrun is `failed` (`success-hook-error` or `success-hook-timeout`) in the `running` stage and carries the handler's result. A hook that outlasts its budget is no longer waited for, is recorded as a `budget-exceeded` diagnostic reaching `onFinally`, and cannot keep the binding in `settling`.
- **Eligibility.** Every prerequisite, the handler and every hook gets its own `current()`. It ends for good when the callback finishes, when its promise settles, when its budget or the work deadline expires, or when cancellation or obsolescence makes the runtime stop waiting; it also needs the binding live and undisposed, the invocation not replaced, the adapter's `isLive()` and an equal subject. A late settlement is dropped (the observer sees `late-settlement` and no value), and a late callback cannot start `onSuccess`, change a decided outcome or write over a newer invocation, provided it asks `current()` first. Arbitrary effects a callback already started are not recalled.
- **Outcomes are decided once.** An obsolete failure stays `failed`, does not run `onCanceled`, does not start `onFailure` (or aborts it if running) and still finalizes; an absent `onFinally` does not skip finalization; an older invocation settling beside a newer one (`whenBusy('replace')`) cannot return the newer one to `idle`, and nothing undoes disposal. The runtime never continues an invocation inside one of its own callbacks' call stacks: cancellation from inside a handler (for example `dispose()`) defers the invocation's next step until that callback returns.
- **Busy policy and revalidation.** An activation that arrives while the binding is `running` or `settling` first rechecks the active invocation (so a press on item B ends item A's stale invocation), and only then meets the policy: `ignore` (default) drops it and tells the observer which invocation was busy, `replace` cancels a running invocation with cause `replaced` or, for one already settling, keeps its outcome and makes its presentation obsolete.
- **`subject` and wake-ups.** `bindAction(event, definition, { subject })` takes an optional reader of the item the instance shows; component or model identity alone cannot tell two items at one position apart. The runtime captures it when the invocation starts and compares a fresh `Object.is` read at its checkpoints (before each prerequisite, when the handler's answer is observed, before a presentation hook starts, at the busy decision and on every `current()`). A reader that throws at activation ends the invocation as `invalid-input`; one that throws later counts as a change. Adapters may supply `watchScope(revalidate)` in `OpenInfo`: the runtime subscribes only while an invocation is unsettled and unsubscribes when it settles, is replaced or is disposed, and a call requests the same recheck any checkpoint does. Lit and React wire it to `DataModel.subscribe` through a microtask; the Lynx fixture wires it to its own item watch, which also keeps its separate tap-admission epoch while idle. An unobserved A, B, A cannot be detected (put a revision into the subject if a row can be deleted and recreated under one key), and once an observed B has canceled an invocation a return to A does not revive it. An instance that is no longer live at a checkpoint disposes the binding.
- **Telemetry.** `observe(observer)` receives phases with the label, opaque binding and invocation ids, elapsed time, status, failure kind and the failed cleanup step's name, and nothing else: no parameters, provided values, results or error objects. A throwing or rejecting observer or listener changes nothing and leaves no unhandled rejection.
- **Synchronous failures.** A failure decided in the event's own call stack for a definition with no `onFailure` is still rethrown to the event caller after the binding returned to `idle` (ACT1 behavior; the Lynx fixture reports it), but only for failures that carry an error (`invalid-input`, `prerequisite-error`, `handler-error`, `success-hook-error`). A refusal is not an error and is not thrown. With an `onFailure` hook the hook receives every failure and nothing is thrown, and an asynchronous failure has no caller to return to.

ACT4 declares no placeholder methods: `atActivation`, the invocation `scope`, `acquire`/`own`/`transfer` and resource release arrive in ACT5 (next section), and `Action.server` and `call` in ACT6. The adapters refuse a stale tap before the shared runtime sees it. Existing application and controller bounds are untouched.

**Evidence** (recorded runs are the ones listed under Verification in the pull request, on Node 26.7.0, npm 12.0.2 and Chromium 156.0.8078.4 through Playwright 1.64.0):

- `packages/core/src/actions/async-actions.test.ts` drives the public builder and binding with a renderer-free adapter, vitest's controlled clock and gated promises: ordered prerequisites and provided values, refusal, stalls, the work deadline in each stage, hook budgets, success-hook failure and timeout, late callback eligibility, both busy policies, replacement and disposal, subject replacement and wake-ups, observers, and the runtime refusals when the types are bypassed. The type-level cases are checked by `npm run typecheck`.
- `packages/react/src/actions/async-actions.test.ts` (jsdom 28.1.0, React 19.3.1) and `apps/lit-host/e2e/react-async-action-binding.spec.ts` (built React consumer under Strict Mode, `?scenario=async`); `apps/lit-host/e2e/async-action-binding.spec.ts` (built Lit consumer, `?scenario=async`, with the Save-style action and a row action with a subject); and `apps/lynx-fixture/e2e/async.spec.ts` (ReactLynx 0.128.0 over GenUI 0.7.0 on Lynx Web: a pending prerequisite, same-position replacement through the item watch, a batch that returns to its first value, disposal before the continuation and session reset).
- Hand mutations of the runtime that the core suite catches (each reverted): `current()` ignoring the callback's own eligibility (5 failures), a failure hook started for an obsolete invocation (1), any settling invocation returning the binding to idle (1), the work deadline never armed (3), a late settlement still deciding (5), no revalidation before the busy policy (1), no wake-up subscription (7).

**Scope.** Common-seam qualification of the shared runtime's admission and currentness against each renderer's real observation seam. In Lit and React, removing a row can be seen first as a changed subject and then as disposal; either cancels, and the specs accept both causes. On GenUI 0.7.0 over Lynx Web the specs cover the keyed session reset, binding disposal and a changed item at a kept position.

Run the async specs with the build in place: `npm run build`, then `npx playwright test e2e/async-action-binding.spec.ts e2e/react-async-action-binding.spec.ts` in `apps/lit-host` and `npx playwright test e2e/async.spec.ts` in `apps/lynx-fixture`.

### Resource ownership in the invocation scope (ACT5)

ACT5 extends the same `@saga-a2ui/core/actions` runtime (no second runtime, no registry, no alternative cleanup protocol) so a local action can acquire an application-owned resource, release it when the invocation ends, or hand it synchronously to an owner that keeps it. The runtime owns invocation-scope cleanup; the application's resource owner stays responsible for what a token means. This slice shows the generic ownership mechanics with an observable fixture owner; CORE2 applies them to the player.

```ts
const play = Action.local<ActionButtonActivation>('play')
  .atActivation(({ scope }) => scope.own(owner.begin(), (lease) => owner.end(lease)))   // the event's own call stack
  .run(async ({ activation }) => {
    const started = await owner.start(activation.token);
    if (started === 'blocked') return { state: 'gesture-needed' } as const;               // the scope still owns the lease
    return activation.transfer((lease) => owner.keep(lease))                              // synchronous adoption, no await between
      ? ({ state: 'playing', lease: activation.token } as const)
      : ({ state: 'gesture-needed' } as const);
  })
  .onSuccess(({ result }) => (result.state === 'playing' ? showPlaying() : showGestureNeeded()))
  .onCanceled(({ activation }) => owner.end(activation.token))                            // every stage carries the token
  .build();
```

- **Three ways in.** `atActivation(({ event, scope }) => value)` runs synchronously after `input`, in the call stack and environment of the adapter's event delivery (the Lit adapter's click handler here), and what it returns reaches the handler and every hook as `activation`. Its scope offers `own(token, release)` and has no `acquire`. `scope.own` on the handler's or a prerequisite's scope takes a token the caller already holds. `scope.acquire(acquire, release)` awaits an acquisition after the event turn and owns the token from its arrival. `Held<Token>` carries the `token` and `transfer`.
- **Release at the end.** Every token the invocation still holds is released newest first, after the outcome hook (`onSuccess` having already decided success, or `onFailure`/`onCanceled`) and before `onFinally`. Each release is its own step with its own `AbortSignal` and its own `hookMs` budget; a release that never settles has its signal aborted and is not waited for, and `settling` is bounded by `hookMs` times the tokens held plus the outcome and final hooks. A release that throws or overruns is a `release` cleanup diagnostic (`threw` or `budget-exceeded`) delivered to `onFinally` in `cleanupErrors` and to the observer by step name; it never changes the decided outcome and never stops the releases after it. Releases run for an obsolete invocation too: nothing in them presents.
- **After retirement.** `own` after the outcome was decided releases the token at once (own budget and signal; a failure reaches the observer only) and throws `InvocationEndedError`. `acquire` on an ended invocation does not start the acquisition and rejects with the same error; a token that arrives after the invocation ended is released at once and the acquisition rejects. `scope.active` is true until the outcome is decided; it is work activity, not freshness (that stays `current()`).
- **Transfer.** `held.transfer(adopt)` calls `adopt(token)` synchronously while the invocation is active and returns true only if `adopt` returned a non-thenable value and the invocation was still active when it returned; the scope then no longer releases the token. It adopts nothing and returns false once the outcome is decided (even before the release step has run) or when the scope no longer holds the token (already transferred). If `adopt` itself ended the invocation (for example by disposing the binding) and returned, the transfer is not reported as completed: it returns false and the scope releases the token in its ordinary place, after the outcome hook for a handler still running, or at once when the release sweep has already passed. A throw from `adopt`, or from inspecting what it returned (a `then` accessor that throws), propagates and ownership stays with the scope. A thenable the types could not see makes `transfer` throw a `TypeError`, keeps ownership with the scope and attaches a rejection handler; a later rejection reaches the observer as a `cleanup-error` with step `adopt`. Work the callback already started is not recalled, which is why an owner's `end(token)` must be idempotent. Whatever way adoption fails or is refused after the invocation ended, the scope releases the token itself rather than leak it. Compile-time: `Synchronous<Returned>` rejects an `async` adoption callback, `Promise<T> | undefined` and an `async` `atActivation`; a promise hidden behind `unknown` is caught at run time.
- **Failures of the event-turn callback.** A throw, or a promise the types could not see, ends the invocation as `failed` in stage `input` with kind `activation-error`; the handler never runs, tokens the callback already took into the scope are released after the failure hook, and the error reaches the event caller after release when no `onFailure` receives it. A failure of `input` or of the subject reader prevents `atActivation` from running at all. The runtime does not continue the invocation inside the callback: a disposal from inside it is noted, the scope stops being active at once, and the cancellation is decided when the callback returns, so a callback that returned still gets its canceled hook with `activation`. If the callback disposes the binding and then throws, no activation value exists: the throw is the outcome (`failed`, stage `input`, `activation-error`, a stage whose hooks carry no `activation`), the invocation is already obsolete so the failure hook does not present, and the scope releases what it owned. That cancellation only leaves the invocation obsolete: it neither aborts nor abandons the cleanup the failure started, so the release sweep (one step per token, each with its own signal and `hookMs` budget) and `onFinally` still run to completion, whether a release settles at once, later or never. A canceled hook typed as carrying `activation` therefore never runs without one.
- **What the application's owner provides.** `release(token)` and any token-scoped `end(token)` affect only that acquisition and are idempotent, a no-op for a token the owner has superseded; acquiring a new token from a single-resource owner supersedes the previous one. Stopping everything the owner holds is the owner's own teardown and is not a nameable operation for an invocation; SAGA never calls it on binding disposal, subject change or session reset. A deliberately retained resource therefore outlives a successful invocation, and outlives `failed(success-hook-error)` or `failed(success-hook-timeout)` when the failure hook keeps it under the selected policy. Later disposal of the binding changes neither.
- **Narrowing before presenting.** `activation` is typed in the handler and every hook that can follow the prefix (not in a failure of the prefix itself, which has none), and `failure.result` is the handler's own result type. The Play action above returns a discriminated result, so a started-and-transferred result (`playing`) is different from a blocked start (`gesture-needed`) before `onSuccess` presents or `onFailure` recovers; the failure hook keeps the lease only for `playing`, and ends exactly `context.activation.token` otherwise, which cannot reach a newer owner's lease.

A scope can own a token without any declared limit: each release gets the resolved `hookMs`, whatever the action overrode. Activation work stays in the event stack and environment the adapter delivers the event in.

**Evidence.**

- `packages/core/src/actions/resource-scope.test.ts` drives the public builder and binding with the renderer-free adapter, a controlled clock, gated promises and an observable single-resource owner that records every call and which leases are audible. It covers activation work in the event's own call stack, ownership of an existing token, acquisition after the event turn, reverse-order release after the outcome hook and before `onFinally` for success, failure and cancellation, a stalled release (own signal, own budget, outcome and later releases untouched), the settling bound, releases that throw or reject, late `own` and late acquisition, a superseded invocation's cleanup unable to reach a newer lease, transfer (success, ended, decided-but-unreleased, throwing, hidden thenable with late rejection, twice, invocation ending during adoption), cancellation before and after the transfer and at each stage, retained resources after success and after a success-hook failure, a blocked start never reported as playing, `activation-error`, a disposal followed by a throw in `atActivation` (an older token, a newer token whose release settles late or never, an asynchronous or stalled `onFinally`, with and without `onFailure`: the sweep and finalization still complete), `scope.active`, and compile-time cases through `@ts-expect-error` (checked by `npm run typecheck`).
- `apps/lit-host/e2e/resource-action-binding.spec.ts` (built Lit consumer, `?scenario=resource`): real clicks and real mount teardown against a page-owned player fixture. The lease is taken inside the click's own task before anything awaits; a started lease is kept past success and past binding disposal until the owner's own `endCurrent()`; a blocked start reports a needed gesture and the scope gives the lease back; a success-hook failure after a blocked start reports failure, never playing, and leaves a newer owner's lease playing; a success-hook failure after a started, transferred start leaves the lease with its owner; a cancellation before the transfer ends exactly that lease; a cancellation after the transfer and before the runtime observes the answer ends exactly that lease once, and the late answer presents nothing; a lease acquired after the event turn is held and released at the end.
- Hand mutations of the runtime that the core suite catches (each reverted): releasing oldest first (5 failures), not marking a transferred token as no longer the scope's (1), a late `own` that does not release (3), a transfer that ignores a decided outcome (1, added after the first mutation run showed it survived), a release budget that is never armed (1), accepting a hidden thenable in adoption (1), a late `own` that does not throw (2), and `activation` not reaching the contexts (19). The development chronology: the specs were written first and run red against the unmodified runtime (every case failed because `atActivation` and `InvocationEndedError` did not exist), then the runtime was written; the mutation run and the decided-but-unreleased transfer spec came after the first green, and the built-consumer page and its browser spec after that.

**Scope.** The shared runtime's ownership mechanics, qualified on the built Lit consumer with a fixture owner. Server actions follow in ACT6.

Run the resource specs with the build in place: `npm run build`, then `npx playwright test e2e/resource-action-binding.spec.ts` in `apps/lit-host`.

### Server actions and the joined contract (ACT6)

ACT6 adds server-call capability to the same `@saga-a2ui/core/actions` runtime (no second runtime, no registry, no handler-name table, no retry layer) and then qualifies the cumulative contract of ACT1 to ACT5 together. Core stays free of MCP: the action takes a `ServerTransport` the application supplies, declared in core by the shape of what it sends and receives. In the example application that transport is the MCP Apps `App` itself. The transport, the server's own handler and every authorization decision stay in the application and in `@saga-a2ui/mcp`.

```ts
export function archiveNoteWith<Event>(noteIdOf: (event: Event) => string, environment: ArchiveEnvironment) {
  return Action.server<Event, CallToolResult>('archive-note', environment.transport)   // `app` is the transport
    .input((event) => ({ noteId: noteIdOf(event) }))
    .before(requireSession(environment))     // the same reusable prerequisites a local action takes
    .before(confirmArchive(environment))
    .before(auditIntent(environment))
    .run(async ({ params, call }) => {
      const reply = await call('archive_note', { noteId: params.noteId });
      if (reply.isError === true) throw new ArchiveRejected('The server declined to archive the note');
      return parseArchived(reply);
    })
    .onSuccess(...).onFailure(...).onCanceled(...)                                      // as for any action; no limits needed
    .build();
}
```

The complete example is `apps/lit-host/e2e/archive-fixture/archive.ts` (test-only application code, one definition for every renderer; only `noteIdOf` depends on the renderer's event).

- **Declaration.** `Action.server<Event, Reply = ServerReply>(label, transport)` starts the same chain as `Action.local` with one difference: the handler context also has `call(name, args, options?)`, where `options` is `{ timeoutMs?, meta? }`. Its work deadline resolves like a local action's, so a server action builds without `limits`. A local handler context has no `call`, by type and at run time. The exported types are `ServerTransport`, `ServerRequest`, `ServerRequestOptions`, `ServerReply`, `ServerCalls` and `ServerCallOptions`; there was no new runtime export.
- **What `call` sends.** The runtime builds the request options. `signal` is the invocation's own signal; `timeout` is the time left on the resolved work deadline, counted from the start of the prerequisites, so time spent in prerequisites is already gone. The handler's third argument can only narrow: `timeoutMs` (finite, positive) is clamped to the time left, and any other field a caller smuggles through a cast (`signal`, `timeout`) is not forwarded. `meta` (a plain object, copied and frozen when the call is made, otherwise a `TypeError` before anything is sent) becomes the request's `_meta` beside, never inside, the arguments; it is per call and shared with no other. `call` returns the transport's reply unchanged: a returned tool-level failure (`isError: true`) is a result, and the runtime does not reinterpret it, so the handler decides what it means. A transport that rejects (a timeout, a lost connection, a host refusal, an abort) rejects `call`, and that reaches the runtime as `handler-error`, or as the deadline's or cancellation's own outcome when that decided first. `call` is invoked as a method of the transport, so an `App` keeps its state, and `Reply` lets a transport keep its own reply type (`CallToolResult` here).
- **When nothing is sent.** A `call` made after the runtime stopped waiting for the handler, after the invocation was canceled, after the work deadline, or after a checkpoint found the subject changed or the instance gone, rejects without calling the transport. The handler never runs while a prerequisite refuses, throws, times out or is canceled, so a protected request is never sent from those stages. The prerequisites' own requests (a session check, a consent prompt, an audit write) are counted apart from the protected request in every test.
- **What an outcome says about the effect.** The runtime reports only how far the handler got, as in the Blueprint's table. A prerequisite-stage or input-stage failure or cancellation: no protected request was sent. A returned tool-level failure that the handler throws on: whatever that tool's own contract says (here "changed nothing"). `handler-error` from a rejected transport, `timeout` in the running stage and `canceled` in the running stage: unknown, with no retry and no invitation to retry. `success-hook-error`, `success-hook-timeout` and `canceled` in the completing stage: the reply was returned, the result is kept on the outcome, and only the client's required work failed or was abandoned. An abort ends the client's wait and leaves the effect unknown: the integration test below has a stalled host that ignores the abort and archives the note afterwards while the view correctly reports an unknown status.
- **Prerequisites are not authorization.** A prerequisite that passes locally never stands in for the server's check: in the integration test the server refuses `n-locked` after the session, confirmation and audit prerequisites all passed, and the application reports `declined`.

**The cumulative contract.** The shared runtime keeps the behavior recorded for ACT1 to ACT5, and the server action takes it unchanged: synchronous and asynchronous local work, ordered reusable prerequisites, both busy policies, per-callback `current()`, immutable outcomes, bounded hooks and finalization, retirement by disposal, replacement, subject change and instance loss, and the ACT5 lease acquisition, release and transfer. `server-actions.test.ts` checks the join for a server action (a lease taken in the event turn and transferred or released across success, a timeout and a cancellation; every hook, the release and `onFinally` bounded by `hookMs`). `authoring-qualification.test.ts` runs the Blueprint's positive and negative authoring cases that the earlier slices did not yet check (P1 to P8, L1, N4, N9 to N11, N17, N18, N23 to N25) against the package's real exports and its own tsconfig rather than the evidence companion's stand-in declarations, and names the suites that check the others (N1 to N3, N5 to N8, N12 to N16, N19 to N22). The renderer-facing cases are the Lit, React and Lynx fixtures themselves, compiled by `npm run typecheck` against the published renderer packages.

**The pinned transport types.** `archive-integration.test.ts` declares `(app: App) => ServerTransport<CallToolResult>` and builds `Action.server<Event, CallToolResult>('archive-note', app)`. They compile against `@modelcontextprotocol/ext-apps` 2.0.3 and `@modelcontextprotocol/client` 2.4.0, the pinned `App.callServerTool(params: CallToolRequest['params'], options?: RequestOptions): Promise<CallToolResult>`, so the Blueprint's stand-ins are replaced by the real types. A transport whose reply has no `content` is a compile error.

**Dependency separation.** Core's own export test bundles `@saga-a2ui/core/actions` and finds `server.ts` in the graph and no MCP, renderer, DOM or other third-party module. The built Lit consumer holds the archive definition and its fixture, which import MCP types only; `view-bundle.spec.ts` (every file under `dist/`, including `dist/action-consumer`) finds no server transport, server registration or credential in it.

**Evidence** (recorded runs are the ones listed under Verification in the pull request, on Node 26.7.0, npm 12.0.2 and Chromium 156.0.8078.4 through Playwright 1.64.0):

- `packages/core/src/actions/server-actions.test.ts` (27 tests, renderer-free adapter, controlled clock, a transport double the test answers): request timing and options, refusal, the shared prerequisite, narrowing and smuggled options, bypassed types, every way a server action ends (success, returned tool failure, rejected transport, success-hook failure and overrun, deadline with a late reply dropped, the transport's own timeout, disposal, replacement, cancellation and deadline during a prerequisite, a late `call`, a changed subject), both busy policies, two instances of one definition under one component id, the type cases, and the joined lease and budget cases.
- `packages/core/src/actions/authoring-qualification.test.ts` (2 tests, compile-time cases) and `exports.test.ts`.
- `apps/lit-host/e2e/archive-fixture/archive-integration.test.ts` (8 tests, `npm run test:headless`): the real `App` is the action's transport, a real `AppBridge` over an in-memory pair is the host, and the host forwards through a real MCP `Client` to a real `McpServer`. Two repeated rows archive their own notes once each; the server refuses what the prerequisites allowed; a refusing session sends nothing to the host; a rejecting host leaves the status unknown without a retry offer; a failing required hook keeps the archived result and sends no second request; a stalled host shows the work deadline reporting an unknown status while the host's late forward still archives the note; a retired row aborts the request's signal and presents nothing; the SDK's own timeout, narrowed through `timeoutMs`, ends as a failed handler with the effect unknown.
- `apps/lit-host/e2e/server-action-binding.spec.ts` (8 tests, built Lit consumer, `?scenario=server`): real clicks on two rows that render one component id, an upstream protocol Button in the same surface, and a page-owned environment the spec answers step by step. Each activation reaches the callable once; the upstream button neither starts it nor is dropped, and a protocol `action` on the bound control is rejected whole; a refusing session, a prerequisite still pending when the surface is retired, and a row that now shows another note all send no protected request; the declined, rejected, success-hook-failure and retired-surface outcomes show what each establishes and never invite a retry for an unknown effect.
- `packages/react/src/actions/server-actions.test.ts` (3 tests, jsdom 28.1.0, React 19.3.1): the same runtime on the React adapter.
- Hand mutations of the runtime that the new suites catch (each reverted): the request carrying no signal (6 failures across the core and integration suites), `call` skipping its checkpoint (1), `call` skipping its eligibility guard (1).
- Full verification of the final head, with the unchanged consumers' evidence rerun: type checking, builds, 803 headless tests, 187 Lit and React browser tests and 58 Lynx Web browser tests, test discovery, static guard and version enrollment.

**Development chronology.** The core tests for `Action.server` were written first and run red against the unmodified runtime (every case failed with `Action.server is not a function`), then `server.ts`, the builder and `call` were written. The outcome, cancellation, busy-policy and join cases exercise rules the earlier slices already implement; the mutation runs above show they can fail. The authoring qualification file, the real-stack integration test, the built consumer scenario and its spec, and the React cases followed once the core was green.

**Scope.** The real `App`, `AppBridge` and MCP server are connected in one process; the browser spec and the React cases use a transport double. Play's recipient metadata mapping, real-player lease and spanning bound stay with their existing owners (CORE2, CORE3, VIEW2, STATE1 and STATE2); no controller safeguard is removed here, and the application listener and the reusable connector's request-lifetime contract (CORE3) are untouched. This is the last shared-contract slice before the existing consumers migrate.

Run the server-action tests with the build in place: `npm run test:headless`, then `npm run build` and `npx playwright test e2e/server-action-binding.spec.ts` in `apps/lit-host`.

### Configurable action defaults and error categories

This amendment ([action binding Blueprint](../blueprints/modules/action_binding.blueprint.md#bounds-the-work-deadline-and-the-hook-budget), design revision `564bcb2a13dd162515a80e7f491d2870990958ab`) replaces the mandatory explicit limits of ACT4 to ACT6. It changes the one shared module in `@saga-a2ui/core/actions`; there is no registry, mutable global, second API or retry layer. A local or server action, with hooks and owned resources, now builds and runs without declaring any limit.

```ts
const host = createInstanceHost({ onSetupError, limits: { deadlineMs: 45_000 } });   // this SDK instance's defaults

Action.server<Press>('archive', transport)
  .run(({ call }) => call('archive_note', {}))
  .limits({ hookMs: 2_000 })        // this action's override of one setting
  .onSuccess(recordArchived)
  .build();                          // work deadline 45,000 ms (instance), each hook or release step 2,000 ms (action)
```

- **Resolution.** Each setting resolves on its own, in this order: the action's `limits` override, the configuration of the SDK instance that owns the binding, then the default (`deadlineMs` 30,000 ms, `hookMs` 5,000 ms). Omitting a setting (or passing `undefined`) inherits it; it never disables a bound. The definition holds only its own override, so one definition bound under two instances uses each instance's values. An instance is the `InstanceHost`: pass `limits` to `createInstanceHost`, to `createLitActions({ attach, onSetupError, limits })` (each presentation's host gets the same values) or to the React `InstanceHostProvider` (fixed for the provider's lifetime, checked when it first renders). The Lynx fixture sets none and runs on the defaults.
- **Validation and snapshots.** A supplied value must be a finite number greater than zero. Zero, negatives, `NaN`, infinities and non-numbers throw a `TypeError` where they are supplied (`limits(...)`, `createInstanceHost`, `createLitActions`, the provider, or `snapshotLimits`), before any binding, activation or effect, even when another layer would have overridden the value. Every supplied object is copied: changing it afterwards, even during an invocation, changes nothing. An invocation's limits are resolved once when its binding is made, from immutable inputs.
- **Bounds.** `deadlineMs` starts when the synchronous activation prefix ends and is shared by the prerequisites and the handler; progress never extends it, and a late result cannot revive the invocation. `hookMs` is separate for `onSuccess`, the outcome hook, each resource release (including a late acquisition's) and `onFinally`. With the defaults, an invocation whose failure hook, release and `onFinally` all stall settles 45 seconds after it started. Timers cannot interrupt blocked JavaScript, a synchronous action still completes synchronously with no timer, a limit longer than one platform timer can span (about 24.8 days) is waited out in consecutive timers, never shortened, and a handler cannot widen `call`'s request below the time left or a narrower transport limit.
- **Error categories.** Every `failure` now also carries `category`, beside its `kind`, the `stage` and any kept `result`. Known names are `timeout`, `canceled`, `authentication-required`, `permission-denied`, `unavailable`, `validation`, `application` and `unknown`; the type is open, so handle a name you do not know. A category comes from evidence only: the runtime's own decisions (a deadline or hook overrun is `timeout`, a refusal is `application`, unreadable input is `validation`), the platform's own `DOMException` of name `TimeoutError` or `AbortError` (what `AbortSignal.timeout` and an aborted `fetch` reject with; an ordinary `Error` that merely carries that name is not one), or an `ActionError(category, message, { cause })` that an application throws when it knows (a 401, a typed server error). Anything else is `unknown`; an unfamiliar error, its message or a `status` field is never read as authentication. The original thrown value stays on `failure.error` (an `ActionError` keeps what it wrapped as `cause`). The SDK shows none of it: choosing a safe message is the application's, and `ObservedEvent` is unchanged.
- **What an outcome says about the effect.** Unchanged and now tested together with the categories: a failure before the handler started sent no handler request; a `handler-error`, a work `timeout` or a cancellation while running leaves the effect unknown (no rollback is implied, no retry is offered or attempted); `success-hook-error` and `success-hook-timeout` keep the handler's result, so a known write followed by a client-step failure is reported as such and is never replayed.

**Migration.** `ServerLimits` is removed (`Limits` has two optional members), a hook, a held resource and a server action no longer need `limits`, and `scope.own` no longer throws without them. The archive example, the Lit and React consumers and the Lynx fixture declare no limits except where a test needs a value.

**Evidence** (Node 26.7.0, npm 12.0.2, Chromium 156.0.8078.4 through Playwright 1.64.0): `packages/core/src/actions/action-limits.test.ts` covers the amendment table through the public builder, instance host and binding with a controlled clock (defaults for a local and a server action, the seven precedence cases, isolation and snapshots, every invalid value at every layer including shadowed ones, the 45-second separate-cleanup timeline, a work deadline that progress cannot extend, a longer override meeting a shorter transport limit, the categories, known success after a hook failure, unknown effects) and its type cases; `packages/lit/src/actions/lit-actions.test.ts` and `packages/react/src/actions/instance-host-limits.test.ts` cover the adapter seams; the earlier suites were migrated to the new contract, and the built Lit, React and Lynx Web browser suites pass unchanged in behavior. The red-green order was followed for the core and adapter tests: they failed first because the API did not exist. Hand mutations of the runtime that the suites catch (each reverted): the instance configuration beating the action's override (3 failures), the timer delay capped at one platform span instead of chained (3), `null` read as an omitted setting (7), an ordinary error carrying a platform error's name accepted (1), a `status: 401` read as authentication (1), the late-release path ignoring the resolved `hookMs` (1), hooks timed by the work deadline (21), and the work deadline restarted at the first wait instead of the end of the prefix (1). The last three of those survived the first mutation run, and the tests that catch them were added after it.

**Scope.** Local qualification of the shared runtime and the Lit and React seams. The numbers are product defaults; HTTP status mapping belongs to STATE2 ([#13](https://github.com/MachineWisdomAI/saga-a2ui/issues/13)).

### The action contract across the current codebase (ACT7)

ACT7 ([#83](https://github.com/MachineWisdomAI/saga-a2ui/issues/83)) is the integration audit that precedes packaging. Its current-codebase scope is implemented and accepted through [PR #145](https://github.com/MachineWisdomAI/saga-a2ui/pull/145), landed at `a704da4d2b76204a8b15dd0cb89ecfacc5ad101a`; the [lifecycle record](../blueprints/modules/action_binding.blueprint.md#status) identifies independent review, affected fixture checks and reused evidence. It adds no runtime and no second API: it checks the delivered action contract (ACT1 to ACT6, the action defaults, CORE2, CORE3 and VIEW2) against the [migration rules](https://github.com/MachineWisdomAI/saga-a2ui/blob/cdad54747dfbba756464676ac3b1b8c90148a566/blueprints/modules/action_binding.blueprint.md#migration-rules), repairs what the audit found, and says what each claim rests on. Vocabulary follows the [module](../blueprints/modules/action_binding.blueprint.md#component-terminology): a *component type* is a kind of control, a *definition* the ID-bearing layout entry (a *template* repeats it per *data item*), a *rendered instance* one component a renderer created, and a *binding* one action definition attached to one event of one instance; an *invocation* is one activation of a binding, which may hold *resources* and make a server *request*. The landed sources it consumes are recorded in the [module Status](../blueprints/modules/action_binding.blueprint.md#status); this section is the current-state reading, and the per-slice sections above stay pinned to their own deliveries.

**What the code supports**:

| Surface | Supports |
| --- | --- |
| `@saga-a2ui/core/actions` | `Action.local` and `Action.server` builders, prerequisites, bounded hooks, activation-scoped resources and transfer, busy policies, `subject` freshness, optional `limits` (30,000 ms work, 5,000 ms per hook or release by default), error categories, `createInstanceHost`. Imports no renderer, DOM implementation or MCP package, and has no registry, handler-name table, global bus or retry layer |
| `@saga-a2ui/lit/actions`, `@saga-a2ui/react/actions` | Opt-in `ActionButton` (shared schema in core), per-presentation or per-provider host, direct attachment through `watchById`/`bindAction`. The main `@saga-a2ui/lit` entry imports no action code |
| `@saga-a2ui/mcp/{server,view,policy}` | Verified request identity, one request lifetime, bounded operations, the view bridge with `onTeardown`/`dispose` |
| Play (`apps/lit-host`) | One protected `Action.server` bound to the control's own instance (mapping A), application-owned lease and Web Audio player, Pause and Resume as local actions; ChatGPT and Claude observations are in receipt [6275325996](https://github.com/MachineWisdomAI/saga-a2ui/issues/15#issuecomment-6275325996) |
| Lynx | Retired by the owner on 2026-10-19; `apps/lynx-fixture` remains as ACT3 qualification history |
| Named hosts | The receipts the Blueprints cite (CORE2 and STATE2, ChatGPT web and Claude web) |

**Traces** (each step names the file that does it).

- *A local action.* The layout names an `ActionButton` and carries no action (`apps/lit-host/e2e/action-consumer/main.ts`). `ActionButtonElement` opens its instance on the presentation's host when its controller exists (`packages/lit/src/actions/action-button.ts`), `createLitActions` runs the application's `attach` once, and `attach` finds the instance with `view.watchById(id, ActionButton, ...)` and binds with `handle.bindAction('activate', definition, { subject })`. The element's click calls `instance.activate('activate', event)` synchronously, so the binding admits the event, the runtime runs input, `atActivation`, prerequisites, the handler and the hooks, and the binding reports state. Retiring the instance (the element leaving the document, a surface replacement, `host.close()`) disposes the binding and cancels an undecided invocation.
- *The repeated-row server Archive flow.* The layout repeats `row-archive` per note, so two instances share a component ID and differ in `dataPath`. `archiveNoteWith` (`apps/lit-host/e2e/archive-fixture/archive.ts`, test-only application code and not a shipped API) reads the note from the pressed instance (`event.read('id')`), runs the session, confirmation and audit prerequisites, then `call('archive_note', ...)` through the application's `ServerTransport`, which is the MCP Apps `App`. A changed `subject` cancels an undecided invocation; every outcome reports what it establishes about the effect; releases and `onFinally` run last. `archive-integration.test.ts` and `server-action-binding.spec.ts` exercise it.
- *Protected Play.* `playback-main.ts` creates the instance host and `PlayControlElement.host` opens the control's instance. `connectPlaybackView(...).attach` binds `play`, `pause` and `resume` with `subject: () => selection`. Play's prefix selects the item, takes a lease from `player-owner.ts` and unlocks audio inside the click; two prerequisites (host capability, recipient key) precede the handler; the handler calls the protected tool with the recipient key as per-call `_meta`, validates the grant (`acceptable`), acquires the bytes and starts the player; on a confirmed start the lease transfers to the owner. Authorization, grant validation, the lease and the player stay in the application; `@saga-a2ui/mcp` keeps the connection and the request lifetime. Host teardown disposes the bindings and the owner stops the audio; the later `dispose()` closes the connection once.

**Audit of the invocation paths.** Every `Action.local` or `Action.server` use in a shipped entry point is Play's. The other users are fixtures (`action-consumer`, `react-action-consumer`, `own-catalog-consumer`, `archive-fixture`, the Lynx fixture), and each binds through `watchById`/`bindAction` on a direct instance. No activation-time handler lookup, `Map` or string-keyed action table, event bus or compatibility shim exists in the packages, the application or the examples; the upstream registrations that remain are the catalog and custom-element setup at the Lit seam (`defineElements`, `Catalog`). The audit repaired one code leftover and the stale descriptions. `PLAYBACK_ATTEMPT_LIMIT_MS` was a leftover of the pre-migration controller's own attempt bound: CORE2 replaced that bound with the action's work deadline, nothing referred to the constant, and its comment described an override that no longer exists, so it is deleted. The PLAY1 and STATE1 sections above, `docs/authorized-playback.md`, `packages/README.md` and the core and Lit package descriptions still described the pre-migration controller (a generation number and `attemptLimitMs`; "Play has not migrated"); they now describe the delivered path.

**Retained owners, with their evidence.** These are deliberately not action invocations, and ACT7 does not convert them.

| Owner | What it keeps | Where to see it |
| --- | --- | --- |
| Read controller (`apps/lit-host/src/mcp/subscriptions-view.ts`) | Incoming tool notifications (`toolinput` and `toolresult` through `runToolResultView`), correlated read and retry settlement (its never-reused read number and its read timer), and current-row selection. `subscriptions-main.ts` wires `retry` and `select` with setup-time `addEventListener` | `subscriptions-view.test.ts` ("stays cleared after a failure until a correlated authenticated response arrives", "an older in-flight read cannot take a later read's identity after a refusal"); it was never an action path |
| Content owner (`@saga-a2ui/components` image consent, `@saga-a2ui/lit/faithful-card`, `@saga-a2ui/react/faithful-card`) | Show and Hide images, link activation and the content-view request, as direct content callbacks with revocable consent | `image-consent.test.ts`, `description-strict.spec.ts`, `react-faithful-card.spec.ts` |
| Listener and resource service (`packages/mcp/src/server/lifetime.ts`, `apps/lit-host/src/mcp/listener.ts`, `media-service.ts`) | The request deadline, the operation limit, finite-response delivery and capability expiry (60 s) | `lifetime*.test.ts`, `request-budgets.test.ts`, `playback-budgets.test.ts` |
| Player (`web-audio-player.ts`, `player-owner.ts`) | The audio-clock start bound for one step and the lease rules for the current player | `web-audio-player.spec.ts`, `player-owner.test.ts` |
| Application spanning bound | None remains. Play's work deadline spans key creation through the start of audio; `HOST_CALL_SAFEGUARD_MS` (60,000 ms) only mirrors the MCP Apps client's own timeout and never widens the remaining work time | `playback-view.test.ts` ("the bound on one Play attempt") |

**Package entry points and dependency direction** were read from source and package manifests for this audit. Core imports `@a2ui/web_core` and Zod only; `mcp` imports MCP packages and Zod and nothing of core or any renderer (at the time of this audit; MCP delivery now imports core for the neutral delivered-result and host-link contracts, and "Consumer boundary scan and package directions" gives the current rows); `components` imports core, upstream and a Markdown parser; Lit and React import `@saga-a2ui/components` only inside their `faithful-card` exports, and declare it an optional peer. Executable checks keep this true: the core export test (the bundled graph has no renderer, MCP or DOM runtime), `packed-consumer.test.ts` (an own-catalog consumer built from packed core and Lit has no FaithfulCard, Markdown parser or server code), `installed-lit-host.test.ts` and `view-bundle.spec.ts` (built views carry no server module or credential). The shipped surface is exactly what `packages/core/src/actions/index.ts`, `packages/lit/src/actions/index.ts` and `packages/react/src/actions/index.ts` export. The Blueprint's declarations that are not exported there (its `askToArchive`, `showArchived`, `Instance*` sketches and the evidence companion) are design illustrations and not a shipped API.

**Which harness proves which claim.**

| Claim | Harness |
| --- | --- |
| Local and server actions, outcomes, cleanup | `packages/core/src/actions/*.test.ts` (renderer-free), `action-binding`, `async-action-binding`, `resource-action-binding` and `server-action-binding` specs (built Lit consumer), `archive-integration.test.ts` (real `App`, `AppBridge` and MCP server in one process) |
| Play, authorization and recovery | `playback-view.test.ts` (real `App`/`AppBridge` forwarding to the real listener), `playback-view.spec.ts` (built view in the local host fixture, real Web Audio); the CORE2 receipt for the ChatGPT and Claude flow it observed |
| A remounted view replaces the old one | `mcp-view.spec.ts` ("remounting the view delivers each result once"): the fixture removes the old iframe |
| Two live views stay apart, and tearing one down leaves the other unchanged | `mcp-view.spec.ts` ("two live views keep their own results..."): two frames and two `AppBridge` instances in different fixture slots at once; headless two-`App` cases in `playback-view.test.ts` and `subscriptions-view.test.ts` |
| Renderer-instance isolation | `catalog-isolation.spec.ts`, `app-element-lifecycle.spec.ts`, the instance-host limit tests |
| The consumer request and failure path (CORE3) | `scripts/request-consumer.test.ts`, `packages/mcp/src/server/request-lifecycle.test.ts`; CORE3's [receipts](../blueprints/features/reusable_mcp_connector.blueprint.md#status) |
| Installed-package behavior | `npm run build:installed-lit-host` and the `dist-installed` specs (VIEW2) |

The local host fixture used to mount one iframe and replace it on remount, so it could only prove replacement. It now mounts views in named slots (`mountView(resource, { slot })`, `deliverToolResult(result, slot)`, `teardownView(slot)`); the default slot behaves as before and every earlier specification is unchanged.

### Installing the SDK and the Lit example from packed artifacts (PACK1)

This PACK1 delivery ([#21](https://github.com/MachineWisdomAI/saga-a2ui/issues/21), [PR #153](https://github.com/MachineWisdomAI/saga-a2ui/pull/153), actual merge `55b99684f8569b994c744de490a134bc6cda90fd`) contributes to the packaging join of the delivered pieces: the action runtime (ACT1 to ACT7), the request contract (CORE3), the installed Lit application (VIEW2) and the optional FaithfulCard (CARD1, CARD2). It installs the actual tarballs outside the repository, in two separately installed consumers of one synthetic notes application (`examples/pack1-consumer`, outside the npm workspace like the other examples), and qualifies the packages and both consumers. It adds no runtime, registry, export, dependency or package, and reuses the existing harness (`scripts/packed-consumer.ts`). A packed tarball carries a version that exists only in a scratch copy (a throwaway `0.0.0-packed-test` at this delivery, the candidate prerelease identity since PACK2, below).

**The two consumers** (`scripts/build-pack1-consumers.ts`; each is built in its own clean directory from its own `npm pack` tarballs, with only the third-party packages those manifests declare linked in):

| | `own` | `card` |
| --- | --- | --- |
| Installed SDK packages | `core`, `lit`, `mcp` | `core`, `lit`, `components`, `mcp` |
| Catalog | the application's own `Line`, upstream `Column`, `Row`, `List` and SAGA's `ActionButton` | the same, plus `faithfulCardEntry` for each note's body |
| Page and server | `own.html`, `server.mjs` | `card.html`, `server.mjs` |
| Excluded by construction | the components package, the Markdown parser, the card element and catalog entry, and the file that uses them | the first consumer's entry file |

Both pages and both servers come from the same application source. The two bundled servers are byte for byte the same apart from the comments naming their scratch directories, so one authorization and disclosure boundary serves both, and the shared packages (`core`, `lit`, `mcp`) have the same tarball digest in both installs. The application's server (`examples/pack1-consumer/server`) declares `list_notes` through `registerProtectedOperation`, and `check_session` and `archive_note` as app-only tools; it will not start without the built page (`ViewArtifactMissing`), and the page's identity is the SHA-256 of the exact bytes it serves.

**Version, peer, resource and catalog relationships** (asserted by `scripts/pack1.test.ts` against the packed manifests, so a change to any of them is a reviewed change to this table):

| Relationship | Declared |
| --- | --- |
| Upstream A2UI | `@a2ui/web_core` 0.13.0 in `core`, `lit`, `components` and `react`; `@a2ui/lit` 0.13.0 in `lit`; `@a2ui/react` 0.13.0 in `react` |
| Zod | Zod 3 only as core's `zod3` alias (`npm:zod@3.25.76`, for A2UI catalog schemas); Zod 4.6.7 in `components` and `mcp` |
| MCP set | `@modelcontextprotocol/client`, `core`, `server` 2.4.0 and `ext-apps` 2.0.3, all in `mcp` and nowhere else |
| Between SDK packages | range `*` in the repository, resolved by installing the packed copy; any other form (`workspace:`, `file:`, `link:`, a path, a URL) fails. Since PACK2 the packed copy pins the exact candidate version instead of `*` |
| Optional components | `lit` and `react` name `@saga-a2ui/components` only as an optional peer (`*`); `core`, `mcp` and `components` name no renderer; `markdown-it` 15.0.3 belongs to `components` alone |
| React | peers `react` and `react-dom` `^19.3.1`; `./faithful-card.css` is a named export, not a file path |
| Resources | every `exports` target is a shipped file; every relative import and resource in shipped source resolves inside its own tarball; every bare import is a declared dependency or peer, or a public export of an owned package; no test or support file ships |

The test also fails if a dependency of the MCP-UI, CopilotKit, AG-UI or Ora stacks appears in a manifest or a consumer graph. The only overlap with those products is shared standards (MCP, MCP Apps, A2UI).

**What each entry point may load** (`scripts/pack1.test.ts`, built from the installed copies; "runs" means the bundle was executed):

- *Server imports without renderer code:* `@saga-a2ui/mcp/server`, `/policy` and `@saga-a2ui/core/actions` bundle for Node with no Lit, upstream renderer, React, components or Markdown parser, and run with no `document`, `window` or `HTMLElement`.
- *Browser imports without Node or server code:* the view side (`main-own.ts`) bundles with the view connection only: no `mcp/server` or `mcp/policy` module, no `@modelcontextprotocol/server` or `node`, no Node built-in import, no backend or credential marker.
- *Neutral components without MCP, renderer or DOM:* the FaithfulCard reader, policy and consent scope, and the action runtime with a local action bound to an instance, bundle and run in plain Node with no MCP package, no renderer and no DOM.
- *Optional catalog behavior:* the `own` page's graph holds no components module, no FaithfulCard element, catalog entry or parser; the `card` page's graph holds all three.

**The browser flow** (`apps/lit-host/e2e/pack1-consumers.spec.ts`, once for each consumer, Chromium through Playwright). The page under test is the one that consumer's own server serves over a real Streamable HTTP MCP connection, mounted by the local host fixture in its sandboxed iframe (`sandbox="allow-scripts"`, opaque origin) under the CSP the server declared (a closed view). Its `tools/call` requests go through the fixture's real `AppBridge` to the same server.

- *Resource and policy.* The tool result links the SHA-256 URI of the built bytes; `resources/read` returns those bytes; the two view-only tools are `visibility: ['app']`. Allowed: results arrive and the view calls the server over the bridge. Denied: from inside the frame a `fetch` to another origin, an image from another origin and `new Function` are each blocked and each reports a `securitypolicyviolation` for `connect-src`, `img-src` and `script-src`. The body of a note, which carries a tracking image and a link, fetches nothing in either consumer; in `card` the link leaves only as the host's `ui/open-link` request, in `own` it is text.
- *Authorization and disclosure.* Private backend fields (a canary) reach neither the wire nor the DOM; another account's note is never shown; an unauthenticated call gets the sign-in sentence and no data. The server decides every `archive_note` itself: after the session check passed, withdrawing the account's permission still gets a refusal; an absent note and another account's note get one identical sentence, so nothing tells them apart; an account named in the arguments is rejected.
- *One definition, two rendered instances.* `archiveNote` is built once and bound with `watchById`/`bindAction` to each row's own `ActionButton` instance; the layout names no action. Both rows pending at once make two session requests and two protected requests, count apart, and each row's result, status and hold arrive on its own row whichever answers first. A press while a row is pending sends nothing. A local action (`mark-read`) on the same rows sends no request.
- *Prerequisite, item change, disposal.* An asynchronous session prerequisite that refuses leaves the protected request count at zero. When the list is replaced so a row shows another note, the in-flight archive is canceled, the server still applies it (so it is reported to nobody on that row) and the row shows nothing; the row then archives its new note. Tearing the view down while a request is pending removes the notes element, gives the hold back, and a late reply presents nowhere.
- *Application-owned resource.* The archive takes a hold (`row-holds.ts`) in `atActivation` with `scope.own`; the scope gives it back on every non-success end, and `onSuccess` hands it to the application's owner with `transfer`. The page shows both lists.

Mutations of the source that the checks catch (each reverted): a `file:` range for a SAGA dependency in the Lit manifest fails the leak check, and binding the archive without its `subject` lets the late result present on the new item and fails the item-change case for both consumers. Removing the success hook's own `current()` check changes nothing, because the runtime does not call `onSuccess` for an invocation it already canceled; the check is a second guard and not what the case depends on.

Run it (the same commands CI runs through `npm run verify`):

    nvm use && npm ci
    npx playwright install chromium
    npm run build                                  # includes npm run build:pack1-consumers (apps/lit-host/dist/pack1, with identity.json)
    npx vitest run --config vitest.config.ts scripts/pack1.test.ts
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/pack1-consumers.spec.ts

`apps/lit-host/dist/pack1/identity.json` (ignored) records the source commit (and whether tracked files were dirty), platform, Node and npm versions, each tarball's SHA-256 and each built page's and server's SHA-256. Quote it with the PR head in an acceptance record rather than committing it.

**Environments.** Reproduced on Linux x64 (Node 26.7.0, npm 12.0.2, Playwright 1.64.0 with Chromium revision 1248), and by the Linux CI job (`ubuntu-latest`, `npm run verify`), which now builds the consumers, runs `scripts/pack1.test.ts` and the browser specification. Independent macOS arm64 review subsequently ran the 12 packed-headless and 20 browser cases, then rebuilt both repaired consumers and passed 16 affected repair/browser cases and client/server type checking on Node 24.14.1/npm 11.11.0. Unchanged earlier results were reused; the [lifecycle record](../blueprints/features/reusable_lit_adapter.blueprint.md#status) separates exact repaired-head and reused evidence.

**Reused, not repeated.** The runtime's exhaustive matrices (ACT1 to ACT7, CORE3's transport and failure map, CARD2's reading and zoom cases) keep their own suites and acceptance records; PACK1 adds one representative case of each integration seam through public imports and does not copy them. The earlier packed own-catalog check (`e2e/own-catalog-consumer/packed-consumer.test.ts`), the answer consumer, the installed Lit application set (`dist-installed`, VIEW2) and the React packed consumer are unchanged and still run.

**Completed PACK1 join.** The complete external authenticated browse/Play application listener and matching installed resources are qualified by the next section (#154); its independent exact-head review and macOS result are recorded in its pull request, not here. The notes consumers prove their own full paths; earlier installed browse/Play browser tests used the workspace application listener. The [lifecycle record](../blueprints/features/reusable_lit_adapter.blueprint.md#status) reconciles all nine criteria with the actual source revisions and retained evidence.

**Scope.** These two notes consumers are hosted by the test's Streamable HTTP listener with a header-based test authenticator; the application's own browse and Play listener is qualified in the next section. The backend is synthetic. The installed set is a Lit qualification; the React consumer follows in REACT1, and PACK2 adds the candidate update and rollback procedure.

### The browse and Play listener, installed and run outside the repository (PACK1 #154)

[#154](https://github.com/MachineWisdomAI/saga-a2ui/issues/154) completes the protected server-and-view join that the two notes consumers above leave open. [PR #156](https://github.com/MachineWisdomAI/saga-a2ui/pull/156) landed as `0ebc4a11b8232e337b3cfe0abdb7efc68c330ac1`; the [reviewed lifecycle mapping](../blueprints/features/reusable_lit_adapter.blueprint.md#status) reconciles all nine PACK1 criteria, independent macOS 15 headless/four browser checks, passing Linux CI and reused host evidence. The application's own synthetic browse and Play listener (`apps/lit-host/src/mcp/serve.ts`, the entry `npm run serve:mcp` runs) is bundled from a copy of the application source into the same clean directory outside the repository as its views, against the same packed `core`, `lit`, `components` and `mcp` tarballs, and then started there as its own Node process. It adds no package, export, harness or runtime. The notes consumers, their `own`/`card` specifications and the installed Lit pages are unchanged and still run.

What changed in the code: `scripts/build-installed-lit-host.ts` also bundles the listener (`buildInstalledHost`, `startInstalledListener`) and records it in the existing ignored `apps/lit-host/dist-installed/identity.json`; `serve.ts` reads its views from `SAGA_VIEWS_DIR` when set (unset, from `dist` as before) and, as before, reads all of them before it opens its port.

- *Installed, not linked.* The consumer's own manifest declares nothing; `@saga-a2ui/{core,lit,components,mcp}` are unpacked tarballs, not symlinks. Every third-party package is linked at the exact version the installed manifests declare, and the repository's stated Node floor is checked. The bundle carries the SDK from installed copies only (every module is classified by canonical path; a workspace SDK or application module fails the build), imports no `@saga-a2ui/*` package at run time, and every other run-time import is a declared package.
- *Ready only with the real views.* The process prints its URL after it has read all four built views. A missing `playback-view` or an empty views directory ends it with a non-zero status before it listens.
- *Served bytes are the installed views.* `resources/read` returns, byte for byte, the playback and subscriptions documents built beside the listener; the public episode view is served at its policy and major address, and its document is the built view plus the head elements of the content policy. The served documents contain no server module, credential, Node import or backend implementation.
- *The path, over HTTP to that process.* Browse: no, invalid, expired and service-only credentials get the documented 401/403 with a challenge and no data; each user sees only their own subscriptions whatever account the arguments name. Opener: the public episode and an opaque `vs_` label. Play: called directly with only `{ episodeId }` and the recipient public key in `_meta`; the capability is only in the private `_meta`, the model-visible text is one fixed sentence; a forged `accountId` is rejected and not echoed; without the key nothing is issued; another user, an unknown episode and an episode without access get the same denial sentence. Media: the capability and a fresh proof from the key it was issued to release the bytes; a capability alone, another holder's key, a proof for another URL, another episode and a replayed proof each get the same `403`. The process's output contains no token, capability or key. This is one representative case of each seam; the exhaustive timing and security matrices stay with `playback.test.ts`, `media.test.ts`, `subscriptions.test.ts` and `request-*.test.ts` against the in-process listener.
- *The built player against that process* (`e2e/installed-listener.spec.ts`, run with `SAGA_BUILT_DIR=dist-installed`, so the host fixture is the installed one too): the view mounted from the listener's own `resources/read` result plays for the entitled user, the audio clock advances after a direct Play and one `200` media read from the listener, and nothing else leaves the page; a user without access sees the denial and the media path is never requested; a refused credential is unconfirmed rather than a denial, and opening again as the entitled user recovers; a host that drops `_meta` gets the unsupported view.

Run it (the same commands CI runs through `npm run verify`):

    npx vitest run --config vitest.config.ts scripts/installed-listener.test.ts scripts/installed-lit-host.test.ts
    npx tsx scripts/build-installed-lit-host.ts      # also writes apps/lit-host/dist-installed/identity.json
    SAGA_BUILT_DIR=dist-installed npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/installed-listener.spec.ts

`identity.json` (ignored) now also records the listener bundle's SHA-256, where each of its modules came from, its run-time imports and the playback document's SHA-256 beside the CARD2 value `7ea1d8d0d696a20921896d1df45905cd22455f5f17fa20cd1d41243591224afd` (`playbackView.matchesCardTwo`). The comparison is recorded for review: a different value names a changed host-facing document. The cases above qualify the server join.

**Scope.** Authentication is the application's `OAuthTokenVerifier` seam with the development-only verifier and its fixed public tokens, sent as a bearer header; a production deployment supplies its own verifier. The backend and media are synthetic (a generated tone). The CARD2, CARD1 and CORE2 host receipts are reused for the unchanged seams. The test's HTTP client reuses the proof signer and fetch helpers of `playback-fixture.ts`, which also import the in-process listener module; that module is not the listener under test. The listener is a loopback process started by the test. macOS and Linux results are reported per run in the pull request.

### Browsing the notes workflow through React (REACT1)

[#28](https://github.com/MachineWisdomAI/saga-a2ui/issues/28) puts the authenticated notes browse of the two Lit consumers above (`list_notes`, then Archive and Mark read on each row) behind a React renderer, without a second application. `examples/pack1-consumer` now builds a third consumer, `react`, from the same contract, server, action definitions, row-hold owner, surface messages and view controller; only the rendered surface differs. It adds no package, export, dependency or runtime to the SDK, and it qualifies the shared seam through a normal React project.

| | `own` / `card` (Lit) | `react` |
| --- | --- | --- |
| Installed SDK packages | `core`, `lit`, `mcp` (and `components` for `card`) | `core`, `react`, `mcp` |
| Catalog | `notes-catalog.ts`: upstream Column, Row, List, the application's `Line`, `ActionButton` | `notes-react-catalog.tsx`: the same upstream contracts built with `createComponentImplementation`, the application's `Line`, `ActionButtonEntry` |
| Renderer composition | `notes-view.ts`: `createA2uiAppElement` and `createLitActions` | `notes-react-view.tsx`: a React root, `InstanceHostProvider`, `useActionSetup` and the published `A2uiSurface` |
| Shared by all | `notes-contract.ts` (wire contract, fixed sentences, `readNotesResult`), `notes-line.ts` (the `Line` roles; each catalog states the schema with its stack's `z3` and `CommonSchemas`), `notes-surface.ts` (layout and data messages), `notes-actions.ts` (`archiveNote` and `markRead`, defined once), `row-holds.ts`, `notes-controller.ts` and `server/` | |

What is shared and what is not: `notes-controller.ts` owns what does not depend on the renderer: the page's status line and logs, the hold owner, the application's actions, replacing the notes a result carries (an error or a result the contract does not accept shows none of it, and the next valid result shows its own notes), and the one retirement that a host teardown and the page going away both use. The renderer supplies a three-method surface (`show` a whole notes list, `ingest` a row's status message, `remove`). The host-triggered `list_notes` delivery stays a controller-owned read: it is not an action and nothing binds it. The same two definitions (`archiveNote`, `markRead`) are bound to every rendered row through `watchById`/`bindAction`, with the archive's `subject` reading the row's `id` from its own data scope, in `notes-react-view.tsx`. The layout names no action and no handler. `ActionButton`'s event type is now core's `InstanceEvent<Event>` (both renderers' controls deliver exactly that), so the definitions import no renderer.

The React view owns one provider and one root. `remove` unmounts the root, which retires every instance and disposes every binding (cancelling what is undecided and giving back the holds), and then releases the message session; results arriving afterwards are ignored. A setup that throws is reported to the provider's sink, shows the problem sentence, reaches a boundary that renders nothing, and leaves nothing bound.

**Browser flow.** `apps/lit-host/e2e/pack1-consumers.spec.ts` now runs for three consumers, so every case below runs for React unchanged: the served page byte for byte, linked from the result under a closed policy; only the public fields, only to the owning account; a result from another server build refused with guidance and none of it rendered, with recovery; a hostile body shown as text and fetching nothing; the sandbox's network, image and eval refusals; one archive definition on two rendered rows keeping each row's pending state, request and result apart; the local action sending nothing; the asynchronous session prerequisite refusing before the protected request; the server deciding every protected request itself; a failure that may follow an applied archive staying unknown; a late result not presenting on a row that now shows another note (the case that needs the `subject`); disposing the view while a request is pending; and the page going away. The strict-schema refusal of a layout that names an action, which the Lit consumers probe through the app element's `ingest`, is checked for React on the real React runtime in `packages/react/src/actions/actions.test.ts`, because the React page exposes no such handle. The candidate rehearsal (`candidate:rehearse`) rebuilds the two Lit combinations a candidate records, so the spec looks for the React consumer only outside a rehearsal's directory.

**Lifecycle cases.** ACT2's jsdom and browser suites already verify the Strict Mode, discarded-render, keyed and root replacement, host-change under a same node, synchronous node disposal, stale-handle and setup-failure cases against `A2uiSurface` 0.13.0 (see ACT2 above) and are reused unchanged. REACT1 adds one case they did not have: `actions.test.ts` › "teardown between a commit's layout and passive effects", where an unmount is queued from the layout phase of the commit that opened the controls. React runs the commit's pending passive effect before it processes that unmount, so on 19.3.1 the setup binds the instances and the unmount then disposes every binding, with no setup error and nothing left to bind; the case characterizes that ordering and will say if a React release changes it. The packed React consumer is a production build, in which Strict Mode adds no extra effects; the development Strict Mode double setup is what ACT2's browser spec runs.

**Peers and dependencies.** The consumer is built and run on `@a2ui/react` 0.13.0 with one `@a2ui/web_core` 0.13.0 and React and React DOM 19.3.1; `scripts/pack1.test.ts` asserts the installed versions and the packed manifest's pins, and the build records them in `identity.json` (`installedVersions`). This is the published 0.13.0 and not the 0.14.0 source (`45633b9`) that the Blueprint inspected. Inspecting the built import graph (`pack1.test.ts`): the React consumer contains no `@saga-a2ui/lit`, `@a2ui/lit`, `@saga-a2ui/components`, FaithfulCard, Markdown parser or Lit element of SAGA's, no server, policy or Node module, and its server bundle is byte for byte the Lit consumers' server (apart from the comment naming each scratch directory). It does contain Lit's runtime modules (`lit`, `lit-html`, `@lit/reactive-element`): upstream `@a2ui/react` 0.13.0 itself imports `@a2ui/web_core/v0_9/basic_catalog`, which loads web_core's Lit-based markdown directive. The test asserts that web_core's directive is in the graph, that no module of SAGA's or of the application imports Lit, and that the Lit consumers contain no React. This is a disclosed upstream dependency overlap, not a SAGA dependency. No MCP-UI, CopilotKit, AG-UI or Ora package is used.

**Tests.** `scripts/pack1.test.ts` (13 headless cases; it now installs three consumers from packed tarballs and checks their package sets, exports used, graphs and servers), `apps/lit-host/e2e/pack1-consumers.spec.ts` (41 browser cases: 14 for each Lit consumer and 13 for React), `packages/react/src/actions/actions.test.ts`. Two hand mutations of the React view were run to show the React cases can fail (each reverted): not unmounting the root on retirement fails the dispose-with-a-pending-request and page-going-away cases, and binding the archive without its `subject` fails the item-change case.

Run it (the same commands CI runs through `npm run verify`):

    npm ci && npx playwright install chromium
    npm run build                                  # includes the React consumer (apps/lit-host/dist/pack1/react)
    npx vitest run --config vitest.config.ts scripts/pack1.test.ts packages/react
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/pack1-consumers.spec.ts

**Scope.** The notes browse and its row actions in a normal React project over the local host fixture. Play has its own React control (see "Playing through React (REACT2)" below). No dependency was added, so `THIRD_PARTY_NOTICES.md` is unchanged.

### Playing through React (REACT2)

[#30](https://github.com/MachineWisdomAI/saga-a2ui/issues/30) puts the protected player of [Authorized playback](../docs/authorized-playback.md) behind a React control, without a second player. `apps/lit-host` builds a second single-file view, `dist/playback-react-view/playback-react.html`, from the same controller (`connectPlaybackView`), the same Play, Pause and Resume definitions, the same player owner and the same listener, media service and entitlement checks. Only the rendered control differs. It adds no package, export or dependency to the SDK. It is qualified on the local fixture host.

| | Lit view | React view |
| --- | --- | --- |
| Page | `playback.html`, `src/playback-main.ts` | `playback-react.html`, `src/playback-react-main.tsx` |
| Control | `lit/play-control.ts` (`PlayControlElement`) | `react/play-control.tsx` (`PlayControlView`, `PlayerPage`) |
| Wording, states and button choice | `playback/play-presentation.ts` (`presentationFor`, `titleFor`), shared | same module |
| Instance on the shared host | the element opens it on `connectedCallback`, retires it on `disconnectedCallback` | a layout effect keyed on the host opens it and its cleanup retires it |
| Description card (CARD1) | beside the control | none on this page |
| SDK packages installed | `core`, `lit`, `components`, `mcp` | `core`, `mcp` (and the application's own `react`, `react-dom`) |

**What the React control owns.** The control is the application's own, like the Lit element, and is not an A2UI node, so it does not use the `@saga-a2ui/react` `ActionButton`. It opens one `PlayControl` instance on the `InstanceHost` that `playback-react-main.tsx` creates with `createInstanceHost`, and `connection.attach` binds Play, Pause and Resume to it through `watchById`/`bindAction` exactly as for the Lit control. The instance is the span between a layout effect's setup and its cleanup, not a render: a render React discards before commit opens nothing, Strict Mode's simulated unmount retires the first instance before the kept one opens, a new host retires the old instance before the new one opens, and leaving the screen retires it. `isLive` is cleared before `retire`, so a retained element delivers nothing from the first moment of cleanup. The press calls `activate` from React's `onClick`, which React delivers synchronously from the DOM event, so the Play activation prefix still unlocks audio inside the user's gesture. A pending press is ignored by the control and by the binding's busy policy; the button stays in place with `aria-disabled` and `aria-busy`; focus moves to the status only when a state removes the button that had it.

**What is reused rather than repeated.** The controller's states, request discipline, label-loss retirement, teardown, deadline and unknown-effect rules, the per-lease player ownership and the server's grant, proof and entitlement checks are unchanged and keep their accepted suites (`playback-view.test.ts`, `player-owner.test.ts`, `playback.test.ts`, `media.test.ts`, `playback-budgets.test.ts`). The shared action contract's prerequisite, hook, busy-policy and limit cases keep `packages/core/src/actions/*.test.ts` and `packages/react/src/actions/*.test.ts`; the repeated-row Archive scenario and the asynchronous local action in React keep `pack1-consumers.spec.ts` (REACT1) and `react-async-action-binding.spec.ts`. Play already exercises both an asynchronous prerequisite (the host-capability check and the recipient key) on a server definition and asynchronous local Pause and Resume. The work and hook limits are the action host's defaults (30,000 ms of work, 5,000 ms per awaited hook or cleanup step), and the 3-second server operation and 10-second request defaults, their overrides, remaining-time clamps and invalid-value rejection are the server's and are not changed.

**Tests added.**

- `apps/lit-host/e2e/playback-view.spec.ts` runs unchanged in a second Playwright project, `react` (`playwright.config.ts`, `e2e/player-renderer.ts`), against the built React view, beside the `lit` project: the allowed, denied, unconfirmed, expired, revoked, replayed and recipient-bound cases, Pause and Resume honesty, pending, keyboard, 320 px and 200 % text reflow, focus, teardown, label loss, the policy that blocks an undeclared media origin, and that the capability reaches only the declared media origin. One case asserts which renderer is under test. The two description-card describes are skipped for React, with the reason in the spec.
- `apps/lit-host/src/react/play-control.test.ts` (headless, real React 19 in jsdom, Strict Mode on): one live instance per committed host, no re-open on a new state, a press delivered inside the click, a pending press ignored, retirement on unmount with a retained element inert, host replacement order, a discarded render opening nothing, and focus. Hand mutations (focus not recorded, `isLive` never cleared) fail four of its nine cases.
- `scripts/installed-lit-host.test.ts` builds the React view from the packed `core` and `mcp` packages outside the repository and asserts that its graph holds only installed copies of those, React and React DOM, and no Lit, A2UI renderer, components package, Markdown parser or MCP server module. `npm run test:browser:installed` runs the player spec, so the React project runs against that build too.

**Build detail.** The view is built with the production React runtime and the production JSX transform whatever `NODE_ENV` the build runs under. The development transform embeds each source file's absolute path, so the headless build (`NODE_ENV=test`) would differ by location. This also means Strict Mode's extra effects are not in the shipped file; the headless test covers them.

Run it:

    npm ci && npx playwright install chromium
    npm run build                                  # includes dist/playback-react-view
    npx vitest run apps/lit-host/src/react scripts/installed-lit-host.test.ts
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/playback-view.spec.ts

**Scope.** A local fixture host (the test-only `AppBridge` and sandboxed iframe), a synthetic account and in-memory loopback media; playback is observed through Chromium's audio clock. The listener serves the Lit view as the `ui://` resource. No dependency was added, so `THIRD_PARTY_NOTICES.md` is unchanged.

### Release candidate, update and rollback (PACK2)

The bounded candidate-preparation scope is accepted at [PR #158](https://github.com/MachineWisdomAI/saga-a2ui/pull/158), actual merge `06aa486e6b8f4d99990d235a0c6177e5c8f14a32`. The [lifecycle record](../blueprints/features/reusable_lit_adapter.blueprint.md#status) maps all seven criteria, exact repair review, 35 headless/two original CLI regressions and 60 rebuilt application stage observations.

[#22](https://github.com/MachineWisdomAI/saga-a2ui/issues/22) turns the packed installs of PACK1 into an auditable **candidate**: the five packages, the views and servers built from them, and the record that ties them together. It adds no runtime, export, registry or package, and publishes, tags and deploys nothing. The maintainer guide is [docs/candidate-update-and-rollback.md](../docs/candidate-update-and-rollback.md); this section records what the change did and found.

What changed in the code:

- `scripts/packed-consumer.ts` is now the one place packages are packed. `installPackedSdk` no longer stamps a throwaway `0.0.0-packed-test`; every consumer of this repository (the answer, PACK1, React card and installed Lit application builds, and the tests that install packages) installs the same candidate tarball: version `0.0.0-candidate.g<12 hex of the commit>` (`.dirty` when tracked files differ), every SDK dependency and peer pinned to exactly that version, `LICENSE` in every tarball and `THIRD_PARTY_NOTICES.md` in `components`, which brings `markdown-it` into a consumer's view. The repository manifests are untouched, so no owned version is introduced and no enrollment applies.
- `scripts/release-candidate.ts` (`npm run candidate:pack -- --out DIR`, run by CI after `npm run verify` and uploaded as a workflow artifact) packs the five packages into `DIR/packages`, requires every consumer identity under `apps/lit-host/dist*` to name exactly those tarball digests and this revision, installs the tarballs with the real package manager into a clean directory, runs `npm ls --all`, tries a set that mixes two builds, and writes `candidate.json`, `CANDIDATE.md` and the consumer lockfile. `npm run candidate:verify -- --candidate FILE --modules DIR --combination own|card [--page FILE]` resolves the named combination and reports, with the tarball to reinstall, each package of the installed set that is not the candidate, a package of that combination that is not installed (the optional `components` is required for `card` only), a `--modules` location with no `@saga-a2ui` package, a sibling at the wrong version or missing, a built view that is not the recorded resource, and any carried check the record predates (exit 1; a missing or unknown combination is exit 2). `npm run candidate:rehearse -- --candidate FILE` (`scripts/candidate-rehearsal.ts`, run by CI after `candidate:pack`) rehearses an install of candidate A, an update to B and a rollback to A as built applications, below.
- `examples/pack1-consumer/src/notes-view.ts` (an application-owned starter file): a successful result that fails the view's contract now shows `MISMATCH_TEXT` and renders none of it, where before it showed the generic problem sentence.
- `apps/lit-host/e2e/pack1-consumers.spec.ts` gains two cases for both consumers, below. CI uploads the artifact; `.gitignore` ignores `candidate-out/`.

Findings that shaped the candidate:

- **A fresh `npm install` of the packages needs an override.** `@a2ui/markdown-it` 0.2.2 (what npm resolves) peers `@a2ui/web_core ^0.14.0`, which conflicts with the pinned 0.13.0, and npm stops with ERESOLVE. The workspace root carries the Markdown compatibility override and patched DOMPurify and Hono overrides listed in [public installation](public-install.md#install-one-stack-plus-framework-peers); npm honors overrides of the root project only, so an application must carry them. The candidate install check uses the root's overrides and records them.
- **`private` does not stop `npm publish`.** npm 12.0.2 accepted the private candidate manifest in `npm publish --dry-run`, for a directory and for a tarball. Candidate manifests therefore also name `https://candidate-artifact.invalid/` in `publishConfig.registry` (a host that cannot resolve, RFC 6761), which npm honored in the same dry run ("Publishing to https://candidate-artifact.invalid/"). Neither field is the safeguard on its own: no CI job holds a publish credential and the release recipe in the guide builds from a reviewed release change.
- **The tarballs carried no license.** Apache-2.0 requires it to travel with the code; the staged copy now adds it.
- **A mixed set is refused at install.** npm answers `E404` for the sibling at the exact version that is not among the tarballs named beside it; the check is recorded as `versionMismatch.installProbe` in `candidate.json`.

**Predecessor.** Public npm releases of SAGA packages already exist (`core`, `components`, `mcp` and `react` at `0.1.0-rc.1` and later prereleases). A candidate is a separate artifact with a candidate-only version, and a candidate rehearsal is a local source rehearsal. The update and rollback sequence is rehearsed between two candidate builds only (`scripts/release-candidate.test.ts`): it packs two builds, installs one, updates to the other (a half-updated set is reported per package with the tarball to reinstall), and restores the first, whose package manifests return byte for byte. `scripts/candidate-rehearsal.ts` (`npm run candidate:rehearse`) then does it as applications: for `own` and for `card` it installs candidate A, updates to B and restores A, each time installing the consumer from that stage's tarballs alone, checking the installed set against the combination, rebuilding the page and the server, connecting a real MCP client to the rebuilt server to confirm it serves the rebuilt page, and running the ten `pack1-consumers.spec.ts` cases (disclosure, per-request authorization, known versus unknown effect, one definition on two rendered rows, prerequisite, subject freshness, disposal, page teardown, no handler-name routing, view/server mismatch) in a real browser against that stage's rebuilt files (`SAGA_PACK1_DIR` points the spec at them). It fails unless each case ran once per consumer and passed, and unless the rollback restored the first install's view digest and (with the scratch directory name in its region comments normalized) its server bundle. A and B are one revision with different version strings, so the rebuilt views are identical and nothing observable changes in the update: this shows the procedure and the per-stage behavior. `rehearsal.json` and a `CANDIDATE.md` section record the artifact digests and the cases that ran.

**Carried through every claimed combination.** The combinations are `notes-own`, `notes-card` and the browse and Play application (each lists its packages, its `ui://views/<filename>.<fingerprint>.html` resources, its server bundle digest and its catalog entries in `candidate.json`). `CARRIED_CASES` in `scripts/release-candidate.ts` names the 15 checks each claim rests on, by file and exact title: disclosure and per-request authorization (including after a withdrawn permission), known versus unknown effect, one definition bound to two rendered instances, prerequisite, subject freshness, disposal and page teardown, the installed listener's authentication, scoping, entitlement and media binding, and two added here: a layout that names an action or handler is refused by the installed catalog and a press sends nothing (so a resource cannot route by handler name), and a result from a server of another build is refused with guidance and renders none of it. A headless test fails if a listed title no longer exists, and `candidate:verify` reports a record that lacks one as `floor-missing`, which is how a rollback avoids silently undoing an authorization fix.

**Evidence** (Linux x64, Node 26.7.0, npm 12.0.2, Playwright 1.64.0 Chromium; CI pins Node 22.12.0 and records the version it ran): `scripts/release-candidate.test.ts` (31 headless cases: identity, manifest pinning and refusal of any other form, license, unpublishable registry, same artifact for the same revision, exclusions, installed set checks for whole, own-catalog, incomplete, half-updated, rolled-back, missing and foreign packages and a missing modules location, view pairing, consumer-identity checks, the carried cases, and the `candidate:verify` command run as a subprocess: accepts the exact `own` set, refuses `card` with `components` absent, refuses a missing or empty `--modules`, treats a missing or unknown `--combination` as a usage error); `scripts/candidate-rehearsal.test.ts` (4 headless cases: A→B→A installed from each stage's tarballs, rebuilt and served with the browser run recorded, a failed or unrun case refused, a half-updated install refused, the browser report read); a real `npm run candidate:rehearse` on this tree, which ran the ten `pack1-consumers.spec.ts` cases for `own` and `card` at install, update and rollback (20 passed each stage, 60 in all); the existing `pack1`, answer, React card, own-catalog and installed-listener headless suites updated for the candidate stamp; `apps/lit-host/e2e/pack1-consumers.spec.ts` (28 browser cases, both consumers). The mismatch case was written first and failed on the old text; the handler-name case characterizes existing behavior and was shown able to fail. Hand mutations (each reverted): leaving SDK ranges unpinned (8 failures across the candidate and PACK1 suites), the installed-set check ignoring sibling ranges (1), and making `ActionButton`'s schema non-strict, rebuilt into both consumers (the handler-name case fails for both), and the new required-package loop of `checkInstalledCombination` emptied (the incomplete-set case and the `candidate:verify` card case fail, the review's reproducer).

Publication is a separate owner decision; the guide gives the recipe. If the 5-second timeout of `verify-safeguards.test.ts` ("discovers the repository CSP unit test…") expires when the whole headless suite runs on a loaded machine, rerun that file alone.

### The clean Lit and Node starter (STARTER1)

[#23](https://github.com/MachineWisdomAI/saga-a2ui/issues/23) adds the first maintained starter, `templates/lit-node`, and qualifies its pair: the `lit-mcp` stack (a Lit view with MCP delivery) on the `node` server target, which uses the official `@modelcontextprotocol/node` 2.1.1 adapter that the connector design selected. It adds no package, runtime export or dependency to the SDK: the starter composes the accepted public interfaces (`@saga-a2ui/core/actions`, `@saga-a2ui/lit` and `/actions`, `@saga-a2ui/mcp/server`, `/view`, `/policy`), and the packed candidate (PACK2) is what it is installed from. [`templates/README.md`](../templates/README.md) describes the template layout, and the starter's own [README](../templates/lit-node/README.md) is what a developer reads first.

**What the starter is.** A new project, not a demo: no account, token, media or business record, and no test verifier. It serves two endpoints from one Node listener: a public `get_status` and a protected `get_account` that shows the verified account of that request. Everything that decides identity or access is a file the application owns and the starter leaves refusing: `server/verifier.ts` rejects every credential (so the protected endpoint fails closed until an identity provider is configured), and `server/authorization.ts` is the placeholder policy asked again for every request. The view composes its own catalog (`src/catalog.ts`; no registry, no forced FaithfulCard), builds one local action fluently (`src/actions.ts`, clearing an application-owned input) and attaches it directly to the rendered Clear control (`src/view.ts`); the layout names no action. The view ends its discovery subscription, its bindings and its element in one idempotent `retire()` that a host teardown and `pagehide` both call. The comments explain that ending a binding ends the view's side only; work a server action already started belongs to the server.

**One source for init, guides and CI.** `scripts/starter-template.ts` exports a template into a directory that does not exist (it never overwrites or follows a symbolic link, installs nothing and runs nothing; a failure removes only what that call created), pins every `@saga-a2ui/*` dependency to one SDK build (the template declares `*`; any other range is an error) and cuts the existing-backend snippets out of the same files: `register-protected-operation`, `identity-handoff` and `bind-action`, marked with `// #region saga-snippet:<name>` comments that are not in the exported starter. `npm run starter:snippets [-- --out DIR]` lists or writes them. A guide or the CLI includes these lines instead of retyping them; the test below fails if a snippet differs from the starter's text, and an unclosed, unopened, nested or repeated region is an error.

**How the pair is qualified.** `scripts/build-starter.ts` exports the template as a developer receives it, installs the packed candidate tarballs of `core`, `lit` and `mcp` beside it (the PACK1/PACK2 harness, no registry; only third-party packages the starter's own manifest declares are linked in), runs its type check (both projects), and builds it with the starter's own Vite configuration files: the single-file view and the Node server bundle. `npm run build` runs it for every qualified template (`apps/lit-host/dist/starters/<template>`, ignored, with `identity.json` recording the source commit, platform, tarball digests and artifact digests).

- `scripts/starter.test.ts` (19 cases, headless): a real MCP client over HTTP against the listener bundled from the exported starter. Public: answers with no credential, links the built page by its SHA-256 `ui://` URI and serves exactly those bytes, and neither the verifier nor the policy is asked. Protected: an allowed account sees its own account; an account the application's policy denies gets one fixed sentence that names no account; no credential, a malformed, unknown or expired one, one without the scope, and a service credential that names no account are each refused at HTTP (401 or 403 with a challenge) before any protected work, and an absent credential does not so much as reach the verifier. Concurrency: two overlapping requests, both held inside the policy at once, each see only their own account; and a verifier that rewrites one object it keeps returning does not change a request whose body is still arriving (the request copies and freezes what its verification produced). Clocks: with the listener's budgets set to 150 ms per operation and 1 s per request, a verifier that never answers is cut off at the operation limit with a 503 well inside the request limit, while the public endpoint keeps working (the defaults are the SDK's 3 s and 10 s); an invalid budget fails before the port opens; the server will not start without the built page. An asynchronous prerequisite that refuses stops a server action before any protected request (the verifier and the policy are not reached), and the same action with a prerequisite that proceeds sends exactly one. The shipped `server/main.ts`, run as its own process, serves the public status and refuses every credential. The exported files and built artifacts contain no test identity or demo verifier, import the runtime and do not copy it, and pin every SDK package to the installed build; the built page carries no listener, transport or verifier.
- `scripts/starter-template.test.ts` (9 cases): export, stamping, refusal of an existing path or link, no output for a non-template or a failed export, template metadata against the manifest, snippets as the starter's own lines, and malformed regions.
- `apps/lit-host/e2e/starter.spec.ts` (5 cases, Chromium): the page the starter's server serves, mounted in the local host fixture under the closed policy it declared. It is byte-identical to the build and linked from the result; the protected and public results show the account and the status; Clear empties the application-owned input through the directly attached action, refocuses it, and sends no request; a result from a server of another build, and a failure, render none of it and the view recovers; a host teardown and `pagehide` each remove the element, and a retained Clear control then does nothing.

The test identities, credentials and policy exist only in those specifications, supplied through the listener's public options by a qualification entry that the harness adds outside the exported starter.

Mutations of the source that the checks catch (each reverted): returning the verifier's own `AuthInfo` instead of the request's frozen copy fails the rewritten-record case; dropping the scope check fails the without-scope case; removing the binding disposal and element removal from `retire()` fails the retained-control case in the browser.

**Environments.** Linux x64, Node 26.7.0, npm 12.0.2, Playwright 1.64.0 Chromium revision 1248 (the repository pins Node 22.12.0 in CI).

**Scope.** This section qualifies the `lit-node` pair. `express` ([#62](https://github.com/MachineWisdomAI/saga-a2ui/issues/62), the next section), `hono` and `fastify` (later sections) each own their template, attach recipe and qualification, as does `hapi` ([#65](https://github.com/MachineWisdomAI/saga-a2ui/issues/65), `templates/lit-hapi`); the CLI (CLI1, CLI2), the demo and the guides are separate sections. The listener is a loopback process: TLS, a public host name and `allowedHosts`, the real identity provider and the real backend are the application's. The starter's `@saga-a2ui/*` versions name the packed candidate build. The SDK itself is unchanged.

### The clean Lit and Express starter (STARTER-EXPRESS)

[#62](https://github.com/MachineWisdomAI/saga-a2ui/issues/62) qualifies the second pair: the `lit-mcp` stack on the `express` server target (`templates/lit-express`). It reuses STARTER1 as it stands: the same view (`src/`), the same operations, request authentication, identity, authorization and verifier files (`server/`, byte-identical to `templates/lit-node` apart from the listener), the same export, stamping and snippet code (`scripts/starter-template.ts`), the same packed candidate install and the same qualification cases. It adds no SDK package, runtime export or framework layer; the SDK is unchanged.

**The recipe, pinned from what is installed.** `express` 5.3.0 (the latest 5.x), the official `@modelcontextprotocol/express` 2.0.2 adapter (peers `express` `^4.18.0 || ^5.0.0` and `@modelcontextprotocol/server` `^2.3.0`; Node 20 or newer), `@modelcontextprotocol/node` 2.1.1 for the Streamable HTTP transport, `@modelcontextprotocol/server` 2.4.0 and `@types/express` 5.0.6, on Node 22.12 or newer. Every one is an exact version in the template's manifest and in the repository's `apps/lit-host` manifest and lockfile, from which the qualification links them; a test reads the installed adapter's manifest and fails if the installed `express` or server is outside its peer ranges, or the starter promises an older Node than the adapter supports. This pair has its own listener and its own cases; the tested recipe is Express 5.3.0.

**What is Express's and what stays the application's.** The listener (`server/listener.ts`) is an Express application: the adapter's `localhostHostValidation()` and `localhostOriginValidation()` refuse another Host or Origin with 403 before anything else, an `identify` middleware (the `identity-handoff` snippet) calls the starter's own `authenticate` and puts the result on `req.auth` for the transport, and a route per endpoint reads its body and serves one MCP request with a server and transport built for it. It does not use the adapter's `createMcpExpressApp` or `requireBearerAuth`, and says why: the first installs `express.json()` ahead of every route, a parser with no deadline, so a body that stalls would hold the request open; the second would take authentication out of the request's lifetime and decide the required scope for the application. Authentication, the required scope, the account and what it may see stay in `server/authenticate.ts`, `server/identity.ts`, `server/verifier.ts` and `server/authorization.ts`; Express adds no verifier, session or "current user". The request's clock starts in the first middleware, before authentication, with the same 3 s per operation and 10 s per request, resolved per field and validated before the port opens.

**How the pair is qualified.** `scripts/qualified-starters.ts` lists the templates CI qualifies (`lit-node`, `lit-express`, `lit-fastify`, `lit-hono`); `scripts/starter-template.test.ts` fails for a template directory that is not listed, so a pair is not offered before its evidence exists. `scripts/starter-qualification.ts` is the one headless suite (the cases of the STARTER1 section, moved without change) and each pair's test file calls it: `scripts/starter.test.ts` for `lit-node` and `scripts/starter-express.test.ts` for `lit-express`, which adds the Express cases. `scripts/build-starter.ts` builds each qualified template into `apps/lit-host/dist/starters/<template>` and `apps/lit-host/e2e/starter.spec.ts` runs against each.

- `scripts/starter-express.test.ts` (31 headless cases: the 25 shared cases and 6 Express cases), against the listener bundled from the exported, installed and built `lit-express` starter, with a real MCP client over HTTP. Allowed, denied, public and missing-credential behavior is the shared set: an allowed account sees its own account, a denied one gets a fixed sentence that names no account, and no, malformed, unknown, expired, wrong-scope or account-less credentials are refused at HTTP (401 or 403 with a challenge) before any protected work; concurrency, the clocks and the body and delivery boundary (a stalled body is one 408 and a closed connection and does nothing protected; a response the deadline overtakes is destroyed) are the shared set, and they are the evidence that Express's own body parser is not in the path. The Express cases: another Host or Origin is refused with 403 before the verifier or the policy is asked; both loopback spellings are served; an unknown path, a path spelled in another case and a trailing slash each get a bare 404 that does not name Express; a protected request of any method is authenticated before the transport sees it; and the recipe above.
- `apps/lit-host/e2e/starter.spec.ts` (24 browser cases, 6 per pair, Chromium): the page the server serves is byte-identical to the build, mounted in the local host fixture under the closed policy; the protected and public results show the account and the status; Clear works through the attached action; a result of another build or a failure renders none of it; teardown and `pagehide` dispose the bindings. New for every pair: two overlapping requests for two different accounts, both held inside the application's policy at once, are each delivered to their own view, and each view shows only its own account.
- `scripts/starter-template.test.ts` (20 cases): export, stamping, refusal of an existing path, metadata against the manifest and snippets, now for every qualified template.

Mutations of the source that the checks catch (each reverted): installing `express.json()` ahead of the routes fails the shared cases (the body is consumed before the lifetime reads it); removing the adapter's Host and Origin middleware fails both refusal cases.

**Generated snippets and metadata.** The three snippets the template declares are the same names as the Node pair's (`register-protected-operation`, `identity-handoff`, `bind-action`) and are cut by `npm run starter:snippets -- --template lit-express` from the tested files; `identity-handoff` shows the Express middleware. `templates/lit-express/template.json` uses the existing schema (stack `lit-mcp`, server `express`, adapter `@modelcontextprotocol/express` 2.0.2); pair discovery belongs to CLI1 ([#26](https://github.com/MachineWisdomAI/saga-a2ui/issues/26)), whose supported-pair list gained this pair through [#179](https://github.com/MachineWisdomAI/saga-a2ui/issues/179). The clean output contains no synthetic account, credential, media or demo verifier; `server/verifier.ts` refuses every credential.

**Evidence.** Linux x64, Node 26.7.0, npm 12.0.2, Playwright Chromium; CI pins Node 22.12.0. The packages are packed candidate tarballs and the listener is a loopback process. A shared root `package.json` script change (`typecheck` for the two new projects) and the lockfile addition of `express`, the adapter and `@types/express` are the only shared files touched; Hono ([#63](https://github.com/MachineWisdomAI/saga-a2ui/issues/63)) and Fastify ([#64](https://github.com/MachineWisdomAI/saga-a2ui/issues/64)) own their templates and consume the harness through `qualifyStarter` and `QUALIFIED_STARTERS`.

### The clean Lit and Hono starter (STARTER-HONO)

[#63](https://github.com/MachineWisdomAI/saga-a2ui/issues/63) adds the second maintained template, `templates/lit-hono`, and qualifies its pair: the `lit-mcp` stack on the `hono` server target. It reuses the shared harness (`scripts/starter-template.ts` for export, stamping and snippets; `scripts/build-starter.ts` for the packed-artifact install, type check and build; `scripts/starter-qualification.ts` for the headless suite) and changes no SDK package, runtime export or shared starter script (it adds `lit-hono` to `scripts/qualified-starters.ts`; the root `package.json` gains the type-check entries, and `apps/lit-host` the three dependencies below). [`templates/README.md`](../templates/README.md) lists every template; the starter's own [README](../templates/lit-hono/README.md) is what a developer reads first.

**The recipe, from the installed packages.** The official adapter is `@modelcontextprotocol/hono` 2.0.2 (Apache-2.0; the connector design selected the official adapter per target and named no version). Its declared peers are `hono` ^4.11.4 and `@modelcontextprotocol/server` ^2.3.0, and the template pins the exact versions this suite installs and ran against: `hono` 4.13.16, `@hono/node-server` 2.1.5 (the Node host for a Hono application), `@modelcontextprotocol/server` and `client` 2.4.0, Node 22.12.0 or later (`engines`; the adapter itself needs 20). The Hono starters and the SDK local listener are qualified on 2.1.5. The official `@modelcontextprotocol/node` adapter retains its own nested 1.x dependency. The Node adapter's version of the first pair is not carried over: the pins are read back from `node_modules` by the test below, and the adapter's peer ranges are asserted so a new adapter release that changes them is noticed. `apps/lit-host` supplies the third-party pool used by the packed-consumer harness. The root also pins `@hono/node-server` 2.1.5 as a development dependency so qualification resolves the same version as the SDK and Hono starters.

**What differs from `templates/lit-node`, and why.** Only the server adapter files: `server/listener.ts` (a Hono application on a loopback Node listener, using the adapter's `hostHeaderValidation` and `localhostOriginValidation` and the Web Standard Streamable HTTP transport from `@modelcontextprotocol/server`), `server/authenticate.ts` (takes the `Authorization` header value, not a Node request, so the identity rules are unchanged), `package.json` and the README. The view, operations, identity, policy, verifier and tsconfig/Vite files are byte-identical to the Node starter, and a test fails if they drift. The adapter's `createMcpHonoApp` is deliberately not used: it reads and parses the body in a middleware that runs before the application's routes, so that wait could not be a stage of the request's lifetime. The listener installs the adapter's two validators itself and reads each POST body with the SDK's own bounded reader (`readRequestBody`) as the lifetime's `body` stage, in front of any server or transport, so the optional per-stage budgets and the 3 s operation / 10 s request clocks (started at admission, before authentication) keep their meaning. Identity is the verified `AuthInfo`, copied and frozen per request by `authenticate` and passed to the transport as that request's `authInfo`; nothing is stored on the Hono context or any shared object. No new framework layer: authentication and authorization stay in the application's `verifier.ts`, `authenticate.ts` and `authorization.ts`.

**How the pair is qualified.** `lit-hono` is listed in `scripts/qualified-starters.ts`, so it rides the shared inventory with `lit-node`, `lit-express` and `lit-fastify` and has no pair-specific build or browser file: `scripts/build-starter.ts` (`npm run build:starter`, part of `npm run build`) builds it into `apps/lit-host/dist/starters/lit-hono` with `identity.json` (source commit, adapter, tarball and artifact digests), and `scripts/starter-template.test.ts` fails for a template directory that is not listed.

- `scripts/starter-hono.test.ts` (30 headless cases: the 25 shared cases and 5 Hono cases) calls the shared suite (`qualifyStarter('lit-hono', ...)` in `scripts/starter-qualification.ts`): a real MCP client over HTTP against the listener bundled from the exported starter. The shared cases are those of the STARTER1 and STARTER-EXPRESS sections: the public operation answers with no credential and serves exactly the built page's bytes; an allowed account sees its own account; a denied account gets one fixed sentence that names no account; no, malformed, unknown, expired, wrong-scope and no-account credentials are each refused at HTTP (401 or 403 with a challenge) before any protected work; two overlapping requests held inside the policy together each see only their own account, and a verifier that rewrites the one object it returns does not change a request whose body is still arriving; a verifier that never answers is cut off by the operation limit (503) while the public endpoint keeps working; an invalid budget fails before the port opens; the HTTP body and delivery boundary (stalled public and protected bodies are answered 408 and the connection closed with nothing built or called, a caller leaving mid-body, oversized and non-JSON bodies, a finite response the peer will not read is destroyed rather than held); the server will not start without the built page; an asynchronous prerequisite that refuses sends no protected request; the shipped `server/main.ts` runs as its own process, serves the public status and refuses every credential; and the exported files and built artifacts contain no test identity or demo verifier, import the runtime rather than copy it, and the built page carries no listener, transport or adapter. The cases specific to this pair: a request for another Host name or from another Origin is refused 403 on both endpoints before any credential or protected work; the local host name the starter lists is served; the exported manifest pins the adapter, host, Hono and MCP packages to the installed versions; and the Hono starter differs from the Node starter in the adapter files only. The snippets are checked for every template by `scripts/starter-template.test.ts`.
- `apps/lit-host/e2e/starter.spec.ts` (Chromium), for `lit-hono` as for each listed pair: the page the Hono server serves, mounted in the local host fixture under the closed policy it declared: byte-identical to the build and linked from the result; account and status shown; Clear works through the directly attached action and sends nothing; a result of another build and a failure render nothing and the view recovers; host teardown and `pagehide` dispose the bindings; and two people's overlapping requests, held inside the policy together, each reach their own view showing only their own account.

Mutations of the source that the checks catch (each reverted): returning the verifier's own `AuthInfo` instead of the request's frozen copy fails the rewritten-record case; dropping the scope check fails the wrong-scope case; removing the Host or Origin validator fails its refusal case; reading the body outside the lifetime fails the three stalled-body cases; removing the delivery destroy fails the undeliverable-response case.

**Scope.** `express` ([#62](https://github.com/MachineWisdomAI/saga-a2ui/issues/62)) and `fastify` ([#64](https://github.com/MachineWisdomAI/saga-a2ui/issues/64)) are qualified in their own sections, and `hapi` ([#65](https://github.com/MachineWisdomAI/saga-a2ui/issues/65)) has its own template. Qualification alone does not register a pair: this one joined the supported-pair list the CLI ([#26](https://github.com/MachineWisdomAI/saga-a2ui/issues/26)) owns through [#179](https://github.com/MachineWisdomAI/saga-a2ui/issues/179). The [generated existing-backend recipes](../docs/attach-to-existing-backend.md) (GUIDE1, [#25](https://github.com/MachineWisdomAI/saga-a2ui/issues/25)) show its snippets from the template, and the pair is recorded here and in `templates/lit-hono/template.json`. The listener is a loopback process (TLS, a public host name in `ALLOWED_HOSTNAMES`, the real identity provider and backend are the application's). Environment: Linux x64, Node 26.7.0, npm 12.0.2, Playwright Chromium revision 1248 (CI pins Node 22.12.0).

### The clean React and Hono starter (STARTER-REACT-HONO)

`templates/react-hono` is the first maintained template for the `react-mcp` stack, and `saga init --a2ui-stack react-mcp --server hono DIR` creates it. It is the `lit-hono` application with a React view, and it changes no SDK package or runtime export. [`templates/README.md`](../templates/README.md) lists every template; the starter's own [README](../templates/react-hono/README.md) is what a developer reads first.

**What is shared with `lit-hono`, and what is not.** `server/` is the `lit-hono` text, byte for byte, with the same Hono 4.13.16, `@hono/node-server` 2.1.5 and `@modelcontextprotocol/hono` 2.0.2 pins; so are `tsconfig.server.json`, `vite.server.config.ts` and the wire contract `src/contract.ts` apart from one constant. `scripts/starter-hono.test.ts` fails if the React copy's server files, server build files, contract or Hono pins drift from the Lit copy, so a server fix lands in both. The view artifact check in `server/operations.ts` no longer looks for `<starter-app`: each template declares the `VIEW_MARKER` its built page must contain in `src/contract.ts` (`<starter-app` for the five Lit templates, `<div id="root"` for `react-hono`), and the qualification reads the marker from the built entry. The view is `src/*.tsx` over `@saga-a2ui/react-mcp-stack` with the `react-jsx` setting and `react`/`react-dom` 19.3.1: the same layout, a `Line` and a `Column` of its own over the stack's layout contract, the SAGA `ActionButton`, public status, the protected account operation (the verifier refuses every credential) and the bound "Clear the note" local action. `template.json` names `react-mcp`, `hono` and the five React-side SDK packages (`core`, `react`, `components`, `mcp`, `react-mcp-stack`).

**How the pair is qualified.** It is listed in `scripts/qualified-starters.ts` and rides the shared inventory, and its row is in `SUPPORTED_PAIRS` because its qualification passes. The checks that assumed Lit now read the template's stack: the stack-import check (`@saga-a2ui/<stack>-stack`), the page marker, the teardown selector in `apps/lit-host/e2e/starter.spec.ts` (`#root` for a React template), `extractSnippets` (which reads `.tsx` and records each snippet's language, so a recipe is fenced as `ts` or `tsx`), the packed set in `scripts/saga-init-offered.test.ts`, `REQUIRED_TEMPLATES` and the stack-import units. The Hono cases both Hono templates share live in `scripts/starter-hono-cases.ts`.

- `scripts/starter-react-hono.test.ts` (35 headless cases: the shared suite and the Hono cases) runs a real MCP client over HTTP against the listener bundled from the exported starter, installed from packed candidate tarballs, type-checked and built with its own scripts.
- `apps/lit-host/e2e/starter.spec.ts` (Chromium, local host fixture) runs its six cases for `react-hono`: the served page is byte-identical to the build, the operation's result reaches the React view, Clear the note empties the input without a server call, a result of another build renders nothing, and host teardown and `pagehide` leave `#root` empty and dispose the binding.
- `scripts/saga-init-offered.test.ts` runs the real command for the pair, installs the packed candidates and builds the project; `scripts/saga.test.ts` covers the refusals, including the React stack on any other server.

**Scope.** React is offered on the `hono` server target; `saga demo` builds the Lit and Node demonstration.

### The standalone synthetic demonstration (DEMO1)

[#24](https://github.com/MachineWisdomAI/saga-a2ui/issues/24) runs the whole protected workflow from a download that was built outside the repository. `demo/lit-node` is the demonstration, `scripts/build-demo.ts` (`npm run build:demo`, part of `npm run build`) makes the download, and [`demo/lit-node/README.md`](../demo/lit-node/README.md) is what a person who receives it reads. It adds no package, runtime export or dependency to the SDK, and nothing is published, deployed or made public.

**The pair, chosen from evidence.** The one pair is the `lit-mcp` stack on the `node` server target (`templates/lit-node`, `@modelcontextprotocol/node` 2.1.1): the only pair STARTER1 (#23, `cdb9f45`) qualified, so it is the only one with accepted evidence. The demonstration imports the starter's own request-authentication glue (`server/authenticate.ts`, `server/identity.ts`) unchanged, and the build fails if the exported copy differs from the template's text. Every synthetic identity, credential, episode, note and tone lives in `demo/lit-node/fixtures`, which the template never imports; a test fails if the clean starter carries a demonstration credential or record.

**What is reused, not rebuilt.** Browse, Standard and Strict descriptions, and protected Play are the application's installed views and listener (`apps/lit-host`: PACK1 #154 and its CORE, STATE and CARD work), unchanged; their `request-*`, `playback` and `media` budget and security matrices keep their own suites and are not repeated. The small non-playback action example is the PACK1 notes application (`examples/pack1-consumer`, its own-catalog consumer), mounted behind the starter's authentication. Its server is the PACK1 server unchanged; the demonstration adds only an endpoint (`demo/lit-node/server/notes-endpoint.ts`) that hosts it. The one change outside `demo/` is that the local host fixture appends a view to a `[data-view-area]` element when the page has one (`e2e/host-fixture/host.ts`), which leaves every existing specification as it was.

**The download.** `scripts/build-demo.ts` packs `core`, `lit`, `components` and `mcp` as the PACK2 candidate (version `0.0.0-candidate.g<12 hex>`, exact sibling pins), unpacks them as installed dependencies of a clean directory outside the repository, copies the demonstration, the application's three views and listener, the notes example and the exported starter glue into it with the repository's layout, builds the five pages with their own Vite configurations and bundles the server against the installed copies only (a module loaded from the workspace fails the build; the server bundle must not import `@saga-a2ui/*` at run time). The output is `server.mjs`, `views/` (episode, subscriptions, playback, notes, host), `package.json` (only the third-party packages the server still imports, at the versions the installed manifests declare; the `zod3` alias is kept as the SDK declares it), the licence and notices, and `release.json`, which records the source commit, the pair, the candidate version and tarball digests, the starter glue digests and the digest of every file. The playback page is byte-identical to the CARD2-accepted installed playback document (`7ea1d8d0…`).

**Local-only authentication.** The sign-in choices are `dev-auth.ts`'s fixed public tokens. The host page opens with a banner that says so and offers no field to type a credential, the process prints the same sentence on every start and refuses `NODE_ENV=production`. A real-host run uses that host's supported authentication through its own `OAuthTokenVerifier`.

**What the host page does.** It is the repository's local host fixture with a page around it: it reads each tool's linked resource, mounts it in a sandboxed `allow-scripts` frame under the policy the resource declares, delivers the tool result and forwards the view's own `tools/call` (with its `_meta`) through the process's `POST /host/rpc`, with the credential chosen on the page. That surface answers only this origin, only JSON, only `tools/list`, `tools/call` and `resources/read`, and only five fixed endpoints; its nine demonstration controls (`hold archives`, `revoke play access after next grant`, …) change Alice's synthetic account to make a state visible. It is a stand-in host.

**Action example, failure and cleanup.** The notes' Archive is one fluent definition bound directly to each rendered row, with an asynchronous session prerequisite, per-binding state and an application-owned hold. The browser specification shows each outcome the issue names: a refused prerequisite sends no protected request and gives the hold back; a withdrawn permission is the server's authoritative refusal (`The server declined; nothing changed`) after a passed session check; closing the view while the server is working only stops the client waiting, the hold is given back, and the server still applies the archive once the backend answers; success hands the hold to the owner. Play keeps its accepted mapping A: the private grant stays in call metadata, a grant revoked before its bytes is `expired`, a credential the listener refuses is `unavailable` and not a denial, and a changed sign-in label retires the player until a fresh view.

Run it (the same commands CI runs through `npm run verify`):

    npm run build                                  # includes build:demo (apps/lit-host/dist/demo)
    npx vitest run --config vitest.config.ts scripts/demo.test.ts
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/demo.spec.ts
    cd apps/lit-host/dist/demo && npm install --omit=dev && npm start

**Evidence.** `scripts/demo.test.ts` (18 headless cases) builds the download, starts `server.mjs` as its own process and checks its contents and manifest, the starter-glue digest, the absence of workspace SDK imports, the local-only banner and the production refusal, the host surface's origin, content-type, endpoint and method limits, browse scoping and the HTTP refusals, and the notes endpoint's authentication and server-side decisions. `apps/lit-host/e2e/demo.spec.ts` (17 browser cases) drives that process through its host page: browse and refused credentials, a changed sign-in, both description levels with Show images and consent revocation, entitled, denied, revoked, expired and recovered Play with the audio clock advancing, label loss, closing the view, and the notes cases above. Mutations of the source that the checks catch (each reverted): dropping the host surface's origin check fails the origin case, and making the revoke-after-grant control a no-op fails the expired-Play case. Third-party packages come from the repository's installed copies when the tests run the download; a separate `npm install --omit=dev` of the download (42 packages, no vulnerabilities reported) and a start from that install were also run by hand. Linux x64, Node 26.7.0, npm 12.0.2, Playwright Chromium; CI pins Node 22.12.0. Host receipts for the unchanged shared behavior are reused; the host seam changed only as stated above.

### The static source-linked tour (TOUR1)

[#32](https://github.com/MachineWisdomAI/saga-a2ui/issues/32) lets a visitor try the notes example's allowed, denied and obsolete outcomes and find the matching source without running a backend. `demo/tour` is the page, `scripts/build-tour.ts` (`npm run build:tour`, part of `npm run build`) builds it, and [`demo/tour/README.md`](../demo/tour/README.md) is what a reader of the build opens. It adds no package, runtime export, server or dependency, and nothing is published, deployed or made public.

**What is reused, not rebuilt.** The views are the notes example's own-catalog Lit page and its React page (`examples/pack1-consumer`, PACK1 and REACT1), built from packed candidate tarballs outside the repository exactly as the demonstration builds its notes view, and mounted by the repository's local host fixture. The action definitions, prerequisite, direct per-row attachment, application-owned holds, renderer and cleanup are the example's and the SDK's, unchanged. The synthetic notes moved from `demo/lit-node/fixtures/world.ts` to `demo/lit-node/fixtures/notes.ts` so the demonstration and the tour read the same records; the demonstration's behavior is unchanged.

**What is simulated.** `demo/tour/src/simulated-world.ts` answers the view's three tool calls from the example's synthetic in-memory backend and the situation the visitor chose with named controls (the demonstration's, plus failing after a write and listing in the opposite order). It is local tour data, not an authorization implementation and not an action-routing layer. The tour's choice of who is asking authenticates nobody.

**Evidence.** `scripts/tour.test.ts` runs the notes application's real `createNotesServer` over a real MCP client and the simulated server through the same situations (listing, the session check, an allowed archive, another person's, absent and already archived notes, no identity, withdrawn permission after a valid session check, a failure after the write, a held archive) and requires the same reply from both. It also finds every quoted source line in the file the page links, checks that each guide heading exists, that the quoted lines are the ones `docs/actions.md` quotes, and that the scenarios, renderer choices (Lit and React only; no Lynx) and the banner order are as the issue requires. `apps/lit-host/e2e/tour.spec.ts` builds the page and drives it in Chromium with every non-local request refused: the banner first in the reading order; every scenario in both renderers (allowed, refused by a prerequisite, denied after a valid session check, Bob's own notes, no credential, an unknown outcome after a write, two independent rows, an obsolete completion, closing the view); keyboard use (Tab order and focus indicators, arrow keys on radios, Enter and Space on controls and on a rendered row); a 320 px screen with no sideways scroll; text contrast under the system's light and dark preferences and under both chosen themes; accessible names, heading order, live regions and the frame title; and that no request leaves the page.

Run it:

    npm run build                                  # includes build:tour (apps/lit-host/dist/tour)
    npx vitest run --config vitest.config.ts scripts/tour.test.ts
    npm exec -w @saga-a2ui/lit-host-app -- playwright test e2e/tour.spec.ts

**Scope.** The tour simulates the session check, the denial and the server's effects, and the page labels each simulated interaction where it appears. The tour plays no media. The views keep the application's own colors, so a dark theme darkens the page around the frame, not the view inside it.

### The Fastify starter (STARTER-FASTIFY)

[#64](https://github.com/MachineWisdomAI/saga-a2ui/issues/64) qualifies the second pair: the `lit-mcp` stack on the `fastify` server target, `templates/lit-fastify`. It adds no package, runtime export or dependency to the SDK and changes no shared harness code: it reuses the STARTER1 export, stamping, snippet and packed-install code (`scripts/starter-template.ts`, `scripts/build-starter.ts`) and the shared qualification (`scripts/qualified-starters.ts`, `scripts/starter-qualification.ts`) as they are; it joins the inventory by adding `lit-fastify` to `QUALIFIED_STARTERS`. The view, the operations, the authentication and the identity and authorization files are the Node starter's own text; only `server/listener.ts`, `package.json`, `template.json` and the README differ.

**Adapter and peers, from the installed packages.** `@modelcontextprotocol/fastify` 2.0.1 (the official adapter; its peers are `fastify ^5.2.0` and `@modelcontextprotocol/server ^2.3.0`), `fastify` 5.12.7 and `@modelcontextprotocol/server` 2.4.0, with the Streamable HTTP transport of `@modelcontextprotocol/node` 2.1.1 that the adapter's own documentation pairs it with (the adapter implements no MCP transport). All are exact pins. The adapter package declares Node `>=20`; the starter and CI keep `>=22.12.0`. The pair is qualified on its own. `template.json` keeps the existing schema: the adapter is `@modelcontextprotocol/fastify` 2.0.1 and the other pins are in the template's manifest. The qualification installs `fastify` and the adapter from `apps/lit-host`'s dependencies, as it does the Node adapter.

**What the Fastify listener does.** `createMcpFastifyApp` creates the app and validates the Host and Origin headers (`ALLOWED_HOSTS` is the application's list of host names; the transport carries no second copy of that check). Authentication is an `onRequest` hook of the protected route only (the `identity-handoff` snippet): it runs before the body is read, hands the frozen per-request `AuthInfo` to the transport as the request's `auth`, and answers a refusal with the challenge and an empty body. SAGA adds no Fastify plugin, decorator or authentication layer: the application's verifier and policy files are unchanged and remain the only place identity and access are decided. Fastify's own body parsers read a body with no deadline, so the listener replaces them with one that passes the unread stream on; `readJsonBody` reads it as the request lifetime's bounded `body` stage, and the route handler hijacks the reply so that the transport and the deadline answer it. The 3 s operation and 10 s request defaults, the per-field overrides, the 408 with a closed connection, the 413 and 400 answers, and the destruction of a response the deadline overtakes are the Node listener's, moved to module level; the lifetime starts in the first application `onRequest` hook, after the adapter's Host and Origin checks.

**How the pair is qualified.** `lit-fastify` is listed in `scripts/qualified-starters.ts`, so `scripts/starter-template.test.ts` accepts its directory, `scripts/build-starter.ts` builds it into `apps/lit-host/dist/starters/lit-fastify` (with `identity.json`: source commit, platform, tarball digests and artifact digests) and `apps/lit-host/e2e/starter.spec.ts` runs its 6 browser cases against that build. `scripts/starter-fastify.test.ts` (31 headless cases: the 25 shared cases and 6 Fastify cases) calls the shared `qualifyStarter` suite against the starter exported from the packed candidate tarballs, type-checked and built with its own configuration, with a real MCP client over HTTP: the whole matrix of the other pairs (public; allowed; denied with a fixed sentence; no, malformed, unknown, expired, scope-less and account-less credentials refused at HTTP before any protected work; two overlapping requests each seeing their own identity; a verifier that rewrites the object it returns; the authentication, body and delivery clocks; an invalid budget failing before the port opens; the server refusing to start without the built page; the prerequisite that refuses sending no protected request; the starter run as its own process refusing every credential; and no test identity, demo verifier or copy of an SDK implementation in the output), plus what only this pair has: a foreign Host or Origin is refused with 403 before any credential is read while `localhost` and an absent Origin are served, an unserved path is a 404 that asks no one, the protected route requires a credential whatever the method, a content type Fastify would have rejected is answered by the transport rather than a Fastify parser error, and the adapter and peers are pinned and installed as declared. The three snippets are checked for every qualified template in `scripts/starter-template.test.ts`, which also requires the Fastify `identity-handoff` to carry `reply.code(decision.status)`. The browser cases include two overlapping requests for different accounts, both held inside the application's policy at once, each delivered to its own view, which shows only its own account.

Mutations the checks catch (each reverted): creating the app without the adapter's Host and Origin validation fails both adapter cases, and holding the verified context in shared state instead of the request fails the rewritten-record case.

**Scope.** `hono` ([#63](https://github.com/MachineWisdomAI/saga-a2ui/issues/63)) and `express` ([#62](https://github.com/MachineWisdomAI/saga-a2ui/issues/62)) are qualified in their own sections, and `hapi` ([#65](https://github.com/MachineWisdomAI/saga-a2ui/issues/65)) has its own template. The pair joined the supported-pair list the CLI ([#26](https://github.com/MachineWisdomAI/saga-a2ui/issues/26)) owns through [#179](https://github.com/MachineWisdomAI/saga-a2ui/issues/179); the [generated existing-backend recipes](../docs/attach-to-existing-backend.md) (GUIDE1, [#25](https://github.com/MachineWisdomAI/saga-a2ui/issues/25)) show its snippets from the template. Because the starter's parsers are replaced for the whole app, a Fastify application that attaches SAGA to existing routes keeps its own parsers by registering the two MCP routes in a plugin of their own. Linux x64, Node 26.7.0, npm 12.0.2, Playwright 1.64.0 Chromium (CI pins Node 22.12.0).

### Creating a project with `saga init` (CLI1)

[#26](https://github.com/MachineWisdomAI/saga-a2ui/issues/26) adds the command a developer runs to get the starter above as a new project. It is `scripts/saga.ts`, run from a checkout like the other scripts; it is not a package and nothing is published.

```sh
npx tsx scripts/saga.ts init --a2ui-stack lit-mcp --server node ./my-app
npx tsx scripts/saga.ts --help        # usage and the supported pairs
```

**What it does.** `--a2ui-stack <renderer>-mcp` and `--server <target>` name a pair; `init` copies that pair's maintained template (`exportTemplate`, the one implementation the starter, the snippets and the qualification share) into the new directory, with every `@saga-a2ui/*` dependency pinned to the build of the checkout it ran from (`0.0.0-candidate.g<12 hex>`, `.dirty` when tracked files differ; the identity of PACK2, not a release). It then prints the ordinary next commands (`cd`, `npm install`, `npm run build`, `npm start`) and says that the candidate is not published, so the install has to come from that build's tarballs ([candidate guide](../docs/candidate-update-and-rollback.md)). Exit status: 0 created, 1 refused or failed, 2 command line not understood, 130 interrupted.

**What it offers.** (A later change added `react-mcp` on `hono` from `templates/react-hono`; see the React and Hono starter section.) `SUPPORTED_PAIRS` in `scripts/saga.ts` is a plain list of the pairs CI qualifies: `lit-mcp` on `node` (`templates/lit-node`), `express` (`templates/lit-express`), `fastify` (`templates/lit-fastify`) and `hono` (`templates/lit-hono`), the four then in `QUALIFIED_STARTERS`, each qualified by its `scripts/starter*.test.ts` and `apps/lit-host/e2e/starter.spec.ts`. The three framework rows were registered by [#179](https://github.com/MachineWisdomAI/saga-a2ui/issues/179), the shared registration for criterion 5 of [#62](https://github.com/MachineWisdomAI/saga-a2ui/issues/62), [#63](https://github.com/MachineWisdomAI/saga-a2ui/issues/63) and [#64](https://github.com/MachineWisdomAI/saga-a2ui/issues/64); each row names its template explicitly and adds no code, parser or copy of a template. A template directory existing does not add a pair, and a pair whose template stops declaring that stack and server is refused. Any other pair (a React recipe, another stack) is refused before anything is written, and the refusal lists the supported ones. The owner of a further pair adds one row when its own qualification passes, and removes it while that fails; there is no registry or generator behind the list. When this section was written the list held four pairs; `hapi` ([#65](https://github.com/MachineWisdomAI/saga-a2ui/issues/65)) joined it with the SAGA-maintained Hapi starter (`templates/lit-hapi`), so `init` now offers five.

**What it will not do.** It creates one new directory and nothing else. A target that exists (a directory, a file, or a symbolic link, including a dangling one) is refused and left as it was; a missing parent directory is refused rather than created; a parent that is a symbolic link is resolved first, so the copy goes where the path leads. It starts no process: no install, no package manager, no script and no hook, and the starter's manifest declares no lifecycle hook. The directory is created only if it does not exist at that moment, so a competing creation is refused instead of merged into. If a write fails, the directory this run created is removed and nothing beside it is touched. "The directory this run created" is identified by the directory itself (device and inode from the exclusive creation), not by its path: before every file, after the last one and before any removal, the path is checked to still lead to that directory. If another process moved it away and put something else at the path, the command stops writing, removes nothing there, leaves the replacement as it is, and says so. Node has no directory-relative file calls, so a replacement landing between that check and the one call that follows it is not excluded; the check narrows the window to that instant, it does not close it. The copy hands control back to the event loop before each file, so a real SIGINT or SIGTERM is seen before the next write or before success is reported (a synchronous copy would run the signal callback only after it had finished): the directory this run created is removed, the created message is not printed, and the command exits 130. A second signal during that short cleanup is ignored. A process killed outright (SIGKILL, power loss) can leave a partial directory, which the developer deletes and re-creates with the same command.

**Evidence.** `scripts/saga.test.ts` (34 `init` cases, headless; the `demo` cases are in the next section) calls the command through its entry (`runCli`) for the created project, the clean output, an unsupported pair, command lines it cannot understand, every refused target and parent, a failing write, an abort during the copy and an output path replaced during the copy (the replacement is kept intact whether a write then fails, the copy carries on, the replacement comes after the last file, or an interrupt arrives), each time comparing the disk before and after; four further cases run `scripts/saga.ts` as a real process with stand-in `npm`, `npx`, `pnpm` and `yarn` on the `PATH` and show none was run, and that a real SIGINT and a real SIGTERM (sent by the process to itself on its fourth write; not SIGKILL) end with exit 130, no output directory and the neighbours untouched. `scripts/starter-template.test.ts` gained the case for a directory that appears between the existence check and its creation, one for an output replaced before a failing write, and one for the interruptible export reacting to a callback that only the event loop can run. Template content, stamping and snippets, and the behavior of the exported starter, keep their STARTER1 qualification and are not repeated. `scripts/saga.test.ts` also runs the real command for each of the four framework pairs and compares the output with that pair's template, adapter pin and SDK pins; the installed, typechecked and built output of each is the existing starter qualification's, unchanged.

### Creating the demonstration with `saga demo` (CLI2)

[#29](https://github.com/MachineWisdomAI/saga-a2ui/issues/29) adds the second command of the same CLI: the standalone demonstration of the qualified pair as a new directory. It is the same `scripts/saga.ts` (one parser, one set of exit codes), not a second program.

```sh
npx tsx scripts/saga.ts demo --a2ui-stack lit-mcp --server node ./my-demo
cd my-demo && npm install --omit=dev && npm start
```

**What it creates.** The DEMO1 download ([guide](../demo/lit-node/README.md)), exactly: `server.mjs`, the five built pages under `views/`, `package.json`, `README.md`, `LICENSE`, `THIRD_PARTY_NOTICES.md` and `release.json`, which ties them to the commit and candidate build of the checkout the command ran from. It is not a starter: its synthetic accounts, fixed development credentials and media live only in this output (`demo/lit-node/fixtures`, bundled into `server.mjs`), and `saga init` still exports the clean `templates/lit-node` with none of them. The output says on every start that it is local-only, and the command says so when it finishes.

**One implementation.** `stageDemo` in `scripts/build-demo.ts` runs DEMO1's own `prepareDemo`, `buildDemo` and `writeDownload` in a scratch directory outside the repository and the destination, and hands over the files; there is no second generator and no copied fixture. `createDirectoryInterruptibly` in `scripts/starter-template.ts` writes them. It is the destination handling `exportTemplate` already used (new directory only, ownership by device and inode, removal only of what this run created), now taking a list of files instead of a template, so `init` and `demo` differ only in where the files come from.

**What it offers.** `SUPPORTED_DEMO_PAIRS` in `scripts/saga.ts` is the entries of `SUPPORTED_PAIRS` whose template is `DEMO_TEMPLATE` (`scripts/qualified-starters.ts`, shared with the DEMO1 build): today `lit-mcp` on `node` only. A qualified starter alone adds no demonstration: `init` offers the `express`, `fastify` and `hono` starters, and `demo` still refuses them, because only the Node application is built and qualified as a demonstration. Any other selection is refused before anything is built or written, and the refusal lists the supported ones.

**What it will not do.** The same as `init`. An existing path (a directory, a file or a symbolic link, dangling or not) is refused and left as it was, a missing parent is refused rather than created, and a parent that is a symbolic link is resolved first. The target is checked before the build, so a taken path costs nothing, and again when the copy starts, so a path taken during the build is refused and not merged into. The build packs the repository's own packages with `npm pack` and asks `npm --version`; nothing is installed from a registry, no `npx`, `pnpm` or `yarn` is run, and no script or lifecycle hook of the output runs (its manifest declares only `start`). The output's `npm install --omit=dev` is the developer's own next step.

**Interruption.** A real SIGINT or SIGTERM during the build ends it before its next stage (each page, then the server), removes the scratch directory and exits 130 with nothing created, because the destination does not exist until the build has finished. A stage already running (one Vite build) finishes first. During the copy the behavior is `init`'s: the directory this run created is removed unless the path was replaced meanwhile, in which case nothing there is touched, and exit 130 is reported without the created message. SIGKILL or power loss during the copy can leave a partial directory, as for `init`.

**Evidence.** `scripts/saga.test.ts` covers the command with a stand-in build: selection, the command line, every refused target and parent, a target that appears during the build, a build that fails, a failing write, an abort before, during and after the build and during the copy, and a replaced output path. `scripts/saga-demo.test.ts` runs `scripts/saga.ts demo` as a process with stand-ins for the package managers. It creates the real download and shows that only `npm pack` and `npm --version` ran. It compares every file with what `buildDemoInto` writes (equal bytes; the bundle's region comments differ only in the scratch directory they name, so that file is compared with the name normalized). It checks the digests in `release.json` and the commit and candidate version, starts the created demonstration, shows that a starter made beside it has no demonstration credential or data, and sends a real SIGINT and SIGTERM during the build and during the copy.

### MCP Apps 2 recipe (MCPV2)

The browse and Play paths run on one peer-complete MCP Apps 2 recipe. It replaces the earlier `@modelcontextprotocol/sdk` 1.32.1 / `ext-apps` 1.7.5 / Zod 3 set; nothing of the old set remains installed or imported, and there is no compatibility layer. It is qualified locally against the `AppBridge` fixture; actual-host mapping (MAP1) belongs to the [connector Blueprint](../blueprints/features/reusable_mcp_connector.blueprint.md).

| Package | Exact version | License |
| --- | --- | --- |
| `@modelcontextprotocol/ext-apps` | 2.0.3 | MIT |
| `@modelcontextprotocol/client`, `core`, `server` | 2.4.0 | Apache-2.0 |
| `@modelcontextprotocol/node` | 2.1.1 | Apache-2.0 |
| `zod` (MCP seam, hoisted to the workspace root) | 4.6.7 | MIT |
| `@a2ui/lit`, `@a2ui/web_core` (unchanged) | 0.13.0 | Apache-2.0 |
| `zod` (each A2UI package's own nested copy) | 3.25.76 | MIT |

**The bundled URI parser.** The `client` and `server` packages bundle the JSON Schema engine and its `fast-uri` parser into their own files, so a lockfile entry or an override does not change it; `core` does not bundle the parser (checked in the published 2.4.0 tarballs, where `client` and `server` each carry `fast-uri` 3.1.8 and `core` carries none). `fast-uri` 3.1.8 has four advisories, all fixed in 3.1.9 (the GitHub advisory database and the 3.1.9 release notes are the sources): CVE-2026-110306 (a percent-encoded scheme is decoded into a live scheme), CVE-2026-110180 (a malformed domain host is rewritten by the second parser that canonicalizes it, so the host that was checked differs from the host used), CVE-2026-110095 (dot-segment removal applied to a relative reference in `normalize` and `serialize`) and CVE-2026-110725 (an unescaped first-segment colon in a `suffix` reference, only with that non-default option). The only repository code that builds an MCP client for a remote endpoint it does not own is the maintainer network module (`scripts/maintainer-network.ts`), whose sessions list tools with a raw request that the client does not cache, so no peer schema is compiled today. Its client still compiles any peer tool schema through `SchemaIdentifierValidator`, so a later change that caches a listing cannot reach the parser with an unvetted identifier: a schema whose `$id`, `$ref`, `$dynamicRef`, `$schema`, `$anchor` or `$dynamicAnchor` is not a plain URI reference (no dot segment, colon outside the scheme, percent-encoding, query, credential, backslash, or a host other than letters, digits, hyphens and dots with an optional port) is refused for that tool and never compiled. That filter rejects the input form of each of the four advisories; `scripts/maintainer-network.test.ts` covers an encoded scheme (`%` and `%u` forms), a dot segment, a first-segment colon, and a host with two `@` or a control character. The names under `dependentRequired` are property names, so that keyword is read as data like `enum` and `const`, not as identifier keywords. The shipped packages construct no such client; a server compiles only the schemas its own application registers. The residual risk is a bundled parser flaw reached through a form the filter admits; the trigger to reconsider is an `@modelcontextprotocol/client` release that bundles `fast-uri` 3.1.9 or later, when the filter can be dropped or kept as a guard.

Install with `npm ci` on Node 22.12.0 or newer (the MCP packages need Node 20+, so the workspace engine is unchanged). `ext-apps` declares `zod ^4.2`, `core`/`client`/`server` as peers and `node` requires `server ^2.3.0`; all are direct dependencies of `apps/lit-host`, so `npm ls --all` reports no missing or invalid peer.

**Two Zod versions, one boundary.** Zod 4 belongs to the MCP seam: tool, projection and request-metadata schemas (`mcp/episode.ts`, `mcp/subscriptions.ts`, `playback/playback.ts`, `mcp/request-auth.ts`) and the FaithfulCard reader and content policy configuration (`packages/components/src/faithful-card/reader.ts`, `policy.ts`) import `zod`; the component's A2UI catalog schema (`catalog.ts`) imports Zod 3 from `@saga-a2ui/core/protocols/a2ui/zod3`. Zod 3 belongs to upstream A2UI, whose `ComponentApi` and message schemas are Zod 3. Anything this application authors *for A2UI* (`saga-panel/contract.ts`, the decoder's types, the protocol test) imports `z` from `protocols/a2ui/zod3.ts`, which re-exports the exact-version `zod3` alias. `zod/v3` inside the Zod 4 package is not a substitute: its declarations differ from upstream's and the compiler's comparison runs out of memory. The root `package.json` declares `zod` 4.6.7 so that npm hoists it where `ext-apps` and the MCP packages share one copy and leaves each A2UI package its own Zod 3. `zod-to-json-schema`, which A2UI uses, is locked under `@a2ui/web_core` for the same reason (hoisted, its peer would resolve to Zod 4); `npm run candidate:identity` and its test fail if that placement drifts. A change to the A2UI pin is a separate decision. No Ansari package or version was touched.

**What moved together** (one change, no old path kept):

- Transport: `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node` replaces the monolithic SDK's transport. The listener still owns hosting, the Host-header rebinding check, the body bound and the request-classification gate (`protected-request.ts`) before any server is built.
- Verified request context: the application's `authenticate` is unchanged in behaviour, but its seam is now the server package's `OAuthTokenVerifier`/`OAuthError`, and the frozen snapshot reaches a tool as `ctx.http.authInfo`. The request signal and `_meta` are `ctx.mcpReq.signal` and `ctx.mcpReq._meta`.
- Runtime schemas: input and output are Zod 4 objects passed whole (no raw shapes). `PlayRequestSchema` is a `strictObject` with one fixed sentence for every issue; the recipient key's `d` member stays "absent or rejected" (`z.undefined().optional()`, because Zod 4 no longer treats an `undefined`-typed key as optional).
- Browser integration: views use the `App` and `PostMessageTransport` from `ext-apps` 2, whose runtime is built on `@modelcontextprotocol/client`; the view modules import types from that package. The test host fixture uses the matching `AppBridge`.
- Removed: the `@modelcontextprotocol/sdk` dependency, the raw-shape request exports (`EpisodeRequestShape`, `SubscriptionsRequestShape`) and the hand-written legacy `ui/resourceUri` key on Play (`registerAppTool` now accepts the strict schema and writes it).

Behaviour kept from the merged Play code: freshness and recipient binding, the 60-second capability, revocation on every acquisition, ranges, cache headers, the declared-origin-only `connect-src`, no redirects, and the fixed unsupported-recipient failure with zero entitlement checks and zero media reads. The unchanged specs (`playback.test.ts`, `media.test.ts`, `playback-view.test.ts`, `e2e/playback-view.spec.ts`) pass against the new recipe without edits to their expectations.

**Built views now carry the MCP client library.** `ext-apps` 2 imports `Protocol` from `@modelcontextprotocol/client`, so the single-file views grew and now contain the client's OAuth error classes. The bundle guard (`e2e/view-bundle.spec.ts`) therefore matches the credential header as a quoted name (`"authorization"`) instead of the bare word, and also forbids the HTTP client and server transports by name. The views set no header, use no HTTP client and read no credential. Inlined MIT and Apache-2.0 code keeps its license; carry the upstream notices with any view you distribute outside this repository (see [public install](../docs/public-install.md)).

**Candidate identities for MAP1.** After `npm run build`, `npm run candidate:identity` prints the source commit, the lockfile hash, every recipe package's resolved version and tarball integrity, the three served `ui://` resources with their built file and SHA-256, the Node version and the last verify receipt's per-command results (`--out FILE` writes it instead; keep the file in ignored `.wise-agents/`). The episode view is not served verbatim: the content policy embeds its restrictions in the document, and the URI is the SHA-256 byte identity of that served document (`ui://views/<filename>.<32-character-sha256-prefix>.html`). The report therefore builds that resource through the same `contentResource` the server registers and gives the served URI, byte count and SHA-256, with the raw build identified separately under `rawBuild`. Pass the candidate's configured policy as `--image-host HOST` (repeatable), `--level strict` and `--blocked-presentation placeholder|inert-text`; without them the report describes the default policy, and an invalid value is an error rather than a fallback. `scripts/candidate-identity.test.ts` compares the report with the resource a server returns for the default and for a configured policy. The same lockfile and sources produced identical resource hashes in this tree and in a fresh `npm ci` copy. Quote the output with the PR head in the acceptance record; do not commit a pasted copy, because the commit hash cannot name itself.

**Run it.** `npm ci`, `npx playwright install chromium`, `npm run verify`. The browser specs exercise the real listener and the built views: the public result (`mcp-view.spec.ts`), allowed, denied, changed-sign-in and refused browse (`subscriptions-view.spec.ts`), the app-only Play (declared `visibility: ['app']`, capability only in result `_meta`), and the unsupported-recipient failure for a host that drops request metadata (`playback-view.spec.ts`).