@multiplatform.one/node-graph 7.7.2

package/src/react-flow/GraphNodeHost.tsx

@@ -0,0 +1,101 @@
+/**
+ * The ONE registered React Flow node type.
+ *
+ * Same shape as the edge layer (design §4.4): one registration, switching on
+ * the model kind internally, so the node component count stays at one however
+ * many kinds a schema declares. It looks the kind up in the schema and renders
+ * that kind's own `render` — the consumer's Tamagui body — which is what keeps
+ * nodes Tamagui rather than a fixed shape this package chose.
+ *
+ * `renderMode` is computed HERE, from the live zoom, and handed down as a prop
+ * (design §5). Every mode keeps the same box: below `overviewZoom` children
+ * fade, they do not unmount, because React Flow 12 installs a per-node
+ * `ResizeObserver` and a height-changing LOD would re-measure every node on
+ * every zoom tick and move every edge endpoint with it.
+ */
+
+import { createContext, memo, useContext, useEffect, useMemo } from "react";
+import type { EdgeKindDefs, GraphSchema, NodeKindDefs, PortSpec } from "../model/index";
+import { nodeKindSpec } from "../model/index";
+import { lodForZoom } from "../nodes/lod";
+import type { GraphFlowNodeData } from "./flowAdapter";
+import { registerMountedNode } from "./nodeCensus";
+import { useStore } from "./xy";
+import type { NodeProps } from "./xy";
+
+export interface GraphHostValue {
+  readonly schema: GraphSchema<NodeKindDefs, EdgeKindDefs>;
+  /** Below this zoom the graph draws in `overview` mode (design §5). */
+  readonly overviewZoom: number;
+  /** Touch surface: fields are display-only and taps route to the sheet. */
+  readonly coarsePointer: boolean;
+  readonly readOnly: boolean;
+  readonly setNodeData: (id: string, patch: Record<string, unknown>) => void;
+}
+
+const GraphHostContext = createContext<GraphHostValue | null>(null);
+
+export const GraphHostProvider = GraphHostContext.Provider;
+
+export function useGraphHost(): GraphHostValue {
+  const value = useContext(GraphHostContext);
+  if (!value) {
+    throw new Error(
+      "[@multiplatform.one/node-graph] a graph node rendered outside <NodeGraph>. " +
+        "The node type is registered by the canvas and cannot be used on its own.",
+    );
+  }
+  return value;
+}
+
+function GraphNodeHostComponent({ id, data, selected, dragging }: NodeProps) {
+  const host = useGraphHost();
+  const nodeData = data as unknown as GraphFlowNodeData;
+  const zoom = useStore((state) => state.transform[2]);
+  const spec = nodeKindSpec(host.schema, nodeData.kind);
+
+  /**
+   * The census, design 9.5's `nodesMounted` (MPO-211).
+   *
+   * This is the only component React Flow mounts once per RENDERED node, so
+   * it is the only place the number is knowable — with `onlyRenderVisibleElements`
+   * on, the store still holds every node while only the visible ones mount, and
+   * the document holds more still. Registering here counts what is painted,
+   * whatever body the consumer's schema renders.
+   *
+   * Before the early return: the unknown-kind branch below still mounted a node.
+   */
+  useEffect(() => registerMountedNode(id), [id]);
+
+  const setData = useMemo(
+    () => (patch: Record<string, unknown>) => host.setNodeData(id, patch),
+    [host, id],
+  );
+
+  if (!spec) {
+    // A kind the schema does not declare. Loud rather than blank: a node that
+    // silently renders nothing is the hardest kind of missing thing to find.
+    return (
+      <div data-graph-node-unknown={nodeData.kind} role="alert">
+        {`unknown node kind: ${nodeData.kind}`}
+      </div>
+    );
+  }
+
+  const Render = spec.render;
+  return (
+    <Render
+      id={id}
+      data={nodeData.data}
+      selected={selected ?? false}
+      dragging={dragging ?? false}
+      renderMode={lodForZoom(zoom, host.overviewZoom)}
+      readOnlyFields={host.readOnly || host.coarsePointer}
+      ports={nodeData.ports as readonly PortSpec[]}
+      measure={spec.measure}
+      setData={setData as never}
+    />
+  );
+}
+
+export const GraphNodeHost = memo(GraphNodeHostComponent);

