@multiplatform.one/node-graph 7.7.2

package/src/react-flow/xy.ts

@@ -0,0 +1,131 @@
+/**
+ * THE ONLY `@xyflow` import site in this package.
+ *
+ * `no-restricted-imports` in the repo's `oxlintrc.json` refuses `@xyflow/*`
+ * everywhere else under `public/node-graph/src`, so a React Flow major bump has
+ * exactly one reconciliation site instead of thirty. `xy.spec.ts` asserts every
+ * name below still resolves and that the installed version is inside the range
+ * `package.json` declares, so an upgrade fails CI rather than a user.
+ *
+ * The list is deliberately narrow. It is what the editor uses, not a mirror of
+ * upstream — a name nobody imports is a name nobody reconciles. Add one here
+ * (and to the spec's list) when a task actually needs it.
+ *
+ * Upgrade runbook: README.md.
+ *
+ * ONE name comes from `@xyflow/system` rather than `@xyflow/react`:
+ * `getHandlePosition`. React Flow does not re-export it (its own index re-lists
+ * `getBezierPath` and friends and stops there), and it is the function that
+ * turns a handle's measured BOX into the point an edge is drawn to — which is
+ * the whole reason the 44pt hit region is a pseudo-element and not element
+ * growth (design 7.1 H2). Asserting that law against our own reimplementation
+ * would prove nothing, so the spec calls the real one. `package.json` pins
+ * `@xyflow/system` to the exact version `@xyflow/react` pins, and `xy.spec.ts`
+ * fails if the two ever split.
+ */
+
+export { getHandlePosition } from "@xyflow/system";
+export type { Handle as HandleBounds, InternalNodeBase } from "@xyflow/system";
+
+export {
+  applyEdgeChanges,
+  applyNodeChanges,
+  Background,
+  BaseEdge,
+  Controls,
+  EdgeLabelRenderer,
+  getBezierPath,
+  getSmoothStepPath,
+  getStraightPath,
+  Handle,
+  MarkerType,
+  MiniMap,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  SelectionMode,
+  useEdgesState,
+  useNodesState,
+  useReactFlow,
+  useStore,
+  useStoreApi,
+  useUpdateNodeInternals,
+  /**
+   * The guide layer has to live INSIDE `.react-flow__viewport` so the pan and
+   * zoom transform applies to it for free (design §7.2 S10). This portal is the
+   * only supported way in; rendering a sibling and re-deriving the transform is
+   * how a guide ends up one frame behind the node it points at.
+   */
+  ViewportPortal,
+} from "@xyflow/react";
+
+export type {
+  ColorMode,
+  Connection,
+  Edge,
+  EdgeChange,
+  EdgeMarkerType,
+  EdgeProps,
+  EdgeTypes,
+  HandleType,
+  IsValidConnection,
+  Node,
+  NodeChange,
+  NodeProps,
+  NodeTypes,
+  OnConnect,
+  ReactFlowInstance,
+  Viewport,
+  XYPosition,
+} from "@xyflow/react";
+
+/**
+ * The installed React Flow version, as a plain string.
+ *
+ * Diagnostics has to report it (design §9.5) and only THIS file may reach
+ * `@xyflow`, so it is declared here rather than read at the use site. A literal
+ * rather than an import of `@xyflow/react/package.json`: that path is not in
+ * the package's exports map on every condition, and a bundler that cannot
+ * resolve it would take the whole canvas down to report a version string.
+ *
+ * `xy.spec.ts` asserts this equals the installed version, so it cannot drift
+ * from reality — an upgrade that forgets it fails CI rather than a user.
+ */
+export const xyflowVersion = "12.11.5";
+
+/**
+ * The class React Flow puts on its pane element.
+ *
+ * A class name is part of @xyflow's DOM contract exactly as its exported
+ * symbols are, so it belongs at the same boundary they do. The long press has
+ * to FIND the pane to listen on it (`useLassoSelect.ts`) — that is a DOM
+ * lookup, not a paint rule, and a paint rule is what `checkGraphVarsCoverage`
+ * exists to keep out of `src`. Hardcoding the string at the call site would
+ * have been the wrong kind of coupling either way: when an upgrade renames the
+ * class, a `querySelector` returns null and the long press dies in silence, so
+ * the rename should have exactly one place to land.
+ */
+export const reactFlowPaneSelector = ".react-flow__pane";
+
+/**
+ * The class React Flow puts on a node element. Same boundary rule as
+ * `reactFlowPaneSelector`, and for the same reason: it is a DOM lookup, not a
+ * paint rule, and a rename should have exactly one place to land.
+ *
+ * The lookup this exists for is `NodeGraph/AutoLayout`'s position stamp, which
+ * reads each node's CSS `transform` — React Flow places a node with a
+ * transform and never with a layout offset, so `offsetLeft` / `offsetTop` are
+ * 0 at every arrangement and a stamp built on them is a constant.
+ */
+export const reactFlowNodeSelector = ".react-flow__node";
+
+/**
+ * The class React Flow puts on the pan/zoom viewport — the ONE element whose
+ * transform carries the whole canvas.
+ *
+ * Same boundary rule as the pane and node selectors. The frame sampler's
+ * `didMove` probe (design §13.2) reads this transform to tell a real pan from
+ * an idle page, and a rename that silently returned `null` there would turn
+ * every perf run into a discarded one with no explanation.
+ */
+export const reactFlowViewportSelector = ".react-flow__viewport";

