@multiplatform.one/node-graph 7.7.2

package/src/diagnostics/LiveGraphDiagnostics.tsx

@@ -0,0 +1,121 @@
+/**
+ * A REAL canvas with design §9.5's panel under it — the web half.
+ *
+ * WHY IT EXISTS (MPO-211). `NodeGraph/Diagnostics` was a harness: it walked the
+ * boot stages by hand and fed the panel synthetic input, including
+ * `nodesMounted: loaded ? 12 : 0` — a literal, in the one story whose job was
+ * to prove that number. A harness that hardcodes the thing it exists to prove
+ * is worse than no harness, so the harness keeps the half it is genuinely good
+ * at (breaking the bundle on purpose) and this component owns the measured
+ * half.
+ *
+ * Every number below comes from the canvas mounted beside it:
+ *
+ *  - `nodesMounted` from `nodeCensus`, which counts `GraphNodeHost` instances
+ *    and therefore counts node bodies React Flow actually rendered;
+ *  - `nodesInDocument` from the document handed to the canvas;
+ *  - `faces` from design §6.3's corrupted-first-family probe, run against a
+ *    node title the canvas rendered;
+ *  - `faceDelivery` from `GraphFaces`, which is how the panel says whether the
+ *    asset URL answered or the base64 carried it.
+ *
+ * The native twin is `LiveGraphDiagnostics.native.tsx`, and it reads the same
+ * record out of the WebView's `ready` event instead. Only a `.native.tsx`
+ * twin, never a `.web.*` one (MPO-192).
+ */
+
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { SizableText, YStack } from "tamagui";
+import { useKnobEnvelope } from "../knobs/useKnobEnvelope";
+import { NodeGraph } from "../NodeGraph";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import { demoDocumentLarge } from "../react-flow/fixtures";
+import { mountedNodeCount, subscribeNodeCensus } from "../react-flow/nodeCensus";
+import { Background } from "../react-flow/xy";
+import { GraphFaces } from "../theme/GraphFaces";
+import type { GraphFaceStatus } from "../theme/GraphFaces";
+import { probeRenderedFamily } from "../theme/faces";
+import type { FaceProbe } from "../theme/faces";
+import { GraphDiagnostics } from "./GraphDiagnostics";
+import { useGraphDiagnostics } from "./useGraphDiagnostics";
+
+const schema = demoGraphSchema();
+
+/**
+ * The same twelve `NodeGraph/NodeGraph` → `Main` mounts, built once at module
+ * scope so a re-render cannot hand the canvas a new document identity.
+ */
+const document12 = demoDocumentLarge(12);
+
+/**
+ * The URLs `apps/storybook` serves from `public/fonts` (`staticDirs`).
+ *
+ * Named here so the WEB panel reports `asset` delivery while the device panel
+ * reports `inline` — the two mechanisms of §6.3, each proven where it is the
+ * one that runs.
+ */
+const webAssetUris = {
+  "inter-400": "/fonts/inter-400.woff2",
+  "inter-700": "/fonts/inter-700.woff2",
+} as const;
+
+export function LiveGraphDiagnostics() {
+  const nodesMounted = useSyncExternalStore(
+    subscribeNodeCensus,
+    mountedNodeCount,
+    mountedNodeCount,
+  );
+  const [faces, setFaces] = useState<readonly FaceProbe[]>([]);
+  const [faceDelivery, setFaceDelivery] = useState<readonly GraphFaceStatus[]>([]);
+  const envelope = useKnobEnvelope({});
+
+  const onFaceStatus = useCallback(
+    (statuses: readonly GraphFaceStatus[]) => setFaceDelivery(statuses),
+    [],
+  );
+
+  // Probed once the faces have resolved AND a node has mounted: a width
+  // measured before either is worthless, and `probeFamily` would report it as
+  // inconclusive rather than as a miss.
+  useEffect(() => {
+    if (nodesMounted === 0) return;
+    let live = true;
+    void (async () => {
+      await globalThis.document.fonts.ready;
+      if (!live) return;
+      const title = globalThis.document.querySelector("[data-graph-node-title]");
+      if (!title) return;
+      const probe = probeRenderedFamily(title);
+      if (probe.stack) setFaces([probe]);
+    })();
+    return () => {
+      live = false;
+    };
+  }, [nodesMounted]);
+
+  const diagnostics = useGraphDiagnostics({
+    renderer: "react-flow-web",
+    faces,
+    faceDelivery,
+    nodesMounted,
+    nodesInDocument: document12.nodes.length,
+    culling: true,
+    renderMode: "detail",
+    scheme: envelope.scheme,
+  });
+
+  return (
+    <YStack gap="$3" padding="$3">
+      <GraphFaces assetUris={webAssetUris} onStatus={onFaceStatus} />
+      <YStack width="100%" height={360}>
+        <NodeGraph schema={schema} defaultDocument={document12}>
+          <Background />
+        </NodeGraph>
+      </YStack>
+      <SizableText size="$2" opacity={0.6}>
+        Every value below is read off the canvas above. Nothing here is a literal.
+      </SizableText>
+      <GraphDiagnostics diagnostics={diagnostics} show />
+    </YStack>
+  );
+}

