@archcode-io/engine 0.2.0-preview.0

package/dist/src/layout/balance.js

@@ -0,0 +1,327 @@
+/**
+ * Two-phase layout — how the reference decks are actually drawn.
+ *
+ * One layered layout over the whole tree (ELK `INCLUDE_CHILDREN`) stretches
+ * every system across every layer of the picture: tall empty frames, 10–15 %
+ * ink, aspect 0.4–0.8. Measured on the six reference architectures nothing in
+ * ELK's option space moves that by more than one point. What does is doing what
+ * a person does: lay out each system on its own, then arrange the systems.
+ *
+ *   1. every top-level frame is laid out separately, top-down or left-to-right —
+ *      whichever lands nearer the target aspect;
+ *   2. the top level is laid out again with frames as opaque nodes carrying
+ *      fixed ports on the border facing each partner (people first, downstream
+ *      third parties last);
+ *   3. the leg from a port to the card inside is routed around the frame's other
+ *      members and its title text.
+ *
+ * Deterministic, ~150 ms on the references, and it scores 53 against 39 for the
+ * single pass (aspect 1.3–2.2, no edge through a card).
+ */
+import { footerOf } from '../lens.js';
+import { layoutLayered } from './elk.js';
+import { elkInstance } from './host.js';
+import { nodeBox, textWidth } from './measure.js';
+import { makeGrid, astar, stub, simplify, markUsed, routeSimple } from './route.js';
+const bandOf = (n) => (n.kind === 'actor' ? 0 : n.kind === 'external' ? 2 : 1);
+const cx = (b) => b.x + b.w / 2, cy = (b) => b.y + b.h / 2;
+const idsUnder = (n) => { const out = [n.id]; const w = (k) => { for (const c of k.children) {
+    out.push(c.id);
+    w(c);
+} }; w(n); return out; };
+const underId = (id, f) => id !== f && (id.startsWith(f + '.') || id.startsWith(f + '/'));
+const TITLE_H = 34;
+const WRAP = (t) => ({
+    'elk.partitioning.activate': 'false', 'elk.layered.wrapping.strategy': 'MULTI_EDGE', 'elk.aspectRatio': String(t),
+    'elk.layered.wrapping.additionalEdgeSpacing': '20', 'elk.layered.wrapping.multiEdge.improveCuts': 'true',
+});
+/** Lay one frame out on its own and normalise it to (0, 0). */
+async function frameItem(n, edges, dir, extra) {
+    const sub = await layoutLayered({ roots: [n], edges }, { root: { 'elk.direction': dir, ...extra }, boundary: extra });
+    const frame = sub.nodes.find(k => k.id === n.id);
+    const ox = frame.x, oy = frame.y;
+    for (const k of sub.nodes) {
+        k.x -= ox;
+        k.y -= oy;
+    }
+    for (const e of sub.edges) {
+        e.points = e.points.map(p => ({ x: p.x - ox, y: p.y - oy }));
+        if (e.labelPos)
+            e.labelPos = { x: e.labelPos.x - ox, y: e.labelPos.y - oy };
+    }
+    return { node: n, id: n.id, kind: n.kind, band: 1, w: frame.w, h: frame.h, sub, members: sub.nodes, x: 0, y: 0 };
+}
+/** Whichever of DOWN / RIGHT lands the frame nearer the target aspect (the outer rows add height). */
+async function autoDir(n, edges, target) {
+    let best = null;
+    for (const dir of ['DOWN', 'RIGHT']) {
+        const l = await layoutLayered({ roots: [n], edges }, { root: { 'elk.direction': dir } });
+        const f = l.nodes.find(k => k.id === n.id);
+        const err = Math.abs(Math.log2((f.w / f.h) / (target * 1.3)));
+        if (!best || err < best.err)
+            best = { dir, err };
+    }
+    return best.dir;
+}
+/**
+ * Third parties are drawn at the bottom — unless they feed the system (called
+ * by a person, or only calling in and never called): those read as upstream
+ * and belong in the top row, or every call from them loops back up the page.
+ */
+function smartBands(items, g) {
+    const itemOf = new Map();
+    for (const it of items) {
+        itemOf.set(it.id, it);
+        for (const m of it.members)
+            itemOf.set(m.id, it);
+    }
+    for (const it of items) {
+        if (it.kind !== 'external')
+            continue;
+        let fromActor = false, into = 0, outof = 0;
+        for (const e of g.edges) {
+            const A = itemOf.get(e.from), B = itemOf.get(e.to);
+            if (B === it && A?.band === 0)
+                fromActor = true;
+            if (B === it && A?.band === 1)
+                into++;
+            if (A === it && B?.band === 1)
+                outof++;
+        }
+        if (fromActor || (outof > 0 && into === 0))
+            it.band = 0;
+    }
+}
+/** Is `side` of leaf `n` clear up to the border of its frame (no sibling in the way)? */
+function sideFree(n, side, siblings) {
+    for (const s of siblings) {
+        if (s.id === n.id)
+            continue;
+        const xo = s.x < n.x + n.w && s.x + s.w > n.x, yo = s.y < n.y + n.h && s.y + s.h > n.y;
+        if (side === 'top' && xo && s.y + s.h <= n.y + 1)
+            return false;
+        if (side === 'bottom' && xo && s.y >= n.y + n.h - 1)
+            return false;
+        if (side === 'left' && yo && s.x + s.w <= n.x + 1)
+            return false;
+        if (side === 'right' && yo && s.x >= n.x + n.w - 1)
+            return false;
+    }
+    return true;
+}
+/** Obstacles for a leg inside a frame: every other card whole, nested frames' title strips. */
+export function obstaclesFor(nodes, a, b) {
+    const obs = [];
+    for (const n of nodes) {
+        if (n.id === a.id || n.id === b.id)
+            continue;
+        if (!n.isBoundary) {
+            obs.push(n);
+            continue;
+        }
+        const holds = underId(a.id, n.id) || underId(b.id, n.id);
+        if (holds) {
+            obs.push({ x: n.x, y: n.y, w: Math.min(n.w, 16 + textWidth(n.label, 13) * 1.08 + 10 + textWidth(`[${n.kind}]`, 9.5) + 16), h: TITLE_H });
+            const footer = footerOf(n);
+            if (footer)
+                obs.push({ x: n.x, y: n.y + n.h - footer - 6, w: n.w, h: footer + 6 }); // the agent chips along the bottom
+        }
+        else
+            obs.push(n);
+    }
+    return obs;
+}
+const TOP_OPTS = {
+    'elk.algorithm': 'layered', 'elk.direction': 'DOWN', 'elk.edgeRouting': 'ORTHOGONAL',
+    'elk.partitioning.activate': 'true',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '72', 'elk.spacing.nodeNode': '40',
+    'elk.spacing.edgeNode': '18', 'elk.spacing.edgeEdge': '14', 'elk.layered.spacing.edgeNodeBetweenLayers': '24',
+    'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF', 'elk.layered.nodePlacement.favorStraightEdges': 'true',
+    'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+    'elk.spacing.labelNode': '8', 'elk.spacing.edgeLabel': '6',
+};
+export async function layoutTwoPhase(g, opts = {}) {
+    const target = opts.target ?? 1.6;
+    const dirOpt = opts.dir ?? 'auto';
+    // ---- phase 1: every top-level thing becomes an item ----
+    const items = [];
+    for (const n of g.roots) {
+        if (!n.children.length) {
+            const box = nodeBox(n.label, n.tech, n.kind, n.meta, n.agents);
+            items.push({ node: n, id: n.id, kind: n.kind, band: bandOf(n), w: box.w, h: box.h, sub: null, members: [], x: 0, y: 0 });
+            continue;
+        }
+        const ids = new Set(idsUnder(n));
+        const edges = g.edges.filter(e => ids.has(e.from) && ids.has(e.to));
+        const dir = dirOpt === 'auto' ? await autoDir(n, edges, target) : dirOpt;
+        items.push(await frameItem(n, edges, dir, opts.wrap ? WRAP(target * 1.3) : {}));
+    }
+    if (!items.length)
+        return { nodes: [], edges: [], width: 0, height: 0 };
+    smartBands(items, g);
+    const itemOf = new Map();
+    for (const it of items) {
+        itemOf.set(it.id, it);
+        for (const m of it.members)
+            itemOf.set(m.id, it);
+    }
+    const cross = g.edges.map((e, i) => ({ e, i })).filter(({ e }) => itemOf.get(e.from) && itemOf.get(e.to) && itemOf.get(e.from) !== itemOf.get(e.to));
+    const elk = await elkInstance();
+    const nodeOf = (it) => ({
+        id: it.id, width: it.w, height: it.h,
+        layoutOptions: {
+            'elk.partitioning.partition': String(it.band),
+            // people first, downstream third parties last; an upstream third party sits in
+            // the top partition but must not be FIRST — ELK refuses an edge between two FIRST nodes
+            ...(it.kind === 'actor' ? { 'elk.layered.layering.layerConstraint': 'FIRST' } : {}),
+            ...(it.band === 2 && it.kind === 'external' ? { 'elk.layered.layering.layerConstraint': 'LAST' } : {}),
+        },
+    });
+    // ---- pass 1: no ports — learn who ends up above whom ----
+    const r1 = await elk.layout({
+        id: 'root', layoutOptions: TOP_OPTS, children: items.map(nodeOf),
+        edges: cross.map(({ e, i }) => ({ id: `e${i}`, sources: [itemOf.get(e.from).id], targets: [itemOf.get(e.to).id] })),
+    });
+    const pos1 = new Map(r1.children.map((c) => [c.id, c]));
+    // ---- pass 2: fixed ports at the inner endpoint's coordinate on the facing border ----
+    const ports = new Map(items.map(it => [it.id, []]));
+    const portCount = new Map();
+    const ensurePort = (it, leafId, side) => {
+        const list = ports.get(it.id);
+        const k = `${it.id}::${leafId}::${side}`;
+        const n = portCount.get(k) ?? 0;
+        portCount.set(k, n + 1);
+        const id = `${k}::${n}`;
+        // several edges on one side of one card: spread them 12px apart, deterministically by edge order
+        const spread = n === 0 ? 0 : (n % 2 ? 1 : -1) * 12 * Math.ceil(n / 2);
+        const horizontal = side === 'left' || side === 'right';
+        if (!it.sub) {
+            list.push({ id, side, x: (side === 'left' ? 0 : side === 'right' ? it.w : it.w / 2) + (horizontal ? 0 : spread),
+                y: (side === 'top' ? 0 : side === 'bottom' ? it.h : it.h / 2) + (horizontal ? spread : 0) });
+            return id;
+        }
+        const leaf = it.members.find(l => l.id === leafId);
+        // a top port under the frame's title text would have to snake around it: start right of the title
+        const titleW = 16 + textWidth(it.node.label, 13) * 1.08 + 10 + textWidth(`[${it.kind}]`, 9.5) + 24;
+        list.push({ id, side,
+            x: side === 'left' ? 0 : side === 'right' ? it.w : (side === 'top' ? Math.max(cx(leaf), titleW) : cx(leaf)) + spread,
+            y: side === 'top' ? 0 : side === 'bottom' ? it.h : cy(leaf) + spread });
+        return id;
+    };
+    const sideFor = (from, to) => {
+        const A = pos1.get(from.id), B = pos1.get(to.id);
+        if (A.y + A.height <= B.y)
+            return ['bottom', 'top'];
+        if (B.y + B.height <= A.y)
+            return ['top', 'bottom'];
+        return A.x < B.x ? ['right', 'left'] : ['left', 'right'];
+    };
+    /** The wanted side, unless a sibling blocks it — then the free side facing the partner. */
+    const freeSide = (it, leafId, want, other) => {
+        if (!it.sub)
+            return want;
+        const leaf = it.members.find(l => l.id === leafId);
+        const sib = it.members.filter(n => n.id !== leafId && !leafId.startsWith(n.id + '.') && !n.id.startsWith(leafId + '.'));
+        if (sideFree(leaf, want, sib))
+            return want;
+        const P = pos1.get(it.id), Q = pos1.get(other.id);
+        const alt = want === 'top' || want === 'bottom'
+            ? (Q.x + Q.width / 2 < P.x + P.width / 2 ? ['left', 'right'] : ['right', 'left'])
+            : (Q.y + Q.height / 2 < P.y + P.height / 2 ? ['top', 'bottom'] : ['bottom', 'top']);
+        for (const s of alt)
+            if (sideFree(leaf, s, sib))
+                return s;
+        return want;
+    };
+    const edges2 = cross.map(({ e, i }) => {
+        const A = itemOf.get(e.from), B = itemOf.get(e.to);
+        const [wa, wb] = sideFor(A, B);
+        const sa = freeSide(A, e.from, wa, B), sb = freeSide(B, e.to, wb, A);
+        return { id: `e${i}`, sources: [ensurePort(A, e.from, sa)], targets: [ensurePort(B, e.to, sb)],
+            labels: e.label ? [{ text: e.label, width: textWidth(e.label, 10) + 8, height: 14 }] : [] };
+    });
+    const SIDE = { top: 'NORTH', bottom: 'SOUTH', left: 'WEST', right: 'EAST' };
+    const r2 = await elk.layout({
+        id: 'root', layoutOptions: TOP_OPTS, edges: edges2,
+        children: items.map(it => ({ ...nodeOf(it),
+            layoutOptions: { ...nodeOf(it).layoutOptions, 'elk.portConstraints': 'FIXED_POS' },
+            ports: ports.get(it.id).map(p => ({ id: p.id, width: 1, height: 1, x: p.x - 0.5, y: p.y - 0.5, layoutOptions: { 'elk.port.side': SIDE[p.side] } })) })),
+    });
+    // ---- place ----
+    const out = { nodes: [], edges: [], width: 0, height: 0 };
+    const pos = new Map(r2.children.map((c) => [c.id, c]));
+    for (const it of items) {
+        const c = pos.get(it.id);
+        it.x = c.x;
+        it.y = c.y;
+        if (!it.sub) {
+            const n = it.node;
+            out.nodes.push({ id: n.id, kind: n.kind, label: n.label, tech: n.tech, meta: n.meta, ref: n.ref, phase: n.phase, load: n.load, over: n.over, agents: n.agents, stage: n.stage,
+                transit: n.transit, external: n.external, x: c.x, y: c.y, w: it.w, h: it.h, depth: 0, isBoundary: false });
+            continue;
+        }
+        for (const k of it.sub.nodes)
+            out.nodes.push({ ...k, x: k.x + c.x, y: k.y + c.y });
+        for (const e of it.sub.edges)
+            out.edges.push({ ...e, points: e.points.map(p => ({ x: p.x + c.x, y: p.y + c.y })),
+                labelPos: e.labelPos ? { x: e.labelPos.x + c.x, y: e.labelPos.y + c.y } : undefined });
+    }
+    const byId = new Map(out.nodes.map(n => [n.id, n]));
+    const used = new Map();
+    /** Inner leg: from the border port to the leaf, around the frame's other members. */
+    const leg = (it, leafId, p) => {
+        const n = byId.get(leafId);
+        const frame = byId.get(it.id);
+        const obs = obstaclesFor(out.nodes.filter(k => it.members.some(m => m.id === k.id)), n, n);
+        const inFrame = (q) => q.x >= frame.x - 1 && q.x <= frame.x + frame.w + 1 && q.y >= frame.y - 1 && q.y <= frame.y + frame.h + 1;
+        const inside = (q, r) => q.x > r.x + 0.5 && q.x < r.x + r.w - 0.5 && q.y > r.y + 0.5 && q.y < r.y + r.h - 0.5;
+        const blocked = (q) => !inFrame(q) || obs.some(r => inside(q, r)) || inside(q, n);
+        let best = null;
+        for (const side of ['top', 'bottom', 'left', 'right']) {
+            const st = stub(n, side);
+            if (blocked(st.out))
+                continue;
+            const grid = makeGrid([...obs, n], [p, st.out]);
+            const path = astar(grid, p, st.out, blocked, new Map(used));
+            if (!path)
+                continue;
+            let cost = 0;
+            for (let k = 1; k < path.length; k++)
+                cost += Math.abs(path[k].x - path[k - 1].x) + Math.abs(path[k].y - path[k - 1].y) + 70;
+            if (!best || cost < best.cost)
+                best = { cost, pts: [...path, st.on], grid };
+        }
+        if (!best) {
+            const st = stub(n, p.y <= n.y ? 'top' : p.y >= n.y + n.h ? 'bottom' : p.x < n.x ? 'left' : 'right');
+            return [p, { x: st.on.x, y: p.y }, st.on];
+        }
+        markUsed(best.grid, best.pts, used);
+        return best.pts;
+    };
+    for (const e2 of r2.edges ?? []) {
+        const src = g.edges[+String(e2.id).slice(1)];
+        const sec = e2.sections?.[0];
+        if (!sec)
+            continue;
+        const pts = [sec.startPoint, ...(sec.bendPoints ?? []), sec.endPoint];
+        const A = itemOf.get(src.from), B = itemOf.get(src.to);
+        const head = A.sub ? leg(A, src.from, pts[0]).reverse() : [pts[0]];
+        const tail = B.sub ? leg(B, src.to, pts[pts.length - 1]) : [pts[pts.length - 1]];
+        const lbl = e2.labels?.[0];
+        const edge = { from: src.from, to: src.to, label: src.label, verb: src.verb, derived: src.derived, dashed: src.dashed,
+            points: simplify([...head.slice(0, -1), ...pts, ...tail.slice(1)]),
+            labelPos: lbl && lbl.x !== undefined ? { x: lbl.x, y: lbl.y } : undefined };
+        out.edges.push(edge);
+    }
+    // an edge the top pass could not route (should not happen) still gets a line
+    const routed = new Set(out.edges.map(e => `${e.from}>${e.to}>${e.verb}>${e.label ?? ''}`));
+    for (const e of g.edges) {
+        const a = byId.get(e.from), b = byId.get(e.to);
+        if (!a || !b || routed.has(`${e.from}>${e.to}>${e.verb}>${e.label ?? ''}`))
+            continue;
+        out.edges.push({ from: e.from, to: e.to, label: e.label, verb: e.verb, derived: e.derived, dashed: e.dashed, points: routeSimple(a, b) });
+    }
+    out.width = Math.max(0, ...out.nodes.map(n => n.x + n.w));
+    out.height = Math.max(0, ...out.nodes.map(n => n.y + n.h));
+    return out;
+}

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

