@multiplatform.one/node-graph 7.7.2

package/src/diagnostics/GraphDiagnostics.spec.tsx

@@ -0,0 +1,206 @@
+/**
+ * The panel, and the two things about it that are not cosmetic.
+ *
+ * It has to NAME THE STAGE AND THE PHASE when boot failed, because that pair is
+ * what tells a reader which of design §9.4's five layers let the failure
+ * through — and on a device the panel is the only evidence there is.
+ *
+ * And `deliberateBreak.ts` throws at module scope, so its blast radius has to
+ * stay exactly one dynamic import behind a story control.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen } 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 { GraphDiagnostics } from "./GraphDiagnostics";
+import type { GraphDiagnostics as GraphDiagnosticsRecord } from "./types";
+
+const healthy: GraphDiagnosticsRecord = {
+  stage: "ready",
+  bootMs: 812,
+  renderer: "react-flow-dom",
+  xyflowVersion: "12.11.5",
+  layoutRunner: "none",
+  faces: [],
+  faceDelivery: [],
+  nodesMounted: 12,
+  nodesInDocument: 12,
+  culling: true,
+  renderMode: "detail",
+  scheme: "light",
+  lastError: null,
+};
+
+function draw(diagnostics: GraphDiagnosticsRecord, show = true) {
+  return renderWithProviders(<GraphDiagnostics diagnostics={diagnostics} show={show} />);
+}
+
+afterEach(cleanup);
+
+describe("GraphDiagnostics", () => {
+  it("reports the fields a device screenshot has to carry", () => {
+    draw(healthy);
+    expect(screen.getByText(/stage: ready/)).toBeTruthy();
+    expect(screen.getByText(/renderer: react-flow-dom/)).toBeTruthy();
+    expect(screen.getByText(/xyflow: 12\.11\.5/)).toBeTruthy();
+    expect(screen.getByText(/layoutRunner: none/)).toBeTruthy();
+    expect(screen.getByText(/nodesMounted: 12/)).toBeTruthy();
+  });
+
+  it("reports the document's node count beside the mounted one", () => {
+    // The pair is the point. AC 2.7 asks for twelve nodes; culling mounts ten
+    // of them at the default viewport, and a panel printing one number for both
+    // made that unreadable off a screenshot.
+    draw({ ...healthy, nodesMounted: 10, nodesInDocument: 12 });
+    expect(screen.getByText(/nodesInDocument: 12/)).toBeTruthy();
+    expect(
+      screen.getByText(/nodesMounted: 10 — 2 outside the viewport, culling is on/),
+    ).toBeTruthy();
+  });
+
+  it("says nothing about culling when every node mounted", () => {
+    draw({ ...healthy, nodesMounted: 12, nodesInDocument: 12 });
+    expect(screen.getByText(/nodesMounted: 12$/)).toBeTruthy();
+  });
+
+  it("reports how long boot took, so the watchdog's budget can be re-set from it", () => {
+    draw(healthy);
+    expect(screen.getByText(/bootMs: 812 ms/)).toBeTruthy();
+  });
+
+  it("says there is no boot record rather than printing a zero", () => {
+    draw({ ...healthy, bootMs: null });
+    expect(screen.getByText(/bootMs: no boot record/)).toBeTruthy();
+  });
+
+  it("names which mechanism delivered each face", () => {
+    // Design 6.3 has two, and which one answered is the difference between a
+    // 211 KB base64 payload doing the work and an asset URL doing it.
+    draw({
+      ...healthy,
+      faceDelivery: [
+        { id: "inter-400", family: "Inter", weight: 400, source: "inline" },
+        { id: "inter-700", family: "Inter", weight: 700, source: "asset" },
+      ],
+    });
+    expect(screen.getByText(/faceDelivery: inter-400 · Inter 400 · inline/)).toBeTruthy();
+    expect(screen.getByText(/faceDelivery: inter-700 · Inter 700 · asset/)).toBeTruthy();
+  });
+
+  it("says no faces were mounted rather than leaving the delivery row blank", () => {
+    draw(healthy);
+    expect(screen.getByText(/faceDelivery: no faces mounted/)).toBeTruthy();
+  });
+
+  it("says faces were not probed rather than showing an empty space", () => {
+    draw(healthy);
+    expect(screen.getByText(/faces: not probed/)).toBeTruthy();
+  });
+
+  it("shows a face probe's verdict and both widths", () => {
+    draw({
+      ...healthy,
+      faces: [
+        {
+          stack: "Inter, sans-serif",
+          widthStack: 210.13,
+          widthFirstCorrupted: 205.28,
+          matched: true,
+          conclusive: true,
+        },
+      ],
+    });
+    expect(screen.getByText(/MATCHED/)).toBeTruthy();
+    expect(screen.getByText(/210\.13px vs 205\.28px/)).toBeTruthy();
+  });
+
+  it("draws NOTHING outside dev unless told otherwise", () => {
+    const { container } = draw(healthy, false);
+    expect(container.querySelector("[data-graph-diagnostics]")).toBeNull();
+  });
+
+  it("NAMES THE STAGE AND THE PHASE on a module failure", () => {
+    draw({
+      ...healthy,
+      stage: "faces",
+      lastError: { phase: "module", message: "Cannot use 'import.meta' outside a module" },
+    });
+    expect(screen.getByText(/boot failed at stage faces · phase module/)).toBeTruthy();
+    expect(screen.getByText(/import\.meta/)).toBeTruthy();
+  });
+
+  it("marks the stage reached in the trail, so the remaining layers are visible", () => {
+    draw({
+      ...healthy,
+      stage: "faces",
+      lastError: { phase: "module", message: "x" },
+    });
+    expect(screen.getByText(/script → module → \[faces\] → provider → flow → ready/)).toBeTruthy();
+  });
+
+  it("says the stage was none when boot never stamped one", () => {
+    draw({ ...healthy, stage: null, lastError: { phase: "boot", message: "x" } });
+    expect(screen.getByText(/boot failed at stage none · phase boot/)).toBeTruthy();
+    expect(screen.getByText(/\(none reached\)/)).toBeTruthy();
+  });
+
+  it("draws no failure banner when nothing failed", () => {
+    const { container } = draw(healthy);
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
+});
+
+describe("deliberateBreak's blast radius", () => {
+  const src = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+  function filesUnder(dir: string): string[] {
+    const out: string[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        out.push(...filesUnder(full));
+        continue;
+      }
+      if (/\.(tsx?|jsx?)$/.test(entry.name)) out.push(full);
+    }
+    return out;
+  }
+
+  it("is excluded from the build, so no compiled copy of it exists at all", () => {
+    // Measured, not assumed: `tamagui-build` compiles every source file it
+    // finds, reachable or not, so a story-only importer is NOT enough to keep
+    // it out of `dist`. The first run of this build emitted
+    // dist/esm/diagnostics/deliberateBreak.mjs. The exclude pattern is what
+    // actually keeps it out, the same mechanism that keeps the DOM entry out.
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(src, "../package.json"), "utf8")) as {
+      scripts: Record<string, string>;
+    };
+    expect(pkg.scripts.build).toContain("diagnostics/deliberateBreak");
+  });
+
+  it("throws on evaluation, which is the whole point", async () => {
+    await expect(import("./deliberateBreak")).rejects.toThrow(/deliberate break/);
+  });
+
+  it("is imported by NOTHING under src/ except its own story and this spec", () => {
+    // Two importers, both named. The story, which is the feature, and this
+    // file, which imports it one line above to prove it throws. Anything else
+    // appearing here means a module that throws on evaluation acquired a
+    // caller that is not behind a story control, and the build excludes only
+    // `*.stories.*`.
+    const importers = filesUnder(src).filter(
+      (file) =>
+        !file.endsWith("deliberateBreak.ts") &&
+        /["']\.\/deliberateBreak["']|["'][^"']*\/deliberateBreak["']/.test(
+          fs.readFileSync(file, "utf8"),
+        ),
+    );
+    expect(importers.map((file) => path.relative(src, file)).sort()).toEqual([
+      "diagnostics/GraphDiagnostics.spec.tsx",
+      "diagnostics/GraphDiagnostics.stories.tsx",
+    ]);
+  });
+});

package/src/diagnostics/GraphDiagnostics.stories.tsx

@@ -0,0 +1,194 @@
+/**
+ * `NodeGraph/Diagnostics` — the panel, and the toggle that breaks the bundle
+ * for real (design §12.1, §9.5).
+ *
+ * The `Break` control is not a flag that selects an error branch. It swaps the
+ * dynamic `import()` for one that resolves to a module whose EVALUATION throws,
+ * which is the actual failure design §9.4 layer 3 exists to catch: under Metro
+ * a dynamic import compiles to a require, so a module-eval throw is catchable
+ * and reportable rather than the blank rectangle an `import.meta` parse error
+ * produces. Flipping it here walks the same stamp → import → catch → record
+ * path the DOM entry walks, and the panel then names the stage and the phase.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useEffect, useState } from "react";
+import { SizableText, YStack } from "tamagui";
+import { type BootStage, resetBoot, stampBootStage } from "../dom/boot";
+import { GraphDiagnostics } from "./GraphDiagnostics";
+import { LiveGraphDiagnostics } from "./LiveGraphDiagnostics";
+import { recordGraphError, resetGraphError } from "./lastError";
+import { useGraphDiagnostics } from "./useGraphDiagnostics";
+
+/**
+ * Walks the DOM entry's boot sequence, optionally against a module that throws.
+ *
+ * `stopAt` is how far a healthy boot gets before the import runs — `faces`,
+ * because that is the stage `NodeGraphDomInner` stamps immediately before the
+ * tree it dynamic-imports would take over.
+ */
+function BootHarness({ broken, stopAt }: { broken: boolean; stopAt: BootStage }) {
+  const [loaded, setLoaded] = useState(false);
+  const [, setTick] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    resetBoot();
+    resetGraphError();
+    setLoaded(false);
+    for (const stage of ["script", "module", "faces"] as const) {
+      stampBootStage(stage);
+      if (stage === stopAt) break;
+    }
+    void (async () => {
+      try {
+        if (broken) {
+          // A REAL thrown module import, not a simulated one.
+          await import("./deliberateBreak");
+        }
+        if (cancelled) return;
+        stampBootStage("provider");
+        stampBootStage("flow");
+        stampBootStage("ready");
+        setLoaded(true);
+      } catch (error) {
+        if (cancelled) return;
+        recordGraphError({
+          phase: "module",
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        });
+      }
+      if (!cancelled) setTick((n) => n + 1);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [broken, stopAt]);
+
+  /**
+   * NO NODE COUNTS HERE, and that is the point of the `Live` story below.
+   *
+   * This harness used to pass `nodesMounted: loaded ? 12 : 0` — a literal, in
+   * the one story whose job was to make "12 nodes" readable off a device
+   * screenshot. It proved nothing and read exactly like a measurement. There is
+   * no canvas in this harness, so the honest numbers are zeroes, and the panel
+   * is here to show the BOOT half: the stage, the phase and the thrown message.
+   */
+  const diagnostics = useGraphDiagnostics({
+    renderer: "react-flow-dom",
+    nodesMounted: 0,
+    nodesInDocument: 0,
+    culling: true,
+    renderMode: "detail",
+    scheme: "light",
+  });
+
+  return (
+    <YStack gap="$3" padding="$4" maxWidth={640}>
+      <SizableText size="$2" opacity={0.6}>
+        {broken
+          ? "Break ON — the dynamic import resolves to a module that throws on evaluation"
+          : "Break OFF — boot runs through to ready"}
+      </SizableText>
+      <SizableText size="$1" opacity={0.5}>
+        {loaded ? "boot reached ready" : "boot has not reached ready"} · no canvas is mounted here,
+        so the node counts are zero. `Live` is the story that measures them.
+      </SizableText>
+      <GraphDiagnostics diagnostics={diagnostics} show />
+    </YStack>
+  );
+}
+
+/**
+ * The meta is typed on the HARNESS, not on `GraphDiagnostics`.
+ *
+ * The story's controls drive boot — break it, and how far it got first — and
+ * neither is a prop of the panel. Typing the meta on the panel and casting the
+ * args is how a control silently stops matching what the render reads.
+ */
+const meta: Meta<typeof BootHarness> = {
+  title: "NodeGraph/Diagnostics",
+  component: BootHarness,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Design 9.5's record, rendered so a device screenshot is a diagnosis rather than a photograph of a blank rectangle. The Break control performs a real dynamic import of a module that throws when evaluated, so the fallback path is a story rather than a hope.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof BootHarness>;
+
+export const Main: Story = {
+  argTypes: {
+    broken: { control: "boolean", name: "Break the bundle" },
+    stopAt: {
+      control: "inline-radio",
+      options: ["script", "module", "faces"],
+      name: "Stage reached before the import",
+    },
+  },
+  args: { broken: false, stopAt: "faces" },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Flip Break on and the panel leads with `boot failed at stage faces . phase module` and the thrown message, instead of rendering nothing. Move the stage control and the banner names the new stage, which is how a reader tells which of design 9.4's five layers let a failure through.",
+      },
+    },
+  },
+  render: (args) => <BootHarness broken={args.broken} stopAt={args.stopAt} />,
+};
+
+export const Healthy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: "The record a WebView that came up correctly reports back through the ready event.",
+      },
+    },
+  },
+  render: () => <BootHarness broken={false} stopAt="faces" />,
+};
+
+export const ModuleFailure: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The same panel after a real thrown module import. This is the state design 9.4 layer 3 converts a blank rectangle into.",
+      },
+    },
+  },
+  render: () => <BootHarness broken stopAt="faces" />,
+};
+
+/**
+ * The measured story: a real `<NodeGraph>` with the panel reading ITS numbers.
+ *
+ * On web the panel is built from `useGraphDiagnostics` over the live node
+ * census and a font probe against a rendered node title. On native the same
+ * component mounts the DOM host and renders the diagnostics that arrive on the
+ * `ready` event — the only place either number is knowable on device, because
+ * the canvas lives in a WebView the Hermes side cannot measure.
+ *
+ * This is where AC 2.7 and 2.8's node count and AC-3's DOM half get read off a
+ * device screenshot.
+ */
+export const Live: StoryObj<typeof LiveGraphDiagnostics> = {
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "A real canvas with design 9.5's panel under it. nodesInDocument is the document's twelve; nodesMounted is what React Flow actually rendered, which is fewer while culling is on, and the panel says so on the row. faces is the corrupted-first-family control run against a rendered node title, and faceDelivery says which of 6.3's two mechanisms carried each face — the asset URL on web, the base64 inside the WebView.",
+      },
+    },
+  },
+  render: () => <LiveGraphDiagnostics />,
+};

