@multiplatform.one/node-graph 7.7.2

package/src/native/domEntryRegistry.spec.ts

@@ -0,0 +1,66 @@
+/**
+ * The registry that lets the PACKAGE's own stories reach an APP's `'use dom'`
+ * entry (design §9.3).
+ *
+ * Small surface, and every assertion here is about a rule that was decided
+ * rather than an implementation detail: last writer wins, `null` clears, and
+ * nothing is looked up by string. The last one is the point — a schema
+ * registers by id because `schemaId` is what crosses the bridge, and this does
+ * not, because a DOM entry never crosses it. It is a component handed from one
+ * Hermes module to another.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  clearNodeGraphDomEntry,
+  getNodeGraphDomEntry,
+  setNodeGraphDomEntry,
+} from "./domEntryRegistry";
+import type { NodeGraphDomEntry } from "./domEntryRegistry";
+
+const first = (() => null) as unknown as NodeGraphDomEntry;
+const second = (() => null) as unknown as NodeGraphDomEntry;
+
+afterEach(() => clearNodeGraphDomEntry());
+
+describe("the DOM entry registry", () => {
+  it("starts empty, which is what makes the host draw a fallback", () => {
+    // `NodeGraphNative` reads exactly this. Empty must mean "nothing supplied",
+    // never "something the package invented", or a consumer who forgot to
+    // register would get a canvas that cannot find their config.
+    expect(getNodeGraphDomEntry()).toBeNull();
+  });
+
+  it("returns the entry that was set", () => {
+    setNodeGraphDomEntry(first);
+    expect(getNodeGraphDomEntry()).toBe(first);
+  });
+
+  it("lets the last writer win", () => {
+    // An app has ONE entry. A second call is a hot reload replacing the first,
+    // not two apps competing, so it must not throw and must not keep the old.
+    setNodeGraphDomEntry(first);
+    setNodeGraphDomEntry(second);
+    expect(getNodeGraphDomEntry()).toBe(second);
+  });
+
+  it("clears with null as well as with the test seam", () => {
+    setNodeGraphDomEntry(first);
+    setNodeGraphDomEntry(null);
+    expect(getNodeGraphDomEntry()).toBeNull();
+    setNodeGraphDomEntry(first);
+    clearNodeGraphDomEntry();
+    expect(getNodeGraphDomEntry()).toBeNull();
+  });
+
+  it("holds the component itself, not a serializable stand-in", () => {
+    // The distinction from `registerGraphSchema`, and the reason this registry
+    // takes no id: a schema's `render` has to be reachable from INSIDE the DOM
+    // bundle, so it is looked up by a string that crosses the bridge. A DOM
+    // entry is used on the native side and never crosses anything, so identity
+    // is the whole contract.
+    setNodeGraphDomEntry(first);
+    expect(getNodeGraphDomEntry()).not.toEqual(second);
+    expect(typeof getNodeGraphDomEntry()).toBe("function");
+  });
+});

package/src/native/domEntryRegistry.ts

@@ -0,0 +1,45 @@
+/**
+ * Where an app parks its `'use dom'` entry so the PACKAGE's own stories can
+ * reach it (design §9.3).
+ *
+ * Same move as `registerGraphSchema`, one realm out. A schema registers by id
+ * because a `render` is a component and cannot be JSON; a DOM entry registers
+ * here because it is a component too — but this side of the bridge, so nothing
+ * is serialized and nothing is looked up by string. `NodeGraphNative` takes the
+ * entry as a prop first and reads this only when it was given none.
+ *
+ * It exists for exactly one shape of consumer: a story that lives inside this
+ * package and therefore cannot import the app's config. `public/*` may not
+ * depend on `@package/themes`, so `NodeGraph/NodeGraph` on device had no way to
+ * get a Tamagui config into the WebView at all — which is what it died of.
+ * `apps/storybook-expo` calls `setNodeGraphDomEntry` from its Storybook preview,
+ * and every story in the gallery then renders against the app's real config.
+ *
+ * An app with its own screens never needs this: it passes `domEntry` to
+ * `<NodeGraph />` and skips the global entirely.
+ */
+
+import type { ComponentType } from "react";
+import type { NodeGraphDomProps } from "../dom/NodeGraphDomShell";
+
+/** What a `'use dom'` module's default export looks like from the Hermes side. */
+export type NodeGraphDomEntry = ComponentType<NodeGraphDomProps>;
+
+let registered: NodeGraphDomEntry | null = null;
+
+/**
+ * Last writer wins, deliberately. An app has one entry; a second call is a hot
+ * reload replacing the first, not two apps competing.
+ */
+export function setNodeGraphDomEntry(entry: NodeGraphDomEntry | null): void {
+  registered = entry;
+}
+
+export function getNodeGraphDomEntry(): NodeGraphDomEntry | null {
+  return registered;
+}
+
+/** Test seam, matching `clearGraphSchemas`. */
+export function clearNodeGraphDomEntry(): void {
+  registered = null;
+}

