@legionworks/facet 1.9.0 → 1.10.0

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 are top-aligned while their
+renderer roots are safely centered across the stage. 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.0",
   "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,10 +67,28 @@ 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.                                           |
@@ -94,6 +112,11 @@ 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`. The measured `bunx -p @legionworks/facet facet-mcp` form exited
+  with status 1 under Bun `1.3.14` and the available scratch Bun `1.4.0`; treat
+  that as an environment-specific caveat, not a universal Bun claim.
 
 ## 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

@@ -888,7 +888,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 +1093,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 +1138,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 +1276,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 => {
@@ -1295,6 +1335,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 +1414,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 +1481,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 +1515,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);
   };

package/src/gallery-web/favicon.ts

@@ -10,6 +10,7 @@ export const FAVICON_TINT_BY_STATUS = {
   "partial:opaque_content": "amber",
   "partial:external_resources": "amber",
   "partial:unstable": "amber",
+  "partial:empty_render": "amber",
   tampered: "red",
   timeout: "red",
   shim_only: "grey",

package/src/gallery-web/frame/renderers/chart.ts

@@ -128,6 +128,36 @@ export function withFacetChartTheme(spec: unknown, theme: ResolvedGalleryTheme):
   };
 }
 
+export function withFacetChartDimensions(spec: unknown): unknown {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec)) return spec;
+  const source = spec as Readonly<Record<string, unknown>>;
+  const config = source.config;
+  if (
+    "autosize" in source ||
+    (typeof config === "object" && config !== null && !Array.isArray(config) && "view" in config)
+  )
+    return spec;
+  if ("width" in source && "height" in source) return spec;
+  const authoredConfig =
+    typeof config === "object" && config !== null && !Array.isArray(config)
+      ? (config as Readonly<Record<string, unknown>>)
+      : {};
+  const viewDefaults = {
+    ...(!("width" in source) ? { continuousWidth: 640, discreteWidth: 640 } : {}),
+    ...(!("height" in source) ? { continuousHeight: 360, discreteHeight: 360 } : {}),
+  };
+  // Composite views ignore top-level dimensions; config.view reaches each child view. An
+  // authored config.view wins because its sizing is an explicit author choice. The 640×360
+  // plot defaults leave charts readable in the 1280×800 verifier viewport.
+  return {
+    ...source,
+    config: {
+      ...authoredConfig,
+      view: viewDefaults,
+    },
+  };
+}
+
 /** Render a chart artifact (artifactType "chart"): Vega-Lite JSON bytes. */
 export async function renderChart(
   ctx: RenderContext,
@@ -144,7 +174,7 @@ export async function renderChart(
   }
   let compiled: { spec: unknown };
   try {
-    compiled = compile(withFacetChartTheme(spec, ctx.theme) as never);
+    compiled = compile(withFacetChartTheme(withFacetChartDimensions(spec), ctx.theme) as never);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new FacetRenderError(`vega-lite compile failed: ${message}`, "chart_compile_error");

package/src/gallery-web/frame/styles/frame.css

@@ -98,12 +98,19 @@ body {
  * wider than the stage (it start-aligns and stays reachable by
  * scroll instead).
  */
+#artifact[data-facet-artifact-type="html"],
+#artifact[data-facet-artifact-type="tsx"] {
+  display: flex;
+  flex-direction: column;
+}
+
 #artifact[data-facet-artifact-type="html"] > [data-facet-renderer-root],
 #artifact[data-facet-artifact-type="tsx"] > [data-facet-renderer-root] {
   display: flex;
   justify-content: safe center;
   align-items: flex-start;
-  min-height: 100%;
+  /* A full-height root plus a sibling runtime error makes capture bounds grow on every viewport resize. */
+  flex: 1 0 auto;
 }
 
 #artifact > svg {

package/src/gallery-web/frame-html.ts

@@ -9,6 +9,7 @@
  */
 
 import { galleryDataTheme, type ResolvedGalleryTheme } from "./theme";
+import { artifactMainAttributes } from "../shared/html/artifact-main";
 
 /**
  * Frame element attributes. The shell applies these to every iframe it
@@ -48,7 +49,7 @@ export function buildFrameDocument(options: {
       ? `<link rel="stylesheet" href="/gallery/frame/artifact.css">`
       : "") +
     "</head><body>" +
-    `<main id="artifact" data-facet-artifact-type="${artifactType}"></main>` +
+    `<main ${artifactMainAttributes(artifactType)}></main>` +
     `<script type="module" src="${escapedRuntimeUrl}"></script>` +
     "</body></html>"
   );

package/src/gallery-web/index.html

@@ -17,7 +17,9 @@
         <span class="sep" aria-hidden="true"></span>
         <span id="facet-artifact-title"></span>
         <span class="revision" id="facet-revision">—</span>
-        <span class="status-line" id="facet-status-line">idle</span>
+        <span class="status-line" id="facet-status-line" role="status" aria-live="polite"
+          >idle</span
+        >
         <!--
           Verdict badge. JS wiring: set data-status to the FULL wire
           enum, text to status.split(":")[0], and the tier span to

package/src/gallery-web/styles/verdict.css

@@ -57,6 +57,16 @@
   content: "✓";
 }
 
+.facet-verdict[data-interaction-error="true"] {
+  border-color: var(--facet-fail);
+  box-shadow: var(--facet-glow-danger);
+}
+.facet-verdict[data-interaction-error="true"]::after {
+  content: "✗ runtime";
+  color: var(--facet-fail);
+  font-weight: 700;
+}
+
 .facet-verdict[data-status="error"] {
   border-color: var(--facet-fail-border);
   background: var(--facet-fail-fill);
@@ -100,6 +110,15 @@
   content: "◐";
 }
 
+.facet-verdict[data-status="partial:empty_render"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+.facet-verdict[data-status="partial:empty_render"]::before {
+  content: "◐";
+}
+
 /* The alarm. The only fill, the only glow. Never animated. */
 .facet-verdict[data-status="tampered"],
 .facet-verdict[data-status="insecure:unvalidated"] {
@@ -109,10 +128,6 @@
   font-weight: 700;
   box-shadow: var(--facet-glow-danger);
 }
-.facet-verdict[data-status="tampered"]::before {
-  content: "⊘";
-}
-
 .facet-verdict[data-status="tampered"]::before,
 .facet-verdict[data-status="insecure:unvalidated"]::before {
   content: "⊘";

package/src/harness-adapters/mcp/cli-bridge.ts

@@ -9,7 +9,7 @@ import {
 
 const STDERR_DETAIL_LIMIT = 4_096;
 
-export type FacetToolName = "publish" | "read_back" | "status" | "export" | "open";
+export type FacetToolName = "create" | "publish" | "read_back" | "status" | "export" | "open";
 
 export interface FacetCliInvocation {
   readonly command: string;
@@ -75,6 +75,16 @@ export function buildFacetArgs(
   input: Readonly<Record<string, unknown>>,
 ): string[] {
   switch (tool) {
+    case "create":
+      return [
+        "create",
+        "--project-id",
+        requiredString(input, "projectId"),
+        "--slug",
+        requiredString(input, "slug"),
+        "--title",
+        requiredString(input, "title"),
+      ];
     case "publish": {
       const args = [
         "publish",

package/src/harness-adapters/mcp/main.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 import { createFacetMcpServer } from "./server";