package/src/diagnostics/deliberateBreak.ts

@@ -0,0 +1,35 @@
+/**
+ * A module that throws when it is evaluated. That is its whole job.
+ *
+ * Design §9.5 asks for a story toggle that "deliberately breaks the bundle so
+ * the fallback path is a story rather than a hope". A toggle that only sets a
+ * flag would exercise a branch, not the failure — the real failure is a module
+ * whose EVALUATION throws inside `await import(...)`, which is what the boot
+ * heartbeat of §9.4 layer 3 is built to catch and what the diagnostics panel
+ * has to be able to name.
+ *
+ * SAFE TO SHIP, and `GraphDiagnostics.stories.tsx` is the only importer:
+ *
+ *  - It is reached exclusively through a dynamic `import()` behind a story
+ *    control, so nothing evaluates it unless a human flips the switch.
+ *  - The package build EXCLUDES THIS FILE BY NAME, so no compiled copy exists.
+ *    Excluding only `*.stories.*` was not enough and the first build proved
+ *    it: `tamagui-build` compiles every source file it finds, reachable or
+ *    not, and emitted `dist/esm/diagnostics/deliberateBreak.mjs`. The exclude
+ *    pattern is the same mechanism that keeps the DOM entry out of `dist`.
+ *  - `GraphDiagnostics.spec.tsx` asserts no non-story module under `src/`
+ *    imports it, so it cannot quietly acquire a second caller.
+ *
+ * The message is written to look like the failure it stands in for: the
+ * `import.meta` parse error that blanks a WebView with no reachable error
+ * boundary (design §9.4).
+ */
+
+throw new Error(
+  "deliberate break: Cannot use 'import.meta' outside a module (simulated, node-graph diagnostics story)",
+);
+
+// TypeScript treats a file with no import or export as a global script, and a
+// global script cannot be the target of `import()`. This is what makes the file
+// a module; it never runs, because the throw above is unconditional.
+export {};

package/src/diagnostics/fromWire.spec.ts

