@archcode-io/engine 0.2.0-preview.0

package/dist/src/layout/host.js

@@ -0,0 +1,23 @@
+let factory = null;
+let instance = null;
+/** Replace how ELK instances are made. Takes effect for the next layout. */
+export function configureElk(make) {
+    factory = make;
+    instance = null;
+}
+/** The shared ELK instance — created on first use, reused after. */
+export function elkInstance() {
+    instance ??= factory
+        ? Promise.resolve(factory())
+        : import('elkjs/lib/elk.bundled.js').then(m => new m.default());
+    return instance;
+}
+/**
+ * Run ELK in a Web Worker: `url` is where the host serves `elk-worker.min.js`
+ * from elkjs. The API shim on this side is small; the algorithms load in the
+ * worker, off the UI thread.
+ */
+export async function useElkWorker(url) {
+    const { default: ELK } = await import('elkjs/lib/elk-api.js');
+    configureElk(() => new ELK({ workerUrl: url }));
+}

package/dist/src/layout/label.d.ts

@@ -0,0 +1,49 @@
+export interface Pt {
+    x: number;
+    y: number;
+}
+/**
+ * Where a connector's label belongs: the midpoint **by length**, not the middle
+ * element of the point list. An orthogonal route is made of segments of wildly
+ * different lengths, so picking the middle vertex parks the text in a corner.
+ */
+export declare function labelAnchor(points: readonly Pt[], at?: number): {
+    x: number;
+    y: number;
+    horizontal: boolean;
+};
+/**
+ * Box and text placement for a label of the given width at that anchor.
+ * `flip` puts it on the other side of the line: below a horizontal run
+ * instead of above, left of a vertical run instead of right.
+ */
+export declare function labelBox(points: readonly Pt[], width: number, at?: number, flip?: boolean): {
+    rectX: number;
+    rectY: number;
+    textX: number;
+    textY: number;
+    anchor: "middle";
+} | {
+    rectX: number;
+    rectY: number;
+    textX: number;
+    textY: number;
+    anchor: "end";
+} | {
+    rectX: number;
+    rectY: number;
+    textX: number;
+    textY: number;
+    anchor: "start";
+};
+/** Which side of the nearest segment a point is on: true = the flipped side (below / left). */
+export declare function flippedSide(points: readonly Pt[], p: Pt): boolean;
+/**
+ * An orthogonal polyline as an SVG path with softly rounded corners. Straight
+ * runs stay straight; each bend becomes a small quadratic arc, so parallel
+ * connectors stay readable where several turn together. The radius shrinks on
+ * short segments so two bends never overlap.
+ */
+export declare function roundedPath(points: readonly Pt[], radius?: number): string;
+/** Where along the polyline (0…1 by length) a point projects: the inverse of `labelAnchor`. */
+export declare function fractionAlong(points: readonly Pt[], p: Pt): number;

package/dist/src/layout/label.js

