@legionworks/facet 1.9.0

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

@@ -0,0 +1,112 @@
+/*
+ * Legion Works design tokens — vendored for offline use.
+ *
+ * The gallery renders fully OFFLINE on 127.0.0.1; no remote font or
+ * CDN fetch is allowed. The font stacks reference locally-installed
+ * faces (Space Grotesk, Geist, JetBrains Mono); when those are absent
+ * the system-stack fallback takes over. The CSP forbids external
+ * resource loads anyway, so missing faces degrade silently.
+ */
+
+:root {
+  /* Brand palette — vendored Legion Works colors */
+  --facet-cyan: #86e1fc;
+  --facet-amber: #ff966c;
+  --facet-navy: #16161e;
+  --facet-navy-2: #1d1d27;
+  --facet-navy-3: #232330;
+  --facet-ink: #e9eaf0;
+  --facet-ink-dim: #b6b7c2;
+  --facet-ink-faint: #a6a8b5;
+  --facet-rule: #2e2e3a;
+  --facet-error: #ff6e6e;
+
+  /* Semantic shell surfaces and content roles. */
+  --facet-surface: var(--facet-navy);
+  --facet-surface-raised: var(--facet-navy-2);
+  --facet-surface-stage: #101018;
+  --facet-surface-control: var(--facet-navy-3);
+  --facet-text: var(--facet-ink);
+  --facet-text-muted: var(--facet-ink-dim);
+  --facet-text-faint: var(--facet-ink-faint);
+  --facet-rule-semantic: var(--facet-rule);
+  --facet-focus: var(--facet-cyan);
+  --facet-link: var(--facet-cyan);
+  --facet-shadow-export: rgba(0, 0, 0, 0.28);
+  --facet-live-ok: #c3e88d;
+  --facet-live-partial: #ffc777;
+  --facet-ok: #c3e88d;
+  --facet-fail: #ff757f;
+  --facet-partial: #ffc777;
+  --facet-inert: #a9b8e8;
+  --facet-tamper-ink: #16161e;
+  --facet-ok-border: color-mix(in srgb, var(--facet-ok) 45%, transparent);
+  --facet-ok-fill: transparent;
+  --facet-fail-border: color-mix(in srgb, var(--facet-fail) 45%, transparent);
+  --facet-fail-fill: transparent;
+  --facet-partial-border: color-mix(in srgb, var(--facet-partial) 45%, transparent);
+  --facet-partial-fill: transparent;
+  --facet-inert-border: color-mix(in srgb, var(--facet-inert) 38%, transparent);
+  --facet-inert-fill: transparent;
+  --facet-glow-danger:
+    0 0 0 1px color-mix(in srgb, var(--facet-fail) 40%, transparent),
+    0 8px 32px -8px color-mix(in srgb, var(--facet-fail) 55%, transparent);
+  --facet-tier-border: color-mix(in srgb, var(--facet-ink) 28%, transparent);
+  --facet-tier-fill: color-mix(in srgb, var(--facet-ink) 6%, transparent);
+  --facet-tier-strong-border: color-mix(in srgb, var(--facet-cyan) 45%, transparent);
+  --facet-tier-strong-fill: color-mix(in srgb, var(--facet-cyan) 8%, transparent);
+
+  /* Spacing scale (4px base) */
+  --facet-space-1: 4px;
+  --facet-space-2: 8px;
+  --facet-space-3: 12px;
+  --facet-space-4: 16px;
+  --facet-space-5: 24px;
+  --facet-space-6: 32px;
+
+  /* Radii */
+  --facet-radius-1: 4px;
+  --facet-radius-2: 8px;
+
+  /* Type */
+  --facet-font-sans:
+    "Space Grotesk", "Geist", "Inter", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  --facet-font-mono: "JetBrains Mono", "Geist Mono", "SF Mono", "Menlo", "Consolas", monospace;
+}
+
+[data-theme="light"] {
+  color-scheme: light;
+  --facet-cyan: #075985;
+  --facet-amber: #9a3412;
+  --facet-navy: #f8fafc;
+  --facet-navy-2: #ffffff;
+  --facet-navy-3: #e2e8f0;
+  --facet-ink: #172033;
+  --facet-ink-dim: #334155;
+  --facet-ink-faint: #475569;
+  --facet-rule: #cbd5e1;
+  --facet-error: #b91c1c;
+  --facet-surface-stage: #f1f5f9;
+  --facet-focus: #075985;
+  --facet-link: #075985;
+  --facet-shadow-export: rgba(15, 23, 42, 0.2);
+  --facet-live-ok: #166534;
+  --facet-live-partial: #9a3412;
+  --facet-ok: #166534;
+  --facet-fail: #b91c1c;
+  --facet-partial: #9a3412;
+  --facet-inert: #475569;
+  --facet-tamper-ink: #ffffff;
+  --facet-ok-border: color-mix(in srgb, var(--facet-ok) 50%, transparent);
+  --facet-fail-border: color-mix(in srgb, var(--facet-fail) 50%, transparent);
+  --facet-partial-border: color-mix(in srgb, var(--facet-partial) 50%, transparent);
+  --facet-inert-border: color-mix(in srgb, var(--facet-inert) 45%, transparent);
+  --facet-tier-border: color-mix(in srgb, var(--facet-inert) 45%, transparent);
+  --facet-tier-fill: color-mix(in srgb, var(--facet-inert) 8%, transparent);
+  --facet-tier-strong-border: color-mix(in srgb, var(--facet-cyan) 50%, transparent);
+  --facet-tier-strong-fill: color-mix(in srgb, var(--facet-cyan) 8%, transparent);
+  --facet-glow-danger:
+    0 0 0 1px color-mix(in srgb, var(--facet-fail) 35%, transparent),
+    0 8px 32px -8px color-mix(in srgb, var(--facet-fail) 25%, transparent);
+}

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

