@multiplatform.one/node-graph 7.7.2

package/src/NodeGraph.native.spec.ts

@@ -0,0 +1,164 @@
+/**
+ * The native twin's build-shape invariants (MPO-211 task 2.7).
+ *
+ * These are regex and filesystem assertions rather than renders, for the same
+ * reason `domEntry.spec.ts` gives: the failures they guard against have no
+ * observable runtime. React Flow reaching the Hermes side is a module-eval
+ * throw on a phone with no console; the demo fixtures reaching the DOM entry
+ * chunk is 60 KB nobody notices until they measure. Neither shows up in a
+ * render test, and both are one import away at any time.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { demoGraphSchema } from "./react-flow/demoNodeBody";
+import { demoGraphSchemaId } from "./react-flow/fixtures";
+
+const srcDir = path.dirname(fileURLToPath(import.meta.url));
+
+function read(relative: string): string {
+  return fs.readFileSync(path.join(srcDir, relative), "utf8");
+}
+
+/**
+ * Static RUNTIME `import`/`export … from` specifiers.
+ *
+ * `import type` and `export type` are erased by the compiler, so they are not
+ * edges — `NodeGraphWebProps` is imported that way here on purpose, which is
+ * what keeps both platforms' prop shapes the same object instead of two lists
+ * that drift. A dynamic `import()` is not a static edge either.
+ */
+function staticSpecifiers(source: string): string[] {
+  const out: string[] = [];
+  const re =
+    /(?:^|\n)\s*(?:import|export)\s+(?!type\s)[^;]*?from\s*["']([^"']+)["']|(?:^|\n)\s*import\s*["']([^"']+)["']/g;
+  let match = re.exec(source);
+  while (match !== null) {
+    out.push((match[1] ?? match[2]) as string);
+    match = re.exec(source);
+  }
+  return out;
+}
+
+describe("the demo schema id", () => {
+  /**
+   * The id is the ONE string that crosses the bridge for the package's own
+   * story, so the constant and the schema it names cannot drift: renaming one
+   * without the other leaves the canvas reporting "no graph schema registered".
+   */
+  it("is the id the demo schema actually registers under", () => {
+    expect(demoGraphSchema().id).toBe(demoGraphSchemaId);
+  });
+});
+
+describe("NodeGraph.native.tsx", () => {
+  /**
+   * The whole reason the DOM host exists. React Flow runs in a browser; a
+   * static import here would put it, and its nested zustand, on the Hermes
+   * side, which is the MPO-74 failure class — a module-eval throw at boot with
+   * no console on the device to read it in.
+   */
+  it("never statically imports the canvas or @xyflow", () => {
+    const specifiers = staticSpecifiers(read("NodeGraph.native.tsx"));
+    const canvas = specifiers.filter(
+      (specifier) =>
+        specifier.includes("@xyflow") ||
+        specifier.endsWith("react-flow/xy") ||
+        specifier.endsWith("react-flow/NodeGraphWeb"),
+    );
+    expect(canvas).toEqual([]);
+  });
+
+  /**
+   * Type-only imports are erased, so `NodeGraphWebProps` costs nothing at
+   * runtime and is what keeps the two platforms' prop shapes provably the same
+   * object rather than two lists that drift.
+   */
+  it("takes its prop shape from the web component's, as a type", () => {
+    const source = read("NodeGraph.native.tsx");
+    expect(source).toMatch(
+      /import type \{ NodeGraphWebProps \} from "\.\/react-flow\/NodeGraphWeb"/,
+    );
+    expect(source).toMatch(/schemaId=\{schema\.id\}/);
+  });
+});
+
+/**
+ * Every module the Hermes side actually loads, following RELATIVE imports only.
+ *
+ * Metro prefers a `.native` twin, so this does too. Bare specifiers are not
+ * walked: they are somebody else's graph, and the question here is about ours.
+ */
+function reachableFrom(entry: string): Set<string> {
+  const seen = new Set<string>();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const file = queue.shift() as string;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    for (const specifier of staticSpecifiers(read(file))) {
+      if (!specifier.startsWith(".")) continue;
+      const base = path.join(path.dirname(file), specifier);
+      const candidate = [".native.tsx", ".native.ts", ".tsx", ".ts", "/index.ts"]
+        .map((extension) => `${base}${extension}`)
+        .find((option) => fs.existsSync(path.join(srcDir, option)));
+      if (candidate) queue.push(path.normalize(candidate));
+    }
+  }
+  return seen;
+}
+
+describe("what the Hermes side loads", () => {
+  /**
+   * THE LAYOUT ENGINE IS THE WEBVIEW'S, ALWAYS, and that is what makes the
+   * m6 Android Tidy finding answerable.
+   *
+   * `layout/runner.ts` caches its probed runner in MODULE SCOPE. That is safe
+   * only while the module lives in the realm that runs the layout — a WebView
+   * recreated by Retry is a new realm, so the module is re-evaluated and the
+   * runner is probed again from nothing. Reach the same module from the native
+   * host and the cache outlives the WebView instead: a Retry would then inherit
+   * the answer the dead realm probed, and "broken on Android" and "broken on a
+   * recreated canvas" would become genuinely inseparable rather than merely
+   * unseparated by one device run.
+   *
+   * The blob URL has the same shape — `URL.createObjectURL` registers it in the
+   * realm that spawned the worker — so this one edge protects both.
+   */
+  it("never reaches the layout runner, so a relayout is probed per realm", () => {
+    const reached = reachableFrom("NodeGraph.native.tsx");
+    // The walk is real, not an empty set that trivially passes the filter.
+    expect(reached.has("native/NodeGraph.native.tsx")).toBe(true);
+    expect(reached.has("model/index.ts")).toBe(true);
+    expect([...reached].filter((file) => file.startsWith("layout/"))).toEqual([]);
+  });
+});
+
+describe("NodeGraphDomInner.tsx", () => {
+  /**
+   * STATIC, and deliberately so after measuring. A second dynamic import makes
+   * Metro emit a shared `__common` chunk, and `expo export`'s html serializer
+   * then dies with `Asset not found: …/__common-<hash>.js` while exiting 0 and
+   * writing nothing. The chunk it bought was 5.6 KB.
+   */
+  it("reaches demoNodeBody through a static import, not a dynamic one", () => {
+    const source = read("dom/NodeGraphDomInner.tsx");
+    expect(staticSpecifiers(source).filter((s) => s.includes("demoNodeBody"))).toEqual([
+      "../react-flow/demoNodeBody",
+    ]);
+    expect(source).not.toMatch(/import\("\.\.\/react-flow\/demoNodeBody"\)/);
+  });
+
+  /**
+   * And only on a miss. Registering unconditionally would shadow a consumer who
+   * registered their own schema under the same id, which is a debugging session
+   * nobody would enjoy.
+   */
+  it("only supplies the demo schema when the lookup missed", () => {
+    const source = read("dom/NodeGraphDomInner.tsx");
+    expect(source).toMatch(/schemaId === demoGraphSchemaId \? \(demoGraphSchema\(\)/);
+    expect(source).toMatch(/getGraphSchema\(schemaId\)[\s\S]{0,80}\?\? demoSchema/);
+  });
+});

package/src/NodeGraph.native.tsx

@@ -0,0 +1,278 @@
+/**
+ * `NodeGraph` on native — the same NAME and the same PROPS a web consumer
+ * writes, resolving to the Expo DOM host instead of the canvas.
+ *
+ * The split happens HERE, at a `.native.tsx` twin, and never at a `.web.*` one.
+ * MPO-192's ruling: a `.web.ts` twin replaces the shared file in One's Vite
+ * client build exactly as it does under Metro, which is how the config reader
+ * lost `import.meta.env` in the first place.
+ *
+ * WHY THIS FILE GREW A BODY (MPO-211 task 2.7). It used to forward straight to
+ * `NodeGraphNative`, whose props are the BRIDGE's — `documentJson`, `rev`,
+ * `envelope`, `schemaId` — because that is what can be JSON. That is the right
+ * shape for the host and the wrong shape for a consumer: a story or a screen
+ * that writes `<NodeGraph schema={schema} defaultDocument={doc} />` and works on
+ * web got a DOM component with `documentJson: undefined` on device, and the
+ * watchdog drew the fallback. Found by running it, not by reading it.
+ *
+ * So the serialization lives here, in the one file whose whole job is to be the
+ * same component on both platforms:
+ *
+ *  - the document is serialized once and re-serialized only when the consumer
+ *    hands down a new one;
+ *  - `rev` is stamped here, and the canvas's echo gate refuses the document it
+ *    caused, so a drag does not fight itself (`wire.ts` holds the gate);
+ *  - a commit comes back as commands, is applied to the host's copy with the
+ *    package's own `applyCommand`, and is handed to `onDocumentChange` with the
+ *    same `(document, command)` signature `NodeGraphWeb` uses;
+ *  - the knob envelope is captured from the LIVE native theme by
+ *    `useKnobEnvelope`, which is what makes a knob flip in the on-device theme
+ *    addon reach nodes rendering inside a WebView.
+ *
+ * `children` is accepted and ignored. React Flow's `<Background />` and
+ * `<Controls />` are components, and a component cannot cross the bridge; the
+ * canvas mounts its own chrome from `options`. Accepting them keeps ONE story
+ * file for both platforms, which is the point.
+ *
+ * MILESTONE 6 MAKES THAT CONTRACT AUDIBLE. It was true, correct and silent, and
+ * silence cost five acceptance criteria: every device-facing control milestones
+ * 3-5 built was written as a child here, so on device AutoLayout had no Tidy
+ * button, Perf200 had no sampler and `window.__mpoPerf200` appeared zero times
+ * in the emitted bundle. Nothing threw. The canvas painted. So a canvas given
+ * children now warns ONCE in dev, naming the two places a control may legally
+ * go: a native SIBLING on `graphRef`, or a serializable option the DOM bundle
+ * renders from. `native/graphChildren.ts` holds the message.
+ */
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { ReactNode, Ref } from "react";
+import { useKnobEnvelope } from "./knobs/useKnobEnvelope";
+import type { EdgeKindDefs, GraphCommand, GraphDocument, NodeKindDefs } from "./model/index";
+import { applyCommand, serializeDocument } from "./model/index";
+import { warnOnGraphChildren } from "./native/graphChildren";
+import { NodeGraphNative } from "./native/NodeGraph.native";
+import type { NodeGraphDomOptions } from "./dom/NodeGraphDomShell";
+import type { GraphEventWire, PerfReportWire } from "./dom/wire";
+import type { GraphDiagnosticsWire } from "./dom/wire";
+import type { NodeGraphHandle } from "./react-flow/graphHandle";
+import type { NodeGraphDomEntry } from "./native/domEntryRegistry";
+import type { NodeGraphWebProps } from "./react-flow/NodeGraphWeb";
+
+/**
+ * The web props, minus the four that are web-only by construction.
+ *
+ * `nodeTypes` and `className` are a React Flow registry and a DOM class, and
+ * `onConnectionRefused` takes a verdict object the bridge reports as a code and
+ * a message instead. Omitting them rather than accepting-and-dropping means a
+ * consumer who needs one fails to compile on native rather than at runtime.
+ */
+export type NodeGraphProps<
+  N extends NodeKindDefs = NodeKindDefs,
+  E extends EdgeKindDefs = EdgeKindDefs,
+> = Omit<
+  NodeGraphWebProps<N, E>,
+  "nodeTypes" | "className" | "onConnectionRefused" | "children"
+> & {
+  /** Accepted so one story file serves both platforms. Never rendered here. */
+  readonly children?: ReactNode;
+  /** Refusals arrive over the wire as a code and a message, not as a verdict. */
+  readonly onConnectionRefused?: (code: string, message: string) => void;
+  /** Overridable so a test can make the watchdog fire without waiting four seconds. */
+  readonly readyTimeoutMs?: number;
+  /**
+   * The app's `'use dom'` entry (design §9.3). Native only: on web there is no
+   * bridge and `NodeGraphWebProps` has no such prop, so a screen that passes it
+   * fails to compile for web rather than silently ignoring it.
+   *
+   * A story in THIS package cannot supply one — `public/*` may not import an
+   * app's config — so the Kitchen Sink registers the app's entry once through
+   * `setNodeGraphDomEntry` and every story picks it up.
+   */
+  readonly domEntry?: NodeGraphDomEntry;
+  /**
+   * Design 9.5's record, as the canvas inside the WebView measured it.
+   *
+   * NATIVE ONLY, and deliberately absent from `NodeGraphWebProps`: on web
+   * there is no bridge and no `ready` event to carry one, so a screen that
+   * passes this fails to compile for web rather than silently never firing.
+   * The web twin of a caller reads `useGraphDiagnostics` directly instead.
+   *
+   * It exists because the DOM half of AC-3 has nowhere else to land. `faces`
+   * carries design 6.3's corrupted-first-family probe, run INSIDE the WebView
+   * against a rendered node title, and `nodesMounted` / `nodesInDocument` are
+   * the only honest source for how many nodes actually painted — a story on the
+   * Hermes side can measure neither. `NodeGraph/Diagnostics` -> `Live` renders
+   * this straight into `GraphDiagnostics`.
+   */
+  readonly onReady?: (diagnostics: GraphDiagnosticsWire) => void;
+  /**
+   * The handle a native SIBLING drives the canvas with (milestone 6, §9.1).
+   *
+   * The same eleven commands `NodeGraphWeb` publishes through its own
+   * `graphRef`, so a toolbar written once works on both platforms. This is the
+   * legal replacement for the children this component drops, and the warning it
+   * emits names it.
+   */
+  readonly graphRef?: Ref<NodeGraphHandle>;
+  /**
+   * Arms design §7.3's long press INSIDE the WebView, where the pane element
+   * exists. Serializable, because it crosses the bridge as an option.
+   */
+  readonly longPressLasso?: boolean;
+  /**
+   * A tidy finished: the runner that produced it and its engine milliseconds.
+   *
+   * A REJECTED relayout arrives here too, carrying `error` with `runner: "none"`
+   * and `ms: 0`. Before the m6 device pass a rejection answered with nothing at
+   * all, which is why a stuck "laying out…" could not be told apart from a Tidy
+   * that never reached the canvas.
+   */
+  readonly onLayoutResult?: (result: {
+    runner: string;
+    ms: number;
+    nodeCount: number;
+    error?: string;
+  }) => void;
+  /** A perf run finished. A REJECTED run arrives here too — see `PerfReportWire`. */
+  readonly onPerfReport?: (report: PerfReportWire) => void;
+  /** The long press armed, selected, or was cancelled. */
+  readonly onLasso?: (event: Extract<GraphEventWire, { t: "lasso" }>) => void;
+  /** The canvas painted its first frame. The watchdog's real clock (§9.4). */
+  readonly onPaint?: (bootMs: number | null) => void;
+  /**
+   * EVERY event, undecomposed — the same prop name and the same union
+   * `NodeGraphWeb` takes on web.
+   *
+   * It exists so ONE story file can serve both platforms, which is the point of
+   * this whole component. The typed callbacks above are what a real screen
+   * wants; a story that has to read a runner on a phone and on a desktop wants
+   * one name that means the same thing in both places.
+   */
+  readonly onGraphEvent?: (event: GraphEventWire) => void;
+};
+
+export function NodeGraph<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  props: NodeGraphProps<N, E>,
+) {
+  const {
+    coarsePointer,
+    defaultDocument,
+    domEntry,
+    fitView,
+    graphRef,
+    intent,
+    interactionMode,
+    knobs,
+    longPressLasso,
+    onConnectionRefused,
+    onDocumentChange,
+    onGraphEvent,
+    onLasso,
+    onLayoutResult,
+    onlyRenderVisibleElements,
+    onPaint,
+    onPerfReport,
+    onReady,
+    overviewZoom,
+    presetName,
+    readOnly,
+    readyTimeoutMs,
+    schema,
+  } = props;
+
+  // Once per process, in dev. See `native/graphChildren.ts` for why a contract
+  // that was already written down needed to start speaking.
+  warnOnGraphChildren(props.children);
+
+  // The host's own copy. Controlled beats uncontrolled, exactly as on web; the
+  // seed is read once because a `defaultDocument` that changes identity every
+  // render is a story writing an object literal, not a new document.
+  const seed = useRef(props.document ?? defaultDocument ?? null);
+  const [held, setHeld] = useState<GraphDocument<N, E> | null>(seed.current);
+  const document = props.document ?? held;
+
+  // `rev` is the host's, and it only ever climbs. Every commit the canvas
+  // proposes arrives as `rev + 1`; stamping it here is what lets the canvas
+  // refuse its own echo on the way back in.
+  const [rev, setRev] = useState(0);
+
+  const documentJson = useMemo(
+    () =>
+      document
+        ? serializeDocument(document)
+        : serializeDocument({ version: 1, nodes: [], edges: [] }),
+    [document],
+  );
+
+  const envelope = useKnobEnvelope({
+    intent,
+    knobs,
+    pointer: coarsePointer ? "coarse" : undefined,
+    presetName,
+  });
+
+  const options = useMemo<NodeGraphDomOptions>(
+    () => ({
+      coarsePointer,
+      fitView,
+      interactionMode,
+      longPressLasso,
+      onlyRenderVisibleElements,
+      overviewZoom,
+      readOnly,
+    }),
+    [
+      coarsePointer,
+      fitView,
+      interactionMode,
+      longPressLasso,
+      onlyRenderVisibleElements,
+      overviewZoom,
+      readOnly,
+    ],
+  );
+
+  const onCommit = useCallback(
+    (nextRev: number, commandsJson: string) => {
+      setRev(nextRev);
+      let commands: GraphCommand<N, E>[];
+      try {
+        commands = JSON.parse(commandsJson) as GraphCommand<N, E>[];
+      } catch {
+        // A commit this build cannot parse means the DOM bundle and this host
+        // are out of step. The canvas still holds the real document; dropping
+        // the host's mirror is better than corrupting it.
+        return;
+      }
+      setHeld((current) => {
+        let next = current ?? seed.current;
+        if (!next) return current;
+        for (const command of commands) next = applyCommand(next, command);
+        for (const command of commands) onDocumentChange?.(next, command);
+        return next;
+      });
+    },
+    [onDocumentChange],
+  );
+
+  return (
+    <NodeGraphNative
+      documentJson={documentJson}
+      domEntry={domEntry}
+      envelope={envelope}
+      graphRef={graphRef}
+      onCommit={onCommit}
+      onConnectionRefused={onConnectionRefused}
+      onGraphEvent={onGraphEvent}
+      onLasso={onLasso}
+      onLayoutResult={onLayoutResult}
+      onPaint={onPaint}
+      onPerfReport={onPerfReport}
+      onReady={onReady}
+      options={options}
+      readyTimeoutMs={readyTimeoutMs}
+      rev={rev}
+      schemaId={schema.id}
+    />
+  );
+}