@@ -0,0 +1,113 @@
+/**
+ * Where a connector's label belongs: the midpoint **by length**, not the middle
+ * element of the point list. An orthogonal route is made of segments of wildly
+ * different lengths, so picking the middle vertex parks the text in a corner.
+ */
+export function labelAnchor(points, at = 0.5) {
+    const frac = Math.max(0.02, Math.min(0.98, at));
+    if (points.length < 2) {
+        const p = points[0] ?? { x: 0, y: 0 };
+        return { x: p.x, y: p.y, horizontal: true };
+    }
+    const seg = [];
+    let total = 0;
+    for (let i = 1; i < points.length; i++) {
+        const d = Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+        seg.push(d);
+        total += d;
+    }
+    let walked = 0;
+    for (let i = 0; i < seg.length; i++) {
+        const d = seg[i];
+        if (walked + d >= total * frac || i === seg.length - 1) {
+            const t = d === 0 ? 0 : (total * frac - walked) / d;
+            const a = points[i], b = points[i + 1];
+            return {
+                x: a.x + (b.x - a.x) * t,
+                y: a.y + (b.y - a.y) * t,
+                horizontal: Math.abs(b.x - a.x) >= Math.abs(b.y - a.y),
+            };
+        }
+        walked += d;
+    }
+    const p = points[0];
+    return { x: p.x, y: p.y, horizontal: true };
+}
+/**
+ * Box and text placement for a label of the given width at that anchor.
+ * `flip` puts it on the other side of the line: below a horizontal run
+ * instead of above, left of a vertical run instead of right.
+ */
+export function labelBox(points, width, at = 0.5, flip = false) {
+    const a = labelAnchor(points, at);
+    if (a.horizontal)
+        return flip
+            ? { rectX: a.x - width / 2, rectY: a.y + 4, textX: a.x, textY: a.y + 15, anchor: 'middle' }
+            : { rectX: a.x - width / 2, rectY: a.y - 17, textX: a.x, textY: a.y - 6, anchor: 'middle' };
+    return flip
+        ? { rectX: a.x - 7 - width, rectY: a.y - 8, textX: a.x - 12, textY: a.y + 3.5, anchor: 'end' }
+        : { rectX: a.x + 7, rectY: a.y - 8, textX: a.x + 12, textY: a.y + 3.5, anchor: 'start' };
+}
+/** Which side of the nearest segment a point is on: true = the flipped side (below / left). */
+export function flippedSide(points, p) {
+    let best = { d: Infinity, flip: false };
+    for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1], b = points[i];
+        const dx = b.x - a.x, dy = b.y - a.y, len = dx * dx + dy * dy;
+        const t = len ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / len)) : 0;
+        const q = { x: a.x + dx * t, y: a.y + dy * t };
+        const d = Math.hypot(p.x - q.x, p.y - q.y);
+        if (d < best.d)
+            best = { d, flip: Math.abs(dx) >= Math.abs(dy) ? p.y > q.y : p.x < q.x };
+    }
+    return best.flip;
+}
+/**
+ * An orthogonal polyline as an SVG path with softly rounded corners. Straight
+ * runs stay straight; each bend becomes a small quadratic arc, so parallel
+ * connectors stay readable where several turn together. The radius shrinks on
+ * short segments so two bends never overlap.
+ */
+export function roundedPath(points, radius = 8) {
+    if (points.length < 2)
+        return '';
+    const p = points;
+    let d = `M${p[0].x} ${p[0].y}`;
+    for (let i = 1; i < p.length - 1; i++) {
+        const a = p[i - 1], b = p[i], c = p[i + 1];
+        const inLen = Math.hypot(b.x - a.x, b.y - a.y), outLen = Math.hypot(c.x - b.x, c.y - b.y);
+        const r = Math.min(radius, inLen / 2, outLen / 2);
+        if (r < 1) {
+            d += ` L${b.x} ${b.y}`;
+            continue;
+        }
+        const ux = (b.x - a.x) / inLen, uy = (b.y - a.y) / inLen;
+        const vx = (c.x - b.x) / outLen, vy = (c.y - b.y) / outLen;
+        d += ` L${b.x - ux * r} ${b.y - uy * r} Q${b.x} ${b.y} ${b.x + vx * r} ${b.y + vy * r}`;
+    }
+    const last = p[p.length - 1];
+    d += ` L${last.x} ${last.y}`;
+    return d;
+}
+/** Where along the polyline (0…1 by length) a point projects: the inverse of `labelAnchor`. */
+export function fractionAlong(points, p) {
+    let total = 0, best = { d: Infinity, at: 0.5 }, walked = 0;
+    const seg = [];
+    for (let i = 1; i < points.length; i++) {
+        const d = Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+        seg.push(d);
+        total += d;
+    }
+    if (!total)
+        return 0.5;
+    for (let i = 0; i < seg.length; i++) {
+        const a = points[i], b = points[i + 1], d = seg[i];
+        const t = d === 0 ? 0 : Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / (d * d)));
+        const q = { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };
+        const dist = Math.hypot(p.x - q.x, p.y - q.y);
+        if (dist < best.d)
+            best = { d: dist, at: (walked + d * t) / total };
+        walked += d;
+    }
+    return best.at;
+}

