@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/svg/port-layout.js

@@ -0,0 +1,212 @@
+"use strict";
+// port-layout.ts — Wave 6 (Ports & connections), Card 4.
+//
+// The pluggable port-layout engine: NAMED strategies, attachable to a port group,
+// each with its own args. A strategy answers one question — "where, in node-local
+// coordinates, does the port whose rank is `rank` of `count` sit?" — and knows
+// nothing about glyphs, links or validation.
+//
+// The DEFAULT strategy is `shape`, which defers to the shape registry's
+// `portAnchor`. That is the pre-wave-6 behaviour and it is not going anywhere:
+// the registry is where the geometry-true anchors live (the cylinder's rim seam,
+// the actor's hands, the hexagon's flats), and a generic "spread along the
+// bounding box" would throw all of that away. Shape-awareness and pluggable
+// layout are not alternatives — `shape` is one of the plugins.
+//
+// PURE GEOMETRY: numbers in, numbers out. No VNodes, no models beyond the two
+// read-only inputs, no DOM.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPortLayout = registerPortLayout;
+exports.getPortLayout = getPortLayout;
+exports.hasPortLayout = hasPortLayout;
+exports.portLayoutNames = portLayoutNames;
+exports.compensateForRotation = compensateForRotation;
+exports.runPortLayout = runPortLayout;
+const shape_registry_1 = require("./shape-registry");
+const DEG = Math.PI / 180;
+/** The two node-local endpoints of an edge, corner to corner. */
+function edgeSpan(side, width, height, padding) {
+    switch (side) {
+        case 'left':
+            return { from: { x: 0, y: padding }, to: { x: 0, y: height - padding } };
+        case 'right':
+            return { from: { x: width, y: padding }, to: { x: width, y: height - padding } };
+        case 'top':
+            return { from: { x: padding, y: 0 }, to: { x: width - padding, y: 0 } };
+        case 'bottom':
+            return { from: { x: padding, y: height }, to: { x: width - padding, y: height } };
+    }
+}
+/**
+ * Spread `count` items along a span. Matches the shape registry's own
+ * convention: `(rank + 1) / (count + 1)`, so ONE port sits at the midpoint —
+ * not at the start — and N ports are evenly inset from both corners.
+ */
+function spreadFraction(rank, count) {
+    return (rank + 1) / (count + 1);
+}
+// ===========================================================================
+// The strategies
+// ===========================================================================
+/**
+ * `shape` — defer to the shape registry's true silhouette anchor. THE DEFAULT.
+ */
+const shapeStrategy = (input) => {
+    return (0, shape_registry_1.getShape)(input.shapeType).portAnchor(input.width, input.height, input.side, input.rank, input.count);
+};
+/**
+ * `absolute` — one fixed point. Fractions of the node box by default (so the
+ * port tracks a resize), or raw px with `units: 'px'`.
+ */
+const absoluteStrategy = (input, args) => {
+    var _a, _b, _c, _d;
+    const px = args.units === 'px';
+    return {
+        x: px ? ((_a = args.x) !== null && _a !== void 0 ? _a : 0) : ((_b = args.x) !== null && _b !== void 0 ? _b : 0.5) * input.width,
+        y: px ? ((_c = args.y) !== null && _c !== void 0 ? _c : 0) : ((_d = args.y) !== null && _d !== void 0 ? _d : 0.5) * input.height,
+    };
+};
+/**
+ * `line` — march the group's ports along the segment `start`→`end` (node-local
+ * px). With `step`, they advance at a fixed pitch from `start` (a fixed-pitch
+ * pin header); without it, they divide the segment evenly.
+ */
+const lineStrategy = (input, args) => {
+    var _a, _b;
+    const start = (_a = args.start) !== null && _a !== void 0 ? _a : { x: 0, y: 0 };
+    const end = (_b = args.end) !== null && _b !== void 0 ? _b : { x: input.width, y: 0 };
+    if (typeof args.step === 'number' && args.step !== 0) {
+        const dx = end.x - start.x;
+        const dy = end.y - start.y;
+        const length = Math.hypot(dx, dy) || 1;
+        const distance = args.step * input.rank;
+        return { x: start.x + (dx / length) * distance, y: start.y + (dy / length) * distance };
+    }
+    const t = spreadFraction(input.rank, input.count);
+    return { x: start.x + (end.x - start.x) * t, y: start.y + (end.y - start.y) * t };
+};
+/**
+ * `sideLinear` — spread along the node's own EDGE (the bounding box's, not the
+ * silhouette's), inset by `padding`. The workhorse for rectangular node editors:
+ * a column of inputs down the left, a column of outputs down the right.
+ *
+ * With `step`, ports march at a fixed pitch from the edge's start corner instead
+ * of dividing it — the layout an n8n / Node-RED node uses so that adding a
+ * fifth input doesn't shuffle the other four.
+ */
+const sideLinearStrategy = (input, args) => {
+    var _a;
+    const padding = (_a = args.padding) !== null && _a !== void 0 ? _a : 0;
+    const { from, to } = edgeSpan(input.side, input.width, input.height, padding);
+    if (typeof args.step === 'number' && args.step !== 0) {
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const length = Math.hypot(dx, dy) || 1;
+        const distance = args.step * input.rank;
+        return { x: from.x + (dx / length) * distance, y: from.y + (dy / length) * distance };
+    }
+    const t = spreadFraction(input.rank, input.count);
+    return { x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t };
+};
+/** Shared ellipse maths for the two ring strategies. */
+function onEllipse(input, args, degrees) {
+    var _a, _b;
+    const cx = input.width / 2;
+    const cy = input.height / 2;
+    const rx = (_a = args.radiusX) !== null && _a !== void 0 ? _a : input.width / 2;
+    const ry = (_b = args.radiusY) !== null && _b !== void 0 ? _b : input.height / 2;
+    const radians = degrees * DEG;
+    return { x: cx + rx * Math.cos(radians), y: cy + ry * Math.sin(radians) };
+}
+/**
+ * `ellipse` — every port at ONE angle on the node's inscribed ellipse. Combined
+ * with a per-port `angle` override this is the "hand-place each pin on the dial"
+ * layout.
+ */
+const ellipseStrategy = (input, args) => {
+    var _a;
+    return onEllipse(input, args, (_a = args.angle) !== null && _a !== void 0 ? _a : 0);
+};
+/**
+ * `ellipseSpread` — fan the group's ports around the ellipse: `count` of them
+ * spread across `sweep` degrees starting at `angle`.
+ *
+ * A FULL ring (sweep 360°) divides by `count` so the first and last ports don't
+ * land on the same point; a partial arc divides by `count - 1` so the ports sit
+ * ON both ends of the arc, which is what "from 30° to 150°" is asking for.
+ */
+const ellipseSpreadStrategy = (input, args) => {
+    var _a, _b;
+    const startAngle = (_a = args.angle) !== null && _a !== void 0 ? _a : 0;
+    const sweep = (_b = args.sweep) !== null && _b !== void 0 ? _b : 360;
+    const full = Math.abs(sweep) >= 360;
+    const divisor = full ? input.count : Math.max(1, input.count - 1);
+    const stepAngle = sweep / divisor;
+    return onEllipse(input, args, startAngle + stepAngle * input.rank);
+};
+// ===========================================================================
+// Registry
+// ===========================================================================
+const STRATEGIES = new Map([
+    ['shape', shapeStrategy],
+    ['absolute', absoluteStrategy],
+    ['line', lineStrategy],
+    ['sideLinear', sideLinearStrategy],
+    ['ellipse', ellipseStrategy],
+    ['ellipseSpread', ellipseSpreadStrategy],
+]);
+/** Register a custom strategy. Hosts can add their own; the built-ins are just entries. */
+function registerPortLayout(name, strategy) {
+    STRATEGIES.set(name, strategy);
+}
+function getPortLayout(name) {
+    return (name && STRATEGIES.get(name)) || shapeStrategy;
+}
+function hasPortLayout(name) {
+    return STRATEGIES.has(name);
+}
+/** For tests / tooling. */
+function portLayoutNames() {
+    return Array.from(STRATEGIES.keys());
+}
+/**
+ * Rotate `point` about the node's centre by `-degrees`, so a port on a rotated
+ * node keeps its WORLD-space arrangement (a `compensateRotation` group on a node
+ * spun 90° still shows its inputs on the left of the screen).
+ *
+ * Node-local in, node-local out: the node's own transform then rotates it BACK,
+ * and the two cancel.
+ */
+function compensateForRotation(point, width, height, degrees) {
+    if (!degrees)
+        return point;
+    const cx = width / 2;
+    const cy = height / 2;
+    const radians = -degrees * DEG;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    const dx = point.x - cx;
+    const dy = point.y - cy;
+    return {
+        x: cx + dx * cos - dy * sin,
+        y: cy + dx * sin + dy * cos,
+    };
+}
+/**
+ * Run a port's layout: pick the strategy, apply it, then the shared `dx`/`dy`
+ * nudge and optional rotation compensation.
+ */
+function runPortLayout(spec, input) {
+    var _a, _b, _c;
+    const args = (_a = spec === null || spec === void 0 ? void 0 : spec.args) !== null && _a !== void 0 ? _a : {};
+    const strategy = getPortLayout(spec === null || spec === void 0 ? void 0 : spec.strategy);
+    let point = strategy(input, args);
+    if (args.dx || args.dy) {
+        point = { x: point.x + ((_b = args.dx) !== null && _b !== void 0 ? _b : 0), y: point.y + ((_c = args.dy) !== null && _c !== void 0 ? _c : 0) };
+    }
+    if (args.compensateRotation && input.rotation) {
+        point = compensateForRotation(point, input.width, input.height, input.rotation);
+    }
+    return point;
+}
+//# sourceMappingURL=port-layout.js.map

