@legionworks/facet 1.9.0

package/src/gallery-web/export-menu.ts

@@ -0,0 +1,121 @@
+import {
+  buildGallerySidecar,
+  commitGalleryExportState,
+  downloadBlob,
+  renderFilename,
+  sidecarFilename,
+  sourceFilename,
+  type GalleryExportState,
+} from "./export";
+import { mediaTypeForEvidenceImage } from "../shared/evidence-image";
+
+export interface GalleryExportMenuOptions {
+  readonly document: Document;
+  readonly isExpired: () => boolean;
+}
+
+export interface GalleryExportMenuController {
+  readonly getState: () => GalleryExportState | null;
+  readonly setState: (next: GalleryExportState | null) => void;
+  readonly clear: () => void;
+  readonly close: () => void;
+  readonly sync: () => void;
+}
+
+export function disableGalleryExportMenu(document: Document): void {
+  for (const id of ["facet-export-source", "facet-export-render", "facet-export-sidecar"]) {
+    const item = document.getElementById(id) as HTMLButtonElement | null;
+    if (item !== null) item.disabled = true;
+  }
+}
+
+export function installGalleryExportMenu(
+  options: GalleryExportMenuOptions,
+): GalleryExportMenuController {
+  const { document } = options;
+  let state: GalleryExportState | null = null;
+  const toggle = document.getElementById("facet-export-toggle");
+  const menu = document.getElementById("facet-export-menu");
+  const source = document.getElementById("facet-export-source") as HTMLButtonElement | null;
+  const render = document.getElementById("facet-export-render") as HTMLButtonElement | null;
+  const sidecar = document.getElementById("facet-export-sidecar") as HTMLButtonElement | null;
+  const close = (): void => {
+    if (menu !== null) menu.hidden = true;
+    toggle?.setAttribute("aria-expanded", "false");
+  };
+  const sync = (): void => {
+    const terminal = options.isExpired();
+    if (source !== null) source.disabled = terminal || state === null;
+    if (render !== null) {
+      const available = state?.renderBytes != null;
+      render.disabled = terminal || !available;
+      render.title = available ? "" : "no stored render";
+    }
+    if (sidecar !== null) {
+      const available = state?.verdict != null;
+      sidecar.disabled = terminal || !available;
+      sidecar.title = available ? "" : "no stored verdict";
+    }
+  };
+  toggle?.addEventListener("click", () => {
+    if (options.isExpired() || menu === null) return;
+    menu.hidden = !menu.hidden;
+    toggle.setAttribute("aria-expanded", menu.hidden ? "false" : "true");
+  });
+  document.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape" || menu === null || menu.hidden) return;
+    menu.hidden = true;
+    toggle?.setAttribute("aria-expanded", "false");
+  });
+  document.addEventListener("click", (event) => {
+    if (menu === null || menu.hidden) return;
+    const target = event.target as Node | null;
+    const wrapper = document.getElementById("facet-export");
+    if (wrapper !== null && target !== null && wrapper.contains(target)) return;
+    menu.hidden = true;
+    toggle?.setAttribute("aria-expanded", "false");
+  });
+  source?.addEventListener("click", () => {
+    if (state === null) return;
+    downloadBlob(document, sourceFilename(state), state.sourceBytes, "application/octet-stream");
+  });
+  render?.addEventListener("click", () => {
+    if (state?.renderBytes == null) return;
+    downloadBlob(
+      document,
+      renderFilename(state),
+      state.renderBytes,
+      mediaTypeForEvidenceImage(state.renderFormat ?? "png"),
+    );
+  });
+  sidecar?.addEventListener("click", () => {
+    if (state === null) return;
+    const value = buildGallerySidecar(state, new Date().toISOString());
+    if (value === null) return;
+    downloadBlob(
+      document,
+      sidecarFilename(state),
+      `${JSON.stringify(value, null, 2)}\n`,
+      "application/json",
+    );
+  });
+  sync();
+  return {
+    getState: () => state,
+    setState: (next) => {
+      if (next === null) {
+        state = null;
+        sync();
+        return;
+      }
+      state = commitGalleryExportState(state, next, { expired: options.isExpired() });
+      sync();
+    },
+    clear: () => {
+      state = null;
+      sync();
+    },
+    close,
+    sync,
+  };
+}

package/src/gallery-web/export.ts

