@multiplatform.one/node-graph 7.7.2

package/src/nodes/nodeMeasure.ts

@@ -0,0 +1,216 @@
+/**
+ * The GraphNode measure recipe — pure. No React, no DOM, no `@xyflow`.
+ *
+ * A node is a CONTAINER, not a control (design §11 Size). Everything here
+ * exists to keep it off the control-height ladder: the width rides a per-kind
+ * table, the radius caps at the node's own padding, and the minimum height is
+ * floored by how many ports have to fit down one edge.
+ *
+ * Pure on purpose. `graphNode.spec.ts` runs it in Node with no renderer, so
+ * the laws are falsifiable before a pixel exists.
+ */
+
+import {
+  capContainerRadius,
+  type Knobs,
+  MIN_PRESS_TARGET,
+  resolveRadiusForPart,
+} from "@multiplatform.one/theme";
+
+export type GraphNodeSizeKnob = Knobs["size"];
+export type GraphNodeSpaceKnob = Knobs["space"];
+export type GraphNodeRadiusKnob = Knobs["borderRadius"];
+
+export type GraphPortSide = "left" | "right" | "top" | "bottom";
+
+/**
+ * The structural subset of `PortSpec` this module needs to measure a node.
+ *
+ * TODO(task 1.3): replace with `PortSpec` from `../model` once the schema
+ * lands. It is declared structurally compatible on purpose — `PortSpec` adds
+ * `index`, `dataType` and `arity`, none of which change a measurement — so the
+ * swap is an import change, not a rewrite.
+ */
+export interface GraphNodePort {
+  readonly id: string;
+  readonly side: GraphPortSide;
+  readonly direction: "in" | "out";
+  readonly label?: string;
+}
+
+/** `NodeKindSpec.measure` (design §4.3): width fixed per kind, height knob-driven. */
+export interface GraphNodeMeasure {
+  readonly width: number;
+  readonly minHeight: number;
+}
+
+/**
+ * The default per-kind measure table (design §11 Size: "default 172 / 190 / 216").
+ *
+ * A kind that declares its own `measure` overrides this entirely; the table is
+ * what an undeclared kind falls back to. `minHeight` anchors on design §5's
+ * measured node heights (62 px compact, 72 px default) with `large` one step
+ * above, rather than a number invented here.
+ */
+export const defaultNodeMeasure: Record<GraphNodeSizeKnob, GraphNodeMeasure> = {
+  small: { width: 172, minHeight: 62 },
+  medium: { width: 190, minHeight: 72 },
+  large: { width: 216, minHeight: 84 },
+};
+
+/**
+ * Container padding in px per `space` stop.
+ *
+ * Mirrors `panelPaddingPxMap` in `resolveKnobs.ts`, which is private to that
+ * module — the resolver mirrors the same numbers for the same reason (it stays
+ * pure, so it cannot read live tokens). `graphNode.spec.ts` pins this mirror
+ * against `capContainerRadius(..., "full")`, which returns the padding px
+ * itself, so a change in the resolver fails the spec here instead of drifting.
+ */
+export const nodePanelPaddingPx: Record<GraphNodeSpaceKnob, number> = {
+  small: 13,
+  medium: 18,
+  large: 32,
+};
+
+/**
+ * Vertical pitch between two ports on the same node edge.
+ *
+ * Coarse pointers get the press floor itself (design §7.1 H4: two ports closer
+ * than the hit diameter would have overlapping discs and the wrong one would
+ * win). Fine pointers get 24, which is H3's fine-pointer hit diameter and is
+ * already above every painted stop (8 / 10 / 12), so the pitch never has to
+ * consult the painted ladder — that is what keeps this module independent of
+ * `handleGeometry.ts` rather than circular with it.
+ */
+export const FINE_PORT_PITCH = 24;
+
+export function portSpacing(opts: { readonly coarsePointer: boolean }): number {
+  return opts.coarsePointer ? MIN_PRESS_TARGET : FINE_PORT_PITCH;
+}
+
+/**
+ * §11 Size, GraphNode frame: `remap` to `NodeKindSpec.measure.width`.
+ *
+ * The size knob reaches the width only through the per-kind table. It never
+ * reaches the control-height recipe (`knobProps.control.height`), because a
+ * node is a container and a container that steps with a control ladder is a
+ * control wearing a frame.
+ */
+export function graphNodeWidth(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly measure?: Partial<GraphNodeMeasure>;
+}): number {
+  return opts.measure?.width ?? defaultNodeMeasure[opts.size].width;
+}
+
+/**
+ * How many ports stack down the tallest vertical edge.
+ *
+ * Height crowding is per EDGE, not per node: `left` and `right` ports stack
+ * vertically and can collide with their own side's neighbours, never with the
+ * opposite side's. `top` / `bottom` ports stack horizontally and constrain
+ * width, so they do not enter a height floor at all.
+ */
+export function verticalPortCrowd(ports: readonly GraphNodePort[]): number {
+  let left = 0;
+  let right = 0;
+  for (const port of ports) {
+    if (port.side === "left") left += 1;
+    else if (port.side === "right") right += 1;
+  }
+  return Math.max(left, right);
+}
+
+/**
+ * §7.1 H4, the floor half: a node is tall enough for every port on its
+ * busiest edge to be a real target, instead of ports silently stealing hits
+ * from each other.
+ */
+export function graphNodeMinHeight(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly ports: readonly GraphNodePort[];
+  readonly portSpacingPx: number;
+  readonly measure?: Partial<GraphNodeMeasure>;
+}): number {
+  const declared = opts.measure?.minHeight ?? defaultNodeMeasure[opts.size].minHeight;
+  return Math.max(declared, verticalPortCrowd(opts.ports) * opts.portSpacingPx);
+}
+
+/**
+ * §11 Radius, GraphNode frame: CONTAINER-CAP. The Tamagui value to paint —
+ * the radius token while it fits inside the node's own padding, the padding px
+ * once it would not.
+ */
+export function graphNodeRadius(knobs: {
+  readonly borderRadius: GraphNodeRadiusKnob;
+  readonly space: GraphNodeSpaceKnob;
+}): string | number {
+  return capContainerRadius(knobs.borderRadius, knobs.space);
+}
+
+/**
+ * Radius TOKEN → px.
+ *
+ * Mirrors `borderRadiusMap` / `radiusPxMap` in `resolveKnobs.ts`, both private
+ * to that module. Needed because `capContainerRadius` returns either a token
+ * (`"$4"`) or a px number, and a rendered node has to report ONE number.
+ * `graphNode.spec.ts` pins the whole map against the doctrine table at every
+ * stop and space, so a token that stops meaning what it says fails there.
+ */
+export const nodeRadiusTokenPx: Readonly<Record<string, number>> = {
+  $0: 0,
+  $2: 5,
+  $4: 9,
+  $6: 16,
+  $12: 50,
+};
+
+/**
+ * px for whatever `capContainerRadius` resolved to. A number is already the
+ * capped px; a token goes through the mirror above.
+ */
+export function containerRadiusPx(value: string | number): number {
+  if (typeof value === "number") return value;
+  const px = nodeRadiusTokenPx[value];
+  if (px === undefined) {
+    throw new Error(
+      `containerRadiusPx: "${value}" is not a radius token this module mirrors — add it to nodeRadiusTokenPx beside the resolver's borderRadiusMap`,
+    );
+  }
+  return px;
+}
+
+/**
+ * The same radius in px, resolved through the DG-RAD doctrine table rather
+ * than the resolver.
+ *
+ * Two independent implementations of one law: `graphNodeRadius` goes through
+ * `capContainerRadius` (resolver), this goes through `resolveRadiusForPart`
+ * (doctrine). `graphNode.spec.ts` asserts they agree at every stop, so a
+ * doctrine/resolver drift is a failing test rather than a corner that quietly
+ * clips a child.
+ */
+export function graphNodeRadiusPx(knobs: {
+  readonly borderRadius: GraphNodeRadiusKnob;
+  readonly space: GraphNodeSpaceKnob;
+}): number {
+  return resolveRadiusForPart({
+    radiusClass: "CONTAINER-CAP",
+    stop: knobs.borderRadius,
+    paddingPx: nodePanelPaddingPx[knobs.space],
+  }).px;
+}
+
+/** The complete measure a node is seeded with BEFORE first paint (design §5). */
+export function graphNodeMeasure(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly ports: readonly GraphNodePort[];
+  readonly portSpacingPx: number;
+  readonly measure?: Partial<GraphNodeMeasure>;
+}): GraphNodeMeasure {
+  return {
+    width: graphNodeWidth(opts),
+    minHeight: graphNodeMinHeight(opts),
+  };
+}