@@ -0,0 +1,74 @@
+/**
+ * The `ready` payload becoming design §9.5's record.
+ *
+ * The interesting half is `layoutRunner`: the wire types it as a plain string
+ * so milestone 4 can add a runner without a bridge change, and the record types
+ * it as a union the panel renders. A cast would let a canvas one version ahead
+ * put a runner name on screen that this build knows nothing about; narrowing to
+ * `none` says "no runner I recognise" instead, which is the honest reading of
+ * an unknown value.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { GraphDiagnosticsWire } from "../dom/wire";
+import { graphDiagnosticsFromWire } from "./fromWire";
+
+const wire: GraphDiagnosticsWire = {
+  stage: "ready",
+  bootMs: 1204,
+  renderer: "react-flow-dom",
+  xyflowVersion: "12.11.5",
+  layoutRunner: "none",
+  faces: [
+    {
+      stack: 'Inter, "Helvetica Neue", sans-serif',
+      widthStack: 210.13,
+      widthFirstCorrupted: 205.28,
+      matched: true,
+      conclusive: true,
+    },
+  ],
+  faceDelivery: [{ id: "inter-400", family: "Inter", weight: 400, source: "inline" }],
+  nodesMounted: 10,
+  nodesInDocument: 12,
+  culling: true,
+  renderMode: "detail",
+  scheme: "dark",
+  lastError: null,
+};
+
+describe("graphDiagnosticsFromWire", () => {
+  it("carries every field the panel renders", () => {
+    const record = graphDiagnosticsFromWire(wire);
+    expect(record.stage).toBe("ready");
+    expect(record.bootMs).toBe(1204);
+    expect(record.nodesMounted).toBe(10);
+    expect(record.nodesInDocument).toBe(12);
+    expect(record.faces).toHaveLength(1);
+    expect(record.faceDelivery[0]?.source).toBe("inline");
+    expect(record.scheme).toBe("dark");
+  });
+
+  it("keeps a runner kind it recognises", () => {
+    expect(graphDiagnosticsFromWire({ ...wire, layoutRunner: "worker-blob" }).layoutRunner).toBe(
+      "worker-blob",
+    );
+  });
+
+  it("narrows a runner it does not recognise to none, rather than casting", () => {
+    // A canvas from a later milestone naming a runner this build has never
+    // heard of. Reporting the string verbatim would put an unknown runner on
+    // screen as if this build knew what it meant.
+    expect(graphDiagnosticsFromWire({ ...wire, layoutRunner: "elk-worker" }).layoutRunner).toBe(
+      "none",
+    );
+  });
+
+  it("passes an error through as the panel's banner reads it", () => {
+    const record = graphDiagnosticsFromWire({
+      ...wire,
+      lastError: { phase: "module", message: "boom" },
+    });
+    expect(record.lastError).toEqual({ phase: "module", message: "boom" });
+  });
+});

package/src/diagnostics/fromWire.ts

@@ -0,0 +1,48 @@
+/**
+ * The `ready` event's payload, as design §9.5's record.
+ *
+ * The two shapes are the same fields with one deliberate difference:
+ * `GraphDiagnosticsWire.layoutRunner` is a plain string, so adding a layout
+ * runner in milestone 4 is not a bridge change. This is the one place that
+ * difference is reconciled, and an unknown runner narrows to `"none"` rather
+ * than being cast — a value the panel invented would read as a runner that ran.
+ *
+ * Everything else crosses unchanged. `FaceProbeWire` and `FaceProbe` are the
+ * same five fields, and `graphDiagnosticsWireFields` in `wire.spec.ts` is what
+ * holds them to that.
+ */
+
+import type { GraphDiagnosticsWire } from "../dom/wire";
+import type { GraphDiagnostics, LayoutRunnerKind } from "./types";
+
+const layoutRunnerKinds: readonly LayoutRunnerKind[] = [
+  "worker-blob",
+  "worker-url",
+  "hermes-inline",
+  "inline",
+  "none",
+];
+
+function asLayoutRunner(value: string): LayoutRunnerKind {
+  return (layoutRunnerKinds as readonly string[]).includes(value)
+    ? (value as LayoutRunnerKind)
+    : "none";
+}
+
+export function graphDiagnosticsFromWire(wire: GraphDiagnosticsWire): GraphDiagnostics {
+  return {
+    stage: wire.stage,
+    bootMs: wire.bootMs,
+    renderer: wire.renderer,
+    xyflowVersion: wire.xyflowVersion,
+    layoutRunner: asLayoutRunner(wire.layoutRunner),
+    faces: wire.faces,
+    faceDelivery: wire.faceDelivery,
+    nodesMounted: wire.nodesMounted,
+    nodesInDocument: wire.nodesInDocument,
+    culling: wire.culling,
+    renderMode: wire.renderMode,
+    scheme: wire.scheme,
+    lastError: wire.lastError,
+  };
+}