package/src/libs/renderer/src/svg/port-positioning.d.ts

@@ -0,0 +1,33 @@
+import type { BoundingBox, NodeModel, PortModel } from '@grafloria/engine';
+/**
+ * Calculate port position based on node shape
+ * Returns position relative to node's local coordinate system (0,0 = top-left)
+ *
+ * Phase 3.2: Shape-aware port positioning
+ * - Rectangle: ports spread evenly along the edge (single port = midpoint)
+ * - Circle/Ellipse: ports on the perimeter, fanned symmetrically per side
+ * - Diamond: ports at vertices
+ * - Hexagon: ports spread along the flat edges
+ *
+ * Multiple ports on the same side are distributed by their rank among that
+ * side's ports (ordered by `index`, then declaration order) so they never
+ * stack on the same point.
+ */
+export declare function getPortPositionForShape(port: PortModel, node: NodeModel): {
+    x: number;
+    y: number;
+};
+/**
+ * The port's WORLD position — for hit-testing, magnets and link endpoints alike.
+ * Everything that needs "where is this port on screen" comes through here, so
+ * what you click is always what you see.
+ */
+export declare function portWorldPosition(port: PortModel, node: NodeModel): {
+    x: number;
+    y: number;
+};
+/** Same answer, for callers that already hold the node's bounding box. */
+export declare function portPositionInBounds(port: PortModel, node: NodeModel, bounds: BoundingBox): {
+    x: number;
+    y: number;
+};

