@multiplatform.one/node-graph 7.7.2

package/src/react-flow/flowAdapter.ts

@@ -0,0 +1,170 @@
+/**
+ * Document → React Flow arrays. Pure, so the mapping can be asserted without
+ * mounting anything.
+ *
+ * Two things happen here that cannot happen later:
+ *
+ *  - **Size seeding (design §5).** Every node carries `width` / `height` from
+ *    `graphNodeMeasure` BEFORE first paint, so React Flow's per-node
+ *    `ResizeObserver` CORRECTS a measurement rather than discovering one. On a
+ *    200-node knob flip that is the difference between 200 observer callbacks
+ *    resizing the world and 200 confirming it.
+ *  - **The edge marker.** `markerEnd` on the edge OBJECT, because React Flow
+ *    builds its `<marker>` defs from the edges array. Choosing it inside the
+ *    edge component is too late — measured in task 1.10, where the arrowheads
+ *    painted and the lines did not.
+ */
+
+import type {
+  EdgeKindDefs,
+  GraphDocument,
+  GraphEdgeOf,
+  GraphNodeOf,
+  GraphSchema,
+  NodeKindDefs,
+  PortSpec,
+} from "../model/index";
+import { nodeKindSpec, resolvePorts } from "../model/index";
+import { graphEdgeType } from "../edges/GraphEdge";
+import { edgeMarkerEnd } from "../edges/edgeStyle";
+import type { GraphNodeSizeKnob } from "../nodes/nodeMeasure";
+import { graphNodeMeasure } from "../nodes/nodeMeasure";
+import type { Edge, Node } from "./xy";
+
+/**
+ * What the registered node component receives as `props.data`.
+ *
+ * A type ALIAS, not an interface. React Flow constrains node data to
+ * `Record<string, unknown>`, and TypeScript gives an alias an implicit index
+ * signature while an interface has none — so `interface GraphFlowNodeData`
+ * does not satisfy `Node<T>` and every call site needs a cast. Same rule that
+ * governs the kind maps in `edges/edgeKinds.ts`, and it bites the same way.
+ */
+export type GraphFlowNodeData = {
+  readonly kind: string;
+  /** The consumer's own node payload. */
+  readonly data: unknown;
+  readonly ports: readonly PortSpec[];
+  /** `NodeKindSpec.intent`, so a kind can carry a semantic colour. */
+  readonly intent?: string;
+  readonly locked?: boolean;
+};
+
+export interface FlowMappingOptions {
+  /** The resolved `size` knob; picks the per-kind measure row. */
+  readonly size: GraphNodeSizeKnob;
+  /** `portSpacing({ coarsePointer })`, so the height floor matches the paint. */
+  readonly portSpacingPx: number;
+  /** One React Flow node type name, registered by `NodeGraphWeb`. */
+  readonly nodeType: string;
+}
+
+export function toFlowNodes<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  document: GraphDocument<N, E>,
+  schema: GraphSchema<N, E>,
+  options: FlowMappingOptions,
+): Node<GraphFlowNodeData>[] {
+  return document.nodes.map((node) => flowNode(node, schema, options));
+}
+
+function flowNode<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  node: GraphNodeOf<N>,
+  schema: GraphSchema<N, E>,
+  options: FlowMappingOptions,
+): Node<GraphFlowNodeData> {
+  const spec = nodeKindSpec(schema, node.kind);
+  const ports = resolvePorts(schema, node);
+  const measured = graphNodeMeasure({
+    size: options.size,
+    // `PortSpec` is structurally the `GraphNodePort` the measure table reads:
+    // it adds `index`, `dataType` and `arity`, none of which move a number.
+    ports,
+    portSpacingPx: options.portSpacingPx,
+    measure: spec?.measure,
+  });
+  return {
+    id: node.id,
+    type: options.nodeType,
+    position: node.position,
+    // `initialWidth` / `initialHeight`, NOT `width` / `height`.
+    //
+    // Measured in Chrome on `NodeGraph/NodeGraph → Main`: React Flow treats
+    // `width` / `height` as USER-SET dimensions and writes them as a hard CSS
+    // size, so a 72 px seed CLAMPED every node to 72 px and the Tamagui body —
+    // which is `overflow: visible` by §7.1 H6 — painted right through the
+    // bottom of its own frame and out of the pane. `initialWidth` is the
+    // dimension React Flow uses only until its ResizeObserver reports a real
+    // one, which is exactly design §5's "the observer corrects rather than
+    // discovers". A node the DOCUMENT sizes is a different thing: that is a
+    // user-set dimension and it stays `width` / `height`.
+    initialWidth: measured.width,
+    initialHeight: measured.minHeight,
+    width: node.size?.width,
+    height: node.size?.height,
+    parentId: node.parent,
+    draggable: node.locked ? false : undefined,
+    data: {
+      kind: node.kind,
+      data: node.data,
+      ports,
+      intent: spec?.intent,
+      locked: node.locked,
+    },
+  };
+}
+
+export function toFlowEdges<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  document: GraphDocument<N, E>,
+  schema: GraphSchema<N, E>,
+): Edge[] {
+  return document.edges.map((edge) => flowEdge(edge, schema));
+}
+
+function flowEdge<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  edge: GraphEdgeOf<E>,
+  schema: GraphSchema<N, E>,
+): Edge {
+  const spec = (schema.edges as Record<string, { appearance?: string } | undefined>)[edge.kind];
+  const appearance = spec?.appearance;
+  return {
+    id: edge.id,
+    // ONE registered type, switching on the model kind internally (design §4.4).
+    type: graphEdgeType,
+    source: edge.source.node,
+    sourceHandle: edge.source.port,
+    target: edge.target.node,
+    targetHandle: edge.target.port,
+    markerEnd: edgeMarkerEnd({ kind: edge.kind, appearance }),
+    data: { kind: edge.kind, appearance, label: edge.label },
+  };
+}
+
+/**
+ * Carry React Flow's own transient node flags across a re-derive.
+ *
+ * `selected` and `dragging` live in React Flow's array, not in the document —
+ * selecting a node is not an edit. Re-deriving from the document would drop
+ * them, so a click would deselect itself the moment anything committed.
+ */
+export function preserveFlowState(
+  next: Node<GraphFlowNodeData>[],
+  previous: readonly Node<GraphFlowNodeData>[],
+): Node<GraphFlowNodeData>[] {
+  if (previous.length === 0) return next;
+  const before = new Map(previous.map((node) => [node.id, node]));
+  return next.map((node) => {
+    const prior = before.get(node.id);
+    if (!prior) return node;
+    return {
+      ...node,
+      selected: prior.selected,
+      dragging: prior.dragging,
+      // A measured node keeps its measurement. The seed is a starting guess,
+      // and handing the guess back on every commit makes the observer
+      // re-measure the whole canvas each time anything is edited.
+      measured: prior.measured,
+      initialWidth: prior.measured?.width ?? node.initialWidth,
+      initialHeight: prior.measured?.height ?? node.initialHeight,
+    };
+  });
+}

