@multiplatform.one/node-graph 7.7.2

package/src/nodes/Overview.stories.tsx

@@ -0,0 +1,237 @@
+/**
+ * `NodeGraph/Overview` — 500 nodes, and the crossover you have to watch.
+ *
+ * The thing to check is not that the graph looks different below zoom 0.35.
+ * It is that NOTHING MOVES when it does. React Flow 12 installs a per-node
+ * `ResizeObserver`, so a level of detail that changed a node's height would
+ * re-measure every node on every zoom tick and drag every attached edge
+ * endpoint with it (design §5). At 500 nodes that is a canvas that shivers
+ * whenever a user zooms.
+ *
+ * So: zoom slowly through 0.35 and watch an edge endpoint. It must stay welded
+ * to its port. `lod.spec.tsx` asserts the CAUSE — the element tree is identical
+ * across modes and the declared box does not change — because happy-dom lays
+ * nothing out and cannot measure the effect. This story is where the effect is
+ * checked, in a browser, on the number of nodes that makes it visible.
+ *
+ * The readout above each canvas prints React Flow's OWN measured handle
+ * positions and node height for one node, so the check is a readable number on
+ * both sides of the crossover rather than a squint at a pixel.
+ */
+
+import { Preset, Surface } from "@multiplatform.one/theme";
+import { useState } from "react";
+import { Label, SizableText, Switch, View, XStack, YStack } from "tamagui";
+import type { BuiltinEdgeData } from "../edges/edgeKinds";
+import type { GraphDocument } from "../model/index";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import type { DemoNodeData } from "../react-flow/fixtures";
+import { NodeGraphWeb } from "../react-flow/NodeGraphWeb";
+import { Background, Controls, MiniMap, useStore } from "../react-flow/xy";
+import { defaultOverviewZoom, lodForZoom } from "./lod";
+
+export default {
+  title: "NodeGraph/Overview",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Level of detail at 500 nodes. Below overviewZoom (0.35) node children fade to opacity 0; they never unmount, so the box keeps the same height and React Flow's per-node ResizeObserver has nothing to chase. Zoom through the crossover and watch an edge endpoint: it must not move.",
+      },
+    },
+  },
+};
+
+type Doc = GraphDocument<DemoNodeData, BuiltinEdgeData>;
+
+/**
+ * 500 nodes on a 25-wide grid, chained into a long edge list.
+ *
+ * Deterministic, not random: a story whose graph changes between reloads
+ * cannot be compared against a screenshot from five minutes ago.
+ */
+function bigDocument(count = 500): Doc {
+  const kinds = ["source", "transform", "sink"] as const;
+  const perRow = 25;
+  const nodes = Array.from({ length: count }, (_, index) => {
+    const kind = kinds[index % kinds.length];
+    const data =
+      kind === "source"
+        ? { table: `orders_${index}` }
+        : kind === "transform"
+          ? { expression: `row => row.${index}` }
+          : { target: `warehouse_${index}` };
+    return {
+      id: `n${index}`,
+      kind,
+      position: { x: (index % perRow) * 300, y: Math.floor(index / perRow) * 220 },
+      data,
+    } as Doc["nodes"][number];
+  });
+
+  const edgeKinds = ["flow", "data", "error", "conditional"] as const;
+  const edges: Doc["edges"][number][] = [];
+  for (let index = 0; index + 1 < count; index += 1) {
+    const from = nodes[index];
+    const to = nodes[index + 1];
+    const sourcePort = from.kind === "source" ? "rows" : from.kind === "transform" ? "ok" : null;
+    if (!sourcePort) continue;
+    edges.push({
+      id: `${from.id}->${to.id}`,
+      kind: edgeKinds[edges.length % edgeKinds.length],
+      source: { node: from.id, port: sourcePort },
+      target: { node: to.id, port: "in" },
+      data: {},
+    } as Doc["edges"][number]);
+  }
+  return { version: 1, nodes, edges };
+}
+
+const bigDoc = bigDocument(500);
+const schema = demoGraphSchema();
+
+/**
+ * The live zoom, the mode it resolves to, and the handle positions React Flow
+ * has MEASURED for one node.
+ *
+ * `handleBounds` is what every edge endpoint is computed from, so reading it
+ * directly is reading the thing that must not move — rather than reading a
+ * pixel and hoping.
+ */
+function Readout({ nodeId }: { nodeId: string }) {
+  const zoom = useStore((state) => state.transform[2]);
+  const bounds = useStore((state) => {
+    const node = state.nodeLookup.get(nodeId);
+    const handles = [
+      ...(node?.internals.handleBounds?.source ?? []),
+      ...(node?.internals.handleBounds?.target ?? []),
+    ];
+    return handles
+      .map((handle) => `${handle.id ?? "?"} ${Math.round(handle.x)},${Math.round(handle.y)}`)
+      .join("  |  ");
+  });
+  const height = useStore((state) => state.nodeLookup.get(nodeId)?.measured?.height ?? 0);
+  return (
+    // Pinned as a panel rather than left to flow: as a bare row it rendered
+    // over the canvas at the top-left and the handle numbers — the whole point
+    // of the readout — were clipped off the right edge.
+    <XStack
+      position="absolute"
+      top={0}
+      left={0}
+      right={0}
+      zIndex={6}
+      gap="$5"
+      padding="$2"
+      alignItems="center"
+      flexWrap="wrap"
+      backgroundColor="$background"
+      borderBottomWidth={1}
+      borderColor="$borderColor"
+      pointerEvents="none"
+    >
+      <SizableText size="$2" fontWeight="600">
+        zoom {zoom.toFixed(3)}
+      </SizableText>
+      <SizableText size="$2" fontWeight="600">
+        mode {lodForZoom(zoom, defaultOverviewZoom)}
+      </SizableText>
+      <SizableText size="$2">
+        {nodeId} height {Math.round(height)}
+      </SizableText>
+      <SizableText size="$2" opacity={0.7}>
+        handles {bounds || "not measured yet"}
+      </SizableText>
+    </XStack>
+  );
+}
+
+/**
+ * 500 nodes, culling on, the readout pinned above the canvas.
+ *
+ * Zoom out past 0.35 and back. `height` and `handles` must print the same
+ * numbers on both sides of the crossover; `mode` is the only line that changes.
+ */
+export const main = {
+  name: "Main",
+  // The Preset CASCADES. `cascade={false}` starts from `defaultKnobs` and merges
+  // only `overrides`, so on a story that passes none it replaces the whole knob
+  // set and discards every Storybook global — the page then paints one fixed
+  // signature at every stop, which reads exactly like a component ignoring its
+  // knobs. The milestone-1 fuzz found that on `GraphPort → Crowded`. A fuzz PAGE
+  // may pin, because it passes `overrides` and the page is the evidence; an
+  // ordinary story may not. `Surface size="medium"` stays: it is the size
+  // AUTHORITY over the knob (LC-68), which is what keeps the readout comparable
+  // between reloads, and it is why `size` is not fuzzable here.
+  render: () => (
+    <Preset>
+      <Surface size="medium" density="comfortable">
+        <YStack gap="$3" padding="$3">
+          <View width="100%" height={620}>
+            <NodeGraphWeb schema={schema} defaultDocument={bigDoc}>
+              <Readout nodeId="n1" />
+              <Background />
+              <Controls />
+              <MiniMap pannable zoomable />
+            </NodeGraphWeb>
+          </View>
+          <SizableText size="$2" opacity={0.7}>
+            500 nodes, 333 edges. Zoom through 0.35 with the controls or a pinch and watch the
+            handle numbers: they must not move. The bodies fade; the boxes do not resize.
+          </SizableText>
+        </YStack>
+      </Surface>
+    </Preset>
+  ),
+};
+
+/**
+ * The crossover with the threshold under your thumb.
+ *
+ * Raising `overviewZoom` to 1 puts the whole canvas in overview at ordinary
+ * zoom, which is the cheapest way to see the fade without pinching — and the
+ * readout still has to print the same height.
+ */
+export const crossover = {
+  name: "Crossover",
+  render: () => {
+    const [high, setHigh] = useState(false);
+    return (
+      <Preset>
+        <Surface size="medium" density="comfortable">
+          <YStack gap="$3" padding="$3">
+            <XStack gap="$2" alignItems="center">
+              <Switch
+                id="overview-zoom"
+                size="$2"
+                checked={high}
+                onCheckedChange={(v) => setHigh(Boolean(v))}
+              >
+                <Switch.Thumb />
+              </Switch>
+              <Label htmlFor="overview-zoom" size="$2">
+                overviewZoom 1 (everything is overview) instead of {defaultOverviewZoom}
+              </Label>
+            </XStack>
+            <View width="100%" height={560}>
+              <NodeGraphWeb
+                schema={schema}
+                defaultDocument={bigDoc}
+                overviewZoom={high ? 1 : defaultOverviewZoom}
+              >
+                <Readout nodeId="n1" />
+                <Controls />
+              </NodeGraphWeb>
+            </View>
+            <SizableText size="$2" opacity={0.7}>
+              Flip the switch and read the height. The node fades to a plain box and the number does
+              not change — that is the invariant, and it is why the children fade instead of
+              unmounting.
+            </SizableText>
+          </YStack>
+        </Surface>
+      </Preset>
+    );
+  },
+};