package/src/native/graphChildren.spec.ts

@@ -0,0 +1,67 @@
+/**
+ * Task 6.1: the rule announces itself once, and never for a canvas that gave
+ * none.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  graphChildrenWarning,
+  resetGraphChildrenWarning,
+  warnOnGraphChildren,
+} from "./graphChildren";
+
+describe("warnOnGraphChildren", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    resetGraphChildrenWarning();
+    warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it("warns once, however many canvases are given children", () => {
+    expect(warnOnGraphChildren("a toolbar")).toBe(true);
+    expect(warnOnGraphChildren("another toolbar")).toBe(false);
+    expect(warnOnGraphChildren("a third")).toBe(false);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("names BOTH legal places, not only the ban", () => {
+    warnOnGraphChildren("x");
+    const message = String(warn.mock.calls[0][0]);
+    expect(message).toContain("graphRef");
+    expect(message).toContain("serializable option");
+    // The eleven commands, so the reader does not have to go and find them.
+    for (const command of ["relayout", "perfStart", "perfStop", "undo", "redo"]) {
+      expect(message).toContain(command);
+    }
+  });
+
+  it("says nothing for a canvas with no children", () => {
+    expect(warnOnGraphChildren(undefined)).toBe(false);
+    expect(warnOnGraphChildren(null)).toBe(false);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  /**
+   * `{condition && <Toolbar/>}` with a false condition is the correct code, and
+   * warning about it would train an author to ignore the warning.
+   */
+  it("says nothing for a collapsed conditional child", () => {
+    expect(warnOnGraphChildren(false)).toBe(false);
+    expect(warnOnGraphChildren([false, null, undefined])).toBe(false);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("still warns when only ONE of several children is real", () => {
+    expect(warnOnGraphChildren([false, "a toolbar", null])).toBe(true);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("exports the message so a story author can be pointed at it", () => {
+    expect(graphChildrenWarning).toMatch(/IGNORED/);
+  });
+});

package/src/native/graphChildren.ts

@@ -0,0 +1,62 @@
+/**
+ * The rule, as a warning a story author trips over once (milestone 6, task 6.1).
+ *
+ * `NodeGraph` on native accepts `children` and IGNORES them. That has been the
+ * written contract since milestone 2 and it is still right: React Flow's
+ * `<Background />` and `<Controls />` are components, a component cannot cross a
+ * JSON bridge, and accepting them is what lets ONE story file serve both
+ * platforms.
+ *
+ * What was wrong is that nothing said so at the moment it mattered. Measured
+ * across MPO-212, MPO-213 and MPO-214: every device-facing control and readout
+ * milestones 3-5 built was written as a child of `<NodeGraph>` — AutoLayout's
+ * Tidy button, the Perf200 sampler and its `window.__mpoPerf200`, the Lasso
+ * story's interceptor — and on device all of them silently vanished. Five
+ * pending acceptance criteria, one cause, and no error anywhere: the canvas
+ * painted, so nothing looked broken.
+ *
+ * So the contract now announces itself, ONCE per process, in dev only. Once
+ * because the alternative is a warning per canvas per render, which is how a
+ * console becomes something people stop reading. Dev only because in production
+ * the author is not there and the message is for the author.
+ *
+ * It names both legal places rather than only the ban. A rule that says what
+ * not to do teaches nothing at 2 a.m.
+ */
+
+let warned = false;
+
+/** Test seam. Nothing in the package calls it. */
+export function resetGraphChildrenWarning(): void {
+  warned = false;
+}
+
+export const graphChildrenWarning =
+  "[@multiplatform.one/node-graph] <NodeGraph> was given children on native, and they are " +
+  "IGNORED: the canvas renders inside a WebView and a React element cannot cross the bridge. " +
+  "Put the control OUTSIDE the canvas as a native sibling and drive it through `graphRef` " +
+  "(fitView, relayout, zoomTo, centerOn, setSelection, exportViewport, undo, redo, perfStart, " +
+  "perfStop, perfMark), reading state back from the events; or, if it has to be inside the " +
+  "canvas, express it as a serializable option so the DOM bundle renders it. Design 9.1.";
+
+/**
+ * True when it warned. `children` is checked for a value rather than for a
+ * count: `null`, `false` and `undefined` are all what a conditional child
+ * collapses to, and warning about `{cond && <X/>}` when `cond` is false would
+ * be a warning about code that is doing the right thing.
+ */
+export function warnOnGraphChildren(children: unknown): boolean {
+  if (warned) return false;
+  if (children === null || children === undefined || children === false) return false;
+  if (
+    Array.isArray(children) &&
+    children.every((child) => child === null || child === undefined || child === false)
+  ) {
+    return false;
+  }
+  if (process.env.NODE_ENV === "production") return false;
+  warned = true;
+  // oxlint-disable-next-line no-console -- the one sink a story author reads
+  console.warn(graphChildrenWarning);
+  return true;
+}

package/src/native/graphFallback.spec.ts

@@ -0,0 +1,49 @@
+/**
+ * What the fallback SAYS, which is the only thing a reader on a phone gets.
+ *
+ * The line these hold to account used to be "It never started, which usually
+ * means the bundle failed to parse." On emulator-5590, rebooted fresh, that is
+ * what the screen said — and nothing had failed to parse: the WebView was
+ * still starting and Retry rendered the canvas at once (MPO-211). A watchdog
+ * cannot tell a dead canvas from a slow one, so the wording must not claim it
+ * can.
+ */
+
+import { describe, expect, it } from "vitest";
+import { graphFallbackDetail } from "./GraphFallback.native";
+
+describe("graphFallbackDetail", () => {
+  it("names the stage boot reached, and what the wait cost", () => {
+    const detail = graphFallbackDetail("faces", true, "no-ready", 12000);
+    expect(detail).toContain('"faces"');
+    expect(detail).toContain("12000 ms");
+  });
+
+  it("does not blame a parse error for a timeout it cannot diagnose", () => {
+    const detail = graphFallbackDetail(null, false, "no-ready", 12000);
+    expect(detail).not.toMatch(/never started/);
+    expect(detail).toMatch(/slow cold start/);
+    // The other cause is still named — it is a real possibility, just not the
+    // likelier one, and a reader who retries twice needs to know what a second
+    // silence means.
+    expect(detail).toMatch(/fails? to parse/);
+    expect(detail).toContain("12000 ms");
+  });
+
+  it("still separates 'started and reported' from 'nothing came back'", () => {
+    expect(graphFallbackDetail(null, true, "no-ready", 4000)).toMatch(/reported a problem/);
+    expect(graphFallbackDetail(null, false, "no-ready", 4000)).toMatch(/Nothing came back/);
+  });
+
+  it("says no WebView was created when there is no DOM entry, and names no budget", () => {
+    const detail = graphFallbackDetail(null, false, "no-dom-entry", 12000);
+    expect(detail).toMatch(/no WebView was created/);
+    expect(detail).not.toContain("12000");
+  });
+
+  it("omits the budget entirely when none was waited", () => {
+    expect(graphFallbackDetail("flow", true, "render")).toBe(
+      'It reached "flow" and stopped there.',
+    );
+  });
+});

package/src/native/graphHandleRemount.spec.tsx

@@ -0,0 +1,189 @@
+/**
+ * The handle has to survive a REMOUNT, and until now it did not.
+ *
+ * This is the mechanism behind two of the m6 device pass's findings and it is
+ * one bug, readable in `expo/dom` rather than guessable from a screenshot.
+ * `expo/dom`'s `RawWebView` installs its imperative proxy **in the render
+ * body**, guarded by `ref.current == null`, and nothing ever nulls it again —
+ * React does not manage a ref a component assigns to itself. So on a keyed
+ * remount the OLD proxy is still sitting in the shared ref when the NEW
+ * instance renders, the guard is false, and the new WebView never publishes a
+ * proxy. The consumer keeps a handle wired to a torn-down WebView, whose
+ * `injectJavaScript` goes nowhere.
+ *
+ * Every command through `graphRef` is then silently dead while the canvas
+ * itself paints and pans perfectly, which is exactly what was measured:
+ *
+ *  - **Android `Tidy` never answers.** On BOTH emulators the canvas had come up
+ *    through the watchdog + Retry path, and Retry is `attempt + 1` — a keyed
+ *    remount. iOS never went through Retry and its Tidy answered. That is the
+ *    whole of the difference the device run could not separate.
+ *  - **Culling OFF returns no `perfReport`.** The toggle was a `key` on
+ *    `<NodeGraph>`, so the only way to reach culling-off was through a remount.
+ *    `perfStart` and `perfStop` both went to the dead proxy, and the readout sat
+ *    on `sampling…` because that state is the story's own.
+ *
+ * The fix is not to null the shared ref — the ordering makes that worse, since
+ * the new instance RENDERS before the old one's cleanup runs, so a null on
+ * unmount would wipe a proxy that had just been installed. The fix is to stop
+ * sharing: `NodeGraphNative` gives the DOM entry a ref object it owns, one per
+ * attempt, and publishes the consumer's `graphRef` through a stable forwarder.
+ * That is the same shape `NodeGraphWeb` already uses for `commandSlot`.
+ */
+
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { createElement, useRef } from "react";
+import type { Ref } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { NodeGraphDomProps } from "../dom/NodeGraphDomShell";
+import type { NodeGraphHandle } from "../react-flow/graphHandle";
+import { NodeGraphNative } from "./NodeGraph.native";
+
+afterEach(cleanup);
+
+const envelope = {
+  schemaVersion: 1,
+  knobs: {},
+  intent: null,
+  surface: { size: "md", density: "comfortable" },
+  scheme: "light",
+  themeName: "light",
+  prefersReducedMotion: true,
+  vars: {},
+  fonts: [],
+  pixelRatio: 1,
+  revision: 1,
+} as never;
+
+/** Which WebView instance a command landed in, in arrival order. */
+const landed: { instance: number; command: string }[] = [];
+
+/**
+ * `expo/dom`'s `RawWebView`, reduced to the one behaviour that matters.
+ *
+ * Copied from `expo@55`'s `src/dom/webview-wrapper.tsx`, which does exactly
+ * this: `if (ref != null && typeof ref === 'object' && ref.current == null) {
+ * ref.current = new Proxy(...) }`, in the render body, closing over that
+ * instance's own `webviewRef`. A stale proxy is not an error — it forwards into
+ * a WebView that is gone.
+ */
+let instances = 0;
+function FakeDomEntry(props: NodeGraphDomProps & { readonly ref?: Ref<NodeGraphHandle> }) {
+  const instance = useRef(0);
+  if (instance.current === 0) {
+    instances += 1;
+    instance.current = instances;
+  }
+  const mine = instance.current;
+  const ref = props.ref;
+  if (ref != null && typeof ref === "object" && ref.current == null) {
+    (ref as { current: NodeGraphHandle | null }).current = new Proxy({} as NodeGraphHandle, {
+      get(_target, property) {
+        return () => landed.push({ instance: mine, command: String(property) });
+      },
+    });
+  }
+  return createElement("div", {
+    "data-instance": mine,
+    "data-testid": `webview-${mine}`,
+  });
+}
+
+function element(graphRef: Ref<NodeGraphHandle>, readyTimeoutMs: number, key?: string) {
+  return createElement(NodeGraphNative, {
+    key,
+    documentJson: JSON.stringify({ version: 1, nodes: [], edges: [] }),
+    domEntry: FakeDomEntry as never,
+    envelope,
+    graphRef,
+    readyTimeoutMs,
+    rev: 0,
+    schemaId: "node-graph-demo",
+  });
+}
+
+/**
+ * Through the real providers: `GraphFallback` is Tamagui, and a Tamagui
+ * component with no `TamaguiProvider` above it throws `Missing theme.` — which
+ * is the same throw milestone 2 spent a device cycle on.
+ */
+function mount(graphRef: Ref<NodeGraphHandle>, readyTimeoutMs: number) {
+  return renderWithProviders(element(graphRef, readyTimeoutMs));
+}
+
+describe("the handle across a WebView remount", () => {
+  /**
+   * The Retry path, which is what both Android emulators came up through. A
+   * `relayout` after Retry has to reach the WebView that is on screen, not the
+   * one the watchdog gave up on.
+   */
+  it("reaches the NEW WebView after Retry, not the one that was torn down", async () => {
+    landed.length = 0;
+    instances = 0;
+    const graphRef = { current: null as NodeGraphHandle | null };
+    const view = mount(graphRef, 10);
+
+    expect(graphRef.current).not.toBeNull();
+    graphRef.current?.relayout();
+    expect(landed.at(-1)).toEqual({ instance: 1, command: "relayout" });
+
+    // The watchdog fires — a 10 ms budget and a fake entry that never reports
+    // `paint` or `ready` — and the fallback draws its Retry.
+    await screen.findByText("Retry");
+    // Widen the budget BEFORE the retry so the second attempt is not killed by
+    // the same watchdog while this test is looking at it. `readyTimeoutMs` is
+    // read every render, so the fallback stays up and Retry is still there.
+    view.rerender(element(graphRef, 60_000));
+    fireEvent.click(screen.getByText("Retry"));
+    await waitFor(() => expect(screen.queryByTestId("webview-2")).not.toBeNull());
+
+    graphRef.current?.relayout();
+    expect(
+      landed.at(-1),
+      "a Tidy after Retry landed in the WebView that had already been torn down",
+    ).toEqual({ instance: 2, command: "relayout" });
+  });
+
+  /**
+   * The culling-toggle path: the consumer remounts `<NodeGraph>` under a new
+   * key for its own reasons. `perfStart` and `perfStop` have to reach the
+   * canvas that is on screen, or the run reports nothing at all and the readout
+   * cannot tell that from a canvas that produced no frames.
+   */
+  it("reaches the NEW WebView after the consumer remounts under a new key", async () => {
+    landed.length = 0;
+    instances = 0;
+    const graphRef = { current: null as NodeGraphHandle | null };
+    const view = mount(graphRef, 60_000);
+    await waitFor(() => expect(graphRef.current).not.toBeNull());
+    graphRef.current?.perfStart("run");
+    expect(landed.at(-1)).toEqual({ instance: 1, command: "perfStart" });
+
+    view.rerender(element(graphRef, 60_000, "second"));
+
+    await waitFor(() => expect(screen.queryByTestId("webview-2")).not.toBeNull());
+    graphRef.current?.perfStop("run");
+    expect(landed.at(-1), "the Stop went to the WebView the toggle had already replaced").toEqual({
+      instance: 2,
+      command: "perfStop",
+    });
+  });
+
+  /**
+   * The consumer's ref never reaches `RawWebView`, which is what makes the two
+   * assertions above true rather than lucky. A ref object the entry writes into
+   * is a ref object only the entry may own.
+   */
+  it("never hands the consumer's own ref object to the DOM entry", async () => {
+    landed.length = 0;
+    instances = 0;
+    const graphRef = { current: null as NodeGraphHandle | null };
+    mount(graphRef, 60_000);
+    await waitFor(() => expect(graphRef.current).not.toBeNull());
+    // A proxy from `FakeDomEntry` answers every property with a recorder. The
+    // forwarder does not: reading a name it does not implement gives undefined.
+    expect((graphRef.current as unknown as Record<string, unknown>).notACommand).toBeUndefined();
+    expect(landed).toEqual([]);
+  });
+});