@multiplatform.one/node-graph 7.7.2

package/src/diagnostics/useGraphDiagnostics.ts

@@ -0,0 +1,85 @@
+/**
+ * Reads design §9.5's record out of the state that already exists.
+ *
+ * Nothing here is stored twice. The boot stage comes from the heartbeat's
+ * global, the version from the one `@xyflow` import site, the first error from
+ * the slot the DOM entry writes inline. What a caller passes in is only what
+ * lives in the canvas and nowhere else.
+ *
+ * THE GLOBALS ARE READ ON EVERY RENDER, and that is not an oversight to be
+ * memoized away. Both are written from EFFECTS — `stampBootStage` from the
+ * boot sequence, the error slot from the DOM entry's catch — so both land
+ * after the first render has already happened. A `useMemo` keyed on the input
+ * alone captures them at mount and never looks again, and the panel then
+ * reports `stage: none` on a boot that reached `faces`. Measured on the
+ * Storybook at task 2.6, before the spec existed to catch it.
+ *
+ * Two cheap property reads per render is the correct price. The memo below
+ * exists only to keep the RESULT's identity stable when nothing actually
+ * moved, so a consumer memoizing on it does not re-run every frame.
+ */
+
+import { useMemo } from "react";
+import { readBootElapsedMs, readBootStage } from "../dom/boot";
+import { xyflowVersion } from "../react-flow/xy";
+import { readGraphError } from "./lastError";
+import type { GraphDiagnostics, GraphDiagnosticsInput } from "./types";
+
+const noFaces: readonly [] = Object.freeze([]) as readonly [];
+const noDelivery: readonly [] = Object.freeze([]) as readonly [];
+
+export function useGraphDiagnostics(input: GraphDiagnosticsInput): GraphDiagnostics {
+  const {
+    renderer,
+    nodesMounted,
+    nodesInDocument,
+    culling,
+    renderMode,
+    scheme,
+    layoutRunner,
+    faces,
+    faceDelivery,
+  } = input;
+
+  const stage = readBootStage();
+  // Read every render for the same reason the stage is: it is written from an
+  // effect and would be captured as `null` by a memo keyed on the input alone.
+  const bootMs = readBootElapsedMs();
+  const error = readGraphError();
+  const errorPhase = error?.phase ?? null;
+  const errorMessage = error?.message ?? null;
+
+  return useMemo(
+    () => ({
+      stage,
+      bootMs,
+      renderer,
+      xyflowVersion,
+      layoutRunner: layoutRunner ?? "none",
+      faces: faces ?? noFaces,
+      faceDelivery: faceDelivery ?? noDelivery,
+      nodesMounted,
+      nodesInDocument,
+      culling,
+      renderMode,
+      scheme,
+      lastError:
+        errorPhase && errorMessage !== null ? { phase: errorPhase, message: errorMessage } : null,
+    }),
+    [
+      stage,
+      bootMs,
+      renderer,
+      layoutRunner,
+      faces,
+      faceDelivery,
+      nodesMounted,
+      nodesInDocument,
+      culling,
+      renderMode,
+      scheme,
+      errorPhase,
+      errorMessage,
+    ],
+  );
+}

package/src/dom/GraphDomLayout.spec.tsx