package/src/nodes/handleGeometry.spec.ts

@@ -0,0 +1,161 @@
+/**
+ * Task 1.9, the pure half: H1, H3 and H4 from design §7.1.
+ *
+ * The point of separating these from `GraphPort.spec.tsx` is that the painted
+ * dot and the hit region are two numbers with two different laws, and a sweep
+ * that measures one against the other's row produces the false FAIL
+ * `knob-laws.md` names as the commonest.
+ */
+
+import { MIN_PRESS_TARGET } from "@multiplatform.one/theme";
+import { describe, expect, it } from "vitest";
+import {
+  FINE_PORT_HIT_MIN,
+  paintedPortSize,
+  paintedPortSizePx,
+  portConnectionRadius,
+  portHitSize,
+  portRegionInset,
+} from "./handleGeometry";
+import { FINE_PORT_PITCH, type GraphNodeSizeKnob, portSpacing } from "./nodeMeasure";
+
+const sizes = ["small", "medium", "large"] as const satisfies readonly GraphNodeSizeKnob[];
+
+describe("H1: the painted dot follows the size knob and is never 44", () => {
+  it("is 8 / 10 / 12", () => {
+    expect(paintedPortSize("small")).toBe(8);
+    expect(paintedPortSize("medium")).toBe(10);
+    expect(paintedPortSize("large")).toBe(12);
+  });
+
+  it("is never the press floor at any stop — a 44 px dot is a different component", () => {
+    for (const size of sizes) {
+      expect(paintedPortSize(size)).not.toBe(MIN_PRESS_TARGET);
+      expect(paintedPortSize(size)).toBeLessThan(MIN_PRESS_TARGET);
+    }
+  });
+
+  it("steps with the knob rather than sitting still", () => {
+    expect(new Set(Object.values(paintedPortSizePx)).size).toBe(sizes.length);
+  });
+});
+
+describe("H3: 44 on coarse pointers, max(painted, 24) on fine", () => {
+  it("is exactly the press floor on a coarse pointer at every size", () => {
+    for (const size of sizes) {
+      expect(portHitSize({ size, coarsePointer: true })).toBe(MIN_PRESS_TARGET);
+    }
+  });
+
+  it("is max(painted, 24) on a fine pointer at every size", () => {
+    for (const size of sizes) {
+      expect(portHitSize({ size, coarsePointer: false })).toBe(
+        Math.max(paintedPortSize(size), FINE_PORT_HIT_MIN),
+      );
+    }
+  });
+
+  it("is smaller on fine than on coarse — that split is the whole law", () => {
+    for (const size of sizes) {
+      expect(portHitSize({ size, coarsePointer: false })).toBeLessThan(
+        portHitSize({ size, coarsePointer: true }),
+      );
+    }
+  });
+
+  it("always exceeds the painted dot, so the region grows outward", () => {
+    for (const size of sizes) {
+      for (const coarsePointer of [true, false]) {
+        expect(portHitSize({ size, coarsePointer })).toBeGreaterThan(paintedPortSize(size));
+      }
+    }
+  });
+});
+
+describe("H4: the crowding cap is min(44, portSpacing)", () => {
+  it("caps a coarse hit at the port pitch when the pitch is the tighter number", () => {
+    for (const portSpacingPx of [30, 36, 44, 60]) {
+      expect(portHitSize({ size: "medium", coarsePointer: true, portSpacingPx })).toBe(
+        Math.min(MIN_PRESS_TARGET, portSpacingPx),
+      );
+    }
+  });
+
+  it("does not cap when the ports are far enough apart", () => {
+    expect(portHitSize({ size: "medium", coarsePointer: true, portSpacingPx: 80 })).toBe(
+      MIN_PRESS_TARGET,
+    );
+  });
+
+  it("never lets a crowded hit shrink below the dot the user can see", () => {
+    // A pitch of 4 is narrower than every painted stop. The cap must floor at
+    // the painted size, or the ::after would inset INWARD and the target would
+    // be smaller than the affordance.
+    for (const size of sizes) {
+      expect(portHitSize({ size, coarsePointer: true, portSpacingPx: 4 })).toBe(
+        paintedPortSize(size),
+      );
+    }
+  });
+
+  it("leaves the default pitch uncapped, so the cap is a guard and not the norm", () => {
+    for (const coarsePointer of [true, false]) {
+      const withDefault = portHitSize({ size: "medium", coarsePointer });
+      const explicit = portHitSize({
+        size: "medium",
+        coarsePointer,
+        portSpacingPx: portSpacing({ coarsePointer }),
+      });
+      expect(withDefault).toBe(explicit);
+    }
+    expect(portSpacing({ coarsePointer: true })).toBe(MIN_PRESS_TARGET);
+    expect(portSpacing({ coarsePointer: false })).toBe(FINE_PORT_PITCH);
+  });
+});
+
+describe("H2: the region is an outward inset, so the handle box never moves", () => {
+  it("is negative wherever the hit exceeds the dot", () => {
+    for (const size of sizes) {
+      for (const coarsePointer of [true, false]) {
+        expect(portRegionInset({ size, coarsePointer })).toBeLessThan(0);
+      }
+    }
+  });
+
+  it("is exactly half the difference, so the region stays concentric", () => {
+    for (const size of sizes) {
+      const inset = portRegionInset({ size, coarsePointer: true });
+      expect(paintedPortSize(size) - 2 * inset).toBe(portHitSize({ size, coarsePointer: true }));
+    }
+  });
+
+  it("adds the ring back, because the pseudo-element insets from the PADDING box", () => {
+    // The dot is border-box with a knob-driven ring, so its padding box is
+    // `size - 2 × border`. Without this term Chrome renders a 44 as a 42 —
+    // measured, and the reason the parameter exists at all.
+    for (const size of sizes) {
+      for (const borderWidthPx of [1, 2, 3]) {
+        const inset = portRegionInset({ size, coarsePointer: true, borderWidthPx });
+        const paddingBox = paintedPortSize(size) - 2 * borderWidthPx;
+        expect(paddingBox - 2 * inset).toBe(portHitSize({ size, coarsePointer: true }));
+      }
+    }
+  });
+
+  it("collapses to zero when crowding pins the hit to the dot and there is no ring", () => {
+    expect(portRegionInset({ size: "medium", coarsePointer: true, portSpacingPx: 4 })).toBe(0);
+  });
+});
+
+describe("H5: the magnetic drop radius matches the visible affordance", () => {
+  it("is the hit diameter, not React Flow's 20 px default", () => {
+    for (const size of sizes) {
+      for (const coarsePointer of [true, false]) {
+        expect(portConnectionRadius({ size, coarsePointer })).toBe(
+          portHitSize({ size, coarsePointer }),
+        );
+        expect(portConnectionRadius({ size, coarsePointer })).not.toBe(20);
+      }
+    }
+  });
+});

