@legionworks/facet 1.9.0

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

@@ -0,0 +1,183 @@
+html,
+body {
+  margin: 0;
+  height: 100%;
+  background: var(--facet-frame-surface);
+  color: var(--facet-frame-text);
+  font:
+    14px/1.55 ui-sans-serif,
+    system-ui,
+    -apple-system,
+    "Segoe UI",
+    Roboto,
+    sans-serif;
+}
+
+:root {
+  --facet-frame-surface: #151823;
+  --facet-frame-stage: #151823;
+  --facet-frame-text: #c8d3f5;
+  --facet-frame-muted: #a9b8e8;
+  --facet-frame-faint: #737aa2;
+  --facet-frame-focus: #82aaff;
+  --facet-frame-link: #82aaff;
+  --facet-frame-code: #c3e88d;
+  --facet-frame-code-surface: #1e2030;
+  --facet-frame-rule: #2f334d;
+  --facet-frame-quote: #a9b8e8;
+  --facet-frame-quote-rule: #444a73;
+}
+
+[data-theme="winter"] {
+  --facet-frame-surface: #ffffff;
+  --facet-frame-stage: #f8fafc;
+  --facet-frame-text: #172033;
+  --facet-frame-muted: #334155;
+  --facet-frame-faint: #475569;
+  --facet-frame-focus: #075985;
+  --facet-frame-link: #075985;
+  --facet-frame-code: #166534;
+  --facet-frame-code-surface: #f1f5f9;
+  --facet-frame-rule: #cbd5e1;
+  --facet-frame-quote: #334155;
+  --facet-frame-quote-rule: #64748b;
+}
+
+#artifact {
+  box-sizing: border-box;
+  height: 100%;
+  margin: 0;
+  padding: 16px;
+  overflow: auto;
+}
+
+/*
+ * Standalone diagrams (mermaid/svg/chart) center on both axes when
+ * the rendered root fits the stage. `safe` is load-bearing: it falls
+ * back to start-aligned scrolling the moment the root overflows, so
+ * zoomed-in or naturally oversized content stays 100% reachable by
+ * scroll instead of clipping unreachable off-screen (the regression
+ * a plain `center` reintroduces).
+ */
+#artifact[data-facet-artifact-type="mermaid"],
+#artifact[data-facet-artifact-type="svg"],
+#artifact[data-facet-artifact-type="chart"] {
+  display: flex;
+  justify-content: safe center;
+  align-items: safe center;
+}
+
+/*
+ * Markdown reads top-down (no vertical centering) but should not
+ * stretch to an unreadable line length at wide viewports: cap the
+ * column at a ~92ch measure and center it horizontally. Below that
+ * measure the calc() collapses to the original 16px padding, so
+ * narrow viewports are unaffected.
+ */
+#artifact[data-facet-artifact-type="markdown"] {
+  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).
+ */
+#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%;
+}
+
+#artifact > svg {
+  display: block;
+  width: fit-content;
+  max-height: none;
+  height: auto;
+  /* Flex items shrink by default (min-width: auto); without this a
+     wide diagram would squeeze toward the flex container's width
+     instead of overflowing it — the exact jail regression `safe
+     center` above is meant to prevent. */
+  flex-shrink: 0;
+}
+
+#artifact > canvas,
+#artifact > iframe {
+  display: block;
+  flex-shrink: 0;
+}
+
+#artifact [data-facet-diagram-region] {
+  display: block;
+  overflow: hidden;
+  outline: 1px solid transparent;
+  outline-offset: 2px;
+}
+
+#artifact [data-facet-diagram-region][data-facet-diagram-engaged="true"] {
+  outline-color: var(--facet-frame-focus);
+}
+
+#artifact [data-facet-diagram-region] > svg {
+  display: block;
+  max-width: none;
+}
+
+#artifact a {
+  color: var(--facet-frame-link);
+}
+
+#artifact code,
+#artifact pre {
+  color: var(--facet-frame-code);
+  background: var(--facet-frame-code-surface);
+  border-radius: 4px;
+}
+
+#artifact code {
+  padding: 1px 4px;
+}
+
+#artifact pre {
+  padding: 10px;
+  overflow: auto;
+}
+
+#artifact table {
+  border-collapse: collapse;
+}
+
+#artifact th,
+#artifact td {
+  padding: 4px 8px;
+  border: 1px solid var(--facet-frame-rule);
+}
+
+#artifact blockquote {
+  margin: 0 0 0 8px;
+  padding-left: 12px;
+  color: var(--facet-frame-quote);
+  border-left: 3px solid var(--facet-frame-quote-rule);
+}
+
+#artifact hr {
+  border: 0;
+  border-top: 1px solid var(--facet-frame-rule);
+}

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