@@ -0,0 +1,112 @@
+import {
+  buildExportSidecar,
+  extensionForExport,
+  sidecarFilenameForArtifact,
+} from "../shared/export";
+import type { EvidenceImageFormat } from "../shared/evidence-image";
+import type { ArtifactType } from "../shared/contracts/artifact-types";
+import type { Renderer } from "../shared/contracts/artifact";
+import type { ExportSidecar } from "../shared/contracts/commands/results";
+import type { Verdict } from "../shared/contracts/validation";
+
+export interface GalleryExportState {
+  readonly artifactId: string;
+  readonly revisionSha: string;
+  readonly slug: string;
+  readonly title: string;
+  readonly artifactType: ArtifactType;
+  readonly renderer: Renderer;
+  readonly sourceBytes: Uint8Array;
+  readonly verdict: Verdict | null;
+  readonly renderBytes: Uint8Array | null;
+  readonly renderFormat: EvidenceImageFormat | null;
+}
+
+export interface DownloadBlobUrlRuntime {
+  readonly createObjectURL: (blob: Blob) => string;
+  readonly revokeObjectURL: (url: string) => void;
+}
+
+const browserDownloadBlobUrlRuntime: DownloadBlobUrlRuntime = {
+  createObjectURL: (blob) => URL.createObjectURL(blob),
+  revokeObjectURL: (url) => URL.revokeObjectURL(url),
+};
+
+let downloadBlobUrlRuntime = browserDownloadBlobUrlRuntime;
+
+/** Test-only injection keeps blob URL assertions independent of global URL state. */
+export function setDownloadBlobUrlForTests(runtime: DownloadBlobUrlRuntime | undefined): void {
+  downloadBlobUrlRuntime = runtime ?? browserDownloadBlobUrlRuntime;
+}
+
+export function commitGalleryExportState(
+  current: GalleryExportState | null,
+  next: GalleryExportState,
+  options: { readonly expired?: boolean; readonly swapSucceeded?: boolean } = {},
+): GalleryExportState | null {
+  if (options.expired === true || options.swapSucceeded === false) return current;
+  return next;
+}
+
+export function exportMenuStateFrom(
+  revision: Pick<
+    GalleryExportState,
+    | "artifactId"
+    | "revisionSha"
+    | "slug"
+    | "title"
+    | "artifactType"
+    | "renderer"
+    | "sourceBytes"
+    | "verdict"
+  >,
+  renderBytes: Uint8Array | null,
+  renderFormat: EvidenceImageFormat | null,
+): GalleryExportState {
+  return { ...revision, renderBytes, renderFormat };
+}
+
+export function sourceFilename(state: Pick<GalleryExportState, "slug" | "artifactType">): string {
+  return `${state.slug}${extensionForExport("source", state.artifactType)}`;
+}
+
+export function renderFilename(
+  state: Pick<GalleryExportState, "slug" | "artifactType" | "renderFormat">,
+): string {
+  return `${state.slug}${extensionForExport("render", state.artifactType, state.renderFormat ?? "png")}`;
+}
+
+export function sidecarFilename(state: Pick<GalleryExportState, "slug" | "artifactType">): string {
+  return sidecarFilenameForArtifact(sourceFilename(state));
+}
+
+export function buildGallerySidecar(
+  state: GalleryExportState,
+  exportedAt: string,
+): ExportSidecar | null {
+  if (state.verdict === null) return null;
+  return buildExportSidecar({
+    artifactId: state.artifactId,
+    slug: state.slug,
+    revisionSha: state.revisionSha,
+    artifactType: state.artifactType,
+    renderer: state.renderer,
+    verdict: state.verdict,
+    format: "source",
+    exportedAt,
+  });
+}
+
+export function downloadBlob(
+  document: Document,
+  filename: string,
+  bytes: BlobPart,
+  type: string,
+): void {
+  const url = downloadBlobUrlRuntime.createObjectURL(new Blob([bytes], { type }));
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  downloadBlobUrlRuntime.revokeObjectURL(url);
+}

package/src/gallery-web/favicon.ts