package/src/libs/renderer/src/svg/port-positioning.js

@@ -0,0 +1,101 @@
+"use strict";
+// Shape-Aware Port Positioning Utility (Phase 3.2)
+//
+// Wave 6 (Ports & connections), Card 4: this is now the front door to the
+// PLUGGABLE port-layout engine (see `port-layout.ts`), not just to the shape
+// registry.
+//
+//   port/group declares no layout → strategy `shape` → the shape registry's
+//                                   `portAnchor`, exactly as before. The
+//                                   geometry-true anchors (cylinder rim seam,
+//                                   actor hands, hexagon flats) still win and the
+//                                   emitted geometry is byte-identical.
+//   port/group declares a layout   → that named strategy runs instead.
+//
+// It is also THE port-position function. It has a rival:
+// `PortModel.getAbsolutePosition()` walks the BOUNDING BOX (edge midpoints,
+// blind to the silhouette and to how many ports share a side) and that is what
+// the port hit-test and the magnet were snapping to, while THIS is what actually
+// gets drawn. On any non-rect shape, or any side with more than one port, you
+// were clicking several pixels away from the circle you could see. See
+// `portWorldPosition` — the one true answer, which those call sites now use.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPortPositionForShape = getPortPositionForShape;
+exports.portWorldPosition = portWorldPosition;
+exports.portPositionInBounds = portPositionInBounds;
+const engine_1 = require("@grafloria/engine");
+// Nodes & shapes foundation: shape-specific anchor geometry lives in the shape
+// registry (getShape(type).portAnchor). This module keeps the port-RANKING logic
+// (how many ports share a layout scope, and this port's rank among them) and
+// hands the geometry to the layout engine.
+const port_layout_1 = require("./port-layout");
+/**
+ * Calculate port position based on node shape
+ * Returns position relative to node's local coordinate system (0,0 = top-left)
+ *
+ * Phase 3.2: Shape-aware port positioning
+ * - Rectangle: ports spread evenly along the edge (single port = midpoint)
+ * - Circle/Ellipse: ports on the perimeter, fanned symmetrically per side
+ * - Diamond: ports at vertices
+ * - Hexagon: ports spread along the flat edges
+ *
+ * Multiple ports on the same side are distributed by their rank among that
+ * side's ports (ordered by `index`, then declaration order) so they never
+ * stack on the same point.
+ */
+function getPortPositionForShape(port, node) {
+    const shapeConfig = node.getMetadata('shape') || { type: 'rect' };
+    const { width, height } = node.size;
+    const config = (0, engine_1.resolvePortConfig)(port, node);
+    const side = config.side;
+    const { rank, count } = getLayoutRank(port, node, side, config.groupId);
+    const position = (0, port_layout_1.runPortLayout)(config.layout, {
+        width,
+        height,
+        side,
+        rank,
+        count,
+        shapeType: shapeConfig.type,
+        rotation: node.rotation,
+    });
+    // Apply port offset
+    return {
+        x: position.x + port.offset.x,
+        y: position.y + port.offset.y,
+    };
+}
+/**
+ * The port's WORLD position — for hit-testing, magnets and link endpoints alike.
+ * Everything that needs "where is this port on screen" comes through here, so
+ * what you click is always what you see.
+ */
+function portWorldPosition(port, node) {
+    const local = getPortPositionForShape(port, node);
+    const world = node.getWorldPosition();
+    return { x: world.x + local.x, y: world.y + local.y };
+}
+/** Same answer, for callers that already hold the node's bounding box. */
+function portPositionInBounds(port, node, bounds) {
+    const local = getPortPositionForShape(port, node);
+    return { x: bounds.left + local.x, y: bounds.top + local.y };
+}
+/**
+ * Rank of this port among the ports sharing its LAYOUT SCOPE, plus the size of
+ * that scope. Stable order: by `index`, ties by declaration order.
+ *
+ * The scope is the port's GROUP when it has one (Card 3 — a group is precisely
+ * "the set of ports laid out together", so five inputs in group `in` spread
+ * across five slots even if an ungrouped port also sits on the left edge), and
+ * otherwise its SIDE, which is the pre-wave-6 scope and is what keeps every
+ * existing diagram's port geometry identical.
+ */
+function getLayoutRank(port, node, side, groupId) {
+    const inScope = node
+        .getPorts()
+        .filter((p) => { var _a; return groupId ? p.group === groupId : !p.group && ((_a = p.alignment) === null || _a === void 0 ? void 0 : _a.side) === side; })
+        .map((p, declarationOrder) => ({ p, declarationOrder }))
+        .sort((a, b) => (a.p.index || 0) - (b.p.index || 0) || a.declarationOrder - b.declarationOrder);
+    const rank = inScope.findIndex((entry) => entry.p.id === port.id);
+    return { rank: rank < 0 ? 0 : rank, count: Math.max(1, inScope.length) };
+}
+//# sourceMappingURL=port-positioning.js.map