@@ -0,0 +1,23 @@
+@import "tailwindcss" source(none);
+
+@theme {
+  --color-legion-ink: var(--facet-frame-text);
+  --color-legion-muted: var(--facet-frame-muted);
+  --color-legion-cyan: var(--facet-frame-link);
+  --color-legion-paper: var(--facet-frame-surface);
+  --color-legion-line: var(--facet-frame-rule);
+}
+
+[data-theme="winter"] {
+  --color-legion-ink: var(--facet-frame-text);
+  --color-legion-muted: var(--facet-frame-muted);
+  --color-legion-cyan: var(--facet-frame-link);
+  --color-legion-paper: var(--facet-frame-surface);
+  --color-legion-line: var(--facet-frame-rule);
+}
+
+@plugin "daisyui" {
+  themes:
+    night --default,
+    winter;
+}

package/src/gallery-web/frame/view-box.ts

@@ -0,0 +1,33 @@
+export interface SvgViewBox {
+  readonly minX: number;
+  readonly minY: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ViewportSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface NativeViewState {
+  readonly zoom: number;
+  readonly panX?: number;
+  readonly panY?: number;
+}
+
+export function applySvgViewBox(
+  original: SvgViewBox,
+  viewport: ViewportSize,
+  state: NativeViewState,
+): SvgViewBox {
+  const zoom = state.zoom;
+  const panX = state.panX ?? 0;
+  const panY = state.panY ?? 0;
+  return {
+    minX: original.minX - (panX * original.width) / viewport.width / zoom,
+    minY: original.minY - (panY * original.height) / viewport.height / zoom,
+    width: original.width / zoom,
+    height: original.height / zoom,
+  };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Pure frame-HTML helpers — document + attribute generation, hostname
+ * guard. No DOM mutation; the shell's createArtifactFrame
+ * calls these to assemble the iframe configuration.
+ *
+ * Kept in a separate file from `app.ts` so frame-document invariants — CSP
+ * exactness and artifact-byte absence — are testable without the DOM-touching
+ * surface.
+ */
+
+import { galleryDataTheme, type ResolvedGalleryTheme } from "./theme";
+
+/**
+ * Frame element attributes. The shell applies these to every iframe it
+ * creates.
+ */
+export interface FrameAttributes {
+  readonly referrerpolicy: "no-referrer";
+  readonly allow: "";
+  readonly title: string;
+  readonly src: string;
+}
+
+export function buildFrameAttributes(src = "/gallery/frame"): FrameAttributes {
+  return {
+    referrerpolicy: "no-referrer",
+    allow: "",
+    title: "facet artifact frame",
+    src,
+  };
+}
+
+export function buildFrameDocument(options: {
+  artifactType: string;
+  runtimeUrl: string;
+  theme: ResolvedGalleryTheme;
+}): string {
+  const { artifactType, runtimeUrl, theme } = options;
+  const escapedRuntimeUrl = runtimeUrl
+    .replaceAll("&", "&")
+    .replaceAll('"', """)
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+  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"
+      ? `<link rel="stylesheet" href="/gallery/frame/artifact.css">`
+      : "") +
+    "</head><body>" +
+    `<main id="artifact" data-facet-artifact-type="${artifactType}"></main>` +
+    `<script type="module" src="${escapedRuntimeUrl}"></script>` +
+    "</body></html>"
+  );
+}
+
+/**
+ * The shell trusts the loopback only. Anything else is a DNS-rebind or
+ * a same-origin-policy escape; the guard fires BEFORE the SSE stream
+ * or the iframe is touched.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "127.0.0.1";
+}
+
+export function assertLoopbackHostname(hostname: string): void {
+  if (!isLoopbackHostname(hostname)) {
+    throw new Error(
+      `Refusing to run gallery shell: hostname must be 127.0.0.1 (got: ${JSON.stringify(hostname)})`,
+    );
+  }
+}

package/src/gallery-web/index.html

@@ -0,0 +1,104 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>facet gallery</title>
+    <link id="facet-favicon" rel="icon" />
+    <link rel="stylesheet" href="./styles/tokens.css" />
+    <link rel="stylesheet" href="./styles/verdict.css" />
+    <link rel="stylesheet" href="./styles/app.css" />
+  </head>
+  <body>
+    <div id="facet-shell">
+      <header id="facet-status">
+        <span id="facet-mark" aria-hidden="true">◆</span>
+        <span class="title" id="facet-title">facet</span>
+        <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>
+        <!--
+          Verdict badge. JS wiring: set data-status to the FULL wire
+          enum, text to status.split(":")[0], and the tier span to
+          `· T${verdict.tier}` (empty while unverified). The badge
+          shows read-back results only — the shell never derives one.
+        -->
+        <span class="facet-verdict facet-verdict--sm" id="facet-verdict" data-status="unverified"
+          >unverified<span class="tier"></span
+        ></span>
+      </header>
+      <!-- Evidence strip — unhidden when a verdict is loaded. -->
+      <section id="facet-evidence" hidden>
+        <span class="label">OBSERVED</span>
+        <span id="facet-evidence-counts"></span>
+        <span class="label">CHANNELS</span>
+        <span class="facet-channels" id="facet-evidence-channels"></span>
+        <span class="divergence" id="facet-evidence-divergence"></span>
+        <span class="binding">bound to <span class="sha" id="facet-evidence-sha"></span></span>
+      </section>
+      <main id="facet-canvas">
+        <div id="facet-swapbar" hidden><div class="bar"></div></div>
+        <div id="facet-empty">
+          <span class="glyph" aria-hidden="true">◌</span>
+          <span class="head">No artifact.</span>
+          <span class="sub">Publish one to display it here.</span>
+          <span class="cmd"
+            ><span class="p">$</span> facet publish ./artifact.md
+            <span class="p">&amp;&amp;</span> facet open</span
+          >
+        </div>
+        <div id="facet-expired" hidden>
+          <span class="glyph" aria-hidden="true">✗</span>
+          <span class="head">Session expired.</span>
+          <span class="sub">The display lease is no longer valid.</span>
+          <span class="cmd"><span class="p">$</span> facet open</span>
+        </div>
+        <!-- The iframe is created + appended by app.ts. JS wiring:
+             hide #facet-empty whenever a frame is mounted. -->
+      </main>
+      <footer id="facet-controls">
+        <span id="facet-live" data-state="idle"
+          ><span class="dot" aria-hidden="true">●</span
+          ><span id="facet-live-label">idle</span></span
+        >
+        <span id="facet-error" role="status"></span>
+        <span class="spacer"></span>
+        <button
+          type="button"
+          id="facet-panzoom-toggle"
+          aria-label="toggle pan and zoom"
+          aria-pressed="false"
+        >
+          pan/zoom
+        </button>
+        <button type="button" id="facet-zoom-out" aria-label="zoom out">−</button>
+        <button type="button" id="facet-zoom-reset" aria-label="reset zoom">100%</button>
+        <button type="button" id="facet-zoom-in" aria-label="zoom in">+</button>
+        <button type="button" id="facet-theme-toggle" aria-label="theme: system">
+          theme: system
+        </button>
+        <div id="facet-export" class="facet-export">
+          <button type="button" id="facet-export-toggle" aria-haspopup="menu" aria-expanded="false">
+            export
+          </button>
+          <div id="facet-export-menu" role="menu" hidden>
+            <button type="button" id="facet-export-source" role="menuitem">source</button>
+            <button
+              type="button"
+              id="facet-export-render"
+              role="menuitem"
+              disabled
+              title="no stored render"
+            >
+              render
+            </button>
+            <button type="button" id="facet-export-sidecar" role="menuitem">sidecar</button>
+          </div>
+        </div>
+        <button type="button" id="facet-fullscreen" aria-label="fullscreen">fullscreen</button>
+      </footer>
+    </div>
+    <script type="module" src="./app.ts"></script>
+  </body>
+</html>

package/src/gallery-web/session.ts

@@ -0,0 +1,107 @@
+/**
+ * Session persistence for the gallery shell.
+ *
+ * The gallery's bootstrap token is single-use: once the shell exchanges
+ * it for a lease, the URL fragment is dead. A tab refresh re-submits
+ * the consumed token, the service rejects it, and the shell dies.
+ *
+ * To survive refresh, the shell persists the granted lease to
+ * `sessionStorage` (same-origin, per-tab, survives F5, never reaches the
+ * URL) AFTER a successful bootstrap exchange. On load the order is:
+ *   1. If the URL still carries a fresh `bootstrap=…` token, exchange it.
+ *   2. Otherwise, look up the persisted session and validate it against
+ *      the service (cheap authed source request). A live lease re-renders
+ *      the artifact exactly as before; an expired or service-restart
+ *      lease renders the typed "session expired" state.
+ *
+ * The lease manager is in-memory: a service restart invalidates every
+ * outstanding lease. The persisted session therefore reports a TTL
+ * window — if the service came back within the lease's nominal expiry
+ * the session is still live; otherwise it is honestly expired and the
+ * shell tells the user to run `facet open` again.
+ *
+ * The persisted payload carries the bearer authorization plus the lease
+ * id. They are scoped to the same loopback origin and never leave the
+ * tab; replacing the tab closes the channel. This matches the existing
+ * security rule that leases stay header-only (`X-Gallery-Lease`) and
+ * never reach a URL.
+ */
+
+import { isGalleryThemeMode, type GalleryThemeMode } from "./theme";
+
+export const GALLERY_SESSION_STORAGE_KEY = "facet:gallery-session";
+
+export interface GallerySession {
+  readonly authorization: string;
+  readonly artifactId: string;
+  readonly revisionSha: string;
+  readonly lease: { readonly leaseId: string; readonly expiresAt: number };
+  readonly theme: GalleryThemeMode;
+}
+
+/**
+ * Minimal `sessionStorage`-shaped surface used by the persistence helpers.
+ * Production callers pass `window.sessionStorage`; tests pass an in-memory
+ * shim so the helpers stay free of any browser global reference.
+ */
+export interface SessionStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+}
+
+export function persistSession(storage: SessionStorageLike, session: GallerySession): void {
+  storage.setItem(GALLERY_SESSION_STORAGE_KEY, JSON.stringify(session));
+}
+
+export function clearSession(storage: SessionStorageLike): void {
+  storage.removeItem(GALLERY_SESSION_STORAGE_KEY);
+}
+
+export function readPersistedSession(storage: SessionStorageLike): GallerySession | null {
+  const raw = storage.getItem(GALLERY_SESSION_STORAGE_KEY);
+  if (raw === null || raw.length === 0) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isGallerySession(parsed)) return null;
+  return {
+    authorization: parsed.authorization,
+    artifactId: parsed.artifactId,
+    revisionSha: parsed.revisionSha,
+    lease: parsed.lease,
+    theme: isGalleryThemeMode(parsed.theme) ? parsed.theme : "system",
+  };
+}
+
+export type SessionValidation =
+  | { readonly valid: true; readonly session: GallerySession }
+  | { readonly valid: false; readonly reason: "expired" | "missing" };
+
+export function validatePersistedSession(
+  session: GallerySession,
+  now: number = Date.now(),
+): SessionValidation {
+  if (session.lease.expiresAt <= now) return { valid: false, reason: "expired" };
+  return { valid: true, session };
+}
+
+function isGallerySession(
+  value: unknown,
+): value is Omit<GallerySession, "theme"> & { readonly theme?: unknown } {
+  if (value === null || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  if (typeof record["authorization"] !== "string") return false;
+  if (typeof record["artifactId"] !== "string") return false;
+  if (typeof record["revisionSha"] !== "string") return false;
+  const lease = record["lease"];
+  if (lease === null || typeof lease !== "object") return false;
+  const leaseRecord = lease as Record<string, unknown>;
+  if (typeof leaseRecord["leaseId"] !== "string") return false;
+  if (typeof leaseRecord["expiresAt"] !== "number") return false;
+  return true;
+}