package/src/theme/GraphFaces.spec.tsx

@@ -0,0 +1,101 @@
+/**
+ * What `source: "inline"` MEANS — and the bug that made it mean nothing.
+ *
+ * The branch that reports it carried a comment promising to "confirm THOSE
+ * land" and then marked the face `inline` without asking `document.fonts`
+ * anything. Measured on the iPhone 16e at MPO-211: the canvas reported every
+ * face `inline`, design 6.3's probe ran on the way to `ready` — which the
+ * canvas now waits for the faces to settle before emitting — and measured the
+ * FALLBACK family, reporting `MISS · 205.28px vs 205.28px` on a canvas whose
+ * labels painted in Inter a moment later. The verdict arrived before the thing
+ * it judged.
+ *
+ * `document.fonts` is stubbed rather than exercised: happy-dom has no real
+ * font loading, and what these specs are about is which question the hook
+ * asks, not whether a WOFF2 decodes.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GraphFaces } from "./GraphFaces";
+import type { GraphFaceStatus } from "./GraphFaces";
+import type { GraphFaceAsset } from "./faces";
+
+const face: GraphFaceAsset = {
+  id: "inter-400",
+  family: "Inter",
+  weight: 400,
+  style: "normal",
+  category: "sans-serif",
+  source: "apps/storybook/public/fonts/inter-400.woff2",
+  base64: "AAAA",
+  byteLength: 3,
+  sha256: "0".repeat(64),
+};
+
+interface FontsStub {
+  load: ReturnType<typeof vi.fn>;
+  check: ReturnType<typeof vi.fn>;
+}
+
+/** Installs a `document.fonts` that answers however the test says. */
+function stubFonts(answer: boolean): FontsStub {
+  const fonts: FontsStub = {
+    load: vi.fn(async () => (answer ? [{}] : [])),
+    check: vi.fn(() => answer),
+  };
+  Object.defineProperty(document, "fonts", { value: fonts, configurable: true });
+  return fonts;
+}
+
+afterEach(() => {
+  cleanup();
+  Reflect.deleteProperty(document, "fonts");
+});
+
+async function statusesFor(assetUris?: Record<string, string>) {
+  const seen: (readonly GraphFaceStatus[])[] = [];
+  renderWithProviders(
+    <GraphFaces
+      assetUris={assetUris}
+      faces={[face]}
+      onStatus={(statuses) => seen.push(statuses)}
+      timeoutMs={50}
+    />,
+  );
+  await waitFor(() => expect(seen.at(-1)?.[0]?.source).not.toBe("pending"));
+  return seen.at(-1) as readonly GraphFaceStatus[];
+}
+
+describe("GraphFaces delivery", () => {
+  it("confirms the bytes landed before reporting inline", async () => {
+    const fonts = stubFonts(true);
+    const statuses = await statusesFor();
+    expect(statuses[0]?.source).toBe("inline");
+    // The whole point: it ASKED. Without this call `inline` is a guess, and
+    // the probe that runs on the strength of it measures the fallback.
+    expect(fonts.load).toHaveBeenCalledWith('400 16px "Inter"');
+  });
+
+  it("reports failed, not inline, when the bytes never land", async () => {
+    stubFonts(false);
+    const statuses = await statusesFor();
+    expect(statuses[0]?.source).toBe("failed");
+  });
+
+  it("prefers the asset URL when it answers", async () => {
+    stubFonts(true);
+    const statuses = await statusesFor({ "inter-400": "/fonts/inter-400.woff2" });
+    expect(statuses[0]?.source).toBe("asset");
+  });
+
+  it("starts at pending, so nothing reads a delivery that has not resolved", () => {
+    stubFonts(true);
+    const seen: (readonly GraphFaceStatus[])[] = [];
+    renderWithProviders(
+      <GraphFaces faces={[face]} onStatus={(statuses) => seen.push(statuses)} timeoutMs={50} />,
+    );
+    expect(seen[0]?.[0]?.source).toBe("pending");
+  });
+});