@@ -0,0 +1,56 @@
+/**
+ * The rules that decide whether the canvas is visible at all.
+ *
+ * Asserted as TEXT, like `domEntry.spec.ts`'s invariants and for the same
+ * reason: what this protects cannot fail in a way a render test would notice.
+ * A canvas with no height still mounts, still lays out, still answers the
+ * accessibility tree with every node in the right place, and still reports
+ * `stage: ready` over the bridge. It just paints nothing. There is no error to
+ * catch and no boundary to catch it.
+ */
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { GraphDomLayout, graphDomLayoutCss } from "./GraphDomLayout";
+
+describe("graphDomLayoutCss", () => {
+  /**
+   * Named one by one rather than snapshotted. A snapshot would go green on an
+   * edit that dropped a rule, because the snapshot would be updated with it.
+   */
+  it("gives html and body a height, so a percentage height resolves", () => {
+    expect(graphDomLayoutCss).toMatch(/html,\s*body\s*\{[^}]*height:\s*100%/);
+  });
+
+  it("gives Expo's #root mount point a height too", () => {
+    // The chain is html > body > #root > <React root div> > .mp-graph. A gap
+    // anywhere in it collapses everything below, so every step is named.
+    expect(graphDomLayoutCss).toMatch(/#root\s*\{[^}]*height:\s*100%/);
+    expect(graphDomLayoutCss).toMatch(/#root\s*>\s*div\s*\{[^}]*height:\s*100%/);
+  });
+
+  it("zeroes the body margin", () => {
+    // Not cosmetic: a UA's default 8px margin makes the document wider than the
+    // WebView, and React Flow's viewport then disagrees with the box being
+    // touched by exactly that much.
+    expect(graphDomLayoutCss).toMatch(/body\s*\{[^}]*margin:\s*0/);
+  });
+
+  it("carries no colour and no font", () => {
+    // Paint belongs to the var layer and to `graph.css`; this file is geometry.
+    expect(graphDomLayoutCss).not.toMatch(/color|background|font/i);
+  });
+});
+
+describe("GraphDomLayout", () => {
+  it("renders one style element carrying those rules", () => {
+    const { container } = render(<GraphDomLayout />);
+    const style = container.querySelector("style[data-mpo-graph-layout]");
+    expect(style).not.toBeNull();
+    expect(style?.textContent).toBe(graphDomLayoutCss);
+    // Nothing else. A layout sheet that rendered a box would change the layout
+    // it exists to fix.
+    expect(screen.queryByRole("presentation")).toBeNull();
+    expect(container.children).toHaveLength(1);
+  });
+});

package/src/dom/GraphDomLayout.tsx

@@ -0,0 +1,49 @@
+/**
+ * The four CSS rules without which the canvas is laid out and invisible.
+ *
+ * `NodeGraphWeb` sizes its root `width: 100%; height: 100%`, and React Flow's
+ * own `.react-flow` does the same. A percentage height resolves against the
+ * parent's height, and in an Expo DOM component the chain above it —
+ * `html > body > #root` — is a plain auto-height document. So `height: 100%`
+ * computes to `auto`, `.react-flow` collapses, and `@xyflow/react`'s
+ * `overflow: hidden` on the pane clips every node away.
+ *
+ * MEASURED ON BOTH PLATFORMS at tasks 2.7 and 2.8, and it is the failure that
+ * looks most like nothing being wrong. The iPhone 16e's accessibility tree
+ * carried all ten mounted node bodies with correct titles, correct three-column
+ * geometry, and heights that MOVED when the space knob was flipped — every
+ * signal a reader would take as proof — while the screen showed white. There
+ * was no fallback, because there was no error: boot ran through to `ready`, the
+ * canvas was fine, and it had nowhere to paint. emulator-5592 looked identical.
+ *
+ * The gate spike carried these rules and passed with them
+ * (`components/GraphCanvas.tsx`'s `LAYOUT_CSS`); the package never ported them,
+ * so this is the one part of the gate that was proven and then lost.
+ *
+ * It is a `<style>` element and nothing else, so it costs no layout and cannot
+ * move a node. Mounted by `NodeGraphDomInner` for the same reason `GraphFaces`
+ * is: inside the WebView is the only place either can do anything.
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * `#root` is Expo's own mount point for a DOM component, and `#root > div` is
+ * whatever React renders first inside it — neither is ours to name in markup,
+ * so they are named here.
+ *
+ * `margin: 0` on `body` matters as much as the heights: a UA's default 8px
+ * margin makes the canvas 16px wider than its WebView, and React Flow's pane
+ * then reports a viewport that does not match the box the user is touching.
+ */
+export const graphDomLayoutCss = [
+  "html, body { height: 100%; margin: 0; padding: 0; }",
+  "#root { height: 100%; }",
+  "#root > div { height: 100%; }",
+].join("\n");
+
+/** The sheet, and nothing else. Renders nothing where there is no DOM. */
+export function GraphDomLayout(): ReactNode {
+  if (typeof document === "undefined") return null;
+  return <style data-mpo-graph-layout="root-height">{graphDomLayoutCss}</style>;
+}

package/src/dom/NodeGraphDom.ts

@@ -0,0 +1,43 @@
+"use dom";
+
+/**
+ * The package's OWN `'use dom'` entry — the reference a consumer copies, and
+ * the shape `domEntry.spec.ts` guards.
+ *
+ * It is deliberately three lines of substance, because that is the whole point
+ * of design §9.3's amendment: the entry is APP-OWNED. Everything that makes a
+ * canvas work lives in `NodeGraphDomShell`, which this file renders; what an
+ * app adds is the two things that cannot cross the bridge — its Tamagui config
+ * and its schema registration — and this file, being inside the package, has
+ * neither. Mounted on its own it can therefore only report that the config is
+ * missing, which is why the native host draws `GraphFallback` naming that
+ * instead of mounting it (see `native/NodeGraph.native.tsx`).
+ *
+ * `'use dom'` is the FIRST statement and Metro reads the directive
+ * positionally, so a comment-first file still works while an import-first one
+ * silently becomes an ordinary module.
+ *
+ * The top-level imports are `react` and the shell, and nothing else. The shell
+ * itself imports only `react` and `expo/dom` at the top, so design §9.4 layer
+ * 3's real invariant — no top-level import of anything that can THROW — still
+ * holds through both files.
+ */
+
+import { createElement } from "react";
+import { NodeGraphDomShell } from "./NodeGraphDomShell";
+import type { NodeGraphDomProps } from "./NodeGraphDomShell";
+
+export type {
+  GraphDomCommandSlot,
+  GraphDomCommands,
+  NodeGraphDomHandle,
+  NodeGraphDomInnerProps,
+  NodeGraphDomOptions,
+  NodeGraphDomProps,
+  NodeGraphDomRealmProps,
+  NodeGraphDomShellProps,
+} from "./NodeGraphDomShell";
+
+export default function NodeGraphDom(props: NodeGraphDomProps) {
+  return createElement(NodeGraphDomShell, props);
+}