package/src/nodes/handleGeometry.ts

@@ -0,0 +1,232 @@
+/**
+ * Port geometry — pure. The painted dot and the region you can actually hit
+ * are two different numbers, and design §7.1 is emphatic that conflating them
+ * is the commonest false FAIL in a knob sweep.
+ *
+ * The laws, verbatim from §7.1:
+ *
+ *  H1. The painted dot is 8 / 10 / 12 by the size knob and NEVER grows to 44.
+ *      A 44 px painted dot is a different component.
+ *  H2. The hit region is a pseudo-element, never element growth, because
+ *      `getEdgePosition` reads the handle box's outer edge (`center` defaults
+ *      to false) — growing 8 to 44 would move every rendered edge endpoint 18
+ *      flow units outward on exactly the sides an LR graph uses.
+ *  H3. 44 on coarse pointers, `max(painted, 24)` on fine. A 44 px invisible
+ *      disc around every handle on a dense mouse canvas steals clicks from the
+ *      node body.
+ *  H4. Two ports closer than the hit diameter would have overlapping discs and
+ *      the wrong one would win, so the hit caps at `min(44, portSpacing)`.
+ *  H7. The region is 44 SCREEN px at every zoom, not 44 px of flow space.
+ *      Added in milestone 6, and it is the only law here that was measured on a
+ *      phone before it was written down. Every element a node owns lives inside
+ *      `.react-flow__viewport`, whose transform carries the zoom, so a region
+ *      declared 44 px renders 44 x zoom. On the iPhone 16e at zoom 0.377 that
+ *      is 16.6 pt wide — a half-width of 8.3 pt — and a tap 18 pt off the
+ *      painted centre panned the canvas instead of grabbing the port. Same miss
+ *      on emulator-5592 at zoom 0.397. So the inset carries a 1/zoom term and
+ *      the sheet reads the live zoom from `--mpo-graph-zoom`.
+ *
+ * H2 and H7 are the CSS in `css/graph.css`, not numbers; the rest are here.
+ */
+
+import { MIN_PRESS_TARGET } from "@multiplatform.one/theme";
+import { type GraphNodeSizeKnob, type GraphPortSide, portSpacing } from "./nodeMeasure";
+
+/** H1. Painted diameter per size stop. Never 44 at any stop, by construction. */
+export const paintedPortSizePx: Record<GraphNodeSizeKnob, number> = {
+  small: 8,
+  medium: 10,
+  large: 12,
+};
+
+/**
+ * H3's fine-pointer floor. Below this a mouse target is a coin toss; above 44
+ * it would start eating the node body, which is why fine and coarse differ at
+ * all.
+ */
+export const FINE_PORT_HIT_MIN = 24;
+
+export function paintedPortSize(size: GraphNodeSizeKnob): number {
+  return paintedPortSizePx[size];
+}
+
+/**
+ * H3 with H4's cap applied.
+ *
+ * The floor at the painted size is geometric, not a taste call: the hit region
+ * is a pseudo-element inset OUTWARD from the dot, so a hit smaller than the
+ * dot would inset inward and shrink the target below what the user can see.
+ */
+export function portHitSize(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly coarsePointer: boolean;
+  /** The node's port pitch. Defaults to the pitch for this pointer kind. */
+  readonly portSpacingPx?: number;
+}): number {
+  const painted = paintedPortSize(opts.size);
+  const wanted = opts.coarsePointer ? MIN_PRESS_TARGET : Math.max(painted, FINE_PORT_HIT_MIN);
+  const spacing = opts.portSpacingPx ?? portSpacing({ coarsePointer: opts.coarsePointer });
+  return Math.max(painted, Math.min(wanted, spacing));
+}
+
+/**
+ * The `inset` the `::after` region carries, in px.
+ *
+ * NEGATIVE when the hit is larger than the dot, which is the whole point: the
+ * pseudo-element grows outward from the painted disc without touching the
+ * handle's own box, so `handleBounds` — which reads `getBoundingClientRect()`
+ * and `getDimensions()` — sees nothing change and every edge endpoint stays
+ * where the 8 px dot put it.
+ *
+ * `borderWidthPx` is not decoration. An absolutely positioned pseudo-element
+ * insets from its parent's PADDING box, and the dot is `box-sizing:
+ * border-box` with a knob-driven ring, so the padding box is `size - 2 ×
+ * border`. Measured in Chrome before this term existed: a 44 asked for
+ * rendered as 42. A press floor that lands two pixels under the floor is not
+ * a floor, so the ring is added back here rather than rounded away.
+ */
+export function portRegionInset(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly coarsePointer: boolean;
+  readonly portSpacingPx?: number;
+  /** The dot's ring, from `knobProps.surface.borderWidth`. */
+  readonly borderWidthPx?: number;
+}): number {
+  return portRegionInsetAtZoom({ ...opts, zoom: 1 });
+}
+
+/**
+ * H7. The same inset with the viewport zoom divided back out.
+ *
+ * The region has to be `hit` SCREEN px, and it is painted inside a box the
+ * viewport transform scales by `zoom`. Local width is therefore `hit / zoom`,
+ * and the inset that produces it is `(painted - hit / zoom) / 2`, plus the ring
+ * term H2 already carries. At zoom 1 this IS `portRegionInset`, which is what
+ * `handleGeometry.spec.ts` asserts, so the new term cannot silently change the
+ * number the desktop canvas has always used.
+ *
+ * The floor on `zoom` is not defensive tidiness: dividing by zero in CSS is
+ * silent and yields an infinite region that swallows the whole canvas. React
+ * Flow never emits a zoom of 0, so the guard costs nothing and removes the one
+ * way this arithmetic can produce something catastrophic.
+ *
+ * `css/graph.css` computes the identical expression from
+ * `--mpo-graph-handle-size`, `--mpo-graph-handle-hit`,
+ * `--mpo-graph-handle-border` and `--mpo-graph-zoom`. `GraphPort.spec.tsx`
+ * reads the rule text and checks the two agree, because jsdom cannot resolve a
+ * pseudo-element and a spec written against `getComputedStyle(el, "::after")`
+ * would assert nothing at all.
+ */
+export function portRegionInsetAtZoom(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly coarsePointer: boolean;
+  readonly portSpacingPx?: number;
+  readonly borderWidthPx?: number;
+  /** The live viewport zoom. 1 outside a canvas. */
+  readonly zoom: number;
+}): number {
+  const zoom = opts.zoom > 0 ? opts.zoom : 1;
+  return (paintedPortSize(opts.size) - portHitSize(opts) / zoom) / 2 - (opts.borderWidthPx ?? 0);
+}
+
+/**
+ * What the region ACTUALLY measures on screen, in px, at a given zoom.
+ *
+ * The number MPO-212's 3.4 criterion is about, and the one nothing computed
+ * before milestone 6. With the 1/zoom term this is `portHitSize(opts)` at every
+ * zoom, which is the whole claim — so a spec asserting it at 0.4 and at 2 is
+ * asserting the fix rather than the arithmetic that implements it.
+ */
+export function portRegionScreenSize(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly coarsePointer: boolean;
+  readonly portSpacingPx?: number;
+  readonly borderWidthPx?: number;
+  readonly zoom: number;
+}): number {
+  const zoom = opts.zoom > 0 ? opts.zoom : 1;
+  const painted = paintedPortSize(opts.size);
+  const inset = portRegionInsetAtZoom(opts);
+  // The local box, then back to screen px. `borderWidthPx` enters the inset and
+  // must therefore leave again here, or the ring would be counted twice.
+  const local = painted - 2 * inset - 2 * (opts.borderWidthPx ?? 0);
+  return local * zoom;
+}
+
+/**
+ * H5. `connectionRadius` matches the hit diameter, so the magnetic drop radius
+ * is the visible affordance rather than React Flow's 20 px default. Wired into
+ * the canvas in task 1.11; the number lives here with its siblings.
+ */
+export function portConnectionRadius(opts: {
+  readonly size: GraphNodeSizeKnob;
+  readonly coarsePointer: boolean;
+  readonly portSpacingPx?: number;
+}): number {
+  return portHitSize(opts);
+}
+
+/** A rectangle in the node's own coordinate space, top-left anchored. */
+export interface PortRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The two rectangles a port occupies, which are NOT the same rectangle.
+ *
+ * `box` is what React Flow measures. `handleBounds` is built from
+ * `getBoundingClientRect()` and `getDimensions()` (`dom.ts:82-91`), so `box` is
+ * the handle ELEMENT — and `getHandlePosition` turns it into the point every
+ * edge is drawn to.
+ *
+ * `region` is what a finger lands on: the `::after` pseudo-element. A
+ * pseudo-element is not in the box tree its parent reports, so it moves
+ * `region` without moving `box`.
+ *
+ * Keeping them apart in the TYPE is the mechanism H2 describes. Element growth
+ * would collapse them into one rectangle, and every edge endpoint on an LR
+ * graph would slide outward by half the difference — 18 units at 8 → 44.
+ */
+export interface PortGeometry {
+  /** What `handleBounds` measures. Painted size only; `hit` never enters. */
+  readonly box: PortRect;
+  /** What the pointer hits — the `::after` region. Grows with `hit`. */
+  readonly region: PortRect;
+}
+
+function centredOn(cx: number, cy: number, side: number): PortRect {
+  return { x: cx - side / 2, y: cy - side / 2, width: side, height: side };
+}
+
+/**
+ * Where a port sits on its node, and how big each of its two rectangles is.
+ *
+ * `painted` and `hit` are separate parameters ON PURPOSE, so the endpoint law
+ * is falsifiable: a caller can ask for a 44 px hit and read back a box that did
+ * not move. A single-size signature could not express the broken mechanism, and
+ * a test that cannot express the bug cannot catch it.
+ *
+ * React Flow's own sheet centres a handle on the node edge — `left: 0` /
+ * `right: 0` with `translate(∓50%)` and `top: 50%` with `translateY(-50%)`
+ * (style.css `.react-flow__handle-left` and friends) — so both rectangles are
+ * concentric on that edge point rather than tangent to it.
+ */
+export function portGeometry(opts: {
+  readonly painted: number;
+  readonly hit: number;
+  readonly side: GraphPortSide;
+  readonly nodeWidth: number;
+  readonly nodeHeight: number;
+  /** Distance along the port's edge, from the node's top-left corner. */
+  readonly offset: number;
+}): PortGeometry {
+  const { painted, hit, side, nodeWidth, nodeHeight, offset } = opts;
+  const cx =
+    side === "left" ? 0 : side === "right" ? nodeWidth : Math.min(Math.max(offset, 0), nodeWidth);
+  const cy =
+    side === "top" ? 0 : side === "bottom" ? nodeHeight : Math.min(Math.max(offset, 0), nodeHeight);
+  return { box: centredOn(cx, cy, painted), region: centredOn(cx, cy, hit) };
+}