@legionworks/facet 1.9.0 → 1.10.1

package/docs/reference/mcp.md

@@ -4,12 +4,22 @@ On harnesses with shell access, the CLI is the integration; the MCP adapter is f
 
 Facet's npm package includes the `facet-mcp` bin. It needs Bun `1.4.0`; npm and pnpm install the package, but Bun remains the runtime.
 
-Run the adapter without a checkout:
+Install globally, then run the bin with Bun `1.4.0` or newer:
 
 ```sh
-bunx -p @legionworks/facet facet-mcp
+bun add -g @legionworks/facet
+facet-mcp
 ```
 
+Releases through `1.9.0` ship a `facet-mcp` bin that cannot launch: its entry file has no `#!/usr/bin/env bun` line. Use `1.10.0` or newer. With `1.10.0` on Bun `1.4.0`, each of these answered JSON-RPC `initialize` and listed six tools:
+
+- `bun add -g @legionworks/facet`, then `facet-mcp`
+- `npm i -g @legionworks/facet`, then `facet-mcp`
+- `npx -p @legionworks/facet facet-mcp`
+- `bunx -p @legionworks/facet facet-mcp`
+
+Run `npx -p` from outside a Facet checkout. Inside one, npx resolves the local project instead of the published package and fails with `facet-mcp: command not found`.
+
 The adapter resolves the CLI in this order: `FACET_CLI`, then `bun <adapter-relative-repository>/src/cli/main.ts`, then `facet` on `PATH`. Set `FACET_CLI` to an absolute CLI executable when the adapter should use another installation.
 
 ## Register the server
@@ -21,7 +31,7 @@ OpenCode config:
   "mcp": {
     "facet": {
       "type": "local",
-      "command": ["bunx", "-p", "@legionworks/facet", "facet-mcp"],
+      "command": ["facet-mcp"],
       "enabled": true
     }
   }
@@ -34,8 +44,7 @@ Claude Code project config (`.mcp.json`):
 {
   "mcpServers": {
     "facet": {
-      "command": "bunx",
-      "args": ["-p", "@legionworks/facet", "facet-mcp"]
+      "command": "facet-mcp"
     }
   }
 }
@@ -45,8 +54,7 @@ Codex config (`~/.codex/config.toml`):
 
 ```toml
 [mcp_servers.facet]
-command = "bunx"
-args = ["-p", "@legionworks/facet", "facet-mcp"]
+command = "facet-mcp"
 ```
 
 Set `FACET_HOME` in the host configuration when the adapter must use a non-default Facet runtime directory. Set `FACET_CLI` only for an alternate CLI executable.
@@ -55,6 +63,7 @@ Set `FACET_HOME` in the host configuration when the adapter must use a non-defau
 
 | Tool              | Inputs                                                                                                                    | Effect                                                                       |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `facet_create`    | `projectId`, `slug`, `title`                                                                                              | Creates an artifact; pass its returned `data.artifact.id` to publish.        |
 | `facet_publish`   | `artifactId`, `type`, exactly one of `sourceText` or `file`; optional `execution`, `renderer`, `note`, `parentRevisionId` | Publishes inline source through CLI stdin or reads the named local file.     |
 | `facet_read_back` | `artifactId`; optional `revisionSha`, `tier` (`0` \| `1` \| `visual`)                                                     | Reads the latest or named revision. Tier 1 and visual need browser evidence. |
 | `facet_status`    | optional `artifactId`, `start`                                                                                            | Reads status. Set `start` only when activation is intended.                  |
@@ -65,7 +74,15 @@ Set `FACET_HOME` in the host configuration when the adapter must use a non-defau
 
 Exactly one of `sourceText` or `file` is required. The adapter returns `invalid_request` when both or neither are supplied.
 
-The MCP surface is the five artifact tools; run `facet doctor` through the CLI.
+Tier 0 means structure was parsed and compiled, not rendered. Request
+`facet_read_back` with `tier: "visual"` before reporting a render. Visual
+evidence covers the first rendered state of an interactive TSX artifact;
+later interaction is not validated and does not change the stored verdict.
+When testing by hand with the MCP Inspector CLI, `--tool-arg key=value` passes
+`\n` literally, so multi-line `sourceText` arrives as one line; pass `file`
+instead.
+
+The MCP surface has six artifact tools. Start a cold-home flow with `facet_create`, then call `facet_publish`, `facet_read_back`, and `facet_export`. Each tool advertises its input schema in `tools/list`; run `facet doctor` through the CLI.
 
 ## Result and error handling
 