package/src/diagnostics/GraphDiagnostics.tsx

@@ -0,0 +1,140 @@
+/**
+ * Design §9.5's record, rendered so a screenshot is a diagnosis.
+ *
+ * On a device there is no console to open, so this panel is the whole of the
+ * evidence. It leads with the failure when there is one — **which stage boot
+ * reached and which phase threw** — because that pair is what tells a reader
+ * which of design §9.4's five layers let the failure through, and everything
+ * else is context behind it.
+ *
+ * Dev-only by default, per §9.5. `show` overrides that, which is what the
+ * device runs at 2.7/2.8 use to read the panel out of a release build.
+ */
+
+import { SizableText, YStack } from "tamagui";
+import type { ReactNode } from "react";
+import { bootStages } from "../dom/boot";
+import type { GraphDiagnostics as GraphDiagnosticsRecord } from "./types";
+
+export interface GraphDiagnosticsProps {
+  readonly diagnostics: GraphDiagnosticsRecord;
+  /** Defaults to dev-only. Pass `true` to read the panel in a release build. */
+  readonly show?: boolean;
+}
+
+/** `script → module → …`, with the stage reached marked. */
+function stageTrail(stage: GraphDiagnosticsRecord["stage"]): string {
+  if (!stage) return `${bootStages.join(" → ")}  (none reached)`;
+  const index = bootStages.indexOf(stage);
+  return bootStages.map((name, i) => (i === index ? `[${name}]` : name)).join(" → ");
+}
+
+function Row({ label, value }: { label: string; value: string }) {
+  return (
+    <SizableText size="$1" fontFamily="$mono">
+      {label}: {value}
+    </SizableText>
+  );
+}
+
+/**
+ * The failure banner.
+ *
+ * Named separately because it is the part that has to survive a screenshot at
+ * phone resolution: a reader must get the stage and the phase without zooming.
+ */
+export function GraphBootFailure({
+  diagnostics,
+}: {
+  diagnostics: GraphDiagnosticsRecord;
+}): ReactNode {
+  const { lastError, stage } = diagnostics;
+  if (!lastError) return null;
+  return (
+    <YStack gap="$1" padding="$3" borderRadius="$4" backgroundColor="$red3" role="alert">
+      <SizableText size="$3" fontWeight="600" color="$red11">
+        boot failed at stage {stage ?? "none"} · phase {lastError.phase}
+      </SizableText>
+      <SizableText size="$2" fontFamily="$mono" color="$red11">
+        {lastError.message}
+      </SizableText>
+      <SizableText size="$1" fontFamily="$mono" color="$red11" opacity={0.8}>
+        {stageTrail(stage)}
+      </SizableText>
+    </YStack>
+  );
+}
+
+export function GraphDiagnostics({ diagnostics, show }: GraphDiagnosticsProps): ReactNode {
+  const visible = show ?? process.env.NODE_ENV !== "production";
+  if (!visible) return null;
+  const {
+    stage,
+    bootMs,
+    renderer,
+    xyflowVersion,
+    layoutRunner,
+    faces,
+    faceDelivery,
+    nodesMounted,
+    nodesInDocument,
+    culling,
+    renderMode,
+    scheme,
+  } = diagnostics;
+  // The gap between the two counts is the thing a reader has to be told, not
+  // left to work out: with culling on, a 12-node document paints ten bodies at
+  // the default viewport, and a panel that printed one number for both made
+  // "renders 12 nodes" impossible to read off a screenshot.
+  const culled = nodesInDocument - nodesMounted;
+  return (
+    <YStack
+      gap="$2"
+      padding="$3"
+      borderRadius="$4"
+      backgroundColor="$background"
+      data-graph-diagnostics=""
+    >
+      <GraphBootFailure diagnostics={diagnostics} />
+      <Row label="stage" value={stage ?? "none"} />
+      <Row label="bootMs" value={bootMs === null ? "no boot record" : `${bootMs} ms`} />
+      <Row label="renderer" value={renderer} />
+      <Row label="xyflow" value={xyflowVersion} />
+      <Row label="layoutRunner" value={layoutRunner} />
+      <Row label="nodesInDocument" value={String(nodesInDocument)} />
+      <Row
+        label="nodesMounted"
+        value={
+          culled > 0
+            ? `${nodesMounted} — ${culled} outside the viewport, culling is on`
+            : String(nodesMounted)
+        }
+      />
+      <Row label="culling" value={String(culling)} />
+      <Row label="renderMode" value={renderMode} />
+      <Row label="scheme" value={scheme} />
+      {faceDelivery.length === 0 ? (
+        <Row label="faceDelivery" value="no faces mounted" />
+      ) : (
+        faceDelivery.map((face) => (
+          <Row
+            key={face.id}
+            label="faceDelivery"
+            value={`${face.id} · ${face.family} ${face.weight} · ${face.source}`}
+          />
+        ))
+      )}
+      {faces.length === 0 ? (
+        <Row label="faces" value="not probed" />
+      ) : (
+        faces.map((probe) => (
+          <SizableText key={probe.stack} size="$1" fontFamily="$mono">
+            face: {!probe.conclusive ? "INCONCLUSIVE" : probe.matched ? "MATCHED" : "MISS"} ·{" "}
+            {probe.widthStack.toFixed(2)}px vs {probe.widthFirstCorrupted.toFixed(2)}px ·{" "}
+            {probe.stack}
+          </SizableText>
+        ))
+      )}
+    </YStack>
+  );
+}