package/src/diagnostics/lastError.ts

@@ -0,0 +1,91 @@
+/**
+ * The one error worth reporting, kept where both halves of boot can reach it.
+ *
+ * Same shape and same reason as `dom/boot.ts`: `NodeGraphDom.ts` must carry no
+ * top-level import of ours that could itself throw (design §9.4 layer 3), so it
+ * writes this slot INLINE from its own catch block. A module-scoped variable
+ * would give the entry and the diagnostics panel two separate records, and the
+ * panel would report the empty one.
+ *
+ * Everything here treats the global as untrusted. A record another library
+ * clobbered, or a phase outside the wire's four, reads back as `null` rather
+ * than throwing inside the error path — which is the one path where a second
+ * throw costs you the diagnosis.
+ *
+ * Design: docs/design/node-graph-editor.md §9.5.
+ */
+
+import type { GraphErrorPhase } from "../dom/wire";
+
+/**
+ * The key `NodeGraphDom.ts` writes inline.
+ *
+ * Exported so `useGraphDiagnostics.spec.tsx` can assert the entry's literal and
+ * this module's reader still name the same slot — the one place the two halves
+ * could silently drift.
+ */
+export const graphErrorGlobalKey = "__mp_graph_error";
+
+export interface GraphErrorRecord {
+  readonly phase: GraphErrorPhase;
+  readonly message: string;
+  readonly stack?: string;
+  /** `Date.now()` at the record, so a panel can say how long ago it happened. */
+  readonly at: number;
+}
+
+const phases: readonly GraphErrorPhase[] = ["boot", "module", "render", "runtime"];
+
+function slot(): Record<string, unknown> {
+  return globalThis as unknown as Record<string, unknown>;
+}
+
+function isPhase(value: unknown): value is GraphErrorPhase {
+  return typeof value === "string" && (phases as readonly string[]).includes(value);
+}
+
+/** The record as written, normalised. Anything unrecognisable reads as `null`. */
+export function readGraphError(): GraphErrorRecord | null {
+  const raw = slot()[graphErrorGlobalKey];
+  if (!raw || typeof raw !== "object") return null;
+  const record = raw as Partial<GraphErrorRecord>;
+  if (!isPhase(record.phase)) return null;
+  if (typeof record.message !== "string") return null;
+  return {
+    phase: record.phase,
+    message: record.message,
+    stack: typeof record.stack === "string" ? record.stack : undefined,
+    at: typeof record.at === "number" ? record.at : 0,
+  };
+}
+
+/**
+ * Record an error, keeping the FIRST one.
+ *
+ * A module-eval throw usually produces a train of render errors behind it, and
+ * last-write-wins would report the consequence while the cause scrolled off.
+ * `resetGraphError` is what Retry calls before remounting, so a genuinely new
+ * boot is not judged on the previous one's failure.
+ */
+export function recordGraphError(error: {
+  readonly phase: GraphErrorPhase;
+  readonly message: string;
+  readonly stack?: string;
+}): GraphErrorRecord | null {
+  if (!isPhase(error.phase) || typeof error.message !== "string") return readGraphError();
+  const previous = readGraphError();
+  if (previous) return previous;
+  const record: GraphErrorRecord = {
+    phase: error.phase,
+    message: error.message,
+    stack: error.stack,
+    at: Date.now(),
+  };
+  slot()[graphErrorGlobalKey] = record;
+  return record;
+}
+
+/** Test seam, and what Retry calls before remounting. */
+export function resetGraphError(): void {
+  delete slot()[graphErrorGlobalKey];
+}

package/src/diagnostics/types.ts