package/src/react-flow/GraphPaintProbe.spec.tsx

@@ -0,0 +1,116 @@
+/**
+ * Task 6.6. The paint marker fires ONCE, after two frames, and never twice.
+ *
+ * It is the clock the native watchdog is measured against, so the two things
+ * that matter are both timing claims a browser check cannot make: that it waits
+ * for the frame AFTER the one this mount produced, and that a re-render does
+ * not re-arm it. A second `paint` would be harmless on native (the watchdog is
+ * already cleared) and misleading in a log, which is exactly the kind of defect
+ * that survives a screenshot.
+ */
+
+import { render, cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GraphPaintProbe } from "./GraphPaintProbe";
+
+afterEach(cleanup);
+
+/** A hand-cranked rAF, so "the frame after" is a thing this spec can count. */
+function stubFrames() {
+  const queue: ((t: number) => void)[] = [];
+  const original = {
+    request: globalThis.requestAnimationFrame,
+    cancel: globalThis.cancelAnimationFrame,
+  };
+  globalThis.requestAnimationFrame = ((cb: (t: number) => void) => {
+    queue.push(cb);
+    return queue.length;
+  }) as typeof globalThis.requestAnimationFrame;
+  globalThis.cancelAnimationFrame = (() => undefined) as typeof globalThis.cancelAnimationFrame;
+  return {
+    /** Run everything queued right now, and only that. */
+    tick(t = 0) {
+      const due = queue.splice(0, queue.length);
+      for (const cb of due) cb(t);
+    },
+    pending: () => queue.length,
+    restore() {
+      globalThis.requestAnimationFrame = original.request;
+      globalThis.cancelAnimationFrame = original.cancel;
+    },
+  };
+}
+
+describe("GraphPaintProbe", () => {
+  it("waits for the SECOND frame, because the first is scheduled before the paint", () => {
+    const frames = stubFrames();
+    const onPaint = vi.fn();
+    try {
+      render(<GraphPaintProbe onPaint={onPaint} />);
+      expect(onPaint, "fired before any frame ran").not.toHaveBeenCalled();
+      frames.tick(16);
+      expect(
+        onPaint,
+        "fired on the frame this mount produced, not the one after",
+      ).not.toHaveBeenCalled();
+      frames.tick(32);
+      expect(onPaint).toHaveBeenCalledTimes(1);
+    } finally {
+      frames.restore();
+    }
+  });
+
+  it("fires once, and a re-render does not re-arm it", () => {
+    const frames = stubFrames();
+    const onPaint = vi.fn();
+    try {
+      const view = render(<GraphPaintProbe onPaint={onPaint} />);
+      frames.tick(16);
+      frames.tick(32);
+      expect(onPaint).toHaveBeenCalledTimes(1);
+      view.rerender(<GraphPaintProbe onPaint={onPaint} />);
+      frames.tick(48);
+      frames.tick(64);
+      expect(onPaint).toHaveBeenCalledTimes(1);
+    } finally {
+      frames.restore();
+    }
+  });
+
+  it("reads the callback through a ref, so a fresh arrow each render is free", () => {
+    const frames = stubFrames();
+    const first = vi.fn();
+    const second = vi.fn();
+    try {
+      const view = render(<GraphPaintProbe onPaint={first} />);
+      view.rerender(<GraphPaintProbe onPaint={second} />);
+      frames.tick(16);
+      frames.tick(32);
+      // The LATEST callback, and exactly one call between the two of them —
+      // rebuilding the probe on a new identity would be a second effect and a
+      // second marker.
+      expect(first).not.toHaveBeenCalled();
+      expect(second).toHaveBeenCalledTimes(1);
+    } finally {
+      frames.restore();
+    }
+  });
+
+  /**
+   * A canvas can mount where there is no rAF at all — a spec under happy-dom
+   * with the global removed, or a headless runtime. Firing synchronously is
+   * honest there: the tree rendered and there is no compositor to wait for.
+   */
+  it("fires synchronously where there is no requestAnimationFrame", () => {
+    const original = globalThis.requestAnimationFrame;
+    // oxlint-disable-next-line no-explicit-any -- deleting a global for one assertion
+    (globalThis as any).requestAnimationFrame = undefined;
+    const onPaint = vi.fn();
+    try {
+      render(<GraphPaintProbe onPaint={onPaint} />);
+      expect(onPaint).toHaveBeenCalledTimes(1);
+    } finally {
+      globalThis.requestAnimationFrame = original;
+    }
+  });
+});