@@ -73,6 +90,10 @@ Every tool returns one text content item containing the complete versioned Facet
 
 Typed Facet failures return that same envelope with `isError: true`. The JSON body preserves `error.code`, `error.message`, `error.retryable`, and `error.details`. The adapter converts malformed CLI stdout and subprocess failures into typed `invalid_envelope` errors instead of throwing raw process text through MCP.
 
+For `output_unwritable`, `error.details.out` is the absolute path whose write
+failed. A malformed Mermaid fence is a verdict result, not a tool failure: the
+call returns `isError: false` with `data.verdict.status: "error"`.
+
 ## Boundary
 
 The adapter only shells out to `facet` and parses the shared wire envelope. It does not import service, validation, or gallery code. The boundary checker permits only the MCP SDK, Zod, Node builtins, adapter-local modules, shared contracts, and the shared product version in `src/harness-adapters/mcp/`.

package/docs/reference/security.md

@@ -107,6 +107,13 @@ service.
 |   `2` | Removes Tier 0 and Tier 1 network-namespace isolation. Real validators still run.             |
 |   `3` | Performs no validation and records `insecure:unvalidated`.                                    |
 
+Level 3 skips publish-time validation, not an explicit visual read-back.
+`facet read-back --tier visual` still runs Tier 1, and that verdict carries the
+insecure marker. Evidence consumers must check the marker, not infer trust from
+`status` alone. A level-3 visual verdict does not count toward `facet promote`
+either — the gate refuses it as `insecure:unvalidated` unless the operator
+passes `--allow-unverified`.
+
 Levels compose as a forced floor: the effective level is never below the
 operator's `FACET_INSECURE` value. `FACET_INSECURE_AUTO=1` may raise a level when
 startup probes fail, but it never selects level 3. With auto mode off, hard

package/docs/reference/storage.md

@@ -23,7 +23,7 @@ the evidence root and every per-run evidence directory.
 ## Schema migrations
 
 `runMigrations` records applied versions in `schema_migrations` and applies
-additive fragments in order. The current schema is v9:
+additive fragments in order. The current schema is v10:
 
 | version | change                                                                                                                                                                 |
 | ------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -36,6 +36,7 @@ additive fragments in order. The current schema is v9:
 |      v7 | Backfills HTML observation defaults.                                                                                                                                   |
 |      v8 | Adds `tsx`, declared revision execution, and nullable `render_runs.compiled_path`.                                                                                     |
 |      v9 | Adds `render_runs.screenshot_format`, recorded as `png` or `webp` for retained evidence.                                                                               |
+|     v10 | Adds nullable `templates.promotion_override`; null for pre-v10 templates and for promotions that passed the verification gate.                                         |
 
 Migrations are additive and transactional. Existing revisions are not rewritten
 when a later schema version is applied.
@@ -81,6 +82,10 @@ artifact and unlinks older screenshot and console files. Rows marked
 `retained = 1` are exempt. Cleanup is best-effort; the database row remains the
 authority and the orphan sweep can recover from stale files.
 
+Facet targets one operator on a local machine. The evidence bound is the last
+`EVIDENCE_LAST_N_PER_ARTIFACT` Tier 1 runs per artifact, plus any retained runs.
+There is no quota; retained evidence can grow without a fixed limit.
+
 ## Templates
 
 A template records one immutable revision ID. Later publication to the source

package/docs/reference/tsx.md

@@ -29,6 +29,15 @@ and must not call `createRoot` or self-mount.
 
 ## Imports and styling
 
+Artifacts cannot fetch data (`connect-src 'none'`). Generate source with the
+data embedded, then publish it. For repeated updates, regenerate the file and
+use `facet publish --watch` to publish each changed version:
+
+```sh
+node -e 'const data = [{label:"A", value:3}]; require("node:fs").writeFileSync("report.tsx", `export default function Report(){ return <pre>{JSON.stringify(${JSON.stringify(data)})}</pre> }`)'
+facet publish --artifact-id <id> --type tsx --file report.tsx
+```
+
 The compiler accepts only vendored modules: `react`, `react-dom`,
 `react-dom/client`, `react/jsx-runtime`, and `react/jsx-dev-runtime`.
 Pinned versions are React and React DOM `19.2.8`, TypeScript `5.7.3`.