@@ -0,0 +1,103 @@
+/**
+ * What a WebView that came up wrong is able to tell you (design §9.5).
+ *
+ * Every field here answers a question an agent reading a device screenshot has
+ * to be able to answer without a console: how far did boot get, which renderer
+ * drew this, which layout runner resolved, did the face actually paint, how
+ * many nodes mounted, and what threw first.
+ */
+
+import type { BootStage } from "../dom/boot";
+import type { LayoutRunnerKind as LayoutEngineRunnerKind } from "../layout/types";
+import type { GraphErrorPhase } from "../dom/wire";
+import type { FaceProbe } from "../theme/faces";
+
+/**
+ * Design §8's four, plus `none`.
+ *
+ * `none` is not in the design's union and is not a fifth strategy — it is the
+ * honest state before a canvas has resolved a runner. The alternative was
+ * reporting `inline`, which is a real runner and would read as "the worker
+ * fallback fired" to exactly the person the field exists for.
+ *
+ * The four are IMPORTED rather than restated. Milestone 4 made
+ * `layout/types.ts` the definition, and two hand-kept copies of a union is how
+ * a fifth runner ends up reportable in one file and not the other.
+ */
+export type LayoutRunnerKind = LayoutEngineRunnerKind | "none";
+
+export type GraphRenderer = "react-flow-web" | "react-flow-dom";
+
+/**
+ * Which of design 6.3's two mechanisms actually delivered a face.
+ *
+ * On device this is the whole answer to "did the asset URL work, or did the
+ * 211 KB of base64 carry it" — a question nothing on screen could answer
+ * before MPO-211, because `GraphFaces` reported it to a callback the panel
+ * never saw. `pending` means the probe has not answered yet, and is reported
+ * rather than guessed.
+ */
+export interface GraphFaceDelivery {
+  readonly id: string;
+  readonly family: string;
+  readonly weight: number;
+  readonly source: "asset" | "inline" | "pending" | "failed";
+}
+
+export interface GraphDiagnostics {
+  readonly stage: BootStage | null;
+  /**
+   * Milliseconds from the entry's `script` stamp to this record, or `null`
+   * where no boot record exists.
+   *
+   * The number the native watchdog's budget is set FROM (MPO-211). Design
+   * 9.4's 4000 ms was never measured; on emulator-5590 rebooted fresh it
+   * fired on a canvas that then rendered on the first Retry.
+   */
+  readonly bootMs: number | null;
+  readonly renderer: GraphRenderer;
+  readonly xyflowVersion: string;
+  readonly layoutRunner: LayoutRunnerKind;
+  readonly faces: readonly FaceProbe[];
+  /** Which mechanism delivered each declared face. Empty where none was mounted. */
+  readonly faceDelivery: readonly GraphFaceDelivery[];
+  /**
+   * Node bodies React Flow has MOUNTED, from `nodeCensus` — not the document's
+   * node count, which is the field below.
+   *
+   * The two differ whenever `culling` is true: the demo document has 12 nodes
+   * and mounts 10 at the default viewport. Reporting one number for both is
+   * what made "renders 12 nodes" unreadable off a device screenshot.
+   */
+  readonly nodesMounted: number;
+  /** Nodes in the document the canvas parsed. */
+  readonly nodesInDocument: number;
+  readonly culling: boolean;
+  readonly renderMode: "detail" | "overview";
+  readonly scheme: "light" | "dark";
+  readonly lastError: { readonly phase: GraphErrorPhase; readonly message: string } | null;
+}
+
+/**
+ * What the caller knows, as against what this module derives.
+ *
+ * The split is deliberate. `stage`, `xyflowVersion` and `lastError` are read
+ * from module state and cannot be faked by a caller; the rest are live values
+ * only the canvas holds. Making the canvas hand them in beats reaching into
+ * React Flow's store from a second place — `renderMode` in particular is
+ * already computed once, in `GraphNodeHost`, from the live zoom.
+ */
+export interface GraphDiagnosticsInput {
+  readonly renderer: GraphRenderer;
+  readonly nodesMounted: number;
+  readonly nodesInDocument: number;
+  readonly culling: boolean;
+  readonly renderMode: "detail" | "overview";
+  readonly scheme: "light" | "dark";
+  /** Omitted until `resolveRunner()` has answered. Reported as `none`. */
+  readonly layoutRunner?: LayoutRunnerKind;
+  /** From `probeRenderedFamily`. Omitted reports as an empty list, never absent. */
+  readonly faces?: readonly FaceProbe[];
+  /** From `GraphFaces`' `onStatus`. Omitted reports as an empty list, never absent. */
+  readonly faceDelivery?: readonly GraphFaceDelivery[];
+}