package/src/nodes/overviewNode.tsx

@@ -0,0 +1,71 @@
+/**
+ * The overview body: one plain box with the resolved background (design §5).
+ *
+ * At 500 nodes and zoom 0.2, a Tamagui body per node is 500 knob resolutions,
+ * 500 subtrees and 500 observer callbacks to paint something the size of a
+ * postage stamp. This is what a consumer swaps in instead, and it is also what
+ * the merged single-path edge layer will sit behind in v1.1.
+ *
+ * The load-bearing part is not the div, it is the MEASURE. Width and minimum
+ * height come from `nodeMeasure.ts` — the same recipe `GraphNode` uses, given
+ * the same knobs and the same ports — so swapping the body cannot change the
+ * node's box, and React Flow's per-node `ResizeObserver` has nothing to report.
+ * A "small grey rectangle" here would move every edge endpoint on the canvas
+ * the moment a user zoomed out, which is the failure design §5 is written
+ * against.
+ *
+ * `lod.spec.tsx` asserts the box against `GraphNode`'s rather than against a
+ * number, so the two cannot drift.
+ */
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { YStack } from "tamagui";
+import type { GraphNodeMeasure, GraphNodePort, GraphNodeSizeKnob } from "./nodeMeasure";
+import { graphNodeMinHeight, graphNodeWidth, portSpacing } from "./nodeMeasure";
+
+export interface OverviewNodeProps {
+  readonly id: string;
+  /** Same ports the detail body would render. They set the height floor. */
+  readonly ports?: readonly GraphNodePort[];
+  /** Semantic intent — reaches the resolver, never a colour prop. */
+  readonly intent?: string;
+  readonly selected?: boolean;
+  /** `NodeKindSpec.measure`; falls back to the per-kind default table. */
+  readonly measure?: Partial<GraphNodeMeasure>;
+  /** true on a touch surface — widens the port pitch, raising the floor. */
+  readonly coarsePointer?: boolean;
+}
+
+export function OverviewNode({
+  id,
+  ports,
+  intent,
+  selected = false,
+  measure,
+  coarsePointer = false,
+}: OverviewNodeProps) {
+  // The same resolver call the detail body makes, so the fill is the fill the
+  // user was just looking at rather than a second grey invented here.
+  const { knobProps } = useResolvedKnobs({ component: "GraphNode", intent });
+  const size = knobProps.size as GraphNodeSizeKnob;
+  const portSpacingPx = portSpacing({ coarsePointer });
+
+  return (
+    <YStack
+      data-graph-node={id}
+      data-graph-node-render-mode="overview"
+      data-graph-node-overview=""
+      data-graph-node-width={String(graphNodeWidth({ size, measure }))}
+      {...knobProps.surface}
+      {...knobProps.containerRadius}
+      width={graphNodeWidth({ size, measure })}
+      minHeight={graphNodeMinHeight({ size, ports: ports ?? [], portSpacingPx, measure })}
+      position="relative"
+      // §7.1 H6, and it matters more here, not less: the ports are still
+      // mounted on the node in overview mode, so a clipping frame would eat
+      // them exactly as it would in detail.
+      overflow="visible"
+      opacity={selected ? 1 : 0.9}
+    />
+  );
+}

