@multiplatform.one/node-graph 7.7.2

package/src/react-flow/useGraphController.ts

@@ -0,0 +1,473 @@
+/**
+ * The controller: one document, one undo journal, and the four React Flow
+ * callbacks that keep them honest.
+ *
+ * The rule that shapes everything here: **mid-drag is not a document state.**
+ * React Flow emits a `position` change per animation frame, so a two-second
+ * drag is ~120 of them. Committing each one would fire `onDocumentChange` 120
+ * times, hand a consumer 120 autosaves, and bury the undo stack. So the live
+ * React Flow array moves on every frame (the drag has to look right) while the
+ * DOCUMENT moves once, when React Flow marks the last change `dragging: false`.
+ * `useGraphController.spec.tsx` pins that at 30 changes → 1 commit → 1 undo.
+ *
+ * Controlled and uncontrolled are the same code path with a different source of
+ * truth: `commit` always computes the next document and always calls
+ * `onDocumentChange`; it only WRITES to local state when uncontrolled. A
+ * controlled parent that ignores the callback simply sees nothing move, which
+ * is the behaviour every controlled React input has.
+ *
+ * Design: docs/design/node-graph-editor.md §4.5, §5.
+ */
+
+import { startTransition, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type {
+  ConnectionVerdict,
+  EdgeKindDefs,
+  GraphCommand,
+  GraphDocument,
+  GraphEdgeOf,
+  GraphSchema,
+  HistoryOptions,
+  NodeKindDefs,
+} from "../model/index";
+import { applyCommand, createHistory, validateConnection, validateDrop } from "../model/index";
+import type { NodeId, Size, XY } from "../model/document";
+import type { LayoutRunnerKind } from "../diagnostics/types";
+import { layout, reconcilePositions } from "../layout/layout";
+import type { GraphLayoutOptions } from "../layout/layout";
+import type { LayoutResult } from "../layout/types";
+import { FINE_PORT_PITCH, portSpacing } from "../nodes/nodeMeasure";
+import type { GraphNodeSizeKnob } from "../nodes/nodeMeasure";
+import type { GraphFlowNodeData } from "./flowAdapter";
+import { preserveFlowState, toFlowEdges, toFlowNodes } from "./flowAdapter";
+import { applyEdgeChanges, applyNodeChanges } from "./xy";
+import type { Connection, Edge, EdgeChange, Node, NodeChange } from "./xy";
+
+/**
+ * Dev-only, and genuinely once — a message repeated on every frame of a drag is
+ * how a console gets trained out of a team.
+ */
+const warned = new Set<string>();
+function warnOnce(message: string): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (warned.has(message)) return;
+  warned.add(message);
+  // oxlint-disable-next-line no-console -- the sink for a controller misuse
+  console.warn(`[@multiplatform.one/node-graph] ${message}`);
+}
+
+/** Test seam. A module-level dedupe set outlives a test file otherwise. */
+export function resetControllerWarnings(): void {
+  warned.clear();
+}
+
+export interface UseGraphControllerOptions<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly schema: GraphSchema<N, E>;
+  /** Controlled. Wins over `defaultDocument`, with a warning, when both are passed. */
+  readonly document?: GraphDocument<N, E>;
+  /** Uncontrolled seed. Read once, at mount. */
+  readonly defaultDocument?: GraphDocument<N, E>;
+  readonly onDocumentChange?: (document: GraphDocument<N, E>, command: GraphCommand<N, E>) => void;
+  /** Called when a DROP is refused, with the verdict `validateDrop` returned. */
+  readonly onConnectionRefused?: (verdict: ConnectionVerdict) => void;
+  /** Selection still works; nothing else commits. */
+  readonly readOnly?: boolean;
+  readonly history?: HistoryOptions;
+  /** The resolved `size` knob, for the node measure seed. */
+  readonly size?: GraphNodeSizeKnob;
+  /** Touch surface: widens the port pitch, which raises the node height floor. */
+  readonly coarsePointer?: boolean;
+  /** The React Flow node type name `NodeGraphWeb` registers. */
+  readonly nodeType?: string;
+  /**
+   * Reads the boxes React Flow has MEASURED, at the moment a relayout starts.
+   *
+   * A getter rather than a prop: measured sizes change on every observer
+   * callback, and holding 200 of them in state would re-render the canvas for
+   * a value only `relayout()` ever reads.
+   */
+  readonly readMeasuredSizes?: () => Readonly<Record<NodeId, Size>> | undefined;
+}
+
+export interface GraphController<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly document: GraphDocument<N, E>;
+  readonly nodes: Node<GraphFlowNodeData>[];
+  readonly edges: Edge[];
+  readonly onNodesChange: (changes: NodeChange[]) => void;
+  readonly onEdgesChange: (changes: EdgeChange[]) => void;
+  readonly onConnect: (connection: Connection) => void;
+  readonly isValidConnection: (connection: Connection | Edge) => boolean;
+  readonly commit: (command: GraphCommand<N, E>) => void;
+  readonly undo: () => void;
+  readonly redo: () => void;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  /**
+   * Tidy the graph. ONE `setPositions` command, one undo, design §8.
+   *
+   * Resolves with the engine's result even when nothing was committed (an
+   * empty document, `readOnly`, or a superseded generation), so a caller can
+   * report the runner and the ms without inferring them from a side effect.
+   * `null` means there was nothing to lay out.
+   */
+  readonly relayout: (options?: GraphRelayoutOptions) => Promise<LayoutResult | null>;
+  /** `none` until the first relayout has resolved a runner. */
+  readonly layoutRunner: LayoutRunnerKind;
+  /** Engine milliseconds of the last relayout. `null` before the first. */
+  readonly lastLayoutMs: number | null;
+  /** True from the call until its result has been applied. */
+  readonly layoutPending: boolean;
+}
+
+/** Everything `layout()` takes except the measure knobs, which the canvas owns. */
+export type GraphRelayoutOptions = Omit<GraphLayoutOptions, "size" | "coarsePointer">;
+
+export const defaultGraphNodeType = "mpGraphNode";
+
+const emptyDocument = { version: 1, nodes: [], edges: [] } as const;
+
+function positionsOf(
+  nodes: readonly Node<GraphFlowNodeData>[],
+): Record<string, { x: number; y: number }> {
+  const out: Record<string, { x: number; y: number }> = {};
+  for (const node of nodes) out[node.id] = node.position;
+  return out;
+}
+
+/** The deltas a finished drag actually produced, zero-movement nodes dropped. */
+function dragDeltas<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  document: GraphDocument<N, E>,
+  nodes: readonly Node<GraphFlowNodeData>[],
+): Record<string, { x: number; y: number }> {
+  const live = positionsOf(nodes);
+  const deltas: Record<string, { x: number; y: number }> = {};
+  for (const node of document.nodes) {
+    const to = live[node.id];
+    if (!to) continue;
+    const dx = to.x - node.position.x;
+    const dy = to.y - node.position.y;
+    if (dx === 0 && dy === 0) continue;
+    deltas[node.id] = { x: dx, y: dy };
+  }
+  return deltas;
+}
+
+export function useGraphController<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  options: UseGraphControllerOptions<N, E>,
+): GraphController<N, E> {
+  const {
+    schema,
+    document: controlledDocument,
+    defaultDocument,
+    onDocumentChange,
+    onConnectionRefused,
+    readOnly = false,
+    size = "medium",
+    coarsePointer = false,
+    nodeType = defaultGraphNodeType,
+    readMeasuredSizes,
+  } = options;
+
+  const controlled = controlledDocument !== undefined;
+  if (controlled && defaultDocument !== undefined) {
+    warnOnce(
+      "useGraphController received both `document` and `defaultDocument`. " +
+        "`document` wins; drop `defaultDocument` to silence this.",
+    );
+  }
+
+  const [ownDocument, setOwnDocument] = useState<GraphDocument<N, E>>(
+    () =>
+      defaultDocument ?? controlledDocument ?? (emptyDocument as unknown as GraphDocument<N, E>),
+  );
+  const document = controlled ? controlledDocument : ownDocument;
+
+  const history = useMemo(
+    () => createHistory<N, E>(options.history),
+    // The journal is per-controller, not per-render. Rebuilding it on an
+    // inline `{ limit: 100 }` literal would silently erase the undo stack on
+    // every render of the parent.
+    // oxlint-disable-next-line exhaustive-deps
+    [],
+  );
+  const [historyVersion, setHistoryVersion] = useState(0);
+
+  const portSpacingPx = coarsePointer ? portSpacing({ coarsePointer }) : FINE_PORT_PITCH;
+  const mapping = useMemo(
+    () => ({ size, portSpacingPx, nodeType }),
+    [size, portSpacingPx, nodeType],
+  );
+
+  const [nodes, setNodes] = useState<Node<GraphFlowNodeData>[]>(() =>
+    toFlowNodes(document, schema, mapping),
+  );
+  const [edges, setEdges] = useState<Edge[]>(() => toFlowEdges(document, schema));
+  const nodesRef = useRef(nodes);
+  nodesRef.current = nodes;
+  const documentRef = useRef(document);
+  documentRef.current = document;
+
+  const schemaRef = useRef(schema);
+  schemaRef.current = schema;
+
+  // Re-derive when the AUTHORITATIVE document changes — a controlled prop, or
+  // our own commit. Never mid-drag: `onNodesChange` writes the live array
+  // directly and the document does not move until the drag ends, so this
+  // effect does not fire and cannot fight the pointer.
+  //
+  // The schema is keyed by `schema.id`, NOT by object identity. `createGraphSchema`
+  // returns a fresh object every call, so `useGraphController({ schema:
+  // makeSchema(), … })` — the obvious way to write it, and what the spec does —
+  // would otherwise re-derive, re-render, build another schema and never
+  // settle. Measured: the first version of this effect hung the spec run
+  // outright. `schema.id` is already the schema's identity in this package
+  // (design §4.3: it is what crosses the bridge), so keying on it is not a
+  // workaround, it is the declared identity. A schema mutated in place under
+  // the same id does not re-derive, which is the documented cost.
+  useEffect(() => {
+    const current = schemaRef.current;
+    setNodes((previous) => preserveFlowState(toFlowNodes(document, current, mapping), previous));
+    setEdges(toFlowEdges(document, current));
+  }, [document, schema.id, mapping]);
+
+  const commit = useCallback(
+    (command: GraphCommand<N, E>) => {
+      const current = documentRef.current;
+      const next = history.commit(current, command);
+      setHistoryVersion((version) => version + 1);
+      if (!controlled) setOwnDocument(next);
+      documentRef.current = next;
+      onDocumentChange?.(next, command);
+    },
+    [controlled, history, onDocumentChange],
+  );
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange[]) => {
+      const next = applyNodeChanges(changes, nodesRef.current) as Node<GraphFlowNodeData>[];
+      nodesRef.current = next;
+      setNodes(next);
+      // The generation guard's other half (design §8). Every node the user
+      // moves while a layout is in flight is remembered, so the arriving
+      // result can skip it instead of yanking it back under the pointer.
+      if (layoutTouchedRef.current) {
+        for (const change of changes) {
+          if (change.type === "position") layoutTouchedRef.current.add(change.id);
+        }
+      }
+      if (readOnly) return;
+      // The END of a drag, and only that, is a document edit.
+      const dragEnded = changes.some(
+        (change) => change.type === "position" && change.dragging === false,
+      );
+      if (!dragEnded) return;
+      const deltas = dragDeltas(documentRef.current, next);
+      if (Object.keys(deltas).length === 0) return;
+      commit({ t: "moveNodes", deltas });
+    },
+    [commit, readOnly],
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange[]) => {
+      const next = applyEdgeChanges(changes, edges);
+      setEdges(next);
+      if (readOnly) return;
+      const removed = changes
+        .filter(
+          (change): change is EdgeChange & { type: "remove"; id: string } =>
+            change.type === "remove",
+        )
+        .map((change) => change.id);
+      if (removed.length === 0) return;
+      commit({ t: "removeEdges", ids: removed });
+    },
+    [commit, edges, readOnly],
+  );
+
+  const connectionContext = useCallback(
+    (connection: Connection | Edge) => {
+      if (!connection.source || !connection.target) return undefined;
+      // A handle id is the PORT id. React Flow allows a node with one unnamed
+      // handle, but this package always names them (`GraphPort` requires an
+      // `id`), so a null handle here is a half-built drag, not a default.
+      if (!connection.sourceHandle || !connection.targetHandle) return undefined;
+      return {
+        document: documentRef.current,
+        schema,
+        source: { node: connection.source, port: connection.sourceHandle },
+        target: { node: connection.target, port: connection.targetHandle },
+      };
+    },
+    [schema],
+  );
+
+  const isValidConnection = useCallback(
+    (connection: Connection | Edge) => {
+      if (readOnly) return false;
+      const ctx = connectionContext(connection);
+      if (!ctx) return false;
+      // `validateConnection`, NEVER `validateDrop`: this runs on every pointer
+      // tick of a connection drag, and the drop rules are the O(V+E) ones
+      // (design §4.4). The type refuses a drop-only rule here; the spec pins
+      // that the drop rules do not run.
+      return validateConnection(ctx).ok;
+    },
+    [connectionContext, readOnly],
+  );
+
+  const onConnect = useCallback(
+    (connection: Connection) => {
+      if (readOnly) return;
+      const ctx = connectionContext(connection);
+      if (!ctx) return;
+      const verdict = validateDrop(ctx);
+      if (!verdict.ok) {
+        onConnectionRefused?.(verdict);
+        return;
+      }
+      const kind = defaultEdgeKind(schema);
+      if (!kind) return;
+      const spec = (schema.edges as Record<string, { defaultData?: unknown } | undefined>)[kind];
+      const edge = {
+        id: `${ctx.source.node}:${ctx.source.port}->${ctx.target.node}:${ctx.target.port}`,
+        kind,
+        source: ctx.source,
+        target: ctx.target,
+        // The kind's own `defaultData`. `E[kind]` cannot be proven from a
+        // runtime string, so the cast is at the ONE place the kind is chosen,
+        // not spread through the command type.
+        data: spec?.defaultData ?? {},
+      } as unknown as GraphEdgeOf<E>;
+      commit({ t: "addEdges", edges: [edge] });
+    },
+    [commit, connectionContext, onConnectionRefused, readOnly, schema],
+  );
+
+  /**
+   * Auto-layout, design §8. The whole point of this function is that a tidy is
+   * ONE history entry: `setPositions` carries absolutes, so its inverse holds
+   * the whole prior arrangement and one undo puts the graph back exactly.
+   *
+   * The staleness rules are two, and they are different:
+   *
+   *  - A NEWER relayout supersedes an older one outright. Two arrangements
+   *    landing one after the other would be two undo entries for one button
+   *    press, and the first is not an arrangement anybody asked to keep.
+   *  - A node the user TOUCHED mid-flight is skipped, and the rest of the
+   *    result still applies. Discarding everything because one node moved
+   *    makes a relayout feel like it silently failed.
+   */
+  const measuredRef = useRef(readMeasuredSizes);
+  measuredRef.current = readMeasuredSizes;
+  const layoutGenerationRef = useRef(0);
+  const layoutTouchedRef = useRef<Set<NodeId> | null>(null);
+  const [layoutRunner, setLayoutRunner] = useState<LayoutRunnerKind>("none");
+  const [lastLayoutMs, setLastLayoutMs] = useState<number | null>(null);
+  const [layoutPending, setLayoutPending] = useState(false);
+
+  const relayout = useCallback(
+    async (layoutOptions: GraphRelayoutOptions = {}): Promise<LayoutResult | null> => {
+      const source = documentRef.current;
+      if (source.nodes.length === 0) return null;
+
+      const generation = (layoutGenerationRef.current += 1);
+      layoutTouchedRef.current = new Set<NodeId>();
+      setLayoutPending(true);
+
+      let result: LayoutResult;
+      try {
+        result = await layout(source, schemaRef.current, {
+          ...layoutOptions,
+          size,
+          coarsePointer,
+          measured: layoutOptions.measured ?? measuredRef.current?.(),
+        });
+      } finally {
+        if (layoutGenerationRef.current === generation) setLayoutPending(false);
+      }
+
+      // A later relayout already went out; this one's arrangement is not the
+      // one the user is waiting for.
+      if (layoutGenerationRef.current !== generation) return result;
+
+      const touched = layoutTouchedRef.current ?? new Set<NodeId>();
+      layoutTouchedRef.current = null;
+      setLayoutRunner(result.runner ?? "inline");
+      setLastLayoutMs(result.ms);
+      if (readOnly) return result;
+
+      const positions = reconcilePositions(result, touched) as Record<NodeId, XY>;
+      if (Object.keys(positions).length === 0) return result;
+
+      // `startTransition`, so React never paints a half-laid-out graph and the
+      // 200-node commit cannot preempt the frame the user is panning in.
+      startTransition(() => {
+        commit({ t: "setPositions", positions } as GraphCommand<N, E>);
+      });
+      return result;
+    },
+    [coarsePointer, commit, readOnly, size],
+  );
+
+  const undo = useCallback(() => {
+    const next = history.undo(documentRef.current);
+    setHistoryVersion((version) => version + 1);
+    if (next === documentRef.current) return;
+    if (!controlled) setOwnDocument(next);
+    documentRef.current = next;
+    onDocumentChange?.(next, { t: "batch", commands: [] });
+  }, [controlled, history, onDocumentChange]);
+
+  const redo = useCallback(() => {
+    const next = history.redo(documentRef.current);
+    setHistoryVersion((version) => version + 1);
+    if (next === documentRef.current) return;
+    if (!controlled) setOwnDocument(next);
+    documentRef.current = next;
+    onDocumentChange?.(next, { t: "batch", commands: [] });
+  }, [controlled, history, onDocumentChange]);
+
+  return {
+    document,
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange,
+    onConnect,
+    isValidConnection,
+    commit,
+    undo,
+    redo,
+    // `historyVersion` is what makes these re-read after a commit; the journal
+    // itself is a stable object, so nothing else would tell React to look.
+    canUndo: useMemo(() => history.canUndo(), [history, historyVersion]),
+    canRedo: useMemo(() => history.canRedo(), [history, historyVersion]),
+    relayout,
+    layoutRunner,
+    lastLayoutMs,
+    layoutPending,
+  };
+}
+
+/**
+ * Which kind a fresh connection becomes.
+ *
+ * `"flow"` when the schema has it — control moving is the neutral reading of a
+ * plain drag — otherwise the first declared kind, because a schema that omits
+ * `flow` has said what its own default is by declaration order.
+ */
+function defaultEdgeKind<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  schema: GraphSchema<N, E>,
+): string | undefined {
+  const names = Object.keys(schema.edges);
+  return names.includes("flow") ? "flow" : names[0];
+}
+
+/** Applying a command without a controller — the model half, for a consumer. */
+export function applyGraphCommand<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  document: GraphDocument<N, E>,
+  command: GraphCommand<N, E>,
+): GraphDocument<N, E> {
+  return applyCommand(document, command);
+}

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