package/dist/src/layout/measure.d.ts

@@ -0,0 +1,11 @@
+export declare function textWidth(s: string, size: number): number;
+export interface Box {
+    w: number;
+    h: number;
+}
+/** Extra room a shape needs beyond its text: a head, a cylinder cap. */
+export declare const SHAPE_PAD: Record<string, {
+    top: number;
+    bottom: number;
+}>;
+export declare function nodeBox(label: string, tech: string | undefined, kind: string, meta?: string, agents?: string[]): Box;

package/dist/src/layout/measure.js

@@ -0,0 +1,27 @@
+import { footerOf } from '../lens.js';
+/** Text metrics without a browser: good-enough advance widths for the UI font. */
+const NARROW = new Set([...'iljtfrI1.,:;\'"|!()[]{}']);
+const WIDE = new Set([...'MWmw@']);
+export function textWidth(s, size) {
+    let u = 0;
+    for (const ch of s)
+        u += NARROW.has(ch) ? 0.40 : WIDE.has(ch) ? 0.95 : 0.56;
+    return u * size;
+}
+/** Extra room a shape needs beyond its text: a head, a cylinder cap. */
+export const SHAPE_PAD = {
+    actor: { top: 50, bottom: 10 },
+    datastore: { top: 24, bottom: 16 },
+    cache: { top: 24, bottom: 16 },
+};
+export function nodeBox(label, tech, kind, meta, agents) {
+    const title = textWidth(label, 13);
+    const sub = tech ? textWidth(`[${kind}: ${tech}]`, 10) : textWidth(`[${kind}]`, 10);
+    const third = meta ? textWidth(meta, 10) : 0;
+    const pad = SHAPE_PAD[kind] ?? { top: 0, bottom: 0 };
+    const w = Math.max(kind === 'actor' ? 150 : 158, Math.min(236, Math.max(title, sub, third) + 38));
+    // a host card with agents carries a row of chips under its text
+    const footer = footerOf({ agents, w, isBoundary: false });
+    const h = (tech ? 72 : 60) + (meta ? 14 : 0) + pad.top + pad.bottom + (footer ? footer + 4 : 0);
+    return { w, h };
+}

