@multiplatform.one/node-graph 7.7.2

package/src/interaction/lassoIntercept.spec.ts

@@ -0,0 +1,166 @@
+/**
+ * Task 3.7, the first thing to prove — and deliberately the ONLY thing this
+ * file knows about. No React, no React Flow, no hook: three nested divs and
+ * two listeners.
+ *
+ * Design §7.3 names three mechanisms that were proposed and do not work, and
+ * every one of them failed because it was never isolated from the canvas:
+ * `setPointerCapture` cannot steal a legacy `TouchEvent` from d3; `panOnDrag`
+ * as an array is only consulted for `mousedown`; flipping `panOnDrag` mid-hold
+ * cannot stop a d3 gesture that has already started. So the fourth mechanism
+ * gets tested at its own level before anything is built on it.
+ *
+ * The claim: a capture-phase `touchmove` listener on an ANCESTOR stops the
+ * event before a bubble-phase listener below it ever runs, and removing that
+ * listener restores delivery.
+ *
+ * The fixture mirrors the real tree on purpose. d3-zoom binds `touchmove.zoom`
+ * on the element it is called with, which in React Flow is
+ * `.react-flow__renderer` — an ANCESTOR of `.react-flow__pane`, not the pane
+ * itself. So `mid` carries a bubble listener as well as `target`, and the
+ * interceptor has to sit above them BOTH. An interceptor installed on the pane
+ * would pass a test that only watched the pane and would still let d3 pan the
+ * canvas.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installLassoIntercept } from "./lassoIntercept";
+
+let root: HTMLDivElement;
+let mid: HTMLDivElement;
+let target: HTMLDivElement;
+type Listener = ReturnType<typeof vi.fn<(event: Event) => void>>;
+
+/** Bubble-phase listeners, standing in for d3's `touchmove.zoom`. */
+let onMid: Listener;
+let onTarget: Listener;
+
+beforeEach(() => {
+  root = document.createElement("div");
+  mid = document.createElement("div");
+  target = document.createElement("div");
+  mid.appendChild(target);
+  root.appendChild(mid);
+  document.body.appendChild(root);
+  onMid = vi.fn<(event: Event) => void>();
+  onTarget = vi.fn<(event: Event) => void>();
+  mid.addEventListener("touchmove", onMid);
+  target.addEventListener("touchmove", onTarget);
+});
+
+afterEach(() => {
+  root.remove();
+  vi.restoreAllMocks();
+});
+
+function fire(type: string, touchCount = 1): TouchEvent {
+  const touches = Array.from(
+    { length: touchCount },
+    (_, index) =>
+      new Touch({ identifier: index, target, clientX: 10 + index, clientY: 20 + index }),
+  );
+  const event = new TouchEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    touches,
+    targetTouches: touches,
+    changedTouches: touches,
+  });
+  target.dispatchEvent(event);
+  return event;
+}
+
+describe("the mechanism", () => {
+  it("delivers touchmove to both bubble listeners with nothing installed", () => {
+    fire("touchmove");
+    expect(onTarget).toHaveBeenCalledTimes(1);
+    expect(onMid).toHaveBeenCalledTimes(1);
+  });
+
+  it("a capture listener on the ancestor stops the event reaching either of them", () => {
+    installLassoIntercept({ ancestor: root });
+    fire("touchmove");
+    expect(onTarget).not.toHaveBeenCalled();
+    expect(onMid).not.toHaveBeenCalled();
+  });
+
+  it("restores delivery to both when released", () => {
+    const intercept = installLassoIntercept({ ancestor: root });
+    fire("touchmove");
+    intercept.release();
+    fire("touchmove");
+    expect(onTarget).toHaveBeenCalledTimes(1);
+    expect(onMid).toHaveBeenCalledTimes(1);
+  });
+
+  it("works from the document, which is the ancestor of everything", () => {
+    // The hook's default. A specific ancestor has to be chosen correctly and
+    // `document` cannot be chosen wrongly — it is above `.react-flow__renderer`
+    // however deep the canvas is nested in a consumer's layout.
+    const intercept = installLassoIntercept({ ancestor: document });
+    fire("touchmove");
+    expect(onMid).not.toHaveBeenCalled();
+    intercept.release();
+    fire("touchmove");
+    expect(onMid).toHaveBeenCalledTimes(1);
+  });
+
+  it("hands every swallowed event to the caller, so the marquee can be drawn from them", () => {
+    const onIntercept = vi.fn<(event: TouchEvent) => void>();
+    installLassoIntercept({ ancestor: root, onIntercept });
+    fire("touchmove");
+    fire("touchmove");
+    expect(onIntercept).toHaveBeenCalledTimes(2);
+    expect(onIntercept.mock.calls[0][0].type).toBe("touchmove");
+  });
+});
+
+describe("what it deliberately does NOT swallow", () => {
+  /**
+   * Arming dispatches a `touchcancel` at the pane so d3 ends its gesture
+   * cleanly rather than sitting on a live `g.touch0` (design §7.3 L3). An
+   * interceptor that swallowed every touch event would eat that dispatch and
+   * leave d3 exactly as stuck as doing nothing — which is why this is a spec
+   * and not a comment about the listener's event name.
+   */
+  it.each(["touchstart", "touchend", "touchcancel"])("lets %s through", (type) => {
+    const seen = vi.fn<(event: Event) => void>();
+    mid.addEventListener(type, seen);
+    installLassoIntercept({ ancestor: root });
+    fire(type);
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it("never preventDefaults, so it cannot cancel a scroll the pane wanted", () => {
+    installLassoIntercept({ ancestor: root });
+    const event = fire("touchmove");
+    expect(event.defaultPrevented).toBe(false);
+  });
+});
+
+describe("release", () => {
+  it("is idempotent", () => {
+    const intercept = installLassoIntercept({ ancestor: root });
+    intercept.release();
+    intercept.release();
+    fire("touchmove");
+    expect(onMid).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports whether it is still installed", () => {
+    const intercept = installLassoIntercept({ ancestor: root });
+    expect(intercept.active).toBe(true);
+    intercept.release();
+    expect(intercept.active).toBe(false);
+  });
+
+  it("a second release does not disarm a later interceptor", () => {
+    const first = installLassoIntercept({ ancestor: root });
+    first.release();
+    const second = installLassoIntercept({ ancestor: root });
+    first.release();
+    fire("touchmove");
+    expect(onMid).not.toHaveBeenCalled();
+    second.release();
+  });
+});

package/src/interaction/lassoIntercept.ts

@@ -0,0 +1,81 @@
+/**
+ * The long-press interceptor (design §7.3, task 3.7).
+ *
+ * One capture-phase `touchmove` listener on an ancestor, calling
+ * `stopPropagation()`. That is the whole mechanism, and it is small because
+ * the reasoning that led to it is where the work was:
+ *
+ *  - d3-zoom binds `touchmove.zoom` (`d3-zoom/src/zoom.js:80`) as a legacy
+ *    `TouchEvent`, in the BUBBLE phase, on the element `zoom()` was called
+ *    with — `.react-flow__renderer`, which is an ANCESTOR of the pane.
+ *  - `setPointerCapture` retargets `PointerEvent`s only, so it cannot take
+ *    that away.
+ *  - d3 consults its `filter` in `touchstarted` (`:316`) and never again in
+ *    `touchmoved` (`:340`), so flipping `panOnDrag` 350 ms into a hold cannot
+ *    stop the gesture already running.
+ *
+ * A capture listener above the renderer runs BEFORE any of that, and
+ * `stopPropagation()` in the capture phase ends the event's journey there:
+ * it never descends to the target and never bubbles back up. The listener that
+ * would have panned the canvas is not removed, disabled or raced — it is
+ * simply never reached.
+ *
+ * Three properties this deliberately has, each with a spec:
+ *
+ *  - `touchmove` ONLY. `touchcancel` has to get through, because arming
+ *    dispatches one at the pane so d3 ends its gesture cleanly instead of
+ *    sitting on a live `g.touch0`. An interceptor that swallowed everything
+ *    would eat its own escape hatch.
+ *  - never `preventDefault()`. Suppressing the pan is a propagation decision,
+ *    not a default-action one, and the pane already carries
+ *    `touch-action: none` (design §7.5).
+ *  - `passive: false` is passed explicitly. Chrome makes a `touchmove`
+ *    listener on `document` or `window` passive by DEFAULT, and a passive
+ *    listener that later needed `preventDefault` would fail silently. Stating
+ *    it means the listener behaves as written wherever it is installed.
+ *
+ * No React and no `@xyflow` here on purpose: this is the piece design §7.3
+ * calls the one mechanism no spike has run, so it is testable at its own level
+ * rather than only through a canvas.
+ */
+
+export interface LassoInterceptOptions {
+  /**
+   * Any ancestor of the element d3 is bound to. `.react-flow__renderer` is
+   * itself an ancestor of the pane, so an interceptor on the PANE would be
+   * below the listener it is trying to stop — the hook passes the pane's
+   * `ownerDocument`, which cannot be chosen wrongly.
+   */
+  readonly ancestor: EventTarget;
+  /** Each swallowed event, so the marquee can be drawn from the same stream. */
+  readonly onIntercept?: (event: TouchEvent) => void;
+}
+
+export interface LassoIntercept {
+  /** Removes the listener. Idempotent, and it never removes anyone else's. */
+  readonly release: () => void;
+  readonly active: boolean;
+}
+
+export function installLassoIntercept(options: LassoInterceptOptions): LassoIntercept {
+  const { ancestor, onIntercept } = options;
+  let active = true;
+
+  const handler = (event: Event) => {
+    event.stopPropagation();
+    onIntercept?.(event as TouchEvent);
+  };
+
+  ancestor.addEventListener("touchmove", handler, { capture: true, passive: false });
+
+  return {
+    release() {
+      if (!active) return;
+      active = false;
+      ancestor.removeEventListener("touchmove", handler, { capture: true });
+    },
+    get active() {
+      return active;
+    },
+  };
+}

package/src/interaction/legalTargets.spec.ts

@@ -0,0 +1,304 @@
+/**
+ * Task 3.5. What a finger is allowed to land on.
+ *
+ * The claim is an EQUALITY, not a sample: `legalTargets` returns exactly the
+ * ports `validateConnection` says yes to. So the oracle here is
+ * `validateConnection` itself, run by brute force over every port in the
+ * document, and the fixture is built so that every refusal code in design §4.4
+ * is actually exercised — a set equality over a document where nothing refuses
+ * is an equality between two empty filters.
+ *
+ * `validateConnection`, never `validateDrop`: this runs on the pointer-tick
+ * path, the same one React Flow's `isValidConnection` runs on, and the O(V+E)
+ * cycle rule is a `DropOnlyRule` the type refuses here (design §4.4). A puck
+ * that promised a target the drop then rejected would be worse than no puck.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { ConnectionRule, GraphDocument, GraphSchema, PortRef, PortSpec } from "../model/index";
+import {
+  createGraphSchema,
+  defaultRules,
+  refuseDataTypeMismatch,
+  refuseDirection,
+  refuseDuplicate,
+  refusePortArity,
+  resolvePorts,
+  validateConnection,
+} from "../model/index";
+import { legalTargets, isLegalTarget } from "./legalTargets";
+
+type Kinds = {
+  readonly emit: { readonly note: string };
+  readonly relay: { readonly note: string };
+  readonly sink: { readonly note: string };
+  /** In and out on ONE node, so a self-loop is geometrically possible. */
+  readonly loop: { readonly note: string };
+};
+type Edges = { readonly flow: Record<string, never> };
+
+const noRender = (() => null) as unknown as never;
+
+const port = (spec: PortSpec): PortSpec => spec;
+
+/**
+ * Four kinds chosen so every refusal code has a real port to refuse.
+ *
+ *  - `wrong-direction`: every `out` port is a candidate the enumerator offers
+ *    and direction throws out.
+ *  - `self-loop`: `loop` carries both an in and an out.
+ *  - `port-arity`: `sink.only` is arity "one" and already taken.
+ *  - `duplicate-edge`: `relay.in` already has the very edge under test.
+ *  - `data-type-mismatch`: `relay.typed` takes `text`, the source emits `rows`.
+ *  - `unknown-node` / `unknown-port`: a source that names neither.
+ */
+function schema(rules: readonly ConnectionRule<Kinds, Edges>[] = defaultRules) {
+  return createGraphSchema<Kinds, Edges>({
+    id: "legal-targets-fixture",
+    nodes: {
+      emit: {
+        kind: "emit",
+        render: noRender,
+        defaultData: { note: "" },
+        measure: { width: 190, minHeight: 72 },
+        ports: [port({ id: "rows", side: "right", direction: "out", dataType: "rows" })],
+      },
+      relay: {
+        kind: "relay",
+        render: noRender,
+        defaultData: { note: "" },
+        measure: { width: 190, minHeight: 72 },
+        ports: [
+          port({ id: "in", side: "left", direction: "in", arity: "many", dataType: "rows" }),
+          port({ id: "typed", side: "left", direction: "in", arity: "many", dataType: "text" }),
+          port({ id: "free", side: "left", direction: "in", arity: "many" }),
+          port({ id: "out", side: "right", direction: "out", dataType: "rows" }),
+        ],
+      },
+      sink: {
+        kind: "sink",
+        render: noRender,
+        defaultData: { note: "" },
+        measure: { width: 190, minHeight: 72 },
+        ports: [
+          port({ id: "only", side: "left", direction: "in", arity: "one", dataType: "rows" }),
+          port({ id: "spare", side: "left", direction: "in", arity: "many", dataType: "rows" }),
+        ],
+      },
+      loop: {
+        kind: "loop",
+        render: noRender,
+        defaultData: { note: "" },
+        measure: { width: 190, minHeight: 72 },
+        ports: [
+          port({ id: "self-in", side: "left", direction: "in", arity: "many" }),
+          port({ id: "self-out", side: "right", direction: "out" }),
+        ],
+      },
+    },
+    edges: { flow: { kind: "flow", defaultData: {} } },
+    rules,
+  });
+}
+
+type Doc = GraphDocument<Kinds, Edges>;
+
+function document(): Doc {
+  return {
+    version: 1,
+    nodes: [
+      { id: "e1", kind: "emit", position: { x: 0, y: 0 }, data: { note: "" } },
+      { id: "r1", kind: "relay", position: { x: 260, y: 0 }, data: { note: "" } },
+      { id: "s1", kind: "sink", position: { x: 520, y: 0 }, data: { note: "" } },
+      { id: "l1", kind: "loop", position: { x: 780, y: 0 }, data: { note: "" } },
+    ],
+    edges: [
+      // Makes `r1.in` a DUPLICATE for a drag starting at `e1.rows`.
+      {
+        id: "e1->r1",
+        kind: "flow",
+        source: { node: "e1", port: "rows" },
+        target: { node: "r1", port: "in" },
+        data: {},
+      },
+      // Fills `s1.only`, whose arity is "one".
+      {
+        id: "r1->s1",
+        kind: "flow",
+        source: { node: "r1", port: "out" },
+        target: { node: "s1", port: "only" },
+        data: {},
+      },
+    ],
+  };
+}
+
+/** Every (node, port) pair in the document, in document order. */
+function everyPort(doc: Doc, graph: GraphSchema<Kinds, Edges>): PortRef[] {
+  return doc.nodes.flatMap((node) =>
+    resolvePorts(graph, node).map((spec) => ({ node: node.id, port: spec.id })),
+  );
+}
+
+/** The oracle: filter every port by the rule engine, directly. */
+function bruteForce(
+  doc: Doc,
+  graph: GraphSchema<Kinds, Edges>,
+  source: PortRef,
+  rules?: readonly ConnectionRule<Kinds, Edges>[],
+): PortRef[] {
+  return everyPort(doc, graph).filter(
+    (target) => validateConnection({ document: doc, schema: graph, source, target }, rules).ok,
+  );
+}
+
+const key = (ref: PortRef) => `${ref.node}:${ref.port}`;
+
+describe("the fixture exercises every refusal code, or the equality below is empty", () => {
+  it("produces all five tick-safe codes plus both lookup failures", () => {
+    const doc = document();
+    const graph = schema();
+    const source: PortRef = { node: "e1", port: "rows" };
+    const codeFor = (target: PortRef) => {
+      const verdict = validateConnection({ document: doc, schema: graph, source, target });
+      return verdict.ok ? "ok" : verdict.code;
+    };
+    expect(codeFor({ node: "r1", port: "out" })).toBe("wrong-direction");
+    expect(codeFor({ node: "r1", port: "in" })).toBe("duplicate-edge");
+    expect(codeFor({ node: "r1", port: "typed" })).toBe("data-type-mismatch");
+    expect(codeFor({ node: "s1", port: "only" })).toBe("port-arity");
+    expect(codeFor({ node: "s1", port: "spare" })).toBe("ok");
+    expect(
+      validateConnection({
+        document: doc,
+        schema: graph,
+        source: { node: "l1", port: "self-out" },
+        target: { node: "l1", port: "self-in" },
+      }),
+    ).toMatchObject({ code: "self-loop" });
+    expect(codeFor({ node: "nope", port: "rows" })).toBe("unknown-node");
+    expect(codeFor({ node: "r1", port: "nope" })).toBe("unknown-port");
+  });
+});
+
+describe("legalTargets returns exactly what validateConnection accepts", () => {
+  it("equals the brute-force oracle for every source port in the document", () => {
+    const doc = document();
+    const graph = schema();
+    let checkedNonEmpty = 0;
+    for (const source of everyPort(doc, graph)) {
+      const expected = bruteForce(doc, graph, source).map(key);
+      const actual = legalTargets({ document: doc, schema: graph, source }).map(key);
+      expect(actual, `source ${key(source)}`).toEqual(expected);
+      if (expected.length > 0) checkedNonEmpty += 1;
+    }
+    // An equality between two empty lists proves nothing about the filter.
+    expect(checkedNonEmpty).toBeGreaterThan(0);
+  });
+
+  it("accepts the untyped and the spare port, and nothing the rules refused", () => {
+    const doc = document();
+    const graph = schema();
+    expect(
+      legalTargets({ document: doc, schema: graph, source: { node: "e1", port: "rows" } }).map(key),
+    ).toEqual(["r1:free", "s1:spare", "l1:self-in"]);
+  });
+
+  it("returns nothing for a source that is not a real port", () => {
+    const doc = document();
+    const graph = schema();
+    expect(
+      legalTargets({ document: doc, schema: graph, source: { node: "nope", port: "rows" } }),
+    ).toEqual([]);
+    expect(
+      legalTargets({ document: doc, schema: graph, source: { node: "e1", port: "nope" } }),
+    ).toEqual([]);
+  });
+
+  it("returns nothing for a source that is an INPUT — a connection starts at an output", () => {
+    const doc = document();
+    const graph = schema();
+    expect(
+      legalTargets({ document: doc, schema: graph, source: { node: "r1", port: "in" } }),
+    ).toEqual([]);
+  });
+
+  it("keeps document order, so a candidate list is stable between ticks", () => {
+    const doc = document();
+    const graph = schema();
+    const source: PortRef = { node: "r1", port: "out" };
+    const once = legalTargets({ document: doc, schema: graph, source }).map(key);
+    const twice = legalTargets({ document: doc, schema: graph, source }).map(key);
+    expect(once).toEqual(twice);
+    expect(once).toEqual(bruteForce(doc, graph, source).map(key));
+  });
+});
+
+describe("a port on the source node itself", () => {
+  it("is never returned while a rule refuses self-loops", () => {
+    const doc = document();
+    const graph = schema();
+    const targets = legalTargets({
+      document: doc,
+      schema: graph,
+      source: { node: "l1", port: "self-out" },
+    });
+    expect(targets.some((target) => target.node === "l1")).toBe(false);
+    // …and there IS a same-node input to have returned, so the absence is the
+    // rule biting rather than the fixture having nothing to offer.
+    expect(everyPort(doc, graph).some((ref) => ref.node === "l1" && ref.port === "self-in")).toBe(
+      true,
+    );
+  });
+
+  it("IS returned when the schema's rules allow self-loops", () => {
+    const doc = document();
+    // Every default rule except `refuseSelfLoop`. A schema that wants loops
+    // says so by leaving the rule out; `legalTargets` has no opinion of its own.
+    const graph = schema([
+      refuseDirection,
+      refusePortArity,
+      refuseDuplicate,
+      refuseDataTypeMismatch(),
+    ] as readonly ConnectionRule<Kinds, Edges>[]);
+    const targets = legalTargets({
+      document: doc,
+      schema: graph,
+      source: { node: "l1", port: "self-out" },
+    }).map(key);
+    expect(targets).toContain("l1:self-in");
+    expect(targets).toEqual(
+      bruteForce(doc, graph, { node: "l1", port: "self-out" }, graph.rules).map(key),
+    );
+  });
+});
+
+describe("isLegalTarget is the same answer for one candidate", () => {
+  it("agrees with legalTargets on every port in the document", () => {
+    const doc = document();
+    const graph = schema();
+    const source: PortRef = { node: "e1", port: "rows" };
+    const legal = new Set(legalTargets({ document: doc, schema: graph, source }).map(key));
+    for (const target of everyPort(doc, graph)) {
+      expect(isLegalTarget({ document: doc, schema: graph, source, target }), key(target)).toBe(
+        legal.has(key(target)),
+      );
+    }
+  });
+
+  it("says no to a candidate React Flow snapped to but the rules refuse", () => {
+    // This is the magnetic case: `connectionRadius` is the 44 px hit diameter,
+    // so React Flow will happily snap the drag onto a port the schema refuses.
+    // The puck asks this before it names anything.
+    const doc = document();
+    const graph = schema();
+    expect(
+      isLegalTarget({
+        document: doc,
+        schema: graph,
+        source: { node: "e1", port: "rows" },
+        target: { node: "s1", port: "only" },
+      }),
+    ).toBe(false);
+  });
+});

package/src/interaction/legalTargets.ts

@@ -0,0 +1,91 @@
+/**
+ * Which ports a connection drag is allowed to land on (design §7.4, §4.4).
+ *
+ * `connectionRadius` is the 44 px hit diameter (task 3.4 H5), so React Flow's
+ * magnetism will snap a drag onto whatever handle is nearest — including one
+ * the schema refuses. That is correct behaviour from React Flow and the wrong
+ * thing to SHOW: a puck naming a target the drop then rejects teaches a user
+ * that the affordance lies. So the candidates get filtered through the same
+ * rule engine the drop will use.
+ *
+ * Pure. No React, no DOM, no `@xyflow` — it runs in vitest under Node, and the
+ * same function answers for the puck, for a keyboard flow, and for a headless
+ * consumer that wants to know what its document permits.
+ *
+ * `validateConnection` and never `validateDrop`. This is the pointer-tick path
+ * and `refuseCycle` is O(V+E); the TYPE refuses it here rather than a comment
+ * asking nicely (design §4.4).
+ */
+
+import type {
+  ConnectionRule,
+  EdgeKindDefs,
+  GraphDocument,
+  GraphSchema,
+  NodeKindDefs,
+  PortRef,
+} from "../model/index";
+import { resolvePorts, validateConnection } from "../model/index";
+
+export interface LegalTargetQuery<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly document: GraphDocument<N, E>;
+  readonly schema: GraphSchema<N, E>;
+  /** Where the drag started. An input here yields nothing, by `refuseDirection`. */
+  readonly source: PortRef;
+  /** Defaults to the schema's own rules, which is what the drop will use. */
+  readonly rules?: readonly ConnectionRule<N, E>[];
+}
+
+/**
+ * Every port `validateConnection` accepts for this source, in DOCUMENT order.
+ *
+ * Order is part of the contract: a candidate list that reshuffles between
+ * pointer ticks would make a highlight flicker between two equally legal ports
+ * on the same node.
+ *
+ * A port on the source node is not special-cased. Whether a self-loop is legal
+ * is the schema's call, made by including or omitting `refuseSelfLoop`, and
+ * this function has no opinion of its own — which is what lets a schema that
+ * wants loops have them without a flag here.
+ */
+export function legalTargets<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  query: LegalTargetQuery<N, E>,
+): readonly PortRef[] {
+  const { document, schema, source, rules } = query;
+  const out: PortRef[] = [];
+  for (const node of document.nodes) {
+    for (const spec of resolvePorts(schema, node)) {
+      const target: PortRef = { node: node.id, port: spec.id };
+      if (validateConnection({ document, schema, source, target }, rules).ok) out.push(target);
+    }
+  }
+  return out;
+}
+
+/**
+ * The same answer for ONE candidate, without walking the document.
+ *
+ * What the puck actually calls. React Flow has already told us which handle it
+ * snapped to, so asking about every port to check one is work paid on every
+ * pointer tick of every drag.
+ */
+export function isLegalTarget<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  query: LegalTargetQuery<N, E> & { readonly target: PortRef },
+): boolean {
+  const { document, schema, source, target, rules } = query;
+  return validateConnection({ document, schema, source, target }, rules).ok;
+}
+
+/**
+ * React Flow's magnetic candidates, minus the ones the rules refuse.
+ *
+ * Order is the caller's, not the document's: React Flow hands these back
+ * sorted by distance, and re-sorting them into document order would throw away
+ * the "nearest" the magnetism just computed.
+ */
+export function filterLegalCandidates<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  candidates: readonly PortRef[],
+  query: LegalTargetQuery<N, E>,
+): readonly PortRef[] {
+  return candidates.filter((target) => isLegalTarget({ ...query, target }));
+}