@legionworks/facet 1.9.0 → 1.10.1

package/README.md

@@ -41,10 +41,10 @@ Current gallery captures use the Mermaid fixture in resolved dark and the chart
 
 ## Install
 
-Facet is distributed as `@legionworks/facet`. **Bun is the required runtime**:
-the CLI runs on Bun `1.4.0` or newer. npm and pnpm are distribution channels,
-not Node runtime support; a machine without Bun cannot run the installed CLI and
-will receive a runtime failure.
+Facet is distributed as `@legionworks/facet`. Bun is the required runtime
+(version `1.4.0` or newer); install it first using the [official Bun
+installation instructions](https://bun.sh/docs/installation). npm and pnpm
+distribute Facet, but do not provide Bun. npm alone is not enough.
 
 Recommended:
 
@@ -65,27 +65,56 @@ For a zero-install invocation:
 bunx @legionworks/facet <verb>
 ```
 
-The pinned browser used for visual read-back downloads on the first visual
-read-back. See the [CLI reference](docs/reference/cli.md) for the command
-contract and [MCP reference](docs/reference/mcp.md) for structured-tool-only
-hosts.
+The first visual read-back requires the pinned browser. If it is missing,
+`facet doctor` prints the install command. See the [CLI reference](docs/reference/cli.md) for
+the command contract and [MCP reference](docs/reference/mcp.md) for
+structured-tool-only hosts.
+
+## Quickstart from an installed binary
+
+This walkthrough uses the globally installed `facet` command, not a source
+checkout. It creates disposable runtime and export directories.
+
+```sh
+export FACET_HOME="$(mktemp -d)"
+facet status --start
+facet doctor
+bunx --bun puppeteer browsers install chrome-headless-shell@151.0.7922.77
+SOURCE='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 80"><rect width="240" height="80" rx="8" fill="#202638"/><text x="20" y="48" fill="white">Facet quickstart</text></svg>'
+SOURCE_FILE="$(mktemp)"
+printf '%s' "$SOURCE" > "$SOURCE_FILE"
+ARTIFACT_ID="$(facet create --project-id demo --slug quickstart --title 'Quickstart' | bun -e 'const x=JSON.parse(await Bun.stdin.text()); if(!x.ok) throw new Error(x.error.code); console.log(x.data.artifact.id)')"
+PUBLISH="$(facet publish --artifact-id "$ARTIFACT_ID" --type svg --file "$SOURCE_FILE")"
+printf '%s\n' "$PUBLISH" | bun -e 'const x=JSON.parse(await Bun.stdin.text()); if(!x.ok || !x.data.verdict) throw new Error("publish failed"); console.log(JSON.stringify(x.data.verdict))'
+REVISION_SHA="$(printf '%s\n' "$PUBLISH" | bun -e 'const x=JSON.parse(await Bun.stdin.text()); console.log(x.data.revision.sha256)')"
+facet read-back --artifact-id "$ARTIFACT_ID" --revision-sha "$REVISION_SHA" --tier visual
+EXPORT_DIR="$(mktemp -d)"
+facet export "$ARTIFACT_ID" --format source --out "$EXPORT_DIR/artifact.svg"
+```
+
+`doctor` checks the local runtime and browser setup and prints the browser
+install command if the pinned shell is missing. Install it before visual
+read-back. Inspect `data.verdict` in the publish envelope: an `ok` command
+envelope only confirms transport, and the stored verdict can still have
+`status: "error"`.
 
 ## Verdict language
 
 The gallery and CLI use the same wire enum, glyph, hue, and treatment.
 
-| enum (wire, verbatim)        | glyph | hue       | treatment                        |
-| ---------------------------- | ----- | --------- | -------------------------------- |
-| `ok`                         | `✓`   | `#c3e88d` | outline — proof, not celebration |
-| `error`                      | `✗`   | `#ff757f` | outline                          |
-| `partial:layout_unverified`  | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:opaque_content`     | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:external_resources` | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:unstable`           | `◐`   | `#ffc777` | outline; screenshot required     |
-| `tampered`                   | `⊘`   | `#ff757f` | filled alarm badge               |
-| `timeout`                    | `◌`   | `#737aa2` | dim outline                      |
-| `shim_only`                  | `◇`   | `#737aa2` | dim outline                      |
-| `probe_only`                 | `◈`   | `#737aa2` | dim outline                      |
+| enum (wire, verbatim)        | glyph | hue       | treatment                           |
+| ---------------------------- | ----- | --------- | ----------------------------------- |
+| `ok`                         | `✓`   | `#c3e88d` | outline — proof, not celebration    |
+| `error`                      | `✗`   | `#ff757f` | outline                             |
+| `partial:layout_unverified`  | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:opaque_content`     | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:external_resources` | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:unstable`           | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:empty_render`       | `◐`   | `#ffc777` | empty TSX root; screenshot required |
+| `tampered`                   | `⊘`   | `#ff757f` | filled alarm badge                  |
+| `timeout`                    | `◌`   | `#737aa2` | dim outline                         |
+| `shim_only`                  | `◇`   | `#737aa2` | dim outline                         |
+| `probe_only`                 | `◈`   | `#737aa2` | dim outline                         |
 
 `partial:external_resources` means an artifact references external HTTPS images the no-egress verifier could not load. An `ok` verdict can still carry `Verdict.screenshotError.code: "screenshot_unavailable"` when whole-artifact capture cannot be produced; it records the limit without changing the validation result. `insecure:unvalidated` means level 3 intentionally skipped validation. A missing verdict is `UNVERIFIED` with no tier.
 
@@ -133,7 +162,7 @@ Facet's insecure mode is an explicit, boot-only opt-in (`FACET_INSECURE=1|2|3`)
 
 ## MCP
 
-On harnesses with shell access, the CLI is the integration; the MCP adapter is for structured-tool-only environments. The npm package includes a stdio MCP adapter with five CLI-backed tools: publish, read-back, status, export, and a no-launch frame URL lookup. It requires Bun `1.4.0`. See the [MCP reference](docs/reference/mcp.md) for OpenCode, Claude Code, and Codex registration.
+On harnesses with shell access, the CLI is the integration; the MCP adapter is for structured-tool-only environments. The npm package includes six CLI-backed tools: `facet_create`, `facet_publish`, `facet_read_back`, `facet_status`, `facet_export`, and `facet_open_url`. It requires Bun `1.4.0`. Register it with `bun add -g @legionworks/facet` followed by the bare `facet-mcp` command; `npx -p @legionworks/facet facet-mcp` is the no-install alternative. See the [MCP reference](docs/reference/mcp.md) for OpenCode, Claude Code, and Codex registration.
 
 ## Documentation
 

package/dist/gallery/{chunk-c6s9k9ty.js → chunk-0by8qn4x.js}

@@ -40,6 +40,9 @@ function buildFrameAttributes(src = "/gallery/frame") {
     src
   };
 }