package/src/react-flow/graphHandle.ts

@@ -0,0 +1,112 @@
+/**
+ * The imperative command surface, in a module NEITHER realm owns.
+ *
+ * Milestone 6's rule (design §9.1): a native consumer cannot put React children
+ * inside the canvas, so every control is either a native SIBLING driving the
+ * canvas through this handle, or it is rendered INSIDE the DOM bundle from
+ * serializable options. That makes the handle the load-bearing surface on both
+ * platforms, and it therefore may not live in `dom/`: `NodeGraphDomShell.ts`
+ * imports `expo/dom` at its top, and `NodeGraphWeb` — which now publishes the
+ * same handle through `graphRef` — must not carry that import into a web build
+ * even as an erased type edge.
+ *
+ * Every method returns void and takes JSON. That is not a style choice:
+ * `DOMImperativeFactory` is `{ [key: string]: (...args: JSONValue[]) => void }`,
+ * so an answer can only come back as an EVENT. `exportViewport`, `perfStop` and
+ * `relayout` each answer on the wire rather than by returning.
+ */
+
+/**
+ * Design §9.1's six, plus milestone 6's five.
+ *
+ * The five are here rather than on a second handle because a consumer holds one
+ * ref: a `perfStart` that lived somewhere else would be a second bridge, and
+ * the whole reason the wire is one channel is that a second one is a change to
+ * the bridge rather than to a type.
+ */
+export interface NodeGraphHandle {
+  fitView(): void;
+  /**
+   * Tidy. It emits `{ t: "layoutResult" }` when the engine answers.
+   *
+   * It was a documented NO-OP until milestone 6 — the comment said auto-layout
+   * was milestone 4 and the method was named early so the bridge surface would
+   * not have to change later. Milestone 4 then built the layout engine and
+   * never came back here, so `layoutRunner` read `none` on every device: not
+   * because the runner failed to resolve, but because nothing on a phone could
+   * ask it to run.
+   */
+  relayout(): void;
+  zoomTo(zoom: number): void;
+  centerOn(nodeId: string): void;
+  setSelection(ids: string[]): void;
+  exportViewport(): void;
+  undo(): void;
+  redo(): void;
+  /** Starts the frame sampler in the realm the canvas paints in. */
+  perfStart(label: string): void;
+  /** Stops it and emits `{ t: "perfReport" }`. */
+  perfStop(label: string): void;
+  /** Stamps an instant inside the run, so `relayoutGate` has a window to read. */
+  perfMark(label: string): void;
+  /**
+   * Puts the canvas at an exact viewport, with no animation.
+   *
+   * Five runs have to start from the same place or the median of five is the
+   * median of five experiments. `duration` is deliberately absent: an animated
+   * move is still moving when the sampler starts, and the first frames of every
+   * run would then measure the seek rather than the gesture.
+   */
+  setViewport(x: number, y: number, zoom: number): void;
+  /**
+   * A synthesised two-finger pinch, dispatched on the PANE — which is the
+   * element d3-zoom's touch listener is attached to, and which exists only in
+   * the realm the canvas paints in.
+   *
+   * It is here because the `mobile` MCP has no pinch verb at all (design
+   * §13.2), so on a device a pinch can only be produced from inside the
+   * WebView. That is also the technique that made the native spike's node-drag
+   * measurement unprovable, which is why a pinch row taken this way is reported
+   * SEPARATELY and flagged synthetic. On web the same row is taken with
+   * Chrome's own `Input.synthesizePinchGesture`, which is a browser-level
+   * gesture and a different thing.
+   */
+  synthPinch(scale: number, steps: number): void;
+}
+
+/** What the bridge component registers once the canvas is reachable. */
+export type GraphCommands = NodeGraphHandle;
+
+export interface GraphCommandSlot {
+  current: GraphCommands | null;
+}
+
+/**
+ * The command NAMES, as data.
+ *
+ * The two conditional types below are the compile-time half — a method added to
+ * `NodeGraphHandle` and not to this tuple, or a name here that is not a method,
+ * is a build error. It exists for the same reason `graphEventKinds` does: the
+ * shell has to forward every command by hand across `useDOMImperativeHandle`,
+ * and a forgotten one is a button that silently does nothing on a phone.
+ */
+export const graphCommandNames = [
+  "fitView",
+  "relayout",
+  "zoomTo",
+  "centerOn",
+  "setSelection",
+  "exportViewport",
+  "undo",
+  "redo",
+  "perfStart",
+  "perfStop",
+  "perfMark",
+  "setViewport",
+  "synthPinch",
+] as const;
+
+type DeclaredCommand = (typeof graphCommandNames)[number];
+type AssertNever<T extends never> = T;
+type _EveryMethodIsDeclared = AssertNever<Exclude<keyof NodeGraphHandle, DeclaredCommand>>;
+type _EveryDeclaredIsAMethod = AssertNever<Exclude<DeclaredCommand, keyof NodeGraphHandle>>;