@@ -62,6 +71,13 @@ has no host port or service capability.
 
 ## Storage and export
 
+The TSX verifier loads the vendored `artifact.css` used by the gallery frame.
+A runtime error after initial render, such as one thrown by a click handler,
+appears as a gallery signal in an `aria-live="polite"` status region. It does
+not rewrite the immutable verdict. It clears on revision swap. Switching the
+theme keeps the frame mounted, including interactive component state and any
+runtime error signal already displayed.
+
 Revision source remains immutable. Compilation creates derived bytes recorded at
 the run's `compiled_path`; TSX source export writes the original `.tsx` bytes.
 Render export remains the retained Tier 1 screenshot. Evidence retains the last

package/docs/reference/validation.md

@@ -18,6 +18,7 @@ Every other layer is bound to it through `VerdictSchema.status`.
 | `partial:opaque_content`     | An opaque DOM region was observed, so structural contents were not verified. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently.                                                                                                                                                                                                                                                                                                                                                                   |
 | `partial:external_resources` | The artifact references external HTTPS images the no-egress verifier could not observe. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently.                                                                                                                                                                                                                                                                                                                                                        |
 | `partial:unstable`           | TSX interactive mode: the structure observed at the render barrier differed from the structure observed after a bounded stability window. Deliberately NOT `tampered` — a legitimately animated or async-loading component also changes structure between observations, and branding that a forgery would manufacture the false-verdict class this project has spent three arcs eliminating. `tampered` stays reserved for channel divergence. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently. |
+| `partial:empty_render`       | TSX Tier 1: all authoritative observations agree that the renderer root has no element children and no non-whitespace text. MUST carry a screenshot path, or a typed `screenshotError` marker when capture fails transiently.                                                                                                                                                                                                                                                                                                                    |
 | `tampered`                   | Page-shim or isolated-world observation diverges from protocol authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `timeout`                    | The harness did not emit `render-complete` within `TIER1_RENDER_BARRIER_MS`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `shim_only`                  | Isolated-world channel missing; only the untrusted page-shim produced usable counts.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -43,11 +44,12 @@ ordering, top to bottom:
 3. `probe_only` / `shim_only` — channel availability (meta-claim about the channels, not the page).
 4. `error` — discriminative errors are non-empty, or observed counts disagree with the lexical expectation. Both survive a structure change: a parse error is a parse error whenever it was observed, and a count that never matched the source's expectation never matches.
 5. **`partial:unstable`** — TSX interactive mode; structure changed between the render barrier and the stability window.
-6. `error` (declared-opaque, observed-zero) — the artifact declared opaque regions and none were seen. This sits BELOW `partial:unstable` deliberately: it compares the expectation against a SINGLE observation, so a structure change makes it unsafe to assert. A canvas that painted after the barrier would otherwise be reported as an artifact that never painted at all — a false accusation, which is the failure class the whole partial taxonomy exists to avoid.
-7. `partial:opaque_content` — single-snapshot claim: structure has opaque regions.
-8. `partial:external_resources` — single-snapshot claim: structure has external HTTP references.
-9. `partial:layout_unverified` — single-snapshot claim: visible SVG with zeroed viewBoxes.
-10. `ok`.
+6. `partial:empty_render` — TSX root emptiness, after instability and before other single-snapshot partials.
+7. `error` (declared-opaque, observed-zero) — the artifact declared opaque regions and none were seen.
+8. `partial:opaque_content` — single-snapshot claim: structure has opaque regions.
+9. `partial:external_resources` — single-snapshot claim: structure has external HTTP references.
+10. `partial:layout_unverified` — single-snapshot claim: visible SVG with zeroed viewBoxes.
+11. `ok`.
 
 The rule generalizing rows 4 and 6: a claim that depends on ONE observation
 loses to `partial:unstable`; a claim that holds regardless of when it was
@@ -68,13 +70,21 @@ mode 0700 — the canonical secret-bearing layout matches the DB file
 permissions.
 
 Tier 1 capture happens AFTER the verdict is derived so the