package/src/react-flow/GraphPaintProbe.tsx

@@ -0,0 +1,65 @@
+/**
+ * The `paint` marker — milestone 6, design §9.4.
+ *
+ * `ready` is deliberately LATE. The canvas waits `graphReadySettleMs` (1800)
+ * before stamping it so the diagnostics it carries are filled in rather than
+ * reporting `nodesMounted: 0` and every face `pending`. That was the right fix
+ * for the diagnostics and the wrong clock for the watchdog: on emulator-5592
+ * the 12 s budget fired on a canvas that was ALREADY on screen, and Retry did
+ * not recover emulator-5590. Ready and paint had come apart, and the watchdog
+ * was timing the one that is allowed to be slow.
+ *
+ * So this is the early half, and it carries nothing but the fact that pixels
+ * exist. Two `requestAnimationFrame`s, not one: the first is scheduled before
+ * the browser paints the frame this mount produced, the second runs after it.
+ * A single frame would report "about to paint", which is the claim that was
+ * already being made by `ready` and is not the one the watchdog needs.
+ *
+ * It is a child of `ReactFlow`, so mounting means React Flow rendered. It
+ * renders `null` and fires exactly once per mount.
+ */
+
+import { useEffect, useRef } from "react";
+
+export interface GraphPaintProbeProps {
+  /** Fired once, on the frame after React Flow's first render. */
+  readonly onPaint: () => void;
+}
+
+export function GraphPaintProbe({ onPaint }: GraphPaintProbeProps) {
+  const fired = useRef(false);
+  // Read through a ref so a caller rebuilding the callback each render does not
+  // re-arm the probe — the whole point is that it fires once.
+  const latest = useRef(onPaint);
+  latest.current = onPaint;
+
+  useEffect(() => {
+    if (fired.current) return;
+    let cancelled = false;
+    // A canvas can mount where there is no rAF at all (a spec under happy-dom).
+    // Firing synchronously there is honest: the tree rendered, and there is no
+    // compositor to wait for.
+    const raf = globalThis.requestAnimationFrame;
+    if (typeof raf !== "function") {
+      fired.current = true;
+      latest.current();
+      return;
+    }
+    let inner: number | null = null;
+    const outer = raf(() => {
+      if (cancelled) return;
+      inner = raf(() => {
+        if (cancelled || fired.current) return;
+        fired.current = true;
+        latest.current();
+      });
+    });
+    return () => {
+      cancelled = true;
+      globalThis.cancelAnimationFrame?.(outer);
+      if (inner !== null) globalThis.cancelAnimationFrame?.(inner);
+    };
+  }, []);
+
+  return null;
+}

package/src/react-flow/GraphZoomVar.tsx