package/src/diagnostics/LiveGraphDiagnostics.native.tsx

@@ -0,0 +1,61 @@
+/**
+ * A REAL canvas with design §9.5's panel under it — the NATIVE half, and the
+ * only place AC-3's DOM half can be read (MPO-211).
+ *
+ * The problem this solves. On device the canvas renders inside a WebView, so
+ * every number worth having is measured in a JS realm the Hermes side cannot
+ * reach: how many node bodies actually mounted, and whether §6.3's
+ * corrupted-first-family control says the `$body` face painted. A story on the
+ * Hermes side can measure neither — `NodeGraph/GraphNode` → `FontProof` tries,
+ * and its probe measures the Hermes-side stack, which is not the thing AC-3
+ * asks about. The canvas already computes all of it and sends it over the
+ * `ready` event; until now nothing on a device DISPLAYED it.
+ *
+ * So this mounts the same `<NodeGraph>` the Kitchen Sink's `Main` story mounts,
+ * takes the `ready` payload, and renders it straight into `GraphDiagnostics`.
+ * Nothing is synthesised here. If the canvas never reports, the panel says so
+ * rather than showing zeroes that look like measurements.
+ *
+ * `../NodeGraph.native` is imported by its explicit filename, the same way
+ * `index.native.ts` does it: `onReady` is native-only by construction, so the
+ * shared specifier would resolve to the web twin under `tsgo` and the prop
+ * would not typecheck.
+ */
+
+import { useState } from "react";
+import { SizableText, YStack } from "tamagui";
+import type { GraphDiagnosticsWire } from "../dom/wire";
+import { NodeGraph } from "../NodeGraph.native";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import { demoDocumentLarge } from "../react-flow/fixtures";
+import { GraphDiagnostics } from "./GraphDiagnostics";
+import { graphDiagnosticsFromWire } from "./fromWire";
+
+const schema = demoGraphSchema();
+
+/** The same twelve `NodeGraph/NodeGraph` → `Main` mounts. */
+const document12 = demoDocumentLarge(12);
+
+export function LiveGraphDiagnostics() {
+  const [wire, setWire] = useState<GraphDiagnosticsWire | null>(null);
+
+  return (
+    <YStack flex={1} gap="$3" padding="$3">
+      <YStack width="100%" height={300}>
+        <NodeGraph schema={schema} defaultDocument={document12} onReady={setWire} />
+      </YStack>
+      {wire ? (
+        <>
+          <SizableText size="$2" opacity={0.6}>
+            Read off the canvas above, inside the WebView. Nothing here is a literal.
+          </SizableText>
+          <GraphDiagnostics diagnostics={graphDiagnosticsFromWire(wire)} show />
+        </>
+      ) : (
+        <SizableText size="$2" fontFamily="$mono">
+          waiting for the canvas's ready event…
+        </SizableText>
+      )}
+    </YStack>
+  );
+}