-`partial:layout_unverified`, `partial:opaque_content`, `partial:external_resources`, and `partial:unstable` screenshot mandates are honored. The runner
+`partial:layout_unverified`, `partial:opaque_content`, `partial:external_resources`, `partial:unstable`, and `partial:empty_render` screenshot mandates are honored. The runner
 measures the whole artifact, bounds each axis at 4096 pixels and the total at
 8,388,608 pixels, and encodes evidence under the 8 MiB cap. New captures are
 WebP; legacy PNG evidence remains readable and exportable. Before static
 capture it emulates `prefers-reduced-motion: reduce` and awaits
 `document.fonts.ready`; these pre-flights keep repeated captures byte-identical.
 
+Tier 1 uses the same artifact-type layout rules as the gallery frame: Mermaid,
+SVG, and chart roots are safely centered on both axes, with oversized content
+remaining reachable by scrolling; Markdown is top-aligned in a horizontally
+centered column capped at about 92ch; HTML and TSX use top-aligned document
+flow, where a fixed-width layout can center itself with `mx-auto`. The renderer-parity gate
+compares both the gallery and verifier renderer-module sets and CSS/stylesheet
+sets.
+
 Interactive TSX declares animated-capture eligibility; it does not imply that
 the component is always visibly changing. CSS/Web Animations are probed, and
 eligible captures may contain multiple WebP frames. Static artifacts retain a
@@ -90,8 +100,26 @@ browser or network-namespace failure records a Tier 1 `error` verdict with its
 typed `tier1_*` code; it does not erase the Tier 0 verdict or turn visual
 read-back into `revision_not_found`.
 
+Tier 0 `ok` means the source passed structural checks; rendering is not
+verified. The TTY presenter says `structure checked · rendering not verified`
+and includes a visual read-back command. TSX Tier 0 reports `ok · compiled`.
+The JSON envelope is unchanged. A malformed Mermaid fence returns `error` with
+`mermaid_parse_error`, the parser message, and a zero-based `mermaid fence <i>`
+location.
+
+Tier 0 grammar-checks Mermaid fences but does not sanitize Mermaid label HTML;
+it never renders a diagram. Sanitization happens in Tier 1, when Mermaid runs
+in the real browser.
+
 ## Observed fields and renderer expectations
 