+function usesArtifactStylesheet(artifactType) {
+  return artifactType === "html" || artifactType === "tsx";
+}
 function isLoopbackHostname(hostname) {
   return hostname === "127.0.0.1";
 }
@@ -4349,7 +4352,8 @@ var TemplateSchema = exports_external.object({
   name: exports_external.string().min(1),
   description: exports_external.string().nullable(),
   promotedBy: exports_external.string().min(1),
-  promotedAt: IsoTimestampSchema
+  promotedAt: IsoTimestampSchema,
+  promotionOverride: exports_external.string().nullable()
 });
 
 // src/shared/contracts/observed-counts.ts
@@ -4380,6 +4384,7 @@ var RenderStatusSchema = exports_external.enum([
   "partial:opaque_content",
   "partial:external_resources",
   "partial:unstable",
+  "partial:empty_render",
   "tampered",
   "timeout",
   "shim_only",
@@ -4417,8 +4422,12 @@ var LexicalCountersSchema = exports_external.object({
   html: HtmlStructureCountsSchema.optional()
 });
 var ObservedCountShape = Object.fromEntries(OBSERVED_COUNT_KEYS.map((key) => [key, exports_external.number().int().nonnegative()]));
+var RenderedContentShape = {
+  emptyRendererRoot: exports_external.boolean().optional()
+};
 var VerdictObservedSchema = exports_external.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: exports_external.array(exports_external.string()).optional(),
   errorCount: exports_external.number().int().nonnegative(),
@@ -4472,6 +4481,7 @@ var Tier1ResultSchema = Tier0ResultSchema.extend({
 });
 var ProtocolObservationSchema = exports_external.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: exports_external.array(exports_external.string()),
   errorCount: exports_external.number().int().nonnegative(),
@@ -4486,6 +4496,7 @@ var 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",
@@ -4599,6 +4610,10 @@ var ListRequestSchema = BaseRequestSchema.extend({
   slugPrefix: exports_external.string().optional(),
   limit: exports_external.number().int().positive().max(MAX_LIST_LIMIT).optional()
 });
+var TemplatesRequestSchema = BaseRequestSchema.extend({
+  command: exports_external.literal("templates"),
+  limit: exports_external.number().int().positive().max(MAX_LIST_LIMIT).optional()
+});
 var ReadBackRequestSchema = BaseRequestSchema.extend({
   command: exports_external.literal("readBack"),
   artifactId: exports_external.string().min(1),
@@ -4620,7 +4635,8 @@ var PromoteRequestSchema = BaseRequestSchema.extend({
   revisionId: exports_external.string().min(1),
   name: exports_external.string().min(1),
   description: exports_external.string().nullable().optional(),
-  promotedBy: exports_external.string().min(1)
+  promotedBy: exports_external.string().min(1),
+  allowUnverified: exports_external.boolean().optional()
 });
 var InstantiateRequestSchema = BaseRequestSchema.extend({
   command: exports_external.literal("instantiate"),
@@ -4678,6 +4694,19 @@ var ListResultSchema = BaseResultSchema.extend({
   artifacts: exports_external.array(ArtifactEnvelopeSchema),
   nextCursor: exports_external.string().nullable().optional()
 });
+var TemplatesResultSchema = BaseResultSchema.extend({
+  command: exports_external.literal("templates"),
+  templates: exports_external.array(exports_external.object({
+    name: exports_external.string().min(1),
+    artifactId: exports_external.string().min(1),
+    revisionId: exports_external.string().min(1),
+    revisionSha: exports_external.string().regex(/^[a-f0-9]{64}$/),
+    promotedBy: exports_external.string().min(1),
+    promotedAt: exports_external.string().datetime({ offset: true }),
+    promotionOverride: exports_external.string().nullable(),
+    sourceVerdict: exports_external.object({ status: RenderStatusSchema, tier: exports_external.union([exports_external.literal(0), exports_external.literal(1)]) }).nullable()
+  }))
+});
 var ReadBackResultSchema = BaseResultSchema.extend({
   command: exports_external.literal("readBack"),
   renderer: RendererSchema,
@@ -5164,6 +5193,13 @@ function createArtifactFrame(options) {
       renderResult = handle;
       return handle;
     },
+    setTheme(theme) {
+      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() {
       return renderResult;
     }
@@ -5402,7 +5438,7 @@ function setGalleryVerdict(document2, verdict) {
   badge.dataset.status = verdict.status;
   badge.childNodes[0].textContent = verdict.status.split(":")[0] ?? verdict.status;
   if (tier !== null) {
-    const detail = verdict.status === "partial:opaque_content" ? "opaque" : verdict.status === "partial:layout_unverified" ? "layout" : verdict.status === "partial:external_resources" ? "external" : verdict.status === "partial:unstable" ? "unstable" : null;
+    const detail = verdict.status === "partial:opaque_content" ? "opaque" : verdict.status === "partial:layout_unverified" ? "layout" : verdict.status === "partial:external_resources" ? "external" : verdict.status === "partial:unstable" ? "unstable" : 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}`;
@@ -5546,6 +5582,42 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   let removeThemePreferenceListener = noOp;
   let generation = 0;
   let activeFrame = null;
+  let removeInteractionListener = noOp;
+  const endInteractionSignal = () => {
+    removeInteractionListener();
+    const badge = document2.getElementById("facet-verdict");
+    if (badge !== null)
+      delete badge.dataset.interactionError;
+  };
+  const activateInteractionSignal = (frame) => {
+    endInteractionSignal();
+    const badge = document2.getElementById("facet-verdict");
+    updateGalleryStatus("displayed");
+    const frameWindow = frame.element.raw.contentWindow;
+    if (frameWindow === null || typeof frameWindow.addEventListener !== "function")
+      return;
+    const markFailure = () => {
+      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.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 = () => {
+      frameWindow.removeEventListener("error", markFailure, true);
+      frameWindow.removeEventListener("unhandledrejection", markFailure, true);
+      observer?.disconnect();
+    };
+  };
   const expireSession = () => {
     if (expired)
       return;
@@ -5556,6 +5628,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
     exportMenu?.sync();
     activeFrame?.renderResult?.setGestureMode("native");
     swaps?.close();
+    endInteractionSignal();
     removeThemePreferenceListener();
     clearSession(window2.sessionStorage);
     renderSessionExpired(document2, (message) => setGalleryError(document2, message), (status) => setGalleryStatus(document2, status));
@@ -5687,6 +5760,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   updateGalleryFavicon(source.verdict?.status ?? "unverified");
   updateGalleryVerdict(source.verdict ?? null);
   updateGalleryStatus("displayed");
+  activateInteractionSignal(current);
   updateLiveState("live");
   const themeToggle = document2.getElementById("facet-theme-toggle");
   const updateThemeToggle = (mode) => {
@@ -5718,6 +5792,11 @@ async function startGallery(runtime = browserGalleryRuntime()) {
     const canCommit = () => 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,
@@ -5745,6 +5824,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       return;
     current = next;
     activeFrame = next;
+    activateInteractionSignal(next);
     commitTheme(nextMode, nextResolvedTheme);
     syncPanZoomToggle();
     syncZoomButtons();
@@ -5815,6 +5895,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       if (!result.failedNewFrameReady) {
         current = frame;
         activeFrame = frame;
+        activateInteractionSignal(frame);
         source = revision;
         commitTheme(revisionThemeMode, revisionTheme);
         syncPanZoomToggle();
@@ -5870,6 +5951,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       updateSwapBar("start");
       updateGalleryFavicon("unverified");
       updateGalleryVerdict(null);
+      endInteractionSignal();
       swaps?.enqueue({ kind: "revision", ...event });
     },
     onClose: (event) => {
@@ -5885,6 +5967,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   let zoomButtonPoll;
   const shutdown = () => {
     stream.close();
+    removeInteractionListener();
     removeThemePreferenceListener();
     if (zoomButtonPoll !== undefined)
       clearInterval(zoomButtonPoll);

package/dist/gallery/{chunk-4g8rem85.css → chunk-2dge4gwb.css}

@@ -136,6 +136,17 @@
   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);
@@ -186,6 +197,16 @@
   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: "◐";
+}
+
 .facet-verdict[data-status="tampered"], .facet-verdict[data-status="insecure:unvalidated"] {
   border-color: var(--facet-fail);
   background: var(--facet-fail);
@@ -194,7 +215,7 @@
   font-weight: 700;
 }
 
-.facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="insecure:unvalidated"]:before {
+.facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="insecure:unvalidated"]:before {
   content: "⊘";
 }
 

package/dist/gallery/frame/artifact.css

@@ -5256,6 +5256,9 @@
   .mx-16 {
     margin-inline: calc(var(--spacing) * 16);
   }
+  .mx-auto {
+    margin-inline: auto;
+  }
   .my-0 {
     margin-block: 0px;
   }

package/dist/gallery/frame/chunks/{markdown-fvfncadf.js → markdown-g3asgaw3.js}

@@ -11,6 +11,9 @@ import {
 function isResolvedGalleryTheme(value) {
   return value === "dark" || value === "light";
 }
+function galleryDataTheme(theme) {
+  return theme === "light" ? "winter" : "night";
+}
 
 // src/gallery-web/frame/renderer-validation.ts
 function validateRenderer(value) {
@@ -395,6 +398,11 @@ function installGalleryFrameApi(registry) {
     setPointerEventsForAllChildren(container, mode === "panzoom" ? "none" : "");
   };
   const api = {
+    setTheme(theme) {
+      if (!isResolvedGalleryTheme(theme))
+        throw new FacetRenderError("frame theme is invalid", "invalid_request");
+      document.documentElement.dataset.theme = galleryDataTheme(theme);
+    },
     async render(payload) {
       if (rendered)
         throw new FacetRenderError("frame already rendered", "invalid_request");

package/dist/gallery/frame/frame.css

@@ -78,32 +78,19 @@ body {
   padding-inline: max(16px, calc((100% - 92ch) / 2));
 }
 
-/*
- * Native dashboard artifacts (html, interactive tsx) read top-down
- * like markdown — vertical stays start-aligned — but unlike markdown
- * their width is whatever the fixture authored (often a fixed-width
- * `max-w-*` container), not a fluid readable column. Left unstyled,
- * that narrow content sits pinned to the container's left edge,
- * stranding most of a wide desktop stage as dead space.
- *
- * The centering has to land on the renderer-ROOT element
- * (`.facet-html-root` / `#facet-tsx-mount`), not `#artifact` itself:
- * `renderHtml`/`renderTsx` always mount a single full-width wrapper
- * as `#artifact`'s only child, and the fixture's own narrow content
- * (e.g. `<main class="max-w-2xl">`) is a GRANDCHILD of `#artifact`
- * inside that wrapper — centering `#artifact`'s single full-width
- * child does nothing. `safe center` on the horizontal axis only —
- * the same fallback-to-start mechanism the standalone-diagram rule
- * above uses — centers content that fits and never clips content
- * wider than the stage (it start-aligns and stays reachable by
- * scroll instead).
- */
+/* These selectors match usesArtifactStylesheet in frame-html.ts; CSS cannot import it. */
+#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%;
+  /* Block flow preserves authored sibling order while keeping the renderer root a flex item of the stage. */
+  display: block;
+  /* Filling the stage keeps a sibling runtime-error line outside capture bounds as the viewport resizes. */
+  flex: 1 0 auto;
 }
 
 #artifact > svg {

package/dist/gallery/frame/runtime/chart.js

@@ -3,7 +3,7 @@ import {
 } from "../chunks/markdown-zazx9h4n.js";
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   FacetRenderError,
   createRendererRegistry,
@@ -42693,6 +42693,28 @@ function withFacetChartTheme(spec, theme) {
     }
   };
 }
+function withFacetChartDimensions(spec) {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+    return spec;
+  const source4 = spec;
+  const config = source4.config;
+  if ("autosize" in source4 || typeof config === "object" && config !== null && !Array.isArray(config) && "view" in config)
+    return spec;
+  if ("width" in source4 && "height" in source4)
+    return spec;
+  const authoredConfig = typeof config === "object" && config !== null && !Array.isArray(config) ? config : {};
+  const viewDefaults = {
+    ...!("width" in source4) ? { continuousWidth: 640, discreteWidth: 640 } : {},
+    ...!("height" in source4) ? { continuousHeight: 360, discreteHeight: 360 } : {}
+  };
+  return {
+    ...source4,
+    config: {
+      ...authoredConfig,
+      view: viewDefaults
+    }
+  };
+}
 async function renderChart(ctx, bytes, renderer = "svg") {
   const text3 = decodeArtifactBytes(bytes);
   let spec;
@@ -42704,7 +42726,7 @@ async function renderChart(ctx, bytes, renderer = "svg") {
   }
   let compiled;
   try {
-    compiled = compile(withFacetChartTheme(spec, ctx.theme));
+    compiled = compile(withFacetChartTheme(withFacetChartDimensions(spec), ctx.theme));
   } catch (error3) {
     const message = error3 instanceof Error ? error3.message : String(error3);
     throw new FacetRenderError(`vega-lite compile failed: ${message}`, "chart_compile_error");

package/dist/gallery/frame/runtime/html.js

@@ -3,7 +3,7 @@ import {
 } from "../chunks/markdown-rd8w0ng9.js";
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   createRendererRegistry
 } from "../chunks/markdown-d1wfbs70.js";

package/dist/gallery/frame/runtime/markdown.js

@@ -1,6 +1,6 @@
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   createRendererRegistry,
   decodeArtifactBytes

package/dist/gallery/frame/runtime/mermaid.js

@@ -7,7 +7,7 @@ import"../chunks/markdown-h7pzv34e.js";
 import"../chunks/markdown-zazx9h4n.js";
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   createRendererRegistry
 } from "../chunks/markdown-d1wfbs70.js";

package/dist/gallery/frame/runtime/svg.js

@@ -3,7 +3,7 @@ import {
 } from "../chunks/markdown-zazx9h4n.js";
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   createRendererRegistry
 } from "../chunks/markdown-d1wfbs70.js";

package/dist/gallery/frame/runtime/tsx.js

@@ -3,7 +3,7 @@ import {
 } from "../chunks/markdown-rd8w0ng9.js";
 import {
   installGalleryFrameApi
-} from "../chunks/markdown-fvfncadf.js";
+} from "../chunks/markdown-g3asgaw3.js";
 import {
   RENDER_ERROR_ATTRIBUTE,
   appendRenderError,

package/dist/gallery/index.html

@@ -8,7 +8,7 @@
     
     
     
-  <link rel="stylesheet" crossorigin href="./chunk-4g8rem85.css"><script type="module" crossorigin src="./chunk-c6s9k9ty.js"></script></head>
+  <link rel="stylesheet" crossorigin href="./chunk-2dge4gwb.css"><script type="module" crossorigin src="./chunk-0by8qn4x.js"></script></head>
   <body>
     <div id="facet-shell">
       <header id="facet-status">
@@ -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/docs/reference/cli.md

@@ -28,7 +28,8 @@ Errors use the same top level with `ok: false` and
 | `read-back`   | `--artifact-id`, optional `--revision-sha` (latest when omitted), `--tier` (one of: `0` \| `1` \| `visual`)                       |
 | `status`      | `--artifact-id`, `--start` (valueless start-then-inspect switch)                                                                  |
 | `open`        | `--artifact-id`, optional `--revision-sha` (latest when omitted), `--no-launch`                                                   |
-| `promote`     | `--artifact-id`, `--revision-id`, `--name`, `--description`, `--promoted-by`                                                      |
+| `promote`     | `--artifact-id`, `--revision-id`, `--name`, `--description`, `--promoted-by`, `--allow-unverified`                                |
+| `templates`   | optional `--limit`                                                                                                                |
 | `instantiate` | `--name`, `--new-slug`, `--project-id`                                                                                            |
 | `pin`         | `--revision-id`, `--pinned` (`true` or `false`)                                                                                   |
 | `export`      | `<artifactId>`, `--revision`, `--format source\|render`, `--out`, `--force`, `--include-bytes`                                    |
@@ -96,6 +97,12 @@ available without invoking the desktop launcher, and a launcher failure reports
 defaults to `svg`; `canvas` is valid only for chart artifacts. An invalid
 renderer value is a usage error and exits 64.
 
+For charts, Facet defaults unspecified views to 640×360 through
+`config.view`. These defaults apply only when the spec has no `autosize`, no
+`config.view`, and does not set both top-level `width` and `height`. An authored
+dimension is preserved; composite facet, concat, and repeat views receive the
+defaults through their child view config.
+
 `publish --type html` publishes a static, script-free HTML artifact.
 See [HTML reference](html.md) for the static / script-free contract,
 the denied element and attribute set, the vendored class vocabulary,
@@ -118,7 +125,7 @@ errors and next actions:
 | code                   | next action                                                                                                    |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `artifact_not_found`   | Check the artifact ID and list the project.                                                                    |
-| `revision_not_found`   | Omit the SHA for latest read-back or use an existing SHA.                                                      |
+| `revision_not_found`   | Check that the artifact has a revision; omit the SHA for latest or use an existing SHA.                        |
 | `duplicate_revision`   | Reuse `error.details.revisionSha`; no new revision was stored.                                                 |
 | `output_unwritable`    | Fix the output directory, permissions, or rename target.                                                       |
 | `evidence_unavailable` | Run Tier 1 again or inspect retention and evidence paths.                                                      |
@@ -134,6 +141,27 @@ mode does not assert that its visuals always change.
 `FACET_HOME/secrets/promote.token`. Neither source is accepted as an argv flag
 or emitted in a CLI envelope.
 
+Before promotion, request visual read-back for the exact revision. Promotion
+requires Tier 1 visual verification. A refusal returns `promotion_refused`
+(HTTP 409) with `error.details.reason`: `no_visual_verification` when no visual
+run exists, `error` when Tier 0 failed, or the refused Tier 1 status. The gate refuses `error`,
+`partial:empty_render`, `tampered`, `timeout`, `shim_only`, `probe_only`, and
+`insecure:unvalidated`. Other Tier 1 statuses are allowed when Tier 0 is not an
+error. `--allow-unverified` permits a refused promotion but stores the refusal
+reason in the template's `promotionOverride`; this is an audit record, not
+verification or a passing verdict. A duplicate template name returns
+`template_name_taken` (HTTP 409).
+
+`facet templates [--limit N]` lists promoted templates. It uses the install
+token. Each row includes the source verdict, read from the stored revision when
+the list is requested, and any `promotionOverride` reason.
+
+A Tier 1 verdict whose `insecure.level === 3` marker is present is refused as
+`insecure:unvalidated` even when the verdict's status would otherwise be
+allow-listed (level 3 skips validation); `--allow-unverified` records the same
+reason on `promotionOverride`. Levels 1 and 2 keep their status-based
+treatment — they are real validator results under relaxed sandboxing.
+
 ## Insecure mode
 
 `FACET_INSECURE=1|2|3` sets a boot-only forced floor. `FACET_INSECURE_AUTO=1`

package/docs/reference/export.md

@@ -84,6 +84,10 @@ its sidecar is not a valid export.
 The sidecar describes the stored verdict. Export does not approve, promote,
 revalidate, or otherwise change the artifact.
 
+Evidence consumers must inspect `verdict.insecure` before treating a result as
+validated. In particular, an explicit Tier 1 run under insecure level 3 carries
+the insecure marker even when its status is not `insecure:unvalidated`.
+
 ## `evidence_unavailable`
 
 Render export returns typed `evidence_unavailable` when the selected revision

package/docs/reference/html.md

@@ -142,15 +142,15 @@ an included Tailwind utility outside this list can still render.
 
 ### Recommended Tailwind utilities
 
-`block`, `flex`, `grid`, `inline-flex`, `flex-col`, `flex-wrap`, `items-center`, `justify-between`, `justify-center`, `grid-cols-1`, `grid-cols-2`, `grid-cols-3`, `gap-2`, `gap-3`, `gap-4`, `gap-6`, `p-2`, `p-3`, `p-4`, `p-6`, `px-3`, `px-4`, `py-2`, `py-3`, `m-0`, `mt-2`, `mt-4`, `mb-2`, `mb-4`, `w-full`, `max-w-prose`, `max-w-2xl`, `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `font-medium`, `font-semibold`, `font-bold`, `leading-relaxed`, `text-left`, `text-center`, `text-right`, `text-legion-ink`, `text-legion-muted`, `text-legion-cyan`, `bg-legion-paper`, `bg-legion-ink`, `bg-legion-cyan`, `border`, `border-2`, `border-legion-line`, `rounded`, `rounded-box`, `overflow-x-auto`, `table`, `table-zebra`.
+`block`, `flex`, `grid`, `inline-flex`, `flex-col`, `flex-wrap`, `items-center`, `justify-between`, `justify-center`, `grid-cols-1`, `grid-cols-2`, `grid-cols-3`, `gap-2`, `gap-3`, `gap-4`, `gap-6`, `p-2`, `p-3`, `p-4`, `p-6`, `px-3`, `px-4`, `py-2`, `py-3`, `m-0`, `mt-2`, `mt-4`, `mb-2`, `mb-4`, `mx-auto`, `w-full`, `max-w-prose`, `max-w-2xl`, `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `font-medium`, `font-semibold`, `font-bold`, `leading-relaxed`, `text-left`, `text-center`, `text-right`, `text-legion-ink`, `text-legion-muted`, `text-legion-cyan`, `bg-legion-paper`, `bg-legion-ink`, `bg-legion-cyan`, `border`, `border-2`, `border-legion-line`, `rounded`, `rounded-box`, `overflow-x-auto`, `table`, `table-zebra`.
 
-59 recommended utilities.
+60 recommended utilities.
 
 ### Recommended daisyUI components
 
 `alert`, `badge`, `btn`, `card`, `stat`, `table`.
 
-6 recommended components · 64 documented recommendations.
+6 recommended components · 65 documented recommendations.
 
 <!-- VOCABULARY:END -->