package/src/diagnostics/useGraphDiagnostics.spec.tsx

@@ -0,0 +1,199 @@
+/**
+ * Diagnostics, and the failure they exist for (design §9.5, MPO-211 task 2.6).
+ *
+ * A WebView that comes up empty has no console the user can open. Layers 1-4 of
+ * design §9.4 stop the blank rectangle; this is what makes the surviving
+ * failure legible — which stage boot reached, which renderer, which layout
+ * runner, whether the face painted, and what threw.
+ *
+ * The line that carries the most weight: **a thrown module import surfaces as
+ * `lastError.phase === "module"` rather than a blank render.** That is the
+ * failure design §9.4 layer 3 is built around, and the one an agent reading a
+ * screenshot has to be able to name.
+ */
+
+import { renderHook } from "@testing-library/react";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { resetBoot, stampBootStage } from "../dom/boot";
+import { xyflowVersion } from "../react-flow/xy";
+import {
+  graphErrorGlobalKey,
+  readGraphError,
+  recordGraphError,
+  resetGraphError,
+} from "./lastError";
+import { useGraphDiagnostics } from "./useGraphDiagnostics";
+
+const baseInput = {
+  renderer: "react-flow-dom",
+  nodesMounted: 12,
+  nodesInDocument: 12,
+  culling: true,
+  renderMode: "detail",
+  scheme: "light",
+} as const;
+
+afterEach(() => {
+  resetBoot();
+  resetGraphError();
+});
+
+describe("useGraphDiagnostics", () => {
+  it("reports the last boot stage, not the first", () => {
+    stampBootStage("script");
+    stampBootStage("module");
+    stampBootStage("faces");
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.stage).toBe("faces");
+  });
+
+  it("RE-READS the stage on a later render, not once at mount", () => {
+    // Found on the Storybook, not here, and then brought back as a spec. The
+    // hook derives from two globals nothing in its input mentions, so a memo
+    // keyed on the input alone captures them at mount and never looks again —
+    // and the boot stages are stamped by an EFFECT, which runs after that
+    // first render. The panel then reports `stage: none` on a boot that
+    // reached `faces`, which is the one number it exists to get right.
+    const { result, rerender } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.stage).toBeNull();
+    stampBootStage("script");
+    stampBootStage("module");
+    rerender();
+    expect(result.current.stage).toBe("module");
+  });
+
+  it("RE-READS lastError on a later render, for the same reason", () => {
+    const { result, rerender } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.lastError).toBeNull();
+    recordGraphError({ phase: "module", message: "thrown after mount" });
+    rerender();
+    expect(result.current.lastError?.phase).toBe("module");
+  });
+
+  it("keeps a stable identity when nothing moved, so a consumer memo still holds", () => {
+    const { result, rerender } = renderHook(() => useGraphDiagnostics(baseInput));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+
+  it("reports a null stage when boot never stamped one, rather than inventing script", () => {
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.stage).toBeNull();
+  });
+
+  it("reports the real @xyflow version, and it is not the empty string task 2.4 emitted", () => {
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.xyflowVersion).toBe(xyflowVersion);
+    expect(result.current.xyflowVersion).not.toBe("");
+    expect(result.current.xyflowVersion).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("reports layoutRunner as none until milestone 4 resolves one, never a guess", () => {
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.layoutRunner).toBe("none");
+    const resolved = renderHook(() =>
+      useGraphDiagnostics({ ...baseInput, layoutRunner: "worker-blob" }),
+    );
+    expect(resolved.result.current.layoutRunner).toBe("worker-blob");
+  });
+
+  it("passes renderMode, culling, scheme and the mounted count straight through", () => {
+    const { result } = renderHook(() =>
+      useGraphDiagnostics({
+        ...baseInput,
+        renderMode: "overview",
+        culling: false,
+        scheme: "dark",
+        nodesMounted: 200,
+        nodesInDocument: 200,
+      }),
+    );
+    expect(result.current.renderMode).toBe("overview");
+    expect(result.current.culling).toBe(false);
+    expect(result.current.scheme).toBe("dark");
+    expect(result.current.nodesMounted).toBe(200);
+  });
+
+  it("reports the face probes it was handed", () => {
+    const faces = [
+      {
+        stack: "Inter, sans-serif",
+        widthStack: 100,
+        widthFirstCorrupted: 120,
+        matched: true,
+        conclusive: true,
+      },
+    ];
+    const { result } = renderHook(() => useGraphDiagnostics({ ...baseInput, faces }));
+    expect(result.current.faces).toEqual(faces);
+  });
+
+  it("reports no faces as an empty list, not as a missing key", () => {
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.faces).toEqual([]);
+  });
+});
+
+describe("the module-import failure — what design §9.4 layer 3 exists for", () => {
+  it('surfaces a thrown module import as lastError.phase === "module"', () => {
+    recordGraphError({ phase: "module", message: "Cannot use 'import.meta' outside a module" });
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.lastError).not.toBeNull();
+    expect(result.current.lastError?.phase).toBe("module");
+    expect(result.current.lastError?.message).toContain("import.meta");
+  });
+
+  it("keeps the FIRST error rather than the last, because a cascade buries the cause", () => {
+    // A module-eval throw usually produces render errors behind it. The one
+    // worth reporting is the one that started it.
+    recordGraphError({ phase: "module", message: "the real cause" });
+    recordGraphError({ phase: "render", message: "a consequence" });
+    expect(readGraphError()?.phase).toBe("module");
+    expect(readGraphError()?.message).toBe("the real cause");
+  });
+
+  it("reads a record another library clobbered as null instead of throwing", () => {
+    (globalThis as unknown as Record<string, unknown>)[graphErrorGlobalKey] = "not an object";
+    expect(readGraphError()).toBeNull();
+    const { result } = renderHook(() => useGraphDiagnostics(baseInput));
+    expect(result.current.lastError).toBeNull();
+  });
+
+  it("refuses a phase outside the wire's four", () => {
+    recordGraphError({ phase: "wat" as never, message: "x" });
+    expect(readGraphError()).toBeNull();
+  });
+});
+
+describe("the shell writes the slot this module reads", () => {
+  // `NodeGraphDomShell.ts` cannot import this module — it must carry no
+  // top-level import of ours that could itself throw (design §9.4 layer 3) — so
+  // it writes the global INLINE. That literal and this module's key are the one
+  // place the two halves could silently drift, exactly as `bootGlobalKey` is
+  // for boot.
+  //
+  // It moved out of `NodeGraphDom.ts` when the `'use dom'` entry became
+  // app-owned (design §9.3): the entry is now three lines an app copies, and
+  // every mechanism this asserts lives one file down.
+  const entry = fs.readFileSync(
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../dom/NodeGraphDomShell.ts"),
+    "utf8",
+  );
+
+  it("names the same global key", () => {
+    expect(entry).toContain(graphErrorGlobalKey);
+  });
+
+  it("records the module phase from its own catch block", () => {
+    expect(entry).toMatch(/phase:\s*"module"/);
+  });
+
+  it("still renders an alert rather than returning null on a module error", () => {
+    expect(entry).toContain("data-graph-boot-error");
+    expect(entry).toMatch(/role:\s*"alert"/);
+  });
+});