@legionworks/facet 1.9.0 → 1.10.1

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/runtime.ts

@@ -1,5 +1,5 @@
 import { isTsxExecutionMode, type TsxExecutionMode } from "../../shared/tsx/execution";
-import { isResolvedGalleryTheme } from "../theme";
+import { galleryDataTheme, isResolvedGalleryTheme, type ResolvedGalleryTheme } from "../theme";
 
 import { validateRenderer } from "./renderer-validation";
 import {
@@ -80,6 +80,7 @@ interface DiagramRegionGestures {
 
 export interface GalleryFrameApi {
   render(payload: FrameRenderPayload): Promise<RenderResult>;
+  setTheme(theme: ResolvedGalleryTheme): void;
 }
 
 declare global {
@@ -410,6 +411,11 @@ export function installGalleryFrameApi(registry: RendererRegistry): void {
   };
 
   const api: GalleryFrameApi = {
+    setTheme(theme) {
+      if (!isResolvedGalleryTheme(theme))
+        throw new FacetRenderError("frame theme is invalid", "invalid_request");
+      document.documentElement.dataset.theme = galleryDataTheme(theme);
+    },
     async render(payload: FrameRenderPayload): Promise<RenderResult> {
       if (rendered) throw new FacetRenderError("frame already rendered", "invalid_request");
       const validated = validatePayload(payload);

package/src/gallery-web/frame/styles/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/src/gallery-web/frame/styles/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/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
@@ -30,6 +31,10 @@ export function buildFrameAttributes(src = "/gallery/frame"): FrameAttributes {
   };
 }
 
+export function usesArtifactStylesheet(artifactType: string): boolean {
+  return artifactType === "html" || artifactType === "tsx";
+}
+
 export function buildFrameDocument(options: {
   artifactType: string;
   runtimeUrl: string;
@@ -44,11 +49,11 @@ export function buildFrameDocument(options: {
   return (
     `<!doctype html><html data-theme="${galleryDataTheme(theme)}"><head>` +
     `<meta charset="utf-8"><link rel="stylesheet" href="/gallery/frame/frame.css">` +
-    (artifactType === "html" || artifactType === "tsx"
+    (usesArtifactStylesheet(artifactType)
       ? `<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";

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

@@ -1,11 +1,15 @@
 import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z, ZodError } from "zod";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { type ZodType, ZodError } from "zod";
 import { FACET_VERSION } from "../../shared/version";
 
 import { buildFacetArgs, FacetBridgeError, invokeFacet } from "./cli-bridge";
 import {
+  CreateToolSchema,
   ExportToolSchema,
   OpenUrlToolSchema,
   PublishToolSchema,
@@ -41,12 +45,10 @@ function errorEnvelope(cause: unknown): FacetEnvelope<never> {
   return errEnvelope(requestId(), body);
 }
 
-const LooseToolInputSchema = z.record(z.unknown());
-
 function toolResult(envelope: FacetEnvelope<unknown>) {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(envelope) }],
-    ...(envelope.ok ? {} : { isError: true }),
+    isError: !envelope.ok,
   };
 }
 
@@ -90,75 +92,96 @@ function publishSource(input: PublishToolInput): {
   });
 }
 
-export function createFacetMcpServer(): McpServer {
-  const server = new McpServer({ name: "facet", version: FACET_VERSION });
-
-  server.registerTool(
-    "facet_export",
-    {
-      description:
-        "Export source or stored render evidence into outDir. Check envelope.ok for transport success; a successful publish verdict remains a separate data.verdict.status decision.",
-      inputSchema: LooseToolInputSchema,
-    },
-    async (args) =>
-      withInput(args, ExportToolSchema.parse, async (input) => {
-        mkdirSync(input.outDir, { recursive: true });
-        return invoke(buildFacetArgs("export", input), { cwd: input.outDir });
-      }),
-  );
+function defineTool<T>(
+  schema: ZodType<T>,
+  description: string,
+  run: (input: T) => Promise<ReturnType<typeof toolResult>>,
+) {
+  return {
+    schema,
+    description,
+    execute: (args: unknown) => withInput(args, (input) => schema.parse(input), run),
+  };
+}
 
-  server.registerTool(
-    "facet_open_url",
-    {
-      description:
-        "Return a Facet gallery frameUrl without launching a browser. This always invokes facet open --no-launch; agents must not launch desktop display.",
-      inputSchema: LooseToolInputSchema,
-    },
-    async (args) =>
-      withInput(args, OpenUrlToolSchema.parse, async (input) =>
-        invoke(buildFacetArgs("open", input)),
-      ),
+export function createFacetMcpServer(): Server {
+  const server = new Server(
+    { name: "facet", version: FACET_VERSION },
+    { capabilities: { tools: {} } },
   );
-
-  server.registerTool(
-    "facet_publish",
-    {
-      description:
-        "Publish exactly one sourceText or local file. Check envelope.ok separately from data.verdict.status: stored verdict status error is not a transport failure.",
-      inputSchema: LooseToolInputSchema,
-    },
-    async (args) =>
-      withInput(args, PublishToolSchema.parse, async (input) => {
+  // The high-level SDK validates arguments before the handler and emits plain-text errors.
+  // Wire schemas and handler parsing are separate so invalid calls retain Facet envelopes.
+  const tools = {
+    facet_create: defineTool(
+      CreateToolSchema,
+      "Create an artifact from projectId, slug, and title before publishing source.",
+      async (input) => invoke(buildFacetArgs("create", input)),
+    ),
+    facet_export: defineTool(
+      ExportToolSchema,
+      "Export source or stored render evidence into outDir. Check envelope.ok for transport success; a successful publish verdict remains a separate data.verdict.status decision.",
+      async (input) => {
+        const outDir = resolve(input.outDir);
+        try {
+          mkdirSync(outDir, { recursive: true });
+        } catch (cause) {
+          throw new FacetBridgeError(
+            {
+              code: "output_unwritable",
+              message: `Cannot write export output: ${outDir}`,
+              retryable: false,
+              details: { out: outDir },
+            },
+            cause,
+          );
+        }
+        return invoke(buildFacetArgs("export", input), { cwd: outDir });
+      },
+    ),
+    facet_open_url: defineTool(
+      OpenUrlToolSchema,
+      "Return a Facet gallery frameUrl without launching a browser. This always invokes facet open --no-launch; agents must not launch desktop display.",
+      async (input) => invoke(buildFacetArgs("open", input)),
+    ),
+    facet_publish: defineTool(
+      PublishToolSchema,
+      'Publish exactly one sourceText or local file. Check envelope.ok separately from data.verdict.status: a stored verdict status of error is not a transport failure. Tier 0 parses and compiles structure but is not rendered; call facet_read_back with tier: "visual" before reporting a render.',
+      async (input) => {
         const source = publishSource(input);
         return invoke(buildFacetArgs("publish", { ...input, ...source }), source);
+      },
+    ),
+    facet_read_back: defineTool(
+      ReadBackToolSchema,
+      "Read back a stored verdict at Tier 0, Tier 1, or visual. Tier 1 and visual need browser evidence from the pinned browser; inspect envelope.ok before verdict status. Visual covers the first rendered state; later interaction is not validated and does not change the stored verdict.",
+      async (input) => invoke(buildFacetArgs("read_back", input)),
+    ),
+    facet_status: defineTool(
+      StatusToolSchema,
+      "Read Facet status. Set start only when activation is intended; envelope.ok reports command transport and never replaces verdict.status inspection.",
+      async (input) => invoke(buildFacetArgs("status", input)),
+    ),
+  };
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: Object.entries(tools).map(([name, tool]) => ({
+      name,
+      description: tool.description,
+      inputSchema: toJsonSchemaCompat(tool.schema, { pipeStrategy: "input" }),
+    })),
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    const tool = Object.hasOwn(tools, params.name)
+      ? tools[params.name as keyof typeof tools]
+      : null;
+    if (tool) return tool.execute(params.arguments);
+    return toolResult(
+      errEnvelope(requestId(), {
+        code: "invalid_request",
+        message: `Unknown MCP tool '${params.name}'`,
+        retryable: false,
       }),
-  );
-
-  server.registerTool(
-    "facet_read_back",
-    {
-      description:
-        "Read back the latest or revision-bound stored verdict at Tier 0, Tier 1, or visual. Tier 1 and visual need browser evidence; inspect envelope.ok before verdict status.",
-      inputSchema: LooseToolInputSchema,
-    },
-    async (args) =>
-      withInput(args, ReadBackToolSchema.parse, async (input) =>
-        invoke(buildFacetArgs("read_back", input)),
-      ),
-  );
-
-  server.registerTool(
-    "facet_status",
-    {
-      description:
-        "Read Facet status. Set start only when activation is intended; envelope.ok reports command transport and never replaces verdict.status inspection.",
-      inputSchema: LooseToolInputSchema,
-    },
-    async (args) =>
-      withInput(args, StatusToolSchema.parse, async (input) =>
-        invoke(buildFacetArgs("status", input)),
-      ),
-  );
+    );
+  });
 
   return server;
 }

package/src/harness-adapters/mcp/tool-schemas.ts

@@ -6,6 +6,13 @@ const RevisionShaSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const ExecutionSchema = z.enum(["static", "interactive"]);
 const ReadBackTierSchema = z.union([z.literal(0), z.literal(1), z.literal("visual")]);
 
+export const CreateToolShape = {
+  projectId: z.string().min(1),
+  slug: z.string().min(1),
+  title: z.string().min(1),
+};
+export const CreateToolSchema = z.object(CreateToolShape).strict();
+
 export const PublishToolShape = {
   artifactId: z.string().min(1),
   type: ArtifactTypeSchema,

package/src/service/dispatcher.ts

@@ -513,12 +513,25 @@ export async function dispatch(
         nextCursor: null,
       };
     }
+    case "templates": {
+      return {
+        command: "templates",
+        requestId,
+        templates: deps.repository.listTemplates(command.limit),
+      };
+    }
     case "readBack": {
       const revision =
         command.revisionSha === undefined
           ? deps.repository.getLatestRevision(command.artifactId)
           : deps.repository.getRevisionBySha(command.artifactId, command.revisionSha);
       if (revision === null) {
+        if (deps.repository.getArtifactById(command.artifactId) === null) {
+          throw new FacetError("artifact_not_found", "Artifact not found", {
+            retryable: false,
+            details: { artifactId: command.artifactId },
+          });
+        }
         throw new FacetError("revision_not_found", "Revision not found", {
           retryable: false,
           details: {
@@ -607,6 +620,12 @@ export async function dispatch(
           ? deps.repository.getLatestRevision(command.artifactId)
           : deps.repository.getRevisionBySha(command.artifactId, command.revisionSha);
       if (revision === null) {
+        if (deps.repository.getArtifactById(command.artifactId) === null) {
+          throw new FacetError("artifact_not_found", "Artifact not found", {
+            retryable: false,
+            details: { artifactId: command.artifactId },
+          });
+        }
         throw new FacetError("revision_not_found", "Revision not found", {
           retryable: false,
           details: {
@@ -642,6 +661,9 @@ export async function dispatch(
         revisionId: command.revisionId,
         name: command.name,
         promotedBy: command.promotedBy,
+        ...(command.allowUnverified !== undefined
+          ? { allowUnverified: command.allowUnverified }
+          : {}),
         ...(command.description !== undefined ? { description: command.description } : {}),
       });
       return { command: "promote", requestId, template };

package/src/service/router-guards.ts

@@ -222,6 +222,8 @@ export function statusFor(error: FacetError): number {
     case "tier0_unavailable":
       return 503;
     case "duplicate_revision":
+    case "template_name_taken":
+    case "promotion_refused":
     case "constraint":
     case "foreign_key":
     case "immutable_revision":

package/src/service/store/migrations.ts

@@ -12,8 +12,8 @@ import {
   V7_SCHEMA_FRAGMENT,
   V8_SCHEMA_FRAGMENT,
   V9_SCHEMA_FRAGMENT,
+  V10_SCHEMA_FRAGMENT,
 } from "./schema";
-import { CURRENT_STORAGE_VERSION } from "../../shared/storage-version";
 
 export interface MigrationOptions {
   readonly beforeRecordVersion?: (version: number) => void;
@@ -106,13 +106,23 @@ const MIGRATION_STEPS: readonly MigrationStep[] = [
     requiresForeignKeyDisable: true,
   },
   {
-    version: CURRENT_STORAGE_VERSION,
+    version: 9,
     apply: (db) => {
       db.exec(V9_SCHEMA_FRAGMENT);
     },
   },
+  {
+    version: 10,
+    apply: (db) => {
+      db.exec(V10_SCHEMA_FRAGMENT);
+    },
+  },
 ];
 
+export function latestMigrationVersion(): number {
+  return MIGRATION_STEPS.at(-1)?.version ?? 0;
+}
+
 export function runMigrations(db: Database, options: MigrationOptions = {}): void {
   try {
     db.exec(