package/src/NodeGraph.tsx

@@ -0,0 +1,27 @@
+/**
+ * `NodeGraph` — the one name a consumer imports.
+ *
+ * On web it IS `NodeGraphWeb`. On native it becomes the `expo/dom` host in
+ * milestone 2, which renders this same web canvas inside a WebView; the split
+ * happens at `src/index.native.ts`, never at a `.web.*` twin (MPO-192: one web
+ * build, and a `.web.ts` twin is invisible to it).
+ *
+ * The re-export is a real component rather than `export { NodeGraphWeb as
+ * NodeGraph }` so the name in a React devtools tree, an error boundary and a
+ * profiler flame is the name the consumer wrote.
+ */
+
+import type { EdgeKindDefs, NodeKindDefs } from "./model/index";
+import { NodeGraphWeb } from "./react-flow/NodeGraphWeb";
+import type { NodeGraphWebProps } from "./react-flow/NodeGraphWeb";
+
+export type NodeGraphProps<
+  N extends NodeKindDefs = NodeKindDefs,
+  E extends EdgeKindDefs = EdgeKindDefs,
+> = NodeGraphWebProps<N, E>;
+
+export function NodeGraph<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  props: NodeGraphProps<N, E>,
+) {
+  return <NodeGraphWeb {...props} />;
+}