package/dist/src/layout/ortho.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Orthogonal connectors with a memory — the geometry behind "drag a card and
+ * the arrow stretches instead of being redrawn" (draw.io's behaviour).
+ *
+ * A route is a polyline from a point on the source's border to a point on the
+ * target's border, every segment horizontal or vertical. Three operations:
+ *
+ *   sidePoint / autoSides   where an arrow leaves and enters a box;
+ *   orthoThrough            a route through the waypoints a person set;
+ *   repairRoute             the old route with only its end segments moved,
+ *                           after one or both boxes moved.
+ *
+ * Nothing here avoids obstacles: that is the A* router's job when there is no
+ * route yet. Once a route exists, a person owns its shape.
+ */
+import type { Pt, Rect, Side } from './route.js';
+export type { Pt, Rect, Side };
+/** Where an arrow attaches: a side of the box and a position along it (0…1, default the middle). */
+export interface Anchor {
+    side?: Side;
+    t?: number;
+}
+/** The point on `side` of `r`, `t` of the way along it (left→right, top→bottom). */
+export declare function sidePoint(r: Rect, side: Side, t?: number): Pt;
+/** Which side of `r` a border point sits on (the nearest edge), and how far along it. */
+export declare function anchorOf(p: Pt, r: Rect): Required<Anchor>;
+/** Sides for an arrow from `a` to `b` by where they sit: leave towards the target, enter from the source. */
+export declare function autoSides(a: Rect, b: Rect): [Side, Side];
+/**
+ * Repeated points go, and so does a point that merely sits on a straight run.
+ * A point where the run turns back on itself stays: it is a waypoint someone
+ * put there, and a spike is at least honest about it.
+ */
+export declare function tidy(points: Pt[]): Pt[];
+/**
+ * A route from `a` to `b` through `hints`, in order. Consecutive points that
+ * do not share an axis get a corner; the corner continues the direction the
+ * route was already travelling, so a person's waypoints read as "go here,
+ * then here" rather than as a puzzle. With no hints the result is the
+ * straight line, the L or the Z the two sides call for.
+ */
+export declare function orthoThrough(a: Rect, b: Rect, hints?: Pt[], from?: Anchor, to?: Anchor, stub?: number): Pt[];
+/**
+ * Move only what must move. `points` is the previous route (border to border),
+ * `a` and `b` are the boxes where they are now, `prevA`/`prevB` where they were
+ * (so the arrow keeps leaving from the same spot on the same side). Interior
+ * bends stay; the first and last bends slide along their own axis so the end
+ * segments still meet the borders squarely — and stay at least a stub's length
+ * outside the box. When the old shape cannot hold, the route is rebuilt from
+ * the same two sides.
+ */
+export declare function repairRoute(points: Pt[], a: Rect, b: Rect, prevA?: Rect, prevB?: Rect, stub?: number): Pt[];
+/** True when every segment is horizontal or vertical. */
+export declare const isOrthogonal: (pts: Pt[]) => boolean;

package/dist/src/layout/ortho.js