package/src/react-flow/nodeCensus.spec.ts

@@ -0,0 +1,66 @@
+/**
+ * The node census — the source of design §9.5's `nodesMounted`.
+ *
+ * What these hold, and why each one is here rather than assumed:
+ *
+ *  - the count is of DISTINCT ids, because React mounts, unmounts and remounts
+ *    the same node under StrictMode and a naive `+1 / -1` would drift upward
+ *    every time it did;
+ *  - the release is idempotent, because an effect cleanup can run twice for the
+ *    same reason;
+ *  - subscribers are notified only on a real CHANGE, because the reader is a
+ *    `useSyncExternalStore` and a notification with no change is a render.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  mountedNodeCount,
+  registerMountedNode,
+  resetNodeCensus,
+  subscribeNodeCensus,
+} from "./nodeCensus";
+
+afterEach(resetNodeCensus);
+
+describe("the node census", () => {
+  it("counts distinct nodes, not registrations", () => {
+    const releaseA = registerMountedNode("a");
+    registerMountedNode("a");
+    registerMountedNode("b");
+    expect(mountedNodeCount()).toBe(2);
+    releaseA();
+    expect(mountedNodeCount()).toBe(1);
+  });
+
+  it("survives a release called twice, which an effect cleanup can do", () => {
+    const release = registerMountedNode("a");
+    registerMountedNode("b");
+    release();
+    release();
+    expect(mountedNodeCount()).toBe(1);
+  });
+
+  it("notifies a subscriber on a change and stays silent without one", () => {
+    let notifications = 0;
+    const unsubscribe = subscribeNodeCensus(() => {
+      notifications += 1;
+    });
+    registerMountedNode("a");
+    expect(notifications).toBe(1);
+    // The same id again is not a change, and a `useSyncExternalStore` reader
+    // would re-render for nothing.
+    registerMountedNode("a");
+    expect(notifications).toBe(1);
+    registerMountedNode("b");
+    expect(notifications).toBe(2);
+    unsubscribe();
+    registerMountedNode("c");
+    expect(notifications).toBe(2);
+  });
+
+  it("reads zero after a reset", () => {
+    registerMountedNode("a");
+    resetNodeCensus();
+    expect(mountedNodeCount()).toBe(0);
+  });
+});

package/src/react-flow/nodeCensus.ts

@@ -0,0 +1,69 @@
+/**
+ * How many node bodies React Flow actually has mounted, right now.
+ *
+ * WHY THIS EXISTS. Design §9.5's record calls the field `nodesMounted`, and
+ * until MPO-211 the DOM entry filled it with `document.nodes.length` — the
+ * number of nodes in the DOCUMENT, which is a different number whenever
+ * culling is on. On the demo document that is 12 against 10, and the gap is
+ * the whole reason AC 2.7's "renders 12 nodes" could not be read off a device
+ * screenshot: a panel reporting 12 while ten bodies are painted proves nothing
+ * about either number.
+ *
+ * So the two are reported separately now, and this module owns the harder one.
+ * `GraphNodeHost` is the ONE registered React Flow node type, so it mounts once
+ * per node React Flow decides to render and unmounts when culling drops one.
+ * Counting its instances counts exactly what is on screen, whatever body a
+ * consumer's schema renders — a DOM query for the package's own
+ * `data-graph-node` would miss a custom body, and a `.react-flow__node`
+ * selector is banned outside the token bridge (lint-conventions' GRAPH VARS
+ * COVERAGE).
+ *
+ * The register is a module global rather than React state because two
+ * different trees read it: the canvas's own diagnostics, and a story rendering
+ * `GraphDiagnostics` beside the canvas. It is per JS REALM, which is the right
+ * grain here — inside a WebView there is exactly one canvas, and that is the
+ * realm whose number crosses the bridge.
+ *
+ * `useSyncExternalStore` is the intended reader; `subscribeNodeCensus` and
+ * `mountedNodeCount` are its two halves.
+ */
+
+const mounted = new Set<string>();
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+/**
+ * Count a mounted node body. Returns the release, so a caller's effect cleanup
+ * is the whole of the unregistration.
+ *
+ * Keyed by node id rather than counted, so React's mount → unmount → mount in
+ * StrictMode, and a double-invoked effect, cannot inflate the number.
+ */
+export function registerMountedNode(id: string): () => void {
+  const had = mounted.has(id);
+  mounted.add(id);
+  if (!had) notify();
+  return () => {
+    if (mounted.delete(id)) notify();
+  };
+}
+
+export function mountedNodeCount(): number {
+  return mounted.size;
+}
+
+export function subscribeNodeCensus(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test seam. Never called by the canvas — an unmount releases its own id. */
+export function resetNodeCensus(): void {
+  mounted.clear();
+  notify();
+}