package/src/packageShape.spec.ts

@@ -0,0 +1,145 @@
+/**
+ * The package's own shape is load-bearing, so it is specced like code.
+ *
+ * Three of these four assertions are about a resolver nobody can see failing
+ * until a bundle breaks: Metro picks the FIRST condition it recognises and
+ * never reconsiders `source` or `default` (MPO-185), and `./dom` has to stay
+ * pinned to source on every condition because storybook-expo's
+ * `resolveWorkspaceNativeMain` prefers `dist/esm/index.native.js` whenever it
+ * exists and a compiled copy would shadow the `'use dom'` directive.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** What Metro's file-based fallback accepts at `<pkg>/<subpath>` (lint.mjs:873). */
+const metroFallbackExtensions = ["ts", "tsx", "js", "jsx", "mjs", "cjs"];
+
+/**
+ * The condition names Metro matches per platform when
+ * `resolver.unstable_enablePackageExports` is on (lint.mjs:868). Neither
+ * `source` nor `types` is ever in the set.
+ */
+const metroPlatformConditions = {
+  ios: new Set(["react-native", "import", "require", "default"]),
+  web: new Set(["browser", "import", "require", "default"]),
+};
+
+type ExportTarget = string | { [condition: string]: ExportTarget } | ExportTarget[];
+
+interface PackageJson {
+  readonly dependencies?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+  readonly exports: Record<string, ExportTarget>;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+let pkg: PackageJson;
+
+beforeAll(async () => {
+  pkg = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")) as PackageJson;
+});
+
+/** Every leaf string in an exports entry, whatever the condition nesting. */
+function targetLeaves(target: ExportTarget): string[] {
+  if (typeof target === "string") return [target];
+  if (Array.isArray(target)) return target.flatMap(targetLeaves);
+  return Object.values(target).flatMap(targetLeaves);
+}
+
+function declaresSourceCondition(target: ExportTarget): boolean {
+  if (typeof target === "string") return false;
+  if (Array.isArray(target)) return target.some(declaresSourceCondition);
+  return Object.entries(target).some(
+    ([condition, value]) => condition === "source" || declaresSourceCondition(value),
+  );
+}
+
+/** The first target Metro would pick for one condition set, in declaration order. */
+function metroExportTarget(target: ExportTarget, conditions: Set<string>): string | null {
+  if (typeof target === "string") return target;
+  if (Array.isArray(target)) {
+    for (const item of target) {
+      const hit = metroExportTarget(item, conditions);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  for (const [condition, value] of Object.entries(target)) {
+    if (!conditions.has(condition)) continue;
+    const hit = metroExportTarget(value, conditions);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function hasMetroFallback(subpath: string): boolean {
+  const base = path.join(packageRoot, subpath.replace(/^\.\//, ""));
+  if (metroFallbackExtensions.some((ext) => existsSync(`${base}.${ext}`))) return true;
+  if (existsSync(path.join(base, "package.json"))) return true;
+  return metroFallbackExtensions.some((ext) => existsSync(path.join(base, `index.${ext}`)));
+}
+
+describe("package shape", () => {
+  it('exports["."] declares a source condition', () => {
+    expect(declaresSourceCondition(pkg.exports["."])).toBe(true);
+  });
+
+  it("declares the model, dom, dom-inner, demo and metro subpaths", () => {
+    expect(Object.keys(pkg.exports)).toEqual(
+      expect.arrayContaining(["./model", "./dom", "./dom-inner", "./demo", "./metro"]),
+    );
+  });
+
+  /**
+   * `./dom-inner` is what an APP's `'use dom'` entry imports (design §9.3), so
+   * it lives under the same pin as `./dom`: every runtime condition on source.
+   */
+  /**
+   * `./demo` is pinned to source too, and for a reason neither of the others
+   * has: it must be the SAME MODULE INSTANCE the canvas's inner tree imports.
+   * An app's `'use dom'` entry supplies the schema by value, and a schema built
+   * from `dist/` would carry a second copy of `GraphNode` and `GraphPort` —
+   * Tamagui `styled()` components from a different build, rendering inside a
+   * provider from this one. One bundle, two node implementations.
+   */
+  it("resolves ./dom, ./dom-inner and ./demo to a path under src/ on every condition", () => {
+    for (const subpath of ["./dom", "./dom-inner", "./demo"]) {
+      const leaves = targetLeaves(pkg.exports[subpath]);
+      expect(leaves.length, subpath).toBeGreaterThan(0);
+      for (const leaf of leaves) {
+        // `types` may point at the emitted declaration; every runtime condition
+        // must stay on source, or the "use dom" directive has to survive esbuild
+        // and nobody has proven it does.
+        if (leaf.startsWith("./types/")) continue;
+        expect(leaf, subpath).toMatch(/^\.\/src\//);
+      }
+    }
+  });
+
+  it("keeps @multiplatform.one/components an optional peer, never a dependency", () => {
+    expect(pkg.peerDependencies?.["@multiplatform.one/components"]).toBeDefined();
+    expect(pkg.dependencies?.["@multiplatform.one/components"]).toBeUndefined();
+    expect(pkg.devDependencies?.["@multiplatform.one/components"]).toBeUndefined();
+  });
+
+  it("gives every dist-resolving subpath a Metro file fallback", () => {
+    const missing: string[] = [];
+    for (const [subpath, target] of Object.entries(pkg.exports)) {
+      if (subpath === "." || !subpath.startsWith("./") || subpath.includes("*")) continue;
+      if (hasMetroFallback(subpath)) continue;
+      for (const [platform, conditions] of Object.entries(metroPlatformConditions)) {
+        const resolved = metroExportTarget(target, conditions);
+        if (!resolved?.startsWith("./dist/")) continue;
+        missing.push(`"${subpath}" resolves to ${resolved} on ${platform}, which is never built`);
+        break;
+      }
+    }
+    expect(missing).toEqual([]);
+  });
+});

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

@@ -0,0 +1,242 @@
+/**
+ * Task 3.5, the rendered half.
+ *
+ * The decision — which candidate is worth naming — is a pure function and is
+ * asserted as one. What is left for a render is the two things a pure function
+ * cannot say: that the puck reads REACT FLOW'S OWN connection state rather
+ * than a shape we invented, and that it does not ride the pan/zoom matrix.
+ *
+ * So the connection is driven through the real store (`useStoreApi`), not a
+ * mocked `useStore`. A mock would assert that our selector agrees with our
+ * mock, which is the failure mode this file exists to avoid: the puck's whole
+ * job is to be right about a library's state.
+ */
+
+import { Preset, Surface } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { PortRef } from "../model/index";
+import { ConnectionPuck, connectionPuckLabel } from "./ConnectionPuck";
+import { demoGraphSchema } from "./demoNodeBody";
+import { demoDocument } from "./fixtures";
+import { NodeGraphWeb } from "./NodeGraphWeb";
+import { useStoreApi } from "./xy";
+
+afterEach(cleanup);
+
+const doc = demoDocument;
+const schema = demoGraphSchema;
+
+/**
+ * The demo fixture, in the terms this file needs:
+ *   a (source) -- rows -->  b (transform) -- ok / err -->  c (sink)
+ * and `a.rows -> b.in` ALREADY EXISTS, which is what makes `b.in` a duplicate
+ * and therefore the illegal candidate every case below leans on.
+ */
+const fromA: PortRef = { node: "a", port: "rows" };
+
+describe("connectionPuckLabel", () => {
+  const base = { document: doc(), schema: schema() };
+
+  it("is null when no connection is in progress", () => {
+    expect(connectionPuckLabel({ ...base, source: null, candidate: null })).toBeNull();
+  });
+
+  it("names the candidate node and port when the candidate is legal", () => {
+    const label = connectionPuckLabel({
+      ...base,
+      source: fromA,
+      candidate: { node: "c", port: "in" },
+    });
+    expect(label).toMatchObject({ legal: true, target: "c:in" });
+    expect(label?.text).toContain("c");
+    // The PORT's label, not its id, when the schema gives it one.
+    expect(label?.text).toContain("rows");
+  });
+
+  it("falls back to naming the source when the candidate is refused", () => {
+    // `a.rows -> b.in` is already in the document, so it is a duplicate.
+    const label = connectionPuckLabel({
+      ...base,
+      source: fromA,
+      candidate: { node: "b", port: "in" },
+    });
+    expect(label).toMatchObject({ legal: false, target: "" });
+    expect(label?.text).toContain("from");
+    expect(label?.text).toContain("a");
+  });
+
+  it("falls back the same way over open canvas, with no candidate at all", () => {
+    const label = connectionPuckLabel({ ...base, source: fromA, candidate: null });
+    expect(label).toMatchObject({ legal: false, target: "" });
+  });
+
+  it("uses a consumer's node name when one is supplied", () => {
+    const label = connectionPuckLabel({
+      ...base,
+      source: fromA,
+      candidate: { node: "c", port: "in" },
+      nodeLabel: (id) => (id === "c" ? "Warehouse" : undefined),
+    });
+    expect(label?.text).toContain("Warehouse");
+    expect(label?.text).not.toContain("c /");
+  });
+
+  it("falls back to the port id when the schema declares no label", () => {
+    const label = connectionPuckLabel({
+      ...base,
+      source: fromA,
+      candidate: { node: "nope", port: "mystery" },
+    });
+    // An unresolvable candidate is not legal, so the SOURCE is named — and the
+    // source resolves, so this is still a real name rather than an id soup.
+    expect(label?.legal).toBe(false);
+  });
+});
+
+/**
+ * Drives React Flow's own connection state, then reads what the puck did.
+ *
+ * `fromHandle` / `toHandle` carry more fields on a real drag; the puck reads
+ * `nodeId` and `id`, and constructing a full `Handle` would be theatre.
+ */
+function DriveConnection({ to }: { to: { nodeId: string; id: string } | null }) {
+  const store = useStoreApi();
+  useEffect(() => {
+    store.setState({
+      connection: {
+        inProgress: true,
+        isValid: null,
+        from: { x: 0, y: 0 },
+        to: { x: 0, y: 0 },
+        fromPosition: "right",
+        toPosition: "left",
+        fromNode: null,
+        toNode: null,
+        fromHandle: { nodeId: "a", id: "rows", type: "source" },
+        toHandle: to ? { ...to, type: "target" } : null,
+      },
+    } as never);
+  }, [store, to]);
+  return null;
+}
+
+/**
+ * The canvas mounts its OWN puck (`connectionPuck` defaults to true), so this
+ * adds only the driver. Rendering a second `<ConnectionPuck>` as a child is
+ * what the "exactly one div" case below refuses, and it caught precisely that
+ * mistake in this file before the case was written down.
+ */
+function mountWithConnection(to: { nodeId: string; id: string } | null) {
+  return renderWithProviders(
+    <Preset cascade={false}>
+      <Surface size="medium" density="comfortable">
+        <NodeGraphWeb schema={schema()} defaultDocument={doc()}>
+          <DriveConnection to={to} />
+        </NodeGraphWeb>
+      </Surface>
+    </Preset>,
+  );
+}
+
+function puckOf(container: HTMLElement): HTMLElement | null {
+  return container.querySelector("[data-graph-connection-puck]");
+}
+
+describe("the puck reads React Flow's own connection state", () => {
+  it("renders nothing while no connection is in progress", () => {
+    const { container } = renderWithProviders(
+      <Preset cascade={false}>
+        <Surface size="medium" density="comfortable">
+          <NodeGraphWeb schema={schema()} defaultDocument={doc()} />
+        </Surface>
+      </Preset>,
+    );
+    expect(puckOf(container)).toBeNull();
+  });
+
+  it("names the legal candidate the store snapped to", () => {
+    const { container } = mountWithConnection({ nodeId: "c", id: "in" });
+    const puck = puckOf(container);
+    expect(puck).not.toBeNull();
+    expect(puck?.getAttribute("data-graph-puck-legal")).toBe("true");
+    expect(puck?.getAttribute("data-graph-puck-target")).toBe("c:in");
+    expect(puck?.textContent).toContain("c");
+  });
+
+  it("refuses to name a candidate the rules reject, even though React Flow snapped to it", () => {
+    // The magnetic case, and the reason the filter exists: `connectionRadius`
+    // is the 44 px hit diameter, so a finger 20 px off a duplicate port still
+    // snaps to it. The puck must not promise what the drop will refuse.
+    const { container } = mountWithConnection({ nodeId: "b", id: "in" });
+    const puck = puckOf(container);
+    expect(puck?.getAttribute("data-graph-puck-legal")).toBe("false");
+    expect(puck?.getAttribute("data-graph-puck-target")).toBe("");
+  });
+
+  it("is exactly ONE div, however many ports the graph has", () => {
+    const { container } = mountWithConnection({ nodeId: "c", id: "in" });
+    expect(container.querySelectorAll("[data-graph-connection-puck]")).toHaveLength(1);
+  });
+
+  it("can be turned off, for a consumer that draws its own", () => {
+    const { container } = renderWithProviders(
+      <Preset cascade={false}>
+        <Surface size="medium" density="comfortable">
+          <NodeGraphWeb schema={schema()} defaultDocument={doc()} connectionPuck={false}>
+            <DriveConnection to={{ nodeId: "c", id: "in" }} />
+          </NodeGraphWeb>
+        </Surface>
+      </Preset>,
+    );
+    expect(puckOf(container)).toBeNull();
+  });
+
+  it("mounted a second time renders a second div — which is why the canvas owns it", () => {
+    const { container } = renderWithProviders(
+      <Preset cascade={false}>
+        <Surface size="medium" density="comfortable">
+          <NodeGraphWeb schema={schema()} defaultDocument={doc()} connectionPuck={false}>
+            <DriveConnection to={{ nodeId: "c", id: "in" }} />
+            <ConnectionPuck document={doc()} schema={schema()} />
+          </NodeGraphWeb>
+        </Surface>
+      </Preset>,
+    );
+    expect(container.querySelectorAll("[data-graph-connection-puck]")).toHaveLength(1);
+  });
+});
+
+/**
+ * Counter-scaled, measured rather than claimed.
+ *
+ * happy-dom lays nothing out, so a `getBoundingClientRect` here is zeros and
+ * would pass whatever the puck did. What IS observable is placement: React
+ * Flow's children are siblings of `.react-flow__viewport`, and only the
+ * viewport carries the pan/zoom matrix. An element outside it cannot scale
+ * with the graph, and an element inside it cannot help but. So the assertion
+ * is the DOM relationship, which is the mechanism, not the symptom. The
+ * symptom — the puck staying the same physical size through a pinch — is the
+ * device arm's, and it is recorded as pending.
+ */
+describe("the puck does not ride the pan/zoom matrix", () => {
+  it("renders outside .react-flow__viewport", () => {
+    const { container } = mountWithConnection({ nodeId: "c", id: "in" });
+    const puck = puckOf(container);
+    expect(puck).not.toBeNull();
+    expect(puck?.closest(".react-flow__viewport")).toBeNull();
+  });
+
+  it("still renders inside the canvas root, so it moves with the graph's box", () => {
+    const { container } = mountWithConnection({ nodeId: "c", id: "in" });
+    expect(puckOf(container)?.closest(".react-flow")).not.toBeNull();
+  });
+
+  it("applies no scale of its own — a 1/zoom here would shrink it when zooming IN", () => {
+    const { container } = mountWithConnection({ nodeId: "c", id: "in" });
+    const transform = puckOf(container)?.style.transform ?? "";
+    expect(transform).not.toContain("scale");
+  });
+});