+For Vega-Lite charts, Facet supplies 640×360 view defaults through
+`config.view` only when the spec omits `autosize`, `config.view`, and both
+top-level `width` and `height`. A supplied width or height is preserved while
+the other dimension receives its default. An authored `config.view` or
+`autosize` prevents defaulting. The composite-view defaults reach facet,
+concat, and repeat children; author sizing is not replaced.
+
 The canonical observed fields include `rendererRootSvgCount`, `graphCount`,
 `mermaidNodeCount`, `visibleSvgCount`, `opaqueRegionCount`, `viewBoxes`,
 `errorCount`, and `discriminativeErrors`. `opaqueRegionCount` counts DOM

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legionworks/facet",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "private": false,
   "keywords": [
     "artifacts",
@@ -20,8 +20,8 @@
     "url": "git+https://github.com/legion-works/facet.git"
   },
   "bin": {
-    "facet": "./src/cli/main.ts",
-    "facet-mcp": "./src/harness-adapters/mcp/main.ts"
+    "facet": "src/cli/main.ts",
+    "facet-mcp": "src/harness-adapters/mcp/main.ts"
   },
   "files": [
     "src/**",
@@ -42,7 +42,7 @@
     "build": "bun scripts/build-gallery.ts",
     "prepack": "bun scripts/build-gallery.ts --if-stale",
     "lint": "oxlint --deny-warnings",
-    "format": "oxfmt",
+    "format": "bun scripts/check-format.ts --write",
     "format:check": "bun scripts/check-format.ts",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.runtime-egress-fixture.json",
     "test": "bun test",

package/skills/facet/SKILL.md

@@ -67,15 +67,33 @@ the detected evidence format:
 
 Promotion is operator-only. The CLI discovers the token from
 `FACET_PROMOTE_TOKEN`, then `FACET_HOME/secrets/promote.token`; never put a
-token on argv.
+token on argv. First request visual read-back for the exact revision, then
+promote it. Tier 0 or publication success is not visual verification. The
+`templates` command lists promoted templates and their source verdicts.
+`--allow-unverified` records the refusal reason as `promotionOverride` for
+audit; it does not create verification or turn a refusal into a passing verdict.
+A Tier 1 verdict carrying `insecure.level === 3` is refused as
+`insecure:unvalidated` even when its status would otherwise be allow-listed —
+levels 1 and 2 are real validator runs and keep status-based treatment.
 
 ## Error quick reference
 
+Render statuses are a closed set: `ok`, `error`, `partial:layout_unverified`,
+`partial:opaque_content`, `partial:external_resources`, `partial:unstable`,
+`partial:empty_render`, `tampered`, `timeout`, `shim_only`, `probe_only`, and
+`insecure:unvalidated`.
+
+Tier 0 `ok` means structure checked, not rendered. For visual evidence, run
+`facet read-back --artifact-id <id> --tier visual`. TSX Tier 0 `ok` means
+`ok · compiled`. Tier 1 TSX can return `partial:empty_render` when all
+authoritative channels agree that the renderer root has no elements or
+non-whitespace text; the verdict requires a screenshot.
+
 | Error                    | Do next                                                                                                          |
 | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
 | `invalid_request`        | Correct the command flags, artifact type, or source bytes, then retry.                                           |
 | `artifact_not_found`     | List or create the artifact, then use its returned ID.                                                           |
-| `revision_not_found`     | Omit the SHA for latest, or replace it with a returned revision SHA.                                             |
+| `revision_not_found`     | Check that the artifact has a revision; omit the SHA for latest, or replace it with a returned revision SHA.     |
 | `duplicate_revision`     | Use `error.details.revisionSha` as the existing revision SHA; do not republish identical bytes.                  |
 | `evidence_unavailable`   | Request Tier 1 evidence for that revision before a render export, or export source instead.                      |
 | `output_unwritable`      | Choose a writable `--out` path, resolve collisions, or use `--force` deliberately.                               |
@@ -94,6 +112,10 @@ token on argv.
   or ask a human to inspect.
 - Preserve stdout exactly so callers can parse the versioned envelope.
 - With shell access, the CLI is the integration — MCP is for structured-tool-only hosts, even when the host owns an MCP client. On that surface, `facet_open_url` is safe because it always uses `--no-launch`.
+- For MCP registration, use `bun add -g @legionworks/facet` and the bare
+  `facet-mcp` command, or the no-install fallback `npx -p @legionworks/facet
+facet-mcp` (`bunx -p` also works). Use `1.10.0` or newer; earlier releases
+  ship a `facet-mcp` bin that cannot launch.
 
 ## Deeper reference
 

package/src/cli/commands/promote.ts

@@ -43,6 +43,7 @@ export function buildPromoteRequest(
     revisionId,
     name,
     promotedBy,
+    ...(args["allow-unverified"] === true ? { allowUnverified: true } : {}),
     ...(typeof artifactId === "string" ? { artifactId } : {}),
     ...(typeof description === "string" ? { description } : {}),
   };

package/src/cli/commands/templates.ts

@@ -0,0 +1,25 @@
+import { generateRequestId } from "../../shared/util/time";
+import { FacetError } from "../../shared/errors/facet-error";
+import { MAX_LIST_LIMIT } from "../../shared/config/limits";
+import type { TemplatesRequest } from "../../shared/contracts/commands/requests";
+
+export function buildTemplatesRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): TemplatesRequest {
+  const limit = args["limit"];
+  const limitNumber = typeof limit === "string" ? Number(limit) : undefined;
+  if (
+    limitNumber !== undefined &&
+    (!Number.isSafeInteger(limitNumber) || limitNumber < 1 || limitNumber > MAX_LIST_LIMIT)
+  ) {
+    throw new FacetError(
+      "invalid_request",
+      `--limit must be an integer between 1 and ${MAX_LIST_LIMIT}`,
+    );
+  }
+  return {
+    command: "templates",
+    requestId: generateRequestId(),
+    ...(limitNumber === undefined ? {} : { limit: limitNumber }),
+  };
+}

package/src/cli/main.ts

@@ -37,6 +37,7 @@ import { FacetClient } from "./client";
 
 import { buildCreateRequest } from "./commands/create";
 import { buildListRequest } from "./commands/list";
+import { buildTemplatesRequest } from "./commands/templates";
 import { buildOpenRequest, launchDisplay } from "./commands/open";
 import { buildPinRequest } from "./commands/pin";
 import { buildPromoteRequest } from "./commands/promote";
