@legionworks/facet 1.9.0

package/src/gallery-web/sse-client.ts

@@ -0,0 +1,212 @@
+/**
+ * Authenticated SSE client for the gallery shell.
+ *
+ * The service's `/api/v1/stream` route emits `revision:committed`
+ * events for the artifact bound to the current gallery lease. The
+ * shell must authenticate every connect with `Authorization: Bearer`
+ * + `X-Gallery-Lease` + `X-Gallery-Artifact` headers — EventSource
+ * cannot set custom headers, so we use `fetch()` + ReadableStream
+ * chunk-by-chunk parsing instead.
+ *
+ * On a `revision:committed` event the shell:
+ *   1. Reacquires a fresh lease via the `open` command (rotated).
+ *   2. Fetches the exact revision bytes.
+ *   3. Triggers `replaceArtifactFrame` (double-buffered HMR swap).
+ *
+ * Reconnect: on transient network failure the client retries with a
+ * fresh lease. The lease id is rotated on every reconnect so a stale
+ * lease cannot leak via the SSE transport.
+ */
+
+export interface ConnectRevisionStreamOptions {
+  readonly baseUrl: string;
+  readonly bearer: string;
+  readonly leaseId: string;
+  readonly artifactId: string;
+  /** Called for every `revision:committed` event. */
+  readonly onCommit: (event: {
+    readonly artifactId: string;
+    readonly revisionSha: string;
+    readonly revisionNumber: number;
+    readonly artifactType: string;
+    readonly at: string;
+  }) => void;
+  /** Connection lifecycle state for the gallery shell indicator. */
+  readonly onState?: (state: "idle" | "connecting" | "live") => void;
+  /** Optional: called for `stream:heartbeat` events (used by tests). */
+  readonly onHeartbeat?: (event: { readonly streamId: string; readonly at: string }) => void;
+  /** Optional: called on `stream:close`. */
+  readonly onClose?: (event: {
+    readonly streamId: string;
+    readonly reason: string;
+    readonly at: string;
+  }) => void;
+  /** Abort signal — caller cancels to tear down the stream. */
+  readonly signal?: AbortSignal;
+  /** Hostname guard — fires before the fetch. */
+  readonly hostname: string;
+  /** Inject for tests. Defaults to global fetch. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+export interface ConnectRevisionStreamHandle {
+  /** Cancels the underlying stream + aborts any in-flight fetch. */
+  close(): void;
+}
+
+const HEARTBEAT_PREFIX = ":";
+const MAX_RECONNECT_ATTEMPTS = 3;
+const RECONNECT_DELAY_MS = 100;
+
+/**
+ * Connect to the revision SSE stream. Returns a handle whose `close()`
+ * tears down the connection. The handler MUST run on 127.0.0.1 — a
+ * non-loopback hostname is rejected before the fetch starts.
+ */
+export function connectRevisionStream(
+  options: ConnectRevisionStreamOptions,
+): ConnectRevisionStreamHandle {
+  if (options.hostname !== "127.0.0.1") {
+    throw new Error(
+      `Refusing to connect SSE: hostname must be 127.0.0.1 (got: ${JSON.stringify(options.hostname)})`,
+    );
+  }
+  const fetcher = options.fetchImpl ?? fetch;
+  const url = `${options.baseUrl.replace(/\/$/, "")}/api/v1/stream`;
+  const controller = new AbortController();
+  options.onState?.("connecting");
+  if (options.signal !== undefined) {
+    if (options.signal.aborted) controller.abort();
+    else options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  let closed = false;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempt = 0;
+  const closeWithReason = (reason: string): void => {
+    options.onState?.("idle");
+    options.onClose?.({ streamId: "", reason, at: new Date().toISOString() });
+  };
+  const reconnect = (reason: string): void => {
+    if (closed) return;
+    if (reconnectAttempt >= MAX_RECONNECT_ATTEMPTS) {
+      closeWithReason(reason);
+      return;
+    }
+    const delay = RECONNECT_DELAY_MS * 2 ** reconnectAttempt;
+    reconnectAttempt += 1;
+    options.onState?.("connecting");
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      void connect();
+    }, delay);
+  };
+  const connect = async (): Promise<void> => {
+    try {
+      const response = await fetcher(url, {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${options.bearer}`,
+          "x-gallery-lease": options.leaseId,
+          "x-gallery-artifact": options.artifactId,
+          accept: "text/event-stream",
+        },
+        signal: controller.signal,
+      });
+      if (response.status !== 200 || response.body === null) {
+        const reason = `stream_status_${response.status}`;
+        if (response.status === 401) closeWithReason(reason);
+        else reconnect(reason);
+        return;
+      }
+      reconnectAttempt = 0;
+      options.onState?.("live");
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      // Read chunk-by-chunk; SSE events are `data: <json>\n\n` blocks
+      // separated by blank lines. Heartbeats are `: heartbeat\n\n`.
+      // The `reader.read()` promise rejects when `close()` aborts the
+      // controller, which is the cancellation signal — break out of
+      // the loop without setting `closed` from inside.
+      for (;;) {
+        if (closed) break;
+        const next = await reader.read().catch(() => ({ value: undefined, done: true }));
+        const value = next.value;
+        const done = next.done;
+        if (done || value === undefined) break;
+        buffer += decoder.decode(value, { stream: true });
+        let blockEnd = buffer.indexOf("\n\n");
+        while (blockEnd >= 0) {
+          const block = buffer.slice(0, blockEnd);
+          buffer = buffer.slice(blockEnd + 2);
+          blockEnd = buffer.indexOf("\n\n");
+          if (block.length === 0) continue;
+          if (block.startsWith(HEARTBEAT_PREFIX)) continue;
+          if (!block.startsWith("data: ")) continue;
+          const payloadText = block.slice("data: ".length).trim();
+          if (payloadText.length === 0) continue;
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(payloadText);
+          } catch {
+            continue;
+          }
+          dispatch(options, parsed);
+        }
+      }
+      if (!closed) reconnect("stream_closed");
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      reconnect(error instanceof Error ? error.message : "stream_error");
+    }
+  };
+  void connect();
+  return {
+    close(): void {
+      if (closed) return;
+      closed = true;
+      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
+      try {
+        controller.abort();
+      } catch {
+        // already aborted
+      }
+      try {
+        reader?.cancel().catch(() => undefined);
+      } catch {
+        // already cancelled
+      }
+    },
+  };
+}
+
+function dispatch(options: ConnectRevisionStreamOptions, parsed: unknown): void {
+  if (typeof parsed !== "object" || parsed === null) return;
+  const record = parsed as Record<string, unknown>;
+  if (record["type"] === "revision:committed") {
+    options.onCommit({
+      artifactId: String(record["artifactId"] ?? ""),
+      revisionSha: String(record["revisionSha"] ?? ""),
+      revisionNumber: Number(record["revisionNumber"] ?? 0),
+      artifactType: String(record["artifactType"] ?? ""),
+      at: String(record["at"] ?? new Date().toISOString()),
+    });
+    return;
+  }
+  if (record["type"] === "stream:heartbeat") {
+    options.onHeartbeat?.({
+      streamId: String(record["streamId"] ?? ""),
+      at: String(record["at"] ?? new Date().toISOString()),
+    });
+    return;
+  }
+  if (record["type"] === "stream:close") {
+    options.onClose?.({
+      streamId: String(record["streamId"] ?? ""),
+      reason: String(record["reason"] ?? ""),
+      at: String(record["at"] ?? new Date().toISOString()),
+    });
+    return;
+  }
+}

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

@@ -0,0 +1,420 @@
+/*
+ * Gallery shell layout — verification-instrument treatment.
+ *
+ * Same three-band structure as before (identity → stage → controls)
+ * plus an optional evidence strip under the header. Every selector
+ * app.ts touches is preserved: #facet-status, .title, .revision,
+ * .status-line, #facet-canvas, iframe.facet-hidden / .facet-ready,
+ * #facet-controls button, #facet-error.facet-visible. New elements
+ * are additive ids only.
+ *
+ * Surfaces stay opaque — this is a data instrument, not glass. No
+ * remote assets; system-stack fallback; glyphs are plain Unicode.
+ */
+
+body {
+  margin: 0;
+  background: var(--facet-surface);
+  color: var(--facet-text);
+  font-family: var(--facet-font-sans);
+  font-size: 14px;
+  line-height: 1.45;
+}
+
+#facet-shell {
+  display: grid;
+  grid-template-rows: auto auto 1fr auto;
+  min-height: 100vh;
+}
+
+/* ---- header · identity left, testimony right ---- */
+
+#facet-status {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  height: 52px;
+  padding: 0 20px;
+  border-bottom: 1px solid var(--facet-rule-semantic);
+  background: var(--facet-surface-raised);
+}
+
+#facet-mark {
+  color: var(--facet-cyan);
+  font-size: 13px;
+  transform: translateY(-0.5px);
+}
+
+#facet-status .title {
+  font-weight: 600;
+  color: var(--facet-text);
+}
+
+#facet-status .sep {
+  width: 1px;
+  height: 18px;
+  background: var(--facet-rule-semantic);
+}
+
+#facet-artifact-title {
+  color: var(--facet-text-muted);
+  font-size: 13px;
+}
+#facet-artifact-title:empty {
+  display: none;
+}
+
+#facet-status .revision {
+  font-family: var(--facet-font-mono);
+  color: var(--facet-cyan);
+  font-size: 11.5px;
+}
+
+/* Display-state readout (T2 — display, never a verdict). */
+#facet-status .status-line {
+  margin-left: auto;
+  color: var(--facet-text-faint);
+  font-family: var(--facet-font-mono);
+  font-size: 11px;
+}
+#facet-status .status-line::after {
+  content: " · T2";
+  opacity: 0.6;
+}
+
+/* ---- evidence strip (hidden until a verdict is loaded) ---- */
+
+#facet-evidence {
+  display: flex;
+  align-items: center;
+  gap: 22px;
+  padding: 9px 20px;
+  background: var(--facet-surface-raised);
+  border-bottom: 1px solid var(--facet-rule-semantic);
+  font-family: var(--facet-font-mono);
+  font-size: 11.5px;
+  color: var(--facet-text-muted);
+}
+#facet-evidence[hidden] {
+  display: none;
+}
+#facet-evidence .label {
+  color: var(--facet-text-faint);
+  font-size: 10px;
+  letter-spacing: 0.1em;
+}
+#facet-evidence .sha {
+  color: var(--facet-cyan);
+}
+#facet-evidence .divergence {
+  color: var(--facet-error);
+}
+#facet-evidence .binding {
+  margin-left: auto;
+  color: var(--facet-text-faint);
+}
+
+/* ---- canvas · sunken stage ---- */
+
+/* The stage IS the window: the artifact frame fills every pixel between
+ * header and footer. No inset card, no centering, no size cap — the
+ * frame's own document scrolls its overflow (operator-ruled, twice). */
+#facet-canvas {
+  position: relative;
+  overflow: hidden;
+  background: var(--facet-surface-stage);
+  /* border-box: the reserved padding below must come OUT of the grid's
+     allocated `1fr` row height, not add to it — content-box padding
+     would grow the canvas's total footprint by the footer's height
+     and reintroduce the same off-viewport overflow this fix targets. */
+  box-sizing: border-box;
+  /* Reserve space for the now-fixed #facet-controls footer (its own
+     height, kept in sync above) so artifact content is never hidden
+     under it. */
+  padding-bottom: 44px;
+}
+
+/* Double-buffer progress hairline — position carries the signal, so
+   it also shows (without motion) under reduced motion. */
+#facet-swapbar {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: color-mix(in srgb, var(--facet-focus) 12%, transparent);
+}
+#facet-swapbar[hidden] {
+  display: none;
+}
+#facet-swapbar .bar {
+  width: 34%;
+  height: 100%;
+  background: var(--facet-cyan);
+  transition: width 200ms ease-out;
+}
+#facet-swapbar[data-failed] .bar {
+  background: var(--facet-error);
+}
+
+#facet-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 14px;
+  text-align: center;
+}
+#facet-empty[hidden] {
+  display: none;
+}
+#facet-empty .glyph {
+  font-size: 26px;
+  color: var(--facet-text-faint);
+}
+#facet-empty .head {
+  font-weight: 600;
+  font-size: 15px;
+  color: var(--facet-text);
+}
+#facet-empty .sub {
+  font-size: 13px;
+  color: var(--facet-text-faint);
+}
+#facet-empty .cmd {
+  font-family: var(--facet-font-mono);
+  font-size: 12px;
+  color: var(--facet-text-muted);
+  background: var(--facet-surface);
+  border: 1px solid var(--facet-rule-semantic);
+  border-radius: 6px;
+  padding: 8px 14px;
+}
+#facet-empty .cmd .p {
+  color: var(--facet-text-faint);
+}
+
+#facet-expired {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 14px;
+  text-align: center;
+}
+#facet-expired[hidden] {
+  display: none;
+}
+#facet-expired .glyph {
+  font-size: 26px;
+  color: var(--facet-error);
+}
+#facet-expired .head {
+  font-weight: 600;
+  font-size: 15px;
+  color: var(--facet-text);
+}
+#facet-expired .sub {
+  font-size: 13px;
+  color: var(--facet-text-faint);
+}
+#facet-expired .cmd {
+  font-family: var(--facet-font-mono);
+  font-size: 12px;
+  color: var(--facet-text-muted);
+  background: var(--facet-surface);
+  border: 1px solid var(--facet-rule-semantic);
+  border-radius: 6px;
+  padding: 8px 14px;
+}
+#facet-expired .cmd .p {
+  color: var(--facet-text-faint);
+}
+
+#facet-canvas iframe {
+  border: 0;
+  background: var(--facet-surface);
+  transform-origin: center center;
+  transition:
+    transform 120ms ease-out,
+    opacity 120ms linear;
+}
+
+#facet-canvas iframe.facet-hidden {
+  position: absolute;
+  width: 0;
+  height: 0;
+  opacity: 0;
+  pointer-events: none;
+  border: 0;
+}
+
+#facet-canvas iframe.facet-ready {
+  display: block;
+  width: 100%;
+  height: 100%;
+  opacity: 1;
+}
+
+/* ---- footer · connection left, controls right ---- */
+
+/*
+ * Anchored to the visual viewport, not the document flow — at extreme
+ * small viewports (400x300) whatever pushes the grid's `1fr` canvas
+ * row past its available height carries the whole document past
+ * 100vh, and an in-flow footer rides off the bottom edge with it
+ * (recorded failure: every control landed at y=381 in a 300px-tall
+ * viewport). `position: fixed` decouples the toolbar from that
+ * document height entirely — it always sits at the visual viewport's
+ * own bottom edge. The grid still reserves the `auto` row for it (an
+ * out-of-flow item's track collapses to 0, so nothing double-counts),
+ * and the canvas gets matching bottom padding so fixed positioning
+ * never covers artifact content.
+ */
+#facet-controls {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 5;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 44px;
+  padding: 0 20px;
+  border-top: 1px solid var(--facet-rule-semantic);
+  background: var(--facet-surface-raised);
+}
+
+#facet-live {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-family: var(--facet-font-mono);
+  font-size: 11px;
+  color: var(--facet-text-faint);
+}
+#facet-live .dot {
+  font-size: 9px;
+  color: var(--facet-text-faint);
+}
+#facet-live[data-state="live"] .dot {
+  color: var(--facet-live-ok);
+}
+#facet-live[data-state="connecting"] .dot {
+  color: var(--facet-live-partial);
+}
+
+#facet-controls .spacer {
+  margin-left: auto;
+}
+
+#facet-controls button {
+  height: 28px;
+  min-width: 28px;
+  padding: 0 10px;
+  display: grid;
+  place-items: center;
+  background: var(--facet-surface-control);
+  color: var(--facet-text);
+  border: 1px solid var(--facet-rule-semantic);
+  border-radius: 6px;
+  font-family: var(--facet-font-mono);
+  font-size: 11.5px;
+  cursor: pointer;
+  transition:
+    border-color 120ms ease-out,
+    color 120ms ease-out;
+}
+
+#facet-controls button:hover {
+  border-color: color-mix(in srgb, var(--facet-focus) 48%, transparent);
+  color: var(--facet-focus);
+}
+
+#facet-controls button:focus-visible {
+  outline: 2px solid var(--facet-focus);
+  outline-offset: 2px;
+}
+
+#facet-controls button:active {
+  transform: scale(0.98);
+}
+
+/* Clamp-bound feedback — a disabled zoom-in/out button reads as a
+   no-op instead of silently eating clicks at 0.25x / 8x. */
+#facet-controls button:disabled {
+  opacity: 0.4;
+  cursor: default;
+  color: var(--facet-text-faint);
+}
+#facet-controls button:disabled:hover {
+  border-color: var(--facet-rule-semantic);
+  color: var(--facet-text-faint);
+}
+
+/* Latched state for the pan/zoom mode toggle — the only toolbar
+   button with persistent on/off state rather than a momentary action. */
+#facet-controls button[aria-pressed="true"] {
+  background: var(--facet-focus);
+  color: var(--facet-surface-raised);
+  border-color: var(--facet-focus);
+}
+
+.facet-export {
+  position: relative;
+}
+
+#facet-export-menu {
+  position: absolute;
+  right: 0;
+  bottom: 36px;
+  z-index: 6;
+  display: grid;
+  gap: 4px;
+  min-width: 120px;
+  padding: 6px;
+  border: 1px solid var(--facet-rule-semantic);
+  border-radius: 6px;
+  background: var(--facet-surface-raised);
+  box-shadow: 0 8px 24px var(--facet-shadow-export);
+}
+
+#facet-export-menu[hidden] {
+  display: none;
+}
+
+#facet-export-menu button {
+  width: 100%;
+  justify-content: start;
+}
+
+/* Display-layer failure chip — an event, not a verdict, so it takes
+   the outline treatment (only `tampered` ever fills). */
+#facet-error {
+  display: none;
+  align-items: center;
+  gap: 7px;
+  margin-left: 10px;
+  height: 24px;
+  padding: 0 11px;
+  border: 1px solid var(--facet-fail-border);
+  background: var(--facet-fail-fill);
+  color: var(--facet-error);
+  border-radius: 999px;
+  font-family: var(--facet-font-mono);
+  font-size: 11px;
+}
+#facet-error::before {
+  content: "✗";
+}
+#facet-error.facet-visible {
+  display: inline-flex;
+}
+
+/* Respect prefers-reduced-motion — swaps become instant. */
+@media (prefers-reduced-motion: reduce) {
+  #facet-canvas iframe,
+  #facet-swapbar .bar,
+  #facet-controls button {
+    transition: none;
+  }
+}