package/src/theme/GraphFaces.tsx

@@ -0,0 +1,218 @@
+/**
+ * Gets the `$body` face into the WebView, asset URL first, bytes second.
+ *
+ * Design §6.3's two mechanisms, in the order it names them:
+ *
+ *  1. **Asset URL.** A consumer hands in the URL Expo produced from a
+ *     `require()` of the face. Nothing rides in the bundle for that face.
+ *  2. **Inline base64.** Whatever the first path did not deliver, this does.
+ *     Proven, and the reason `faces.generated.ts` exists.
+ *
+ * The switch between them is not a guess. `document.fonts.load` is awaited and
+ * `document.fonts.check` is read back, so a URL that 404s inside the WebView —
+ * the exact failure that makes the primary path unverified on device — demotes
+ * that face to its bytes instead of leaving the canvas in a fallback family
+ * nobody notices.
+ *
+ * IMPORTING THIS PULLS THE PAYLOAD. `faces.generated.ts` is ~200 KB of base64
+ * and this module's default argument references it, so a consumer that already
+ * registers Inter (every web app in this repo does, through Tamagui) should not
+ * mount `GraphFaces` at all. The DOM bundle is who it is for.
+ *
+ * Design: docs/design/node-graph-editor.md §6.3.
+ */
+
+import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { type GraphFaceAsset, graphFaceCss } from "./faces";
+import { generatedGraphFaces } from "./faces.generated";
+
+/** Which of the two mechanisms actually delivered a face. */
+export type GraphFaceSource = "asset" | "inline" | "pending" | "failed";
+
+/** Per-face outcome, for the diagnostics panel and the `FontProof` story. */
+export interface GraphFaceStatus {
+  readonly id: string;
+  readonly family: string;
+  readonly weight: number;
+  readonly source: GraphFaceSource;
+}
+
+export interface GraphFacesProps {
+  /** Defaults to the generated payload. */
+  readonly faces?: readonly GraphFaceAsset[];
+  /**
+   * `require()`d asset URLs by face id. A face named here is tried from its URL
+   * first; a face absent here goes straight to its bytes.
+   */
+  readonly assetUris?: Readonly<Record<string, string>>;
+  /**
+   * How long to wait for the asset URL before falling back, in ms.
+   *
+   * 1500, well inside the native watchdog's 4000 ms (design §9.4 layer 4), so a
+   * slow face degrades to base64 rather than letting the whole WebView be
+   * declared dead.
+   */
+  readonly timeoutMs?: number;
+  readonly onStatus?: (statuses: readonly GraphFaceStatus[]) => void;
+}
+
+/** `${weight} 16px "${family}"` — the shorthand `document.fonts` wants. */
+function faceQuery(face: GraphFaceAsset): string {
+  return `${face.weight} 16px "${face.family}"`;
+}
+
+async function loadWithin(query: string, timeoutMs: number): Promise<boolean> {
+  const fonts = typeof document === "undefined" ? undefined : document.fonts;
+  if (!fonts) return false;
+  // Promise.race rather than an abort: FontFaceSet.load has no cancellation, so
+  // a hung fetch would otherwise hold the canvas at the fallback family for as
+  // long as the network takes.
+  const timed = new Promise<boolean>((resolve) => {
+    setTimeout(() => resolve(false), timeoutMs);
+  });
+  const loaded = fonts
+    .load(query)
+    .then((matched) => matched.length > 0 && fonts.check(query))
+    .catch(() => false);
+  return Promise.race([loaded, timed]);
+}
+
+/**
+ * Resolves each face to the mechanism that actually delivered it.
+ *
+ * Returns the URIs still worth honouring, so the sheet re-renders with base64
+ * for the ones that did not answer.
+ */
+export function useGraphFaces(
+  faces: readonly GraphFaceAsset[],
+  assetUris: Readonly<Record<string, string>> | undefined,
+  timeoutMs: number,
+): {
+  readonly uris: Readonly<Record<string, string>>;
+  readonly statuses: readonly GraphFaceStatus[];
+} {
+  const requested = useMemo(() => assetUris ?? {}, [assetUris]);
+  const [resolved, setResolved] = useState<Readonly<Record<string, GraphFaceSource>>>({});
+
+  const requestedKey = useMemo(() => JSON.stringify(requested), [requested]);
+  const facesKey = useMemo(() => faces.map((face) => face.id).join(","), [faces]);
+
+  useEffect(() => {
+    let live = true;
+    const run = async () => {
+      const next: Record<string, GraphFaceSource> = {};
+      for (const face of faces) {
+        const query = faceQuery(face);
+        if (requested[face.id]) {
+          // eslint-disable-next-line no-await-in-loop
+          const ok = await loadWithin(query, timeoutMs);
+          if (ok) {
+            next[face.id] = "asset";
+            continue;
+          }
+          // The URL did not answer. The sheet has not re-rendered with the
+          // bytes yet — that happens on the render this `setResolved` causes —
+          // so there is nothing to confirm in this pass. Reported as `inline`
+          // optimistically, which is the one case where the value means
+          // "falling back" rather than "landed".
+          next[face.id] = "inline";
+          continue;
+        }
+        /**
+         * No URL was offered, so the sheet ALREADY carries this face's bytes
+         * and the load is confirmable right now — so confirm it.
+         *
+         * It did not, until MPO-211. The branch's own comment said it would
+         * ("confirm THOSE land") and the code marked `inline` without asking,
+         * which made `source: "inline"` mean "we gave up on the URL" rather
+         * than "the bytes are available". Measured on the iPhone 16e: the
+         * canvas reported every face `inline` and design 6.3's probe, which
+         * runs on the way to `ready`, then measured the FALLBACK family and
+         * reported `MISS · 205.28px vs 205.28px` on a canvas whose labels were
+         * about to paint in Inter. A verdict that arrives before the thing it
+         * judges is worse than no verdict.
+         *
+         * This is the path the DOM bundle takes for every face: a `require()`d
+         * asset URL is the host's to produce and cannot cross the bridge, so
+         * the canvas mounts `GraphFaces` with no `assetUris` at all.
+         */
+        // eslint-disable-next-line no-await-in-loop
+        const landed = await loadWithin(query, timeoutMs);
+        next[face.id] = landed ? "inline" : "failed";
+      }
+      if (live) setResolved(next);
+    };
+    void run();
+    return () => {
+      live = false;
+    };
+    // biome-ignore-start: the two keys ARE the dependencies; the arrays behind
+    // them get a fresh identity every render and would re-probe at 60 Hz.
+    // oxlint-disable-next-line exhaustive-deps
+  }, [facesKey, requestedKey, timeoutMs]);
+  // biome-ignore-end
+
+  const uris = useMemo(() => {
+    const out: Record<string, string> = {};
+    for (const face of faces) {
+      const uri = requested[face.id];
+      // Before the probe answers, honour the URL: rendering base64 first and
+      // swapping to the URL later would download both.
+      if (uri && resolved[face.id] !== "inline") out[face.id] = uri;
+    }
+    return out;
+  }, [faces, requested, resolved]);
+
+  const statuses = useMemo(
+    () =>
+      faces.map((face) => ({
+        id: face.id,
+        family: face.family,
+        weight: face.weight,
+        source: resolved[face.id] ?? ("pending" as GraphFaceSource),
+      })),
+    [faces, resolved],
+  );
+
+  return { uris, statuses };
+}
+
+/**
+ * The `@font-face` sheet, plus the asset-URL-first resolution behind it.
+ *
+ * Renders NOTHING where there is no DOM, and that is not defensive coding — it
+ * is the component being honest about what it is. This is a `<style>` element
+ * and nothing else; `<style>` is a browser intrinsic, and React Native answers a
+ * lowercase intrinsic it does not know with
+ * `View config getter callback for component "style" must be a function`, which
+ * takes the whole tree down. Measured on the iPhone 16e at task 2.7: the
+ * `NodeGraph/GraphNode` → `FontProof` story mounts this directly and died
+ * exactly there, on a device where the story's own error boundary was the only
+ * thing between it and a blank screen.
+ *
+ * The hooks run either way, so the rules of hooks hold and the status callback
+ * still fires; only the element is withheld. A caller on native gets `null` and
+ * should read `GraphDiagnostics`, where the probe that ran INSIDE the WebView
+ * arrives over the `ready` event.
+ */
+export function GraphFaces({
+  faces = generatedGraphFaces,
+  assetUris,
+  timeoutMs = 1500,
+  onStatus,
+}: GraphFacesProps): ReactNode {
+  const { uris, statuses } = useGraphFaces(faces, assetUris, timeoutMs);
+  const sheet = useMemo(() => graphFaceCss(faces, uris), [faces, uris]);
+
+  useEffect(() => {
+    onStatus?.(statuses);
+  }, [onStatus, statuses]);
+
+  if (typeof document === "undefined") return null;
+
+  return (
+    <style data-mpo-graph-faces={String(faces.length)} suppressHydrationWarning>
+      {sheet}
+    </style>
+  );
+}