@@ -168,6 +169,9 @@ async function executeVerb(
     case "list":
       request = buildListRequest(args);
       break;
+    case "templates":
+      request = buildTemplatesRequest(args);
+      break;
     case "readBack":
       request = buildReadBackRequest(args);
       break;

package/src/cli/parser.ts

@@ -77,6 +77,7 @@ const VERB_FLAGS: Readonly<Record<CommandName, readonly FlagDefinition[]>> = {
     { flag: "--slug-prefix", takesValue: true },
     { flag: "--limit", takesValue: true },
   ],
+  templates: [{ flag: "--limit", takesValue: true }],
   readBack: [
     { flag: "--artifact-id", takesValue: true, required: true },
     { flag: "--revision-sha", takesValue: true },
@@ -97,6 +98,7 @@ const VERB_FLAGS: Readonly<Record<CommandName, readonly FlagDefinition[]>> = {
     { flag: "--name", takesValue: true, required: true },
     { flag: "--description", takesValue: true },
     { flag: "--promoted-by", takesValue: true, required: true },
+    { flag: "--allow-unverified", takesValue: false },
   ],
   instantiate: [
     { flag: "--name", takesValue: true, required: true },
@@ -121,6 +123,7 @@ const VERB_TO_COMMAND: Readonly<Record<string, CommandName>> = {
   create: "create",
   publish: "publish",
   list: "list",
+  templates: "templates",
   "read-back": "readBack",
   status: "status",
   open: "open",
@@ -134,6 +137,7 @@ const COMMAND_TO_VERB: Readonly<Record<CommandName, string>> = {
   create: "create",
   publish: "publish",
   list: "list",
+  templates: "templates",
   readBack: "read-back",
   status: "status",
   open: "open",

package/src/cli/presenter.ts

@@ -55,6 +55,7 @@ export const VERDICT_GLYPH: Record<RenderStatus, string> = {
   "partial:opaque_content": "◐",
   "partial:external_resources": "◐",
   "partial:unstable": "◐",
+  "partial:empty_render": "◐",
   tampered: "⊘",
   timeout: "◌",
   shim_only: "◇",
@@ -82,6 +83,7 @@ const STATUS_TONE: Record<RenderStatus, Tone> = {
   "partial:opaque_content": "yellow",
   "partial:external_resources": "yellow",
   "partial:unstable": "yellow",
+  "partial:empty_render": "yellow",
   tampered: "redInverse",
   timeout: "dim",
   shim_only: "dim",
@@ -101,6 +103,10 @@ function row(label: string, value: string): string {
   return `  ${label.padEnd(10, " ")}${value}`;
 }
 
+function shortCell(value: string, width: number): string {
+  return value.length <= width ? value : `${value.slice(0, width - 1)}…`;
+}
+
 function verdictLines(verdict: Verdict, caps: PresenterCaps): string[] {
   const paint = makePaint(caps);
   const tone = STATUS_TONE[verdict.status];
@@ -108,6 +114,9 @@ function verdictLines(verdict: Verdict, caps: PresenterCaps): string[] {
   const head = [
     paint(tone, `${VERDICT_GLYPH[verdict.status]} ${word}`),
     ...(detail === undefined ? [] : [paint("dim", detail)]),
+    ...(verdict.tier === 0 && verdict.status === "ok" && verdict.execution !== undefined
+      ? [paint("dim", "compiled")]
+      : []),
     paint("dim", `tier ${verdict.tier}`),
     `${verdict.artifactId} ${paint("dim", "@")} ${paint("cyan", sha8(verdict.revisionSha))}`,
   ].join(paint("dim", " · "));
@@ -121,6 +130,12 @@ function verdictLines(verdict: Verdict, caps: PresenterCaps): string[] {
       "observed",
       `svg ${o.rendererRootSvgCount} · graphs ${o.graphCount} · nodes ${o.mermaidNodeCount} · errors ${o.errorCount}`,
     ),
+    ...(verdict.tier === 0 && verdict.status === "ok"
+      ? [
+          "  structure checked · rendering not verified",
+          row("verify", `facet read-back --artifact-id ${verdict.artifactId} --tier visual`),
+        ]
+      : []),
   ];
   const first = o.discriminativeErrors?.[0];
   if (first !== undefined)
@@ -163,6 +178,15 @@ export function presentEnvelope(envelope: FacetEnvelope<unknown>, caps: Presente
     if (revision?.sha256 !== undefined) {
       lines.push(row("read-back", `facet read-back --revision-sha ${revision.sha256}`));
     }
+    const tier0 = data["verdict"];
+    if (
+      typeof tier0 === "object" &&
+      tier0 !== null &&
+      (tier0 as Verdict).tier === 0 &&
+      (tier0 as Verdict).status === "ok"
+    ) {
+      lines.push(...verdictLines(tier0 as Verdict, caps));
+    }
     const tier1 = data["tier1Verdict"];
     if (typeof tier1 === "object" && tier1 !== null) {
       lines.push(...verdictLines(tier1 as Verdict, caps));
@@ -188,6 +212,30 @@ export function presentEnvelope(envelope: FacetEnvelope<unknown>, caps: Presente
     }
   }
 
+  if (command === "templates") {
+    const templates = Array.isArray(data["templates"]) ? data["templates"] : [];
+    const lines = ["NAME · SHA · VERDICT · OVERRIDE · BY · DATE"];
+    for (const entry of templates) {
+      const item = entry as Record<string, unknown>;
+      const verdict = item["sourceVerdict"] as { status: RenderStatus; tier: number } | null;
+      lines.push(
+        [
+          shortCell(String(item["name"]), 12),
+          String(item["revisionSha"]).slice(0, 12),
+          verdict === null
+            ? "—"
+            : `${VERDICT_GLYPH[verdict.status]} ${verdict.status} t${verdict.tier}`,
+          item["promotionOverride"] === null
+            ? ""
+            : shortCell(String(item["promotionOverride"]), 12),
+          shortCell(String(item["promotedBy"]), 8),
+          String(item["promotedAt"]).slice(0, 10),
+        ].join(" · "),
+      );
+    }
+    return lines;
+  }
+
   if (command === "doctor") {
     const probes = Array.isArray(data["probes"]) ? data["probes"] : [];
     const lines: string[] = [];

package/src/gallery-web/app.ts

@@ -23,7 +23,12 @@
  * surfaces an error badge.
  */
 
-import { assertLoopbackHostname, buildFrameAttributes, type FrameAttributes } from "./frame-html";
+import {
+  assertLoopbackHostname,
+  buildFrameAttributes,
+  usesArtifactStylesheet,
+  type FrameAttributes,
+} from "./frame-html";
 import { planSwap, type SwapPlanStep } from "./swap";
 import { connectRevisionStream } from "./sse-client";
 import type { VerdictObserved } from "../shared/contracts/validation";
@@ -376,6 +381,7 @@ export interface CreatedArtifactFrame {
     payload: FrameRenderPayload,
     timeoutMs: number,
   ) => Promise<FrameRenderResultHandle>;
+  readonly setTheme: (theme: ResolvedGalleryTheme) => void;
   /** Handle from the last successful render (null before the first). */
   readonly renderResult: FrameRenderResultHandle | null;
 }
@@ -488,6 +494,14 @@ export function createArtifactFrame(options: CreateArtifactFrameOptions): Create
       renderResult = handle;
       return handle;
     },
+    setTheme(theme) {
+      // oxlint-disable-next-line no-underscore-dangle
+      const api = raw.contentWindow?.__facetFrame;
+      if (api === null || api === undefined || typeof api.setTheme !== "function") {
+        throw new Error("frame theme API unavailable");
+      }
+      api.setTheme(theme);
+    },
     get renderResult(): FrameRenderResultHandle | null {
       return renderResult;
     },
@@ -888,7 +902,9 @@ function setGalleryVerdict(document: Document, verdict: Verdict | null): void {
             ? "external"
             : verdict.status === "partial:unstable"
               ? "unstable"
-              : null;
+              : verdict.status === "partial:empty_render"
+                ? "empty"
+                : null;
     const insecure = verdict.insecure === undefined ? null : `INSECURE L${verdict.insecure.level}`;
     const suffix = insecure === null ? `T${verdict.tier}` : `${insecure} · T${verdict.tier}`;
     tier.textContent = detail === null ? `· ${suffix}` : `· ${detail} · ${suffix}`;
@@ -1091,6 +1107,42 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
   let removeThemePreferenceListener: () => void = noOp;
   let generation = 0;
   let activeFrame: CreatedArtifactFrame | null = null;
+  let removeInteractionListener: () => void = noOp;
+  // Every path that leaves the displayed frame ends the signal: a stale flag would paint the
+  // previous artifact's runtime error onto whatever the shell shows next.
+  const endInteractionSignal = (): void => {
+    removeInteractionListener();
+    const badge = document.getElementById("facet-verdict");
+    if (badge !== null) delete badge.dataset.interactionError;
+  };
+  const activateInteractionSignal = (frame: CreatedArtifactFrame): void => {
+    endInteractionSignal();
+    const badge = document.getElementById("facet-verdict");
+    updateGalleryStatus("displayed");
+    const frameWindow = (frame.element.raw as HTMLIFrameElement).contentWindow;
+    if (frameWindow === null || typeof frameWindow.addEventListener !== "function") return;
+    const markFailure = (): void => {
+      if (expired || activeFrame !== frame || frame.renderResult === null) return;
+      if (badge !== null) badge.dataset.interactionError = "true";
+      updateGalleryStatus("displayed · runtime error during interaction");
+    };
+    frameWindow.addEventListener("error", markFailure, true);
+    frameWindow.addEventListener("unhandledrejection", markFailure, true);
+    const frameDocument = (frame.element.raw as HTMLIFrameElement).contentDocument;
+    const observer =
+      frameDocument == null || typeof MutationObserver !== "function"
+        ? null
+        : new MutationObserver(() => {
+            if (frameDocument.querySelector("[data-facet-error]")) markFailure();
+          });
+    if (frameDocument !== null)
+      observer?.observe(frameDocument, { childList: true, subtree: true });
+    removeInteractionListener = (): void => {
+      frameWindow.removeEventListener("error", markFailure, true);
+      frameWindow.removeEventListener("unhandledrejection", markFailure, true);
+      observer?.disconnect();
+    };
+  };
   const expireSession = (): void => {
     if (expired) return;
     generation += 1;
@@ -1100,6 +1152,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
     exportMenu?.sync();
     activeFrame?.renderResult?.setGestureMode("native");
     swaps?.close();
+    endInteractionSignal();
     removeThemePreferenceListener();
     clearSession(window.sessionStorage);
     renderSessionExpired(
@@ -1237,6 +1290,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
   updateGalleryFavicon(source.verdict?.status ?? "unverified");
   updateGalleryVerdict(source.verdict ?? null);
   updateGalleryStatus("displayed");
+  activateInteractionSignal(current);
   updateLiveState("live");
   const themeToggle = document.getElementById("facet-theme-toggle");
   const updateThemeToggle = (mode: GalleryThemeMode): void => {
@@ -1269,6 +1323,11 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
     const canCommit = (): boolean =>
       themeGeneration === generation && nextMode === requestedThemeMode;
     if (!canCommit()) return;
+    if (usesArtifactStylesheet(source.artifactType)) {
+      current.setTheme(nextResolvedTheme);
+      commitTheme(nextMode, nextResolvedTheme);
+      return;
+    }
     const next = createArtifactFrame({
       artifactType: source.artifactType,
       renderer: source.renderer,
@@ -1295,6 +1354,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
     if (!canCommit() || result.cancelled || result.failedNewFrameReady) return;
     current = next;
     activeFrame = next;
+    activateInteractionSignal(next);
     commitTheme(nextMode, nextResolvedTheme);
     syncPanZoomToggle();
     syncZoomButtons();
@@ -1373,6 +1433,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
           if (!result.failedNewFrameReady) {
             current = frame;
             activeFrame = frame;
+            activateInteractionSignal(frame);
             source = revision;
             commitTheme(revisionThemeMode, revisionTheme);
             syncPanZoomToggle();
@@ -1439,6 +1500,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
       updateSwapBar("start");
       updateGalleryFavicon("unverified");
       updateGalleryVerdict(null);
+      endInteractionSignal();
       swaps?.enqueue({ kind: "revision", ...event });
     },
     onClose: (event) => {
@@ -1472,6 +1534,7 @@ export async function startGallery(runtime = browserGalleryRuntime()): Promise<v
     // releases the lease when the TTL fires, which is the only path
     // that lets "refresh the tab" reach the same displayed canvas.
     stream.close();
+    removeInteractionListener();
     removeThemePreferenceListener();
     if (zoomButtonPoll !== undefined) clearInterval(zoomButtonPoll);
   };