@@ -0,0 +1,64 @@
+import { type RenderGraph } from '../lens.js';
+export interface Positioned {
+    id: string;
+    kind: string;
+    label: string;
+    tech?: string;
+    meta?: string;
+    ref?: string;
+    phase?: string;
+    load?: string;
+    over?: boolean;
+    agents?: string[];
+    stage?: string;
+    transit: boolean;
+    external: boolean;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    depth: number;
+    isBoundary: boolean;
+}
+export interface RoutedEdge {
+    from: string;
+    to: string;
+    label?: string;
+    verb: string;
+    derived: boolean;
+    dashed: boolean;
+    points: {
+        x: number;
+        y: number;
+    }[];
+    labelPos?: {
+        x: number;
+        y: number;
+    };
+    /** Where along the route (0…1 by length) the label sits when nothing else placed it — a person dragged it there. */
+    labelAt?: number;
+    /** The label on the other side of the line (below / left) — a person put it there. */
+    labelFlip?: boolean;
+}
+export interface Layout {
+    nodes: Positioned[];
+    edges: RoutedEdge[];
+    width: number;
+    height: number;
+}
+export interface LayoutOptions {
+    /** ELK options merged over the root defaults — the layout experiments live here. */
+    root?: Record<string, string>;
+    boundary?: Record<string, string>;
+}
+/** The single-pass layered layout — used inside frames by the two-phase layout, and as an escape hatch. */
+export declare function layoutLayered(g: RenderGraph, opts?: LayoutOptions): Promise<Layout>;
+import { type BalanceOptions } from './balance.js';
+/**
+ * The default layout: two-phase (frames on their own, then the top level with
+ * ports) — see balance.ts for why. `strategy: 'layered'` gives the old single
+ * pass.
+ */
+export declare function layout(g: RenderGraph, opts?: LayoutOptions & BalanceOptions & {
+    strategy?: 'two-phase' | 'layered';
+}): Promise<Layout>;