@@ -0,0 +1,182 @@
+/**
+ * The boundary is only worth having if it is checked.
+ *
+ * Two failures this catches. A React Flow upgrade that renames or drops a name
+ * fails here instead of at a user's first render, because `xy.ts` is the only
+ * place that names them. And a name added to `xy.ts` without a decision fails
+ * the exact-set assertion, which is what keeps the re-export list from drifting
+ * back into a full mirror of upstream.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import * as xy from "./xy";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const requireFromHere = createRequire(import.meta.url);
+
+/** Every value `xy.ts` re-exports. Types are checked by `pnpm -F … typecheck`. */
+const reExportedValues = [
+  "applyEdgeChanges",
+  "applyNodeChanges",
+  "Background",
+  "BaseEdge",
+  "Controls",
+  "EdgeLabelRenderer",
+  "getBezierPath",
+  "getHandlePosition",
+  "getSmoothStepPath",
+  "getStraightPath",
+  "Handle",
+  "MarkerType",
+  "MiniMap",
+  "Position",
+  "ReactFlow",
+  "ReactFlowProvider",
+  "SelectionMode",
+  "useEdgesState",
+  "useNodesState",
+  "useReactFlow",
+  "useStore",
+  "useStoreApi",
+  "useUpdateNodeInternals",
+  "ViewportPortal",
+] as const;
+
+interface SemVer {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+}
+
+function parseVersion(value: string): SemVer {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value);
+  if (!match) throw new Error(`not a semver: ${value}`);
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/**
+ * Caret ranges only, on purpose. A range this cannot read is a range nobody
+ * reasoned about, so it fails loudly rather than passing silently.
+ */
+function satisfiesCaret(version: string, range: string): boolean {
+  const caret = /^\^(\d+\.\d+\.\d+)$/.exec(range);
+  if (!caret) throw new Error(`declared range is not a caret range: ${range}`);
+  const min = parseVersion(caret[1]);
+  const actual = parseVersion(version);
+  if (actual.major !== min.major) return false;
+  if (actual.minor !== min.minor) return actual.minor > min.minor;
+  return actual.patch >= min.patch;
+}
+
+/**
+ * `@xyflow/system` does not put `./package.json` in its exports map — unlike
+ * `@xyflow/react`, which does — so `require("@xyflow/system/package.json")`
+ * throws ERR_PACKAGE_PATH_NOT_EXPORTED. Resolve the entry and walk up to the
+ * manifest that owns it instead, which also proves the version read is the
+ * version this process would actually import.
+ */
+function installedSystemVersion(): string {
+  let dir = path.dirname(requireFromHere.resolve("@xyflow/system"));
+  for (;;) {
+    const manifest = path.join(dir, "package.json");
+    if (existsSync(manifest)) {
+      const pkg = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string; version: string };
+      if (pkg.name === "@xyflow/system") return pkg.version;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new Error("no @xyflow/system package.json above its resolved entry");
+    dir = parent;
+  }
+}
+
+let declaredRange: string;
+let declaredSystemPin: string;
+
+beforeAll(async () => {
+  const pkg = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")) as {
+    dependencies: Record<string, string>;
+  };
+  declaredRange = pkg.dependencies["@xyflow/react"];
+  declaredSystemPin = pkg.dependencies["@xyflow/system"];
+});
+
+describe("the @xyflow boundary", () => {
+  it("defines every re-exported name", () => {
+    for (const name of reExportedValues) {
+      expect(xy[name], name).toBeDefined();
+    }
+  });
+
+  it("re-exports exactly the decided set, plus the four constants, and nothing else", () => {
+    expect(Object.keys(xy).sort()).toEqual(
+      [
+        ...reExportedValues,
+        "xyflowVersion",
+        "reactFlowPaneSelector",
+        "reactFlowNodeSelector",
+        "reactFlowViewportSelector",
+      ].sort(),
+    );
+  });
+
+  it("owns the pane class name, because a class is part of the DOM contract", () => {
+    // The long press finds the pane by class (`useLassoSelect.ts`). That is a
+    // DOM lookup rather than a paint rule, so `checkGraphVarsCoverage` exempts
+    // THIS file for it — and the exemption is only worth having if the string
+    // is actually here. Pinned so a refactor that inlines it back at the call
+    // site fails here rather than at the next @xyflow upgrade, silently.
+    expect(xy.reactFlowPaneSelector).toBe(".react-flow__pane");
+  });
+
+  it("owns the node class name too, for the same reason", () => {
+    // `NodeGraph/AutoLayout`'s position stamp finds nodes by class to read
+    // their CSS transform — React Flow places a node with a transform and
+    // never with a layout offset, so a stamp built on `offsetLeft` is a
+    // constant. Same boundary, same pin.
+    expect(xy.reactFlowNodeSelector).toBe(".react-flow__node");
+  });
+
+  it("owns the viewport class name, which is what `didMove` is read from", () => {
+    // The frame sampler compares this element's transform at the first sample
+    // against the last (design 13.2). A rename would make the probe return
+    // `null`, every run would report `didMove: false`, and a whole session of
+    // measurement would be discarded for a reason nobody could see.
+    expect(xy.reactFlowViewportSelector).toBe(".react-flow__viewport");
+  });
+
+  it("declares the version diagnostics reports, and it is the INSTALLED one", () => {
+    // Design 9.5 has to report a version, only this file may reach @xyflow, and
+    // a literal that drifts from the installed package is worse than no version
+    // at all — it would send a reader chasing the wrong changelog.
+    const installed = requireFromHere("@xyflow/react/package.json") as { version: string };
+    expect(xy.xyflowVersion).toBe(installed.version);
+  });
+
+  it("pins @xyflow/system to exactly what @xyflow/react pins", () => {
+    // `getHandlePosition` comes straight from `@xyflow/system` — React Flow
+    // does not re-export it, and it is the function the 44pt endpoint law is
+    // asserted against (design 7.1 H2). Two copies of that package on one
+    // canvas would mean the law is proved against a DIFFERENT implementation
+    // than the one drawing the edges: a green test over a broken graph. An
+    // exact pin equal to React Flow's own is what keeps them one module.
+    const reactPkg = requireFromHere("@xyflow/react/package.json") as {
+      dependencies: Record<string, string>;
+    };
+    expect(declaredSystemPin).toBe(reactPkg.dependencies["@xyflow/system"]);
+    expect(installedSystemVersion()).toBe(declaredSystemPin);
+  });
+
+  it("has an installed @xyflow/react inside the declared range", () => {
+    const installed = requireFromHere("@xyflow/react/package.json") as { version: string };
+    expect(declaredRange).toBeDefined();
+    expect(
+      satisfiesCaret(installed.version, declaredRange),
+      `installed ${installed.version} is outside ${declaredRange}`,
+    ).toBe(true);
+  });
+});