@@ -0,0 +1,206 @@
+const EPS = 0.01;
+const same = (a, b) => Math.abs(a - b) < EPS;
+/** The point on `side` of `r`, `t` of the way along it (left→right, top→bottom). */
+export function sidePoint(r, side, t = 0.5) {
+    const k = Math.max(0.02, Math.min(0.98, t));
+    switch (side) {
+        case 'top': return { x: r.x + r.w * k, y: r.y };
+        case 'bottom': return { x: r.x + r.w * k, y: r.y + r.h };
+        case 'left': return { x: r.x, y: r.y + r.h * k };
+        case 'right': return { x: r.x + r.w, y: r.y + r.h * k };
+    }
+}
+/** Which side of `r` a border point sits on (the nearest edge), and how far along it. */
+export function anchorOf(p, r) {
+    const d = { left: Math.abs(p.x - r.x), right: Math.abs(p.x - (r.x + r.w)), top: Math.abs(p.y - r.y), bottom: Math.abs(p.y - (r.y + r.h)) };
+    const side = Object.keys(d).reduce((a, b) => (d[b] < d[a] ? b : a));
+    const t = side === 'left' || side === 'right' ? (p.y - r.y) / (r.h || 1) : (p.x - r.x) / (r.w || 1);
+    return { side, t: Math.max(0, Math.min(1, t)) };
+}
+/** Sides for an arrow from `a` to `b` by where they sit: leave towards the target, enter from the source. */
+export function autoSides(a, b) {
+    const ax = a.x + a.w / 2, ay = a.y + a.h / 2, bx = b.x + b.w / 2, by = b.y + b.h / 2;
+    const dx = bx - ax, dy = by - ay;
+    // overlap in one axis means the boxes are stacked in the other
+    const gapX = Math.max(a.x, b.x) - Math.min(a.x + a.w, b.x + b.w);
+    const gapY = Math.max(a.y, b.y) - Math.min(a.y + a.h, b.y + b.h);
+    if (gapY >= 0 && (gapY >= gapX || gapX < 0))
+        return dy >= 0 ? ['bottom', 'top'] : ['top', 'bottom'];
+    return dx >= 0 ? ['right', 'left'] : ['left', 'right'];
+}
+const outward = (side) => side === 'left' ? { x: -1, y: 0 } : side === 'right' ? { x: 1, y: 0 } : side === 'top' ? { x: 0, y: -1 } : { x: 0, y: 1 };
+const horizontal = (side) => side === 'left' || side === 'right';
+/**
+ * Repeated points go, and so does a point that merely sits on a straight run.
+ * A point where the run turns back on itself stays: it is a waypoint someone
+ * put there, and a spike is at least honest about it.
+ */
+export function tidy(points) {
+    const out = [];
+    for (const p of points) {
+        const q = out[out.length - 1];
+        if (!q || !same(q.x, p.x) || !same(q.y, p.y))
+            out.push({ x: p.x, y: p.y });
+    }
+    for (let i = out.length - 2; i > 0; i--) {
+        const a = out[i - 1], b = out[i], c = out[i + 1];
+        const colH = same(a.y, b.y) && same(b.y, c.y) && (b.x - a.x) * (c.x - b.x) >= 0;
+        const colV = same(a.x, b.x) && same(b.x, c.x) && (b.y - a.y) * (c.y - b.y) >= 0;
+        if (colH || colV)
+            out.splice(i, 1);
+    }
+    return out;
+}
+/**
+ * A route from `a` to `b` through `hints`, in order. Consecutive points that
+ * do not share an axis get a corner; the corner continues the direction the
+ * route was already travelling, so a person's waypoints read as "go here,
+ * then here" rather than as a puzzle. With no hints the result is the
+ * straight line, the L or the Z the two sides call for.
+ */
+export function orthoThrough(a, b, hints = [], from = {}, to = {}, stub = 16) {
+    const [autoA, autoB] = autoSides(a, b);
+    const sa = from.side ?? autoA, sb = to.side ?? autoB;
+    const P = sidePoint(a, sa, from.t), E = sidePoint(b, sb, to.t);
+    const oa = outward(sa), ob = outward(sb);
+    const S = { x: P.x + oa.x * stub, y: P.y + oa.y * stub };
+    const T = { x: E.x + ob.x * stub, y: E.y + ob.y * stub };
+    // the stubs keep the first and last legs perpendicular to their sides; a
+    // waypoint already sitting on that line, further out, makes the stub redundant
+    const onStubLine = (h, from, o) => (o.x ? same(h.y, from.y) && (h.x - from.x) * o.x >= 0 : same(h.x, from.x) && (h.y - from.y) * o.y >= 0);
+    const first = hints[0], last = hints[hints.length - 1];
+    const pts = first && onStubLine(first, P, oa) ? [P] : [P, S];
+    let horiz = horizontal(sa); // the direction the route is travelling
+    const walk = (n, preferHoriz = null) => {
+        const c = pts[pts.length - 1];
+        if (same(c.x, n.x) || same(c.y, n.y)) {
+            pts.push(n);
+            horiz = same(c.y, n.y) ? !same(c.x, n.x) : false;
+            return;
+        }
+        const goH = preferHoriz ?? horiz;
+        pts.push(goH ? { x: n.x, y: c.y } : { x: c.x, y: n.y });
+        pts.push(n);
+        horiz = !goH;
+    };
+    for (const h of hints)
+        walk(h);
+    if (!hints.length) {
+        // no waypoints: an L when the sides face each other on the diagonal, a Z otherwise
+        const hA = horizontal(sa), hB = horizontal(sb);
+        if (hA === hB) {
+            // the Z between the stubs — unless a stub points away from the other box,
+            // in which case the route goes around the outside (leaving by the top to
+            // reach something below means: up, across, down past it, in from below)
+            const facing = hA ? (T.x - S.x) * oa.x >= 0 && (S.x - T.x) * ob.x >= 0 : (T.y - S.y) * oa.y >= 0 && (S.y - T.y) * ob.y >= 0;
+            if (facing) {
+                const mid = hA ? { x: (S.x + T.x) / 2, y: 0 } : { x: 0, y: (S.y + T.y) / 2 };
+                if (hA) {
+                    pts.push({ x: mid.x, y: S.y });
+                    pts.push({ x: mid.x, y: T.y });
+                }
+                else {
+                    pts.push({ x: S.x, y: mid.y });
+                    pts.push({ x: T.x, y: mid.y });
+                }
+            }
+            else if (hA) {
+                const lo = Math.min(a.y, b.y) - 24, hi = Math.max(a.y + a.h, b.y + b.h) + 24;
+                const y = Math.abs((S.y + T.y) / 2 - lo) < Math.abs((S.y + T.y) / 2 - hi) ? lo : hi;
+                pts.push({ x: S.x, y });
+                pts.push({ x: T.x, y });
+            }
+            else {
+                const lo = Math.min(a.x, b.x) - 24, hi = Math.max(a.x + a.w, b.x + b.w) + 24;
+                const x = Math.abs((S.x + T.x) / 2 - lo) < Math.abs((S.x + T.x) / 2 - hi) ? lo : hi;
+                pts.push({ x, y: S.y });
+                pts.push({ x, y: T.y });
+            }
+            pts.push(T);
+            pts.push(E);
+            return tidy(pts);
+        }
+        pts.push(hA ? { x: T.x, y: S.y } : { x: S.x, y: T.y });
+        pts.push(T);
+        pts.push(E);
+        return tidy(pts);
+    }
+    // the last leg arrives at T along the axis the side needs, then steps onto the border
+    if (last && onStubLine(last, E, ob)) {
+        pts.push(E);
+        return tidy(pts);
+    }
+    walk(T, !horizontal(sb));
+    pts.push(E);
+    return tidy(pts);
+}
+/**
+ * Move only what must move. `points` is the previous route (border to border),
+ * `a` and `b` are the boxes where they are now, `prevA`/`prevB` where they were
+ * (so the arrow keeps leaving from the same spot on the same side). Interior
+ * bends stay; the first and last bends slide along their own axis so the end
+ * segments still meet the borders squarely — and stay at least a stub's length
+ * outside the box. When the old shape cannot hold, the route is rebuilt from
+ * the same two sides.
+ */
+export function repairRoute(points, a, b, prevA, prevB, stub = 16) {
+    const old = tidy(points);
+    if (old.length < 2)
+        return orthoThrough(a, b);
+    const fa = anchorOf(old[0], prevA ?? a), fb = anchorOf(old[old.length - 1], prevB ?? b);
+    const P = sidePoint(a, fa.side, fa.t), E = sidePoint(b, fb.side, fb.t);
+    const inner = old.slice(1, -1).map(p => ({ x: p.x, y: p.y }));
+    // when the old shape cannot hold, the boxes have moved enough that the sides are re-chosen too
+    const fallback = () => orthoThrough(a, b, [], {}, {}, stub);
+    if (!inner.length)
+        return same(P.x, E.x) || same(P.y, E.y) ? [P, E] : fallback();
+    const n = inner.length;
+    const hA = horizontal(fa.side), hB = horizontal(fb.side);
+    if (n === 1 && hA === hB)
+        return fallback(); // one bend cannot serve two parallel sides
+    // was each interior segment horizontal? (old[i] → old[i+1], i = 1 … n-1)
+    const segH = inner.map((_, i) => i < n - 1 && same(old[i + 1].y, old[i + 2].y));
+    // the source end: the first bend sits on the axis leaving P, at least a stub away
+    const oa = outward(fa.side);
+    if (hA) {
+        inner[0].y = P.y;
+        inner[0].x = oa.x > 0 ? Math.max(inner[0].x, P.x + stub) : Math.min(inner[0].x, P.x - stub);
+    }
+    else {
+        inner[0].x = P.x;
+        inner[0].y = oa.y > 0 ? Math.max(inner[0].y, P.y + stub) : Math.min(inner[0].y, P.y - stub);
+    }
+    for (let i = 0; i < n - 1; i++) {
+        if (segH[i])
+            inner[i + 1].y = inner[i].y;
+        else
+            inner[i + 1].x = inner[i].x;
+    }
+    // the target end, the same way, walking back
+    const ob = outward(fb.side), L = inner[n - 1];
+    if (hB) {
+        L.y = E.y;
+        L.x = ob.x > 0 ? Math.max(L.x, E.x + stub) : Math.min(L.x, E.x - stub);
+    }
+    else {
+        L.x = E.x;
+        L.y = ob.y > 0 ? Math.max(L.y, E.y + stub) : Math.min(L.y, E.y - stub);
+    }
+    for (let i = n - 1; i > 0; i--) {
+        if (segH[i - 1])
+            inner[i - 1].y = inner[i].y;
+        else
+            inner[i - 1].x = inner[i].x;
+    }
+    // did walking back disturb the source end, or pull the first bend back into the box?
+    const first = inner[0];
+    if (hA ? !same(first.y, P.y) : !same(first.x, P.x))
+        return fallback();
+    const away = hA ? (first.x - P.x) * oa.x : (first.y - P.y) * oa.y;
+    if (away < stub - 1)
+        return fallback();
+    const out = tidy([P, ...inner, E]);
+    return isOrthogonal(out) ? out : fallback();
+}
+/** True when every segment is horizontal or vertical. */
+export const isOrthogonal = (pts) => pts.every((p, i) => i === 0 || same(p.x, pts[i - 1].x) || same(p.y, pts[i - 1].y));