@@ -0,0 +1,48 @@
+/**
+ * `--mpo-graph-zoom` on the canvas root — milestone 6, design §7.1 H7.
+ *
+ * The 44 px port hit region is an `::after` pseudo-element, and every element
+ * a node owns lives INSIDE `.react-flow__viewport`, whose transform carries the
+ * pan and the zoom. So a region declared 44 px renders 44 × zoom SCREEN px, and
+ * on device that was measured rather than reasoned about: on the iPhone 16e at
+ * zoom 0.377 the region was 16.6 pt wide — a half-width of 8.3 pt against a
+ * demanded 18 — and a tap 18 pt off the painted centre panned the canvas
+ * instead of grabbing the port. The same miss on emulator-5592 at zoom 0.397.
+ *
+ * The fix is to counter-scale the region by 1/zoom, which needs the zoom in
+ * CSS. This writes it, and it writes it IMPERATIVELY: `style.setProperty` on a
+ * ref rather than a React prop, because a viewport change is a per-frame event
+ * during a pinch and re-rendering the canvas tree 120 times a second to move a
+ * custom property would cost more than the region is worth.
+ *
+ * The component itself still re-renders per zoom frame — `useStore` is a
+ * subscription — but it renders `null` and has no children, so the cost is one
+ * function call and a store comparison. The SELECTOR reads only `transform[2]`,
+ * so a pan (which changes `transform[0]` and `[1]`) wakes nothing here.
+ */
+
+import { useEffect } from "react";
+import { useStore } from "./xy";
+
+/** The property name, in one place. `css/graph.css` reads it. */
+export const graphZoomVarName = "--mpo-graph-zoom";
+
+export interface GraphZoomVarProps {
+  readonly rootRef: { current: HTMLElement | null };
+}
+
+export function GraphZoomVar({ rootRef }: GraphZoomVarProps) {
+  const zoom = useStore((state) => state.transform[2]);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    // A zoom of 0 is not a thing React Flow produces, but dividing by one in
+    // CSS is silent and produces an infinitely large hit region, which would
+    // swallow the whole canvas. The floor is the same `minZoom` the canvas
+    // defaults to, so the region can never grow past what that zoom allows.
+    root.style.setProperty(graphZoomVarName, String(zoom > 0 ? zoom : 1));
+  }, [rootRef, zoom]);
+
+  return null;
+}

package/src/react-flow/LassoOverlay.tsx

@@ -0,0 +1,59 @@
+/**
+ * The long-press marquee (design §7.3 L4, task 3.7).
+ *
+ * One absolutely-positioned div, painted from `--xy-selection-background-color`
+ * and `--xy-selection-border` — the SAME two variables React Flow's own
+ * `.react-flow__selection` reads (`style.css`), which `graphVars.ts` already
+ * writes from the mpo token layer. So the long-press marquee and the toolbar-
+ * mode marquee are the same rectangle to look at, in both schemes, without this
+ * file knowing a colour. `checkGraphVarsCoverage()` would fail the build for a
+ * `.react-flow__` selector outside `css/graph.css`; reading the variables from
+ * an inline style is the way to match upstream's paint without restating its
+ * selector.
+ *
+ * WHERE IT MOUNTS IS LOAD-BEARING, and this is measured rather than assumed.
+ * Rendered as a SIBLING of the canvas it painted nothing: computed
+ * `background-color: rgba(0, 0, 0, 0)` and `border-style: none`, a correctly
+ * sized rectangle that is entirely invisible. `GraphVars` writes the `--xy-*`
+ * layer onto the `.mp-graph` root, and a variable that is not in scope resolves
+ * to the empty string in silence. So it goes INSIDE the canvas, as a
+ * `NodeGraph` child: React Flow renders children in the `.react-flow`
+ * container, which is screen space, is `position: relative`, and is under the
+ * root the variables are written to.
+ *
+ * Screen space, not the viewport transform. The marquee is drawn under a finger
+ * and it must not scale, shear or move when the viewport is restored on arm.
+ * The rect arrives pane-relative, and the pane fills that same container
+ * exactly, so the two coordinate systems are one.
+ *
+ * `pointer-events: none` is not decoration. The overlay sits on top of the pane
+ * during the one gesture whose events the pane must keep receiving, and a div
+ * that swallowed them would break the lasso by painting it.
+ */
+
+import type { Rect } from "../model/index";
+
+export interface LassoOverlayProps {
+  /** Pane-relative screen px. `null` paints nothing. */
+  readonly rect: Rect | null;
+}
+
+export function LassoOverlay({ rect }: LassoOverlayProps) {
+  if (!rect) return null;
+  return (
+    <div
+      className="mp-graph-lasso"
+      data-testid="mp-graph-lasso"
+      style={{
+        position: "absolute",
+        left: rect.x,
+        top: rect.y,
+        width: rect.width,
+        height: rect.height,
+        background: "var(--xy-selection-background-color)",
+        border: "var(--xy-selection-border)",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}