@@ -0,0 +1,186 @@
+/*
+ * Facet verdict language — tokens + components.
+ * Vendored Legion Works semantics (Tokyo Night palette), fully
+ * offline, no imports, no remote assets. Safe under the frozen CSP.
+ *
+ * Grammar: every verdict is glyph + hue + weight. Glyphs survive
+ * no-color; hue survives small sizes; weight survives peripheral
+ * vision. Only `tampered` is filled and glowing — nothing animates.
+ */
+
+/*
+ * Verdict badge.
+ *   <span class="facet-verdict" data-status="ok">ok<span class="tier">· T1</span></span>
+ * JS sets data-status to the FULL wire enum value and the text to the
+ * status word (`status.split(":")[0]`). The glyph comes from CSS so
+ * markup stays free of presentation.
+ */
+.facet-verdict {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  height: 24px;
+  padding: 0 11px;
+  border-radius: 999px;
+  border: 1px solid var(--facet-inert-border);
+  background: var(--facet-inert-fill);
+  color: var(--facet-inert);
+  font-family: var(--facet-font-mono);
+  font-size: 10.5px;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+.facet-verdict::before {
+  font-size: 12px;
+  font-weight: 400;
+  letter-spacing: 0;
+}
+.facet-verdict .tier {
+  opacity: 0.62;
+  font-weight: 500;
+}
+.facet-verdict--sm {
+  height: 20px;
+  padding: 0 9px;
+  gap: 6px;
+  font-size: 10px;
+}
+
+.facet-verdict[data-status="ok"] {
+  border-color: var(--facet-ok-border);
+  background: var(--facet-ok-fill);
+  color: var(--facet-ok);
+}
+.facet-verdict[data-status="ok"]::before {
+  content: "✓";
+}
+
+.facet-verdict[data-status="error"] {
+  border-color: var(--facet-fail-border);
+  background: var(--facet-fail-fill);
+  color: var(--facet-fail);
+}
+.facet-verdict[data-status="error"]::before {
+  content: "✗";
+}
+
+.facet-verdict[data-status="partial:layout_unverified"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+.facet-verdict[data-status="partial:layout_unverified"]::before {
+  content: "◐";
+}
+.facet-verdict[data-status="partial:opaque_content"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+.facet-verdict[data-status="partial:opaque_content"]::before {
+  content: "◐";
+}
+.facet-verdict[data-status="partial:external_resources"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+.facet-verdict[data-status="partial:external_resources"]::before {
+  content: "◐";
+}
+
+.facet-verdict[data-status="partial:unstable"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+.facet-verdict[data-status="partial:unstable"]::before {
+  content: "◐";
+}
+
+/* The alarm. The only fill, the only glow. Never animated. */
+.facet-verdict[data-status="tampered"],
+.facet-verdict[data-status="insecure:unvalidated"] {
+  border-color: var(--facet-fail);
+  background: var(--facet-fail);
+  color: var(--facet-tamper-ink);
+  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: "⊘";
+}
+
+.facet-verdict[data-status="timeout"]::before {
+  content: "◌";
+}
+.facet-verdict[data-status="shim_only"]::before {
+  content: "◇";
+}
+.facet-verdict[data-status="probe_only"]::before {
+  content: "◈";
+}
+
+/* No verdict yet for the displayed revision — dashed, tierless. */
+.facet-verdict[data-status="unverified"] {
+  border-style: dashed;
+  background: transparent;
+}
+.facet-verdict[data-status="unverified"]::before {
+  content: "◌";
+}
+
+/*
+ * Tier tag — metadata, not a verdict. Square, mono.
+ *   <span class="facet-tier" data-tier="1">T1<span>browser</span></span>
+ * T2 is dashed: it displays, it never testifies.
+ */
+.facet-tier {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  height: 24px;
+  padding: 0 10px;
+  border-radius: 6px;
+  border: 1px solid var(--facet-tier-border);
+  background: var(--facet-tier-fill);
+  color: var(--facet-text);
+  font-family: var(--facet-font-mono);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+}
+.facet-tier span {
+  font-weight: 500;
+  opacity: 0.75;
+}
+.facet-tier[data-tier="1"] {
+  border-color: var(--facet-tier-strong-border);
+  background: var(--facet-tier-strong-fill);
+  color: var(--facet-focus);
+}
+.facet-tier[data-tier="2"] {
+  border-style: dashed;
+  background: transparent;
+  color: var(--facet-inert);
+}
+
+/* Evidence-channel dots (expanded panels only, never in the badge). */
+.facet-channels {
+  font-family: var(--facet-font-mono);
+  letter-spacing: 4px;
+  color: var(--facet-ink-dim);
+}
+.facet-channels[data-agree="true"] {
+  color: var(--facet-ok);
+}
+.facet-channels[data-agree="false"] {
+  color: var(--facet-fail);
+}

package/src/gallery-web/swap.ts

@@ -0,0 +1,64 @@
+/**
+ * Double-buffered HMR swap plan — pure state machine.
+ *
+ * The shell calls `run()` on each step in order. The steps are a
+ * tagged union so callers can introspect the plan without re-deriving
+ * it from a state machine.
+ *
+ * Ordering invariant: `render-new` < `swap` < `apply-view-state` <
+ * `remove-old`. If the new frame fails to render within the wait window,
+ * the plan stops short of `swap` /
+ * `remove-old` — the old frame stays visible with an error badge.
+ */
+
+export type SwapPlanStep =
+  | { readonly name: "build-new"; readonly run: () => void; readonly frameId: string }
+  | { readonly name: "load-new"; readonly run: () => void; readonly frameId: string }
+  | { readonly name: "render-new"; readonly run: () => void; readonly frameId: string }
+  | { readonly name: "swap"; readonly run: () => void }
+  | { readonly name: "apply-view-state"; readonly run: () => void; readonly zoom: number }
+  | { readonly name: "remove-old"; readonly run: () => void; readonly frameId: string };
+
+export interface PlanSwapOptions {
+  readonly currentFrameId: string;
+  readonly nextFrameId: string;
+  readonly viewState: { readonly zoom: number };
+  readonly failNewRender?: boolean;
+  readonly onStep?: (step: SwapPlanStep) => void;
+}
+
+const NOOP = (): void => {};
+
+export function planSwap(options: PlanSwapOptions): readonly SwapPlanStep[] {
+  const { currentFrameId, nextFrameId, viewState, failNewRender, onStep } = options;
+  const emit = (s: SwapPlanStep): SwapPlanStep => {
+    onStep?.(s);
+    return s;
+  };
+  const steps: SwapPlanStep[] = [
+    emit({
+      name: "build-new",
+      frameId: nextFrameId,
+      run: NOOP,
+    }),
+    emit({
+      name: "load-new",
+      frameId: nextFrameId,
+      run: NOOP,
+    }),
+    emit({
+      name: "render-new",
+      frameId: nextFrameId,
+      run: NOOP,
+    }),
+  ];
+  if (failNewRender === true) {
+    return steps;
+  }
+  steps.push(
+    emit({ name: "swap", run: NOOP }),
+    emit({ name: "apply-view-state", zoom: viewState.zoom, run: NOOP }),
+    emit({ name: "remove-old", frameId: currentFrameId, run: NOOP }),
+  );
+  return steps;
+}

package/src/gallery-web/theme.ts

@@ -0,0 +1,40 @@
+export type GalleryThemeMode = "dark" | "light" | "system";
+
+export type ResolvedGalleryTheme = Exclude<GalleryThemeMode, "system">;
+
+export type GalleryMatchMedia =
+  | ((query: string) => Pick<MediaQueryList, "matches"> | null | undefined)
+  | null
+  | undefined;
+
+export function isGalleryThemeMode(value: unknown): value is GalleryThemeMode {
+  return value === "dark" || value === "light" || value === "system";
+}
+
+export function isResolvedGalleryTheme(value: unknown): value is ResolvedGalleryTheme {
+  return value === "dark" || value === "light";
+}
+
+export function resolveGalleryTheme(
+  mode: GalleryThemeMode,
+  matchMedia: GalleryMatchMedia,
+): ResolvedGalleryTheme {
+  if (mode !== "system") return mode;
+  try {
+    const preference = matchMedia?.("(prefers-color-scheme: dark)");
+    if (
+      preference === null ||
+      preference === undefined ||
+      typeof preference.matches !== "boolean"
+    ) {
+      return "dark";
+    }
+    return preference.matches ? "dark" : "light";
+  } catch {
+    return "dark";
+  }
+}
+
+export function galleryDataTheme(theme: ResolvedGalleryTheme): "night" | "winter" {
+  return theme === "light" ? "winter" : "night";
+}

package/src/gallery-web/view-state.ts

@@ -0,0 +1,93 @@
+import type { ViewportSize } from "./frame/view-box";
+
+export const MIN_ZOOM = 0.25;
+export const MAX_ZOOM = 8;
+
+export interface ViewState {
+  zoom: number;
+  panX?: number;
+  panY?: number;
+}
+
+export function clampZoom(zoom: number): number {
+  if (!Number.isFinite(zoom)) return 1;
+  return Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom));
+}
+
+/** Canonical zero state — the one home for the `{ zoom: 1, panX: 0, panY: 0 }` literal. */
+export const EMPTY_VIEW_STATE: Required<ViewState> = { zoom: 1, panX: 0, panY: 0 };
+
+export function resetViewState(_state: ViewState): ViewState {
+  return { ...EMPTY_VIEW_STATE };
+}
+
+/** Fill the optional pan fields so callers stop open-coding `?? 0`. */
+export function normalizeViewState(state: ViewState): Required<ViewState> {
+  return { zoom: state.zoom, panX: state.panX ?? 0, panY: state.panY ?? 0 };
+}
+
+export function zoomAtPoint(
+  state: ViewState,
+  nextZoom: number,
+  cursorX: number,
+  cursorY: number,
+): ViewState {
+  const zoom = clampZoom(nextZoom);
+  const ratio = zoom / state.zoom;
+  const panX = state.panX ?? 0;
+  const panY = state.panY ?? 0;
+  return {
+    zoom,
+    panX: cursorX - (cursorX - panX) * ratio,
+    panY: cursorY - (cursorY - panY) * ratio,
+  };
+}
+
+const ZOOM_KEY_FACTOR = Math.exp(100 * 0.001);
+const PAN_STEP_PX = 10;
+const PAN_STEP_PX_SHIFT = 50;
+
+/**
+ * Map a keydown event to the resulting view state, or null if the key
+ * isn't one of the bound zoom/pan/reset keys. Pure — no DOM access —
+ * so both the shell (parent document) and the frame (iframe document)
+ * keydown listeners can share one tested key-to-state mapping instead
+ * of maintaining parallel copies.
+ */
+export function nextViewStateForKey(
+  state: ViewState,
+  key: string,
+  shiftKey: boolean,
+  rect: ViewportSize,
+): ViewState | null {
+  if (key === "+" || key === "=") {
+    return zoomAtPoint(
+      state,
+      clampZoom(state.zoom * ZOOM_KEY_FACTOR),
+      rect.width / 2,
+      rect.height / 2,
+    );
+  }
+  if (key === "-") {
+    return zoomAtPoint(
+      state,
+      clampZoom(state.zoom / ZOOM_KEY_FACTOR),
+      rect.width / 2,
+      rect.height / 2,
+    );
+  }
+  if (key === "0") {
+    return resetViewState(state);
+  }
+  if (key === "ArrowLeft" || key === "ArrowRight" || key === "ArrowUp" || key === "ArrowDown") {
+    const amount = shiftKey ? PAN_STEP_PX_SHIFT : PAN_STEP_PX;
+    const dx = key === "ArrowLeft" ? -amount : key === "ArrowRight" ? amount : 0;
+    const dy = key === "ArrowUp" ? -amount : key === "ArrowDown" ? amount : 0;
+    return {
+      ...state,
+      panX: (state.panX ?? 0) + dx,
+      panY: (state.panY ?? 0) + dy,
+    };
+  }
+  return null;
+}

package/src/harness-adapters/claude-code/README.md

@@ -0,0 +1,10 @@
+# Facet adapter for Claude Code
+
+Install the adapter where Claude Code can invoke local tools, then point it at
+`facet.sh`. The adapter forwards argv and stdin to the Facet CLI and returns
+stdout unchanged.
+
+Use `facet status` before a workflow. Publish source through stdin; keep
+secrets out of artifacts. Promotion remains operator-only.
+
+→ [Facet agent skill](../../../skills/facet/SKILL.md) · [CLI reference](../../../docs/reference/cli.md)

package/src/harness-adapters/claude-code/facet.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec bun "$SCRIPT_DIR/../../../src/cli/main.ts" "$@"

package/src/harness-adapters/codex/README.md

@@ -0,0 +1,10 @@
+# Facet adapter for Codex
+
+Install the adapter where Codex can invoke local tools, then point it at
+`facet.sh`. The adapter forwards argv and stdin to the Facet CLI and returns
+stdout unchanged.
+
+Use `facet status` before a workflow. Publish source through stdin; keep
+secrets out of artifacts. Promotion remains operator-only.
+
+→ [Facet agent skill](../../../skills/facet/SKILL.md) · [CLI reference](../../../docs/reference/cli.md)

package/src/harness-adapters/codex/facet.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec bun "$SCRIPT_DIR/../../../src/cli/main.ts" "$@"

package/src/harness-adapters/mcp/README.md

@@ -0,0 +1,13 @@
+# Facet MCP adapter
+
+Run this source-archive adapter with Bun:
+
+```sh
+bun src/harness-adapters/mcp/main.ts
+```
+
+It shells out to the Facet CLI, returns the strict CLI envelope as MCP text content, and maps typed CLI failures to MCP tool errors. `FACET_CLI` selects an alternate CLI executable; otherwise the adapter uses the repository CLI, then `facet` on `PATH`.
+
+The adapter imports only adapter-local code, shared contracts, the MCP SDK, Zod, and Node builtins. Do not add service, validation, or gallery imports.
+
+→ [MCP reference](../../../docs/reference/mcp.md)