package/dist/src/layout/route.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Obstacle-aware orthogonal router: a Hanan grid drawn at every obstacle
+ * border (± clearance, two lanes) plus the endpoints, searched with A* and a
+ * bend penalty. Deterministic — ties break by insertion order. A shared
+ * `used` map makes later edges prefer lanes nobody has taken yet.
+ */
+export interface Pt {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export declare const M = 16, LANE = 14, BEND = 70, REUSE = 40;
+export interface Grid {
+    X: number[];
+    Y: number[];
+    obstacles: Rect[];
+}
+export declare function makeGrid(obstacles: Rect[], extra?: Pt[]): Grid;
+type Blocked = (mid: Pt, i: number, j: number) => boolean;
+/** A* from grid point s to t; `blocked(mid)` rejects a move whose midpoint is inside an obstacle. */
+export declare function astar(grid: Grid, s: Pt, t: Pt, blocked: Blocked, used?: Map<string, number>): Pt[] | null;
+/** Remember which grid segments a committed path occupies. */
+export declare function markUsed(grid: Grid, pts: Pt[], used: Map<string, number>): void;
+/** Drop repeated and collinear points. */
+export declare function simplify(pts: readonly Pt[]): Pt[];
+/** Point on a node's side, and the same point pushed `M` outward. */
+export declare function stub(n: Rect, side: Side): {
+    on: Pt;
+    out: Pt;
+};
+export interface RouteSpec {
+    a: Rect;
+    b: Rect;
+    pref?: [Side, Side];
+}
+/**
+ * Route edges `{ a, b, pref }` around the rectangles `obstaclesFor(edge)`
+ * returns. Preferred sides go first; when they only give a detour (more than
+ * two bends) every side pair is tried and the cheapest wins. One polyline (or
+ * null) per edge, in order.
+ */
+export declare function routeAll(edges: RouteSpec[], obstaclesFor: (e: RouteSpec) => Rect[]): (Pt[] | null)[];
+/** The plain two-bend route between two boxes — the fallback, and the live-drag router. */
+export declare function routeSimple(a: Rect, b: Rect): Pt[];
+/**
+ * Route one edge between two boxes around obstacles — what the canvas uses
+ * while a card is being dragged. Falls back to the plain route when the
+ * search finds nothing.
+ */
+export declare function routeAround(a: Rect, b: Rect, obstacles: Rect[]): Pt[];
+export {};