@@ -0,0 +1,54 @@
+import type { RenderStatus } from "../shared/contracts/validation";
+import { RenderStatusSchema } from "../shared/contracts/validation";
+
+export type FaviconTint = "teal" | "amber" | "red" | "amber-red" | "grey";
+
+export const FAVICON_TINT_BY_STATUS = {
+  ok: "teal",
+  error: "red",
+  "partial:layout_unverified": "amber",
+  "partial:opaque_content": "amber",
+  "partial:external_resources": "amber",
+  "partial:unstable": "amber",
+  tampered: "red",
+  timeout: "red",
+  shim_only: "grey",
+  probe_only: "grey",
+  "insecure:unvalidated": "amber-red",
+} as const satisfies Record<RenderStatus, FaviconTint>;
+
+const FAVICON_COLOR_BY_TINT: Record<FaviconTint, string> = {
+  teal: "#86e1fc",
+  amber: "#ffc777",
+  red: "#ff6e6e",
+  "amber-red": "#ff9b6e",
+  grey: "#77809a",
+};
+
+export function faviconTint(state: RenderStatus | "idle" | "expired" | "unverified"): FaviconTint {
+  if (!RenderStatusSchema.options.includes(state as RenderStatus)) return "grey";
+  return FAVICON_TINT_BY_STATUS[state as RenderStatus];
+}
+
+export function renderFavicon(
+  tint: FaviconTint,
+  documentOverride?: Pick<Document, "createElement">,
+): string | null {
+  try {
+    const canvasDocument = documentOverride ?? (typeof document === "undefined" ? null : document);
+    if (canvasDocument === null) return null;
+    const canvas = canvasDocument.createElement("canvas");
+    canvas.width = 32;
+    canvas.height = 32;
+    const context = canvas.getContext("2d");
+    if (context === null) return null;
+    context.fillStyle = FAVICON_COLOR_BY_TINT[tint];
+    context.font = "24px sans-serif";
+    context.textAlign = "center";
+    context.textBaseline = "middle";
+    context.fillText("◆", 16, 16);
+    return canvas.toDataURL("image/png");
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { renderChart } from "../renderers/chart";
+import { createRendererRegistry } from "../renderers/registry";
+
+const registry = createRendererRegistry([["chart", renderChart]]);
+installGalleryFrameApi(registry);

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

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { renderHtml } from "../renderers/html";
+import { createRendererRegistry } from "../renderers/registry";
+
+const registry = createRendererRegistry([["html", renderHtml]]);
+installGalleryFrameApi(registry);

package/src/gallery-web/frame/entries/markdown.ts

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { renderMarkdown } from "../renderers/markdown";
+import { createRendererRegistry } from "../renderers/registry";
+
+const registry = createRendererRegistry([["markdown", renderMarkdown]]);
+installGalleryFrameApi(registry);

package/src/gallery-web/frame/entries/mermaid.ts

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { renderMermaidDocument } from "../renderers/mermaid";
+import { createRendererRegistry } from "../renderers/registry";
+
+const registry = createRendererRegistry([["mermaid", renderMermaidDocument]]);
+installGalleryFrameApi(registry);

package/src/gallery-web/frame/entries/svg.ts

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { createRendererRegistry } from "../renderers/registry";
+import { renderSvgDocument } from "../renderers/svg";
+
+const registry = createRendererRegistry([["svg", renderSvgDocument]]);
+installGalleryFrameApi(registry);

package/src/gallery-web/frame/entries/tsx.ts

@@ -0,0 +1,6 @@
+import { installGalleryFrameApi } from "../runtime";
+import { renderTsx } from "../renderers/tsx";
+import { createRendererRegistry } from "../renderers/registry";
+
+const registry = createRendererRegistry([["tsx", renderTsx]]);
+installGalleryFrameApi(registry);

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

@@ -0,0 +1,91 @@
+/**
+ * Payload + view-state helpers shared by the frame's two coexisting
+ * entry paths (bootstrap channel + direct API). One copy instead of
+ * two — divergence while both paths are installed is the drift this
+ * module exists to prevent.
+ */
+
+import type { TsxExecutionMode } from "../../shared/tsx/execution";
+import type { ResolvedGalleryTheme } from "../theme";
+import type { SvgViewBox } from "./view-box";
+
+/**
+ * Payload the shell sends to the frame's direct render API. Bytes are
+ * always Uint8Array by the time this crosses that boundary — the
+ * service delivers bytes, so a string payload here is a bug to
+ * surface, not a form to accept. One definition; both the frame
+ * runtime and the shell import it instead of re-declaring.
+ */
+export interface FrameRenderPayload {
+  readonly artifactType: string;
+  readonly renderer: string;
+  readonly bytes: Uint8Array;
+  readonly theme: ResolvedGalleryTheme;
+  readonly execution?: TsxExecutionMode;
+}
+
+export interface FrameViewState {
+  readonly zoom: number;
+  readonly panX: number;
+  readonly panY: number;
+}
+
+/**
+ * Whether the frame's wheel/drag gesture listeners are live. `native`
+ * leaves wheel/pointer events untouched (document scroll, text
+ * selection); `panzoom` installs wheel-zoom-at-cursor and drag-pan and
+ * suppresses the rendered root's own pointer events so a drag can't
+ * also select text or click through. Standalone diagram artifacts
+ * (mermaid/svg/chart) default to `panzoom`; documents default to
+ * `native` with a shell toolbar toggle — see `installGalleryFrameApi`.
+ */
+export const GESTURE_MODES = ["native", "panzoom"] as const;
+export type GestureMode = (typeof GESTURE_MODES)[number];
+
+export function isGestureMode(value: unknown): value is GestureMode {
+  return typeof value === "string" && (GESTURE_MODES as readonly string[]).includes(value);
+}
+
+/** Cross-realm-safe — frame payloads arrive via postMessage from other realms. */
+export function isUint8Array(value: unknown): value is Uint8Array {
+  return Object.prototype.toString.call(value) === "[object Uint8Array]";
+}
+
+export function decodePayloadBytes(bytes: Uint8Array | string): Uint8Array {
+  if (typeof bytes !== "string") return new Uint8Array(bytes);
+  // Base64 form (used by hosts that must embed bytes as text).
+  const binary = atob(bytes);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+export function parseViewBox(value: string | null): SvgViewBox | null {
+  if (value === null) return null;
+  const values = value
+    .trim()
+    .split(/[\s,]+/)
+    .map(Number);
+  if (
+    values.length !== 4 ||
+    values.some((entry) => !Number.isFinite(entry)) ||
+    values[2]! <= 0 ||
+    values[3]! <= 0
+  )
+    return null;
+  return { minX: values[0]!, minY: values[1]!, width: values[2]!, height: values[3]! };
+}
+
+export function isFrameViewState(value: unknown): value is FrameViewState {
+  if (value === null || typeof value !== "object") return false;
+  const state = value as Record<string, unknown>;
+  return (
+    typeof state.zoom === "number" &&
+    Number.isFinite(state.zoom) &&
+    state.zoom > 0 &&
+    typeof state.panX === "number" &&
+    Number.isFinite(state.panX) &&
+    typeof state.panY === "number" &&
+    Number.isFinite(state.panY)
+  );
+}

package/src/gallery-web/frame/renderer-validation.ts

@@ -0,0 +1,13 @@
+import { isRenderer, type Renderer } from "../../shared/contracts/renderers";
+
+import { FacetRenderError } from "./renderers/registry";
+
+export function validateRenderer(value: unknown): Renderer {
+  if (!isRenderer(value)) {
+    throw new FacetRenderError(
+      "artifact payload is missing a supported renderer",
+      "invalid_request",
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Chart renderer — validated Vega-Lite spec → SVG via the vendored
+ * Vega runtime in SVG mode.
+ *
+ * The data loader is DISABLED: inline/named data only. Every loader
+ * entry point (`load`, `http`, `file`) rejects, so a spec carrying
+ * `data.url` fails closed with a facet-error instead of fetching —
+ * the frame CSP (`connect-src 'none'`) is the backstop.
+ *
+ * A spec that renders ZERO marks is an error, not an ok render: an
+ * empty SVG root would tell the verifier "one renderer root" while
+ * showing the operator nothing.
+ */
+
+import { compile } from "vega-lite";
+import { View, loader, parse, type Loader } from "vega";
+import { expressionInterpreter } from "vega-interpreter";
+
+import type { Renderer } from "../../../shared/contracts/renderers";
+import type { ResolvedGalleryTheme } from "../../theme";
+import { FacetRenderError, type RenderContext, decodeArtifactBytes } from "./registry";
+import { importSanitizedSvgText } from "./svg";
+
+/** Every fetch path on the blocked loader rejects with the same typed error. */
+const denyBlockedFetch = (): Promise<never> =>
+  Promise.reject(
+    new FacetRenderError("external chart data is not permitted", "chart_external_data"),
+  );
+
+/** A loader whose every fetch path rejects — inline data only. */
+export function createBlockedLoader(): Loader {
+  const blocked = loader();
+  blocked.load = denyBlockedFetch;
+  blocked.http = denyBlockedFetch;
+  blocked.file = denyBlockedFetch;
+  return blocked;
+}
+
+/**
+ * Count vega data-mark groups in rendered SVG text. Vega wraps each
+ * DATA mark set in a group carrying `role-mark` (axes/legends are
+ * `role-axis`/`role-legend` and do NOT count). Vega emits the group
+ * even when it holds zero items, so the zero-marks gate counts the
+ * tuples in the view's data sets instead (`countDataTuples`).
+ */
+export function countVegaMarks(svgText: string): number {
+  return (svgText.match(/class="[^"]*\bmark-[a-z]+[^"]*role-mark/g) ?? []).length;
+}
+
+/**
+ * Total tuples across the compiled spec's named data sets — the mark
+ * items the renderer will actually draw. A spec whose pipeline yields
+ * zero tuples renders axes-only: an empty chart the gate must reject.
+ * Reads through the public `view.data(name)` surface; unknown sets
+ * count as zero.
+ */
+export function countDataTuples(view: View, compiledSpec: unknown): number {
+  const data =
+    typeof compiledSpec === "object" && compiledSpec !== null
+      ? (compiledSpec as { data?: unknown }).data
+      : undefined;
+  if (!Array.isArray(data)) return 0;
+  let total = 0;
+  for (const entry of data) {
+    const name =
+      typeof entry === "object" && entry !== null ? (entry as { name?: unknown }).name : undefined;
+    if (typeof name !== "string") continue;
+    try {
+      total += view.data(name).length;
+    } catch {
+      // unknown data set — counts as zero tuples
+    }
+  }
+  return total;
+}
+
+/**
+ * Vega's loader swallows fetch failures and silently substitutes its
+ * built-in sample data — a spec with `data.url` would render a WRONG
+ * chart that looks like success. Reject url-bearing compiled specs
+ * up front: inline/named/generated data only.
+ */
+export function compiledSpecHasExternalUrl(spec: unknown): boolean {
+  if (typeof spec !== "object" || spec === null) return false;
+  const data = (spec as { data?: unknown }).data;
+  if (!Array.isArray(data)) return false;
+  return data.some(
+    (entry) =>
+      typeof entry === "object" &&
+      entry !== null &&
+      typeof (entry as { url?: unknown }).url === "string",
+  );
+}
+
+const FACET_CHART_CONFIG: Readonly<
+  Record<ResolvedGalleryTheme, Readonly<Record<string, unknown>>>
+> = {
+  dark: {
+    background: "#151823",
+    style: {
+      "guide-label": { fill: "#c8d3f5" },
+      "guide-title": { fill: "#c8d3f5" },
+    },
+  },
+  light: {
+    background: "#ffffff",
+    style: {
+      "guide-label": { fill: "#172033" },
+      "guide-title": { fill: "#172033" },
+    },
+  },
+};
+
+export function withFacetChartTheme(spec: unknown, theme: ResolvedGalleryTheme): unknown {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec)) return spec;
+  const source = spec as Readonly<Record<string, unknown>>;
+  const authoredConfig = source.config;
+  return {
+    ...source,
+    config: {
+      ...FACET_CHART_CONFIG[theme],
+      ...(authoredConfig !== null &&
+      typeof authoredConfig === "object" &&
+      !Array.isArray(authoredConfig)
+        ? authoredConfig
+        : {}),
+    },
+  };
+}
+
+/** Render a chart artifact (artifactType "chart"): Vega-Lite JSON bytes. */
+export async function renderChart(
+  ctx: RenderContext,
+  bytes: Uint8Array,
+  renderer: Renderer = "svg",
+): Promise<void> {
+  const text = decodeArtifactBytes(bytes);
+  let spec: unknown;
+  try {
+    spec = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FacetRenderError(`chart spec is not valid JSON: ${message}`, "chart_invalid_json");
+  }
+  let compiled: { spec: unknown };
+  try {
+    compiled = compile(withFacetChartTheme(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");
+  }
+  if (compiledSpecHasExternalUrl(compiled.spec)) {
+    throw new FacetRenderError("external chart data is not permitted", "chart_external_data");
+  }
+  // `ast: true` + the expression INTERPRETER is Vega's CSP-safe path.
+  // The default compiles expressions with `Function`/eval, which the
+  // frame's nonce-only CSP blocks outright — every chart rendered as an
+  // "unsafe-eval" error instead of a plot.
+  const runtime = parse(compiled.spec as never, {}, { ast: true });
+  const view = new View(runtime, {
+    loader: createBlockedLoader(),
+    renderer: "none",
+    expr: expressionInterpreter,
+  });
+  try {
+    if (renderer === "canvas") view.renderer("canvas").initialize(ctx.container);
+    await view.runAsync();
+    if (countDataTuples(view, compiled.spec) === 0) {
+      throw new FacetRenderError("chart spec renders zero marks", "chart_zero_marks");
+    }
+    if (renderer === "svg") {
+      const svgText = await view.toSVG();
+      await importSanitizedSvgText(ctx.container, svgText);
+    }
+  } catch (error) {
+    if (error instanceof FacetRenderError) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FacetRenderError(`vega render failed: ${message}`, "chart_render_error");
+  } finally {
+    view.finalize();
+  }
+}