package/dist/src/layout/elk.js

@@ -0,0 +1,267 @@
+import { footerOf, AGENT_MIN_W } from '../lens.js';
+import { elkInstance } from './host.js';
+import { nodeBox, textWidth } from './measure.js';
+/**
+ * Reading order: people at the top, your systems in the middle, third parties
+ * at the bottom. This is how every hand-drawn C4 context diagram is arranged,
+ * and ELK will not discover it on its own.
+ */
+function partitionOf(n) {
+    if (n.kind === 'actor')
+        return 0;
+    if (n.kind === 'external')
+        return 2;
+    return 1; // transit is deliberately NOT pinned: pinning it manufactures
+    // back-edges that then have to crawl around the whole diagram
+}
+/**
+ * Top to bottom, the way a C4 picture is read: people on top, the system in
+ * the middle, third parties at the bottom. A left-to-right layering of the
+ * same graphs came out 4–7 times wider than tall — unreadable at "fit" on a
+ * landscape screen; top-down lands near 0.6–0.7 and the datastore clusters
+ * already stack downwards. Spacing is deliberately tight: the six reference
+ * architectures measured 12–15 % ink at the wider values.
+ */
+const ROOT_OPTS = {
+    'elk.algorithm': 'layered',
+    'elk.direction': 'DOWN',
+    'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+    'elk.edgeRouting': 'ORTHOGONAL',
+    'elk.partitioning.activate': 'true',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '56',
+    'elk.spacing.nodeNode': '28',
+    'elk.spacing.edgeNode': '18',
+    'elk.spacing.edgeEdge': '14',
+    'elk.layered.spacing.edgeNodeBetweenLayers': '22',
+    'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
+    'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+    'elk.layered.thoroughness': '70',
+    'elk.layered.cycleBreaking.strategy': 'GREEDY',
+    'elk.layered.nodePlacement.favorStraightEdges': 'true',
+    // NOTE: elk.layered.wrapping is incompatible with partitioning — enabling it
+    // throws inside ELK. Narrowing wide diagrams needs a different lever.
+    'elk.aspectRatio': '1.7',
+    'elk.spacing.labelNode': '8',
+    'elk.spacing.edgeLabel': '6',
+};
+const BOUNDARY_OPTS = {
+    'elk.padding': '[top=48,left=26,bottom=26,right=26]',
+    'elk.spacing.nodeNode': '26',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '50',
+};
+/**
+ * A store belongs beside the service that owns it.
+ *
+ * In a plain left-to-right layered graph a datastore lands in the next column,
+ * far from its service and often past three unrelated boxes. Putting the owner
+ * and its stores into an invisible group keeps them adjacent and makes the
+ * `writes` edge short. (A strict "directly below" would need the group laid out
+ * separately, which ELK refuses to mix with INCLUDE_CHILDREN.)
+ */
+const CLUSTER_OPTS = {
+    'elk.algorithm': 'layered',
+    'elk.direction': 'DOWN',
+    'elk.padding': '[top=0,left=0,bottom=0,right=0]',
+    'elk.spacing.nodeNode': '26',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '30',
+};
+const STORAGE = new Set(['datastore', 'cache']);
+/** Title strip height: a meta line that cannot sit beside the title in a 300px frame wraps under it. */
+function headOf(n) {
+    if (!n.meta)
+        return 48;
+    const need = 16 + textWidth(n.label, 13) * 1.08 + 10 + textWidth(`[${n.kind}]`, 9.5) + 24 + textWidth(n.meta, 10) * 1.2 + 14;
+    return need > 300 ? 62 : 48;
+}
+/** The single-pass layered layout — used inside frames by the two-phase layout, and as an escape hatch. */
+export async function layoutLayered(g, opts = {}) {
+    const rootOpts = { ...ROOT_OPTS, ...(opts.root ?? {}) };
+    const boundaryOpts = { ...BOUNDARY_OPTS, ...(opts.boundary ?? {}) };
+    const elk = await elkInstance();
+    // ---- index the source tree ----
+    const meta = new Map();
+    const parentOf = new Map();
+    const index = (ns, parent) => {
+        for (const n of ns) {
+            meta.set(n.id, n);
+            parentOf.set(n.id, parent);
+            index(n.children, n.id);
+        }
+    };
+    index(g.roots);
+    // ---- pull each store under the single service that owns it ----
+    const clusterOf = new Map(); // storeId -> ownerId
+    {
+        const writers = new Map();
+        for (const e of g.edges) {
+            const to = meta.get(e.to);
+            if (!to || !STORAGE.has(to.kind))
+                continue;
+            (writers.get(e.to) ?? writers.set(e.to, new Set()).get(e.to)).add(e.from);
+        }
+        for (const [id, n] of meta) {
+            if (!STORAGE.has(n.kind))
+                continue;
+            const declared = n.ownedBy;
+            const inferred = writers.get(id)?.size === 1 ? [...writers.get(id)][0] : undefined;
+            const owner = declared ?? inferred;
+            if (!owner || !meta.has(owner))
+                continue;
+            if (parentOf.get(owner) !== parentOf.get(id))
+                continue; // same container only
+            // An owner that is itself a frame (a service opened to its components)
+            // cannot host a cluster: the store would be cut out of its parent and
+            // never placed anywhere. It stays a plain neighbour instead.
+            if (meta.get(owner).children.length)
+                continue;
+            clusterOf.set(id, owner);
+        }
+        // The cluster becomes a real level of the hierarchy, so the owner→store
+        // edge lands inside it: that single edge is what makes ELK stack the store
+        // beneath its service instead of parking it in the next column.
+        const owners = new Set(clusterOf.values());
+        for (const owner of owners) {
+            const cid = `__cluster__${owner}`;
+            parentOf.set(cid, parentOf.get(owner)); // once per owner, before rebinding
+            parentOf.set(owner, cid);
+        }
+        for (const [store, owner] of clusterOf)
+            parentOf.set(store, `__cluster__${owner}`);
+    }
+    const chain = (id) => {
+        const out = [];
+        let cur = id;
+        while (cur !== undefined) {
+            out.unshift(cur);
+            cur = parentOf.get(cur);
+        }
+        return out;
+    };
+    /**
+     * Attach every edge to the lowest container that holds both endpoints.
+     * ELK reports edge coordinates relative to the edge's own container, so
+     * placing edges by hand is what makes the offsets predictable — reading
+     * them from a flat root list gives mixed coordinate frames.
+     */
+    const lca = (a, b) => {
+        const ca = chain(a), cb = chain(b);
+        let last;
+        for (let i = 0; i < Math.min(ca.length, cb.length) - 0; i++) {
+            if (ca[i] === cb[i] && (i < ca.length - 1) && (i < cb.length - 1))
+                last = ca[i];
+            else
+                break;
+        }
+        return last;
+    };
+    const edgesByContainer = new Map();
+    g.edges.forEach((e, i) => {
+        const c = lca(e.from, e.to) ?? '__root__';
+        const arr = edgesByContainer.get(c) ?? [];
+        arr.push({
+            id: `e${i}`, sources: [e.from], targets: [e.to],
+            labels: e.label ? [{ text: e.label, width: textWidth(e.label, 10) + 8, height: 14 }] : [],
+        });
+        edgesByContainer.set(c, arr);
+    });
+    const plain = (n) => {
+        const boundary = n.children.length > 0;
+        const box = nodeBox(n.label, n.tech, n.kind, n.meta, n.agents);
+        const part = partitionOf(n);
+        return {
+            id: n.id,
+            ...(boundary ? {} : { width: box.w, height: box.h }),
+            layoutOptions: {
+                ...(boundary ? boundaryOpts : {}),
+                // a frame with agent chips along its bottom needs the footer row below its members
+                ...(boundary && (footerOf(n) || headOf(n) > 48) ? { 'elk.padding': `[top=${headOf(n)},left=26,bottom=${26 + footerOf(n)},right=26]` } : {}),
+                // the footer was sized for a frame at least this wide; hold the frame open to it
+                // (ELK transposes the graph for DOWN/UP and forgets to transpose this option — so we do)
+                ...(boundary && footerOf(n) ? { 'elk.nodeSize.constraints': 'MINIMUM_SIZE', 'elk.nodeSize.minimum': /DOWN|UP/.test(rootOpts['elk.direction'] ?? '') ? `(0, ${AGENT_MIN_W})` : `(${AGENT_MIN_W}, 0)` } : {}),
+                ...(part !== undefined && parentOf.get(n.id) === undefined ? { 'elk.partitioning.partition': String(part) } : {}),
+                // people share the first row and third parties the last one, whatever
+                // the edges would prefer — the picture is read top to bottom
+                ...(parentOf.get(n.id) === undefined && n.kind === 'actor' ? { 'elk.layered.layering.layerConstraint': 'FIRST' } : {}),
+                ...(parentOf.get(n.id) === undefined && n.kind === 'external' ? { 'elk.layered.layering.layerConstraint': 'LAST' } : {}),
+            },
+            children: n.children.filter(c => !clusterOf.has(c.id)).map(toElk),
+            edges: edgesByContainer.get(n.id) ?? [],
+            labels: boundary ? [{ text: n.label, width: textWidth(n.label, 13), height: 18 }] : [],
+        };
+    };
+    const toElk = (n) => {
+        const owned = [...clusterOf.entries()].filter(([, o]) => o === n.id).map(([s]) => s);
+        if (!owned.length || n.children.length)
+            return plain(n);
+        return {
+            id: `__cluster__${n.id}`,
+            layoutOptions: CLUSTER_OPTS,
+            children: [plain(n), ...owned.map(id => plain(meta.get(id)))],
+            edges: edgesByContainer.get(`__cluster__${n.id}`) ?? [],
+            labels: [],
+        };
+    };
+    const graph = {
+        id: 'root',
+        layoutOptions: rootOpts,
+        children: g.roots.filter(n => !clusterOf.has(n.id)).map(toElk),
+        edges: edgesByContainer.get('__root__') ?? [],
+    };
+    const res = await elk.layout(graph);
+    const nodes = [];
+    const abs = new Map();
+    const walkNodes = (children, ox, oy, depth) => {
+        for (const c of children) {
+            const x = ox + (c.x ?? 0), y = oy + (c.y ?? 0);
+            abs.set(c.id, { x, y });
+            if (String(c.id).startsWith('__cluster__')) {
+                walkNodes(c.children ?? [], x, y, depth);
+                continue;
+            }
+            const m = meta.get(c.id);
+            nodes.push({
+                id: c.id, kind: m?.kind ?? '', label: m?.label ?? c.id, tech: m?.tech, meta: m?.meta, ref: m?.ref, phase: m?.phase, load: m?.load, over: m?.over, agents: m?.agents, stage: m?.stage,
+                transit: m?.transit ?? false, external: m?.external ?? false,
+                x, y, w: c.width ?? 0, h: c.height ?? 0, depth,
+                isBoundary: (c.children?.length ?? 0) > 0,
+            });
+            if (c.children?.length)
+                walkNodes(c.children, x, y, depth + 1);
+        }
+    };
+    walkNodes(res.children ?? [], 0, 0, 0);
+    const edges = [];
+    const walkEdges = (n, ox, oy) => {
+        for (const e of n.edges ?? []) {
+            const src = g.edges[Number(String(e.id).slice(1))];
+            if (!src)
+                continue;
+            const sec = e.sections?.[0];
+            const pts = sec ? [sec.startPoint, ...(sec.bendPoints ?? []), sec.endPoint] : [];
+            const lbl = e.labels?.[0];
+            edges.push({
+                from: src.from, to: src.to, label: src.label, verb: src.verb,
+                derived: src.derived, dashed: src.dashed,
+                points: pts.map((p) => ({ x: p.x + ox, y: p.y + oy })),
+                labelPos: lbl ? { x: (lbl.x ?? 0) + ox, y: (lbl.y ?? 0) + oy } : undefined,
+            });
+        }
+        for (const c of n.children ?? []) {
+            const a = abs.get(c.id) ?? { x: ox + (c.x ?? 0), y: oy + (c.y ?? 0) };
+            walkEdges(c, a.x, a.y);
+        }
+    };
+    walkEdges(res, 0, 0);
+    return { nodes, edges, width: res.width ?? 0, height: res.height ?? 0 };
+}
+import { layoutTwoPhase } from './balance.js';
+/**
+ * The default layout: two-phase (frames on their own, then the top level with
+ * ports) — see balance.ts for why. `strategy: 'layered'` gives the old single
+ * pass.
+ */
+export async function layout(g, opts = {}) {
+    if (opts.strategy === 'layered' || opts.root || opts.boundary)
+        return layoutLayered(g, opts);
+    return layoutTwoPhase(g, opts);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Where ELK runs. The engine does not care: it asks for an instance and
+ * awaits `layout()`. By default that is the bundled ELK on the calling thread
+ * (Node, tests, a script). A browser host that would rather keep its UI
+ * responsive hands over a factory once — `useElkWorker(url)` is the usual one
+ * — and every layout after that runs in a Web Worker.
+ *
+ * The bundled ELK is loaded on first use, not on import: a page that has
+ * configured a worker never pays for the 1.4 MB of algorithms twice.
+ */
+export interface ElkLike {
+    layout(graph: unknown, options?: unknown): Promise<any>;
+}
+/** Replace how ELK instances are made. Takes effect for the next layout. */
+export declare function configureElk(make: (() => ElkLike | Promise<ElkLike>) | null): void;
+/** The shared ELK instance — created on first use, reused after. */
+export declare function elkInstance(): Promise<ElkLike>;
+/**
+ * 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 declare function useElkWorker(url: string): Promise<void>;