package/src/libs/renderer/src/svg/port-spots.d.ts

@@ -0,0 +1,69 @@
+import type { PortSpot, PortSpreadSpec } from '@grafloria/engine';
+import { type FanoutSide } from './link-fanout';
+export type Side = FanoutSide;
+export interface SpotInput {
+    /** World position of the port's anchor (its glyph centre). */
+    x: number;
+    y: number;
+    /** Glyph half-extents — a spot names a corner/edge of THIS box. */
+    hw: number;
+    hh: number;
+    /** The port's side: the default direction, and the default spot. */
+    side: Side;
+}
+/** Unit tangent of a side — the axis links spread along. */
+export declare function sideTangent(side: Side): {
+    x: number;
+    y: number;
+};
+/**
+ * Resolve `spot` to a world point on the glyph box, plus the direction the link
+ * travels there.
+ *
+ * `default` (and an absent spec) resolves to the glyph CENTRE and the port's
+ * own side — byte-for-byte the pre-wave-6 endpoint. Nothing moves unless the
+ * author asks it to.
+ */
+export declare function resolveSpot(spot: PortSpot | undefined, input: SpotInput): {
+    point: {
+        x: number;
+        y: number;
+    };
+    direction: Side;
+};
+/**
+ * The signed lane offsets for `count` links sharing one port, spaced `spacing`
+ * apart and CENTRED on the port's own attachment point.
+ *
+ *   count 1 → [0]                 ← a lone link NEVER moves. This is the whole
+ *                                   byte-stability guarantee: a port with one
+ *                                   link renders exactly where it always did.
+ *   count 2 → [-s/2, +s/2]
+ *   count 3 → [-s, 0, +s]
+ */
+export declare function spreadOffsets(count: number, spacing: number, max?: number): number[];
+/**
+ * Slide an attachment point along the port's EDGE (its tangent) by one lane.
+ *
+ * Along the tangent, deliberately — sliding along the NORMAL would push the
+ * endpoint off the node and leave a visible gap between the link and the port
+ * it is supposed to be touching.
+ */
+export declare function applySpread(point: {
+    x: number;
+    y: number;
+}, side: Side, laneOffset: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The lane assignment for every link on one port: `linkId → offset`.
+ *
+ * Lanes are ordered by a STABLE key (the id of the link's other endpoint, then
+ * the link's own id) rather than by insertion order, so the fan doesn't reshuffle
+ * itself every time an unrelated link is added or the diagram is reloaded.
+ */
+export declare function assignSpreadLanes(entries: Array<{
+    linkId: string;
+    sortKey: string;
+}>, spec: PortSpreadSpec | undefined): Map<string, number>;

package/src/libs/renderer/src/svg/port-spots.js

@@ -0,0 +1,154 @@
+"use strict";
+// port-spots.ts — Wave 6 (Ports & connections), Card 5.
+//
+// Where on a port's glyph does a link actually attach, and which way does it
+// leave? And when N links all land on ONE port, how do they share it?
+//
+// Two problems, one module:
+//
+//   1. ATTACHMENT SPOT. Every link used to attach to the port's centre point and
+//      leave along the port's side. `fromSpot`/`toSpot` let a port say otherwise
+//      — attach at the glyph's top-left corner, leave downward, stand off 4px.
+//
+//   2. MULTI-LINK SPREAD. Every link landing on a port landed on the SAME point,
+//      so five links into one input arrived as a single overdrawn stroke. The
+//      spread fans them along the port's edge — the tangent, not the normal, so
+//      they still arrive travelling the right way.
+//
+// This module does NOT route. It computes ENDPOINTS and hands them to the routing
+// engine, which is exactly the seam the routers already consume (`getLinkEndpoints`
+// → `{start, end, sourceDirection, targetDirection}`). No router is touched.
+//
+// PURE GEOMETRY.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sideTangent = sideTangent;
+exports.resolveSpot = resolveSpot;
+exports.spreadOffsets = spreadOffsets;
+exports.applySpread = applySpread;
+exports.assignSpreadLanes = assignSpreadLanes;
+const engine_1 = require("@grafloria/engine");
+// Wave 4 already worked out the unit outward normal of a side for the self-loop
+// router. There is exactly one right answer, so there is exactly one function.
+const link_fanout_1 = require("./link-fanout");
+/** Unit tangent of a side — the axis links spread along. */
+function sideTangent(side) {
+    const normal = (0, link_fanout_1.sideNormal)(side);
+    return { x: -normal.y, y: normal.x };
+}
+/**
+ * Resolve `spot` to a world point on the glyph box, plus the direction the link
+ * travels there.
+ *
+ * `default` (and an absent spec) resolves to the glyph CENTRE and the port's
+ * own side — byte-for-byte the pre-wave-6 endpoint. Nothing moves unless the
+ * author asks it to.
+ */
+function resolveSpot(spot, input) {
+    var _a, _b, _c;
+    const { x, y, hw, hh, side } = input;
+    const name = (_a = spot === null || spot === void 0 ? void 0 : spot.spot) !== null && _a !== void 0 ? _a : 'default';
+    const direction = (_b = spot === null || spot === void 0 ? void 0 : spot.direction) !== null && _b !== void 0 ? _b : side;
+    let px = x;
+    let py = y;
+    switch (name) {
+        case 'top':
+            py = y - hh;
+            break;
+        case 'bottom':
+            py = y + hh;
+            break;
+        case 'left':
+            px = x - hw;
+            break;
+        case 'right':
+            px = x + hw;
+            break;
+        case 'topLeft':
+            px = x - hw;
+            py = y - hh;
+            break;
+        case 'topRight':
+            px = x + hw;
+            py = y - hh;
+            break;
+        case 'bottomLeft':
+            px = x - hw;
+            py = y + hh;
+            break;
+        case 'bottomRight':
+            px = x + hw;
+            py = y + hh;
+            break;
+        case 'center':
+        case 'default':
+        default:
+            // The glyph centre — the historical attachment point.
+            break;
+    }
+    // Stand-off: push the attachment further out along the travel direction, so a
+    // link can start clear of a big glyph (or of its own arrowhead).
+    const distance = (_c = spot === null || spot === void 0 ? void 0 : spot.distance) !== null && _c !== void 0 ? _c : 0;
+    if (distance) {
+        const normal = (0, link_fanout_1.sideNormal)(direction);
+        px += normal.x * distance;
+        py += normal.y * distance;
+    }
+    return { point: { x: px, y: py }, direction };
+}
+/**
+ * The signed lane offsets for `count` links sharing one port, spaced `spacing`
+ * apart and CENTRED on the port's own attachment point.
+ *
+ *   count 1 → [0]                 ← a lone link NEVER moves. This is the whole
+ *                                   byte-stability guarantee: a port with one
+ *                                   link renders exactly where it always did.
+ *   count 2 → [-s/2, +s/2]
+ *   count 3 → [-s, 0, +s]
+ */
+function spreadOffsets(count, spacing, max = 0) {
+    if (count <= 1)
+        return [0];
+    // A cap folds the outer lanes back onto the outermost allowed one, so a port
+    // with 50 links doesn't grow a 500px fan.
+    const lanes = max > 0 ? Math.min(count, max) : count;
+    const offsets = [];
+    for (let i = 0; i < count; i++) {
+        const lane = Math.min(i, lanes - 1);
+        offsets.push((lane - (lanes - 1) / 2) * spacing);
+    }
+    return offsets;
+}
+/**
+ * Slide an attachment point along the port's EDGE (its tangent) by one lane.
+ *
+ * Along the tangent, deliberately — sliding along the NORMAL would push the
+ * endpoint off the node and leave a visible gap between the link and the port
+ * it is supposed to be touching.
+ */
+function applySpread(point, side, laneOffset) {
+    if (!laneOffset)
+        return point;
+    const tangent = sideTangent(side);
+    return { x: point.x + tangent.x * laneOffset, y: point.y + tangent.y * laneOffset };
+}
+/**
+ * The lane assignment for every link on one port: `linkId → offset`.
+ *
+ * Lanes are ordered by a STABLE key (the id of the link's other endpoint, then
+ * the link's own id) rather than by insertion order, so the fan doesn't reshuffle
+ * itself every time an unrelated link is added or the diagram is reloaded.
+ */
+function assignSpreadLanes(entries, spec) {
+    var _a, _b;
+    const lanes = new Map();
+    if (!(spec === null || spec === void 0 ? void 0 : spec.enabled) || entries.length <= 1) {
+        for (const entry of entries)
+            lanes.set(entry.linkId, 0);
+        return lanes;
+    }
+    const sorted = [...entries].sort((a, b) => a.sortKey.localeCompare(b.sortKey) || a.linkId.localeCompare(b.linkId));
+    const offsets = spreadOffsets(sorted.length, (_a = spec.spacing) !== null && _a !== void 0 ? _a : engine_1.DEFAULT_PORT_SPREAD_SPACING, (_b = spec.max) !== null && _b !== void 0 ? _b : 0);
+    sorted.forEach((entry, i) => { var _a; return lanes.set(entry.linkId, (_a = offsets[i]) !== null && _a !== void 0 ? _a : 0); });
+    return lanes;
+}
+//# sourceMappingURL=port-spots.js.map

package/src/libs/renderer/src/svg/route-memo.d.ts

@@ -0,0 +1,63 @@
+import type { RoutedPath } from '@grafloria/engine';
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RouteMemoStats {
+    /** links whose route had to be computed this frame */
+    routed: number;
+    /** links served from the previous frame's route */
+    reused: number;
+}
+/**
+ * How far outside a link's routed bounding box an obstacle can still have shaped
+ * that route. The router pushes off the port by `gapOffset` (30), keeps
+ * `obstacleMargin` (20) clearance from every body, and moves on a `gridSize`
+ * (10) lattice — so an obstacle that shaped this route is within ~60 units of
+ * it. 80 buys margin over that without pulling in half the diagram.
+ *
+ * This is the one approximation in the cache, and it is deliberately generous:
+ * being too eager here costs a re-route, being too clever costs a wrong route.
+ */
+export declare const ROUTE_INFLUENCE_PAD = 80;
+export declare class RouteMemo {
+    private entries;
+    private prevRects;
+    /** Bumped by the caller when something OUTSIDE the node rects changes the obstacle set. */
+    private epoch;
+    private _stats;
+    get stats(): Readonly<RouteMemoStats>;
+    get size(): number;
+    /**
+     * Start a frame. Diffs this frame's node rectangles against last frame's and
+     * returns the world regions that changed — each moved node contributes BOTH
+     * where it was and where it now is, because a link routed around its old
+     * position is just as stale as one routed through its new one.
+     *
+     * `obstacleEpoch` covers obstacle-set changes that are NOT node rects — a
+     * group collapsing hides its members and adds a block, and no node moved. A
+     * change there drops the whole cache, which is the honest thing to do: it is
+     * rare, and reasoning about which links a collapse touched is how you ship a
+     * stale route.
+     */
+    beginFrame(rects: Map<string, Rect>, obstacleEpoch: string): Rect[];
+    /** The route for this link if its inputs are unchanged since we cached it. */
+    lookup(linkId: string, key: string): RoutedPath | undefined;
+    store(linkId: string, key: string, routed: RoutedPath): void;
+    /** A route computed but NOT cacheable (e.g. no route found) must not keep a stale entry. */
+    drop(linkId: string): void;
+    invalidate(linkIds: Iterable<string>): void;
+    clear(): void;
+}
+/** Grow a rect by `pad` on every side. */
+export declare function inflate(r: Rect, pad: number): Rect;
+/**
+ * Merge dirty rects that overlap or nearly touch, so a drag of one node does not
+ * fire N separate spatial queries. Cheap and approximate: one pass, absorbing
+ * into the first box that already covers the candidate's neighbourhood. The
+ * result is a SUPERSET of the input regions, which is the safe direction — it
+ * can only invalidate more links, never fewer.
+ */
+export declare function coalesce(rects: Rect[], maxBoxes?: number): Rect[];