package/src/theme/GraphVarsStyle.tsx

@@ -0,0 +1,113 @@
+/**
+ * The var layer as one `<style>` tag, plus the adapter that reads a live
+ * Tamagui theme into `GraphThemeAccess`.
+ *
+ * Design 6.2 names this file `GraphVars.tsx`, next to `graphVars.ts`. Those two
+ * are the SAME module specifier on a case-insensitive filesystem, and the
+ * resolver's extension order (.ts before .tsx) means `import … from
+ * "./GraphVars"` silently returns `graphVars.ts` — measured on macOS, where
+ * `head ./GraphVars.ts` prints the pure module. The COMPONENT keeps its design
+ * name; only the file gains a suffix, so `graphVars.ts` and the lint check's
+ * exemption path are unchanged.
+ *
+ * Design: docs/design/node-graph-editor.md 6.2.
+ */
+
+import { type ReactNode, useMemo } from "react";
+import { getVariable, useTheme as useTamaguiTheme } from "tamagui";
+import type { ResolvedKnobs } from "@multiplatform.one/theme";
+import { type GraphCssVarsOptions, type GraphThemeAccess, graphCssVars } from "./graphVars";
+
+/**
+ * The class the graph root carries; every rule in `css/graph.css` is scoped to it.
+ *
+ * `mp-graph`, not `mp-graph-root`: design 7.1 and 7.5 write the selectors as
+ * `.mp-graph .react-flow__handle` and `.mp-graph .react-flow__pane`, and the
+ * port rules landed by task 1.9 use that prefix. One name, and it is the
+ * design's. Nothing outside this constant may spell it.
+ */
+export const graphRootClassName = "mp-graph";
+
+export interface GraphVarsProps {
+  /** The `--xy-*` / `--mpo-graph-*` layer, from `graphCssVars` or straight off the envelope. */
+  readonly vars: Readonly<Record<string, string>>;
+  readonly scheme: "light" | "dark";
+  /**
+   * The envelope's revision. The sheet is rebuilt on THIS and nothing else:
+   * `vars` is derived from the envelope, so its revision is the authority on
+   * whether anything moved, and a fresh `vars` object identity on every render
+   * would otherwise re-serialize the whole sheet at 60 Hz during a drag.
+   * `graphCss.spec.ts` pins that behaviour rather than leaving it as a comment.
+   */
+  readonly revision: number;
+  /** Scope selector. Defaults to the graph root class. */
+  readonly selector?: string;
+}
+
+/** A CSS custom-property block, deterministic in key order so a diff is readable. */
+export function graphVarsSheet(
+  vars: Readonly<Record<string, string>>,
+  scheme: "light" | "dark",
+  selector: string,
+): string {
+  const declarations = Object.keys(vars)
+    .sort()
+    .map((name) => `  ${name}: ${vars[name]};`)
+    .join("\n");
+  return `${selector} {\n  color-scheme: ${scheme};\n${declarations}\n}\n`;
+}
+
+export function GraphVars({ vars, scheme, revision, selector }: GraphVarsProps): ReactNode {
+  const scope = selector ?? `.${graphRootClassName}`;
+  // biome-ignore-start: the revision IS the dependency — see the prop's doc.
+  // oxlint-disable-next-line exhaustive-deps
+  const sheet = useMemo(() => graphVarsSheet(vars, scheme, scope), [revision, scope]);
+  // biome-ignore-end
+  return (
+    <style data-mpo-graph-vars={String(revision)} suppressHydrationWarning>
+      {sheet}
+    </style>
+  );
+}
+
+/**
+ * Read a live Tamagui theme into the two forms `graphCssVars` needs.
+ *
+ * The CSS form comes from the Variable itself (`var(--…)` on web) rather than
+ * from a reconstructed prefix, so nothing here has to know how Tamagui names
+ * its custom properties. The raw form is the literal value, and is used only by
+ * the two blended entries.
+ */
+export function useGraphThemeAccess(): GraphThemeAccess {
+  const theme = useTamaguiTheme();
+  return useMemo(() => {
+    const read = (key: string): unknown => (theme as unknown as Record<string, unknown>)[key];
+    return {
+      css: (key: string) => {
+        const value = read(key);
+        if (value == null) return undefined;
+        const variable = (value as { variable?: string }).variable;
+        if (typeof variable === "string" && variable) return variable;
+        const resolved = getVariable(value as never);
+        return typeof resolved === "string" ? resolved : undefined;
+      },
+      raw: (key: string) => {
+        const value = read(key);
+        if (value == null) return undefined;
+        if (typeof value === "string") return value;
+        const val = (value as { val?: unknown }).val;
+        return typeof val === "string" ? val : undefined;
+      },
+    };
+  }, [theme]);
+}
+
+/** `graphCssVars` against the live theme. */
+export function useGraphCssVars(
+  resolved: ResolvedKnobs,
+  options?: GraphCssVarsOptions,
+): Record<string, string> {
+  const theme = useGraphThemeAccess();
+  const pointer = options?.pointer;
+  return useMemo(() => graphCssVars(resolved, theme, { pointer }), [resolved, theme, pointer]);
+}