@yalehwang/plantuml-js 0.2.2 → 0.3.0

package/dist/layout/compound.js

@@ -0,0 +1,1178 @@
+/**
+ * Compound layout — lay packages out as independent blocks, place the blocks,
+ * then route the edges that cross block boundaries.
+ *
+ * A single hierarchical layered run (`INCLUDE_CHILDREN`) routes every edge but
+ * stacks all layers of every package into one tall strip: the 660-entity
+ * archguard `all-classes` graph came out 13455×79369. Here each top-level
+ * package is laid out on its own (packed to a balanced rectangle), the blocks
+ * are arranged as plain nodes — layered for small block counts, rectpacking for
+ * large ones — and [[routeOrthogonal]] draws the cross-block edges around the
+ * leaf boxes along the channels between blocks.
+ */
+import { estimateEntitySize, PACKAGE_LABEL, } from '../foundation/layout.js';
+import { measureTextWidth } from '../foundation/text-measure.js';
+import { routeOrthogonal } from './grid-router.js';
+import { mergeElkOptions } from './elk-graph.js';
+import { relationSemantics } from '../foundation/relation-semantics.js';
+import { runPlacementStrategies, } from './placement-strategy.js';
+const PACKAGE_PREFIX = 'pkg::';
+/** Block aspect ratio beyond which a flat block is repacked instead of layered. */
+const BLOCK_MAX_ASPECT = 2.2;
+/**
+ * Width beyond which a lopsided nested block is split into child blocks and
+ * rect-packed; narrower strips keep their (low-crossing) layered routing.
+ */
+const NESTED_SPLIT_WIDTH = 3500;
+/** Block count above which blocks are packed instead of layered. */
+const PACK_BLOCK_THRESHOLD = 12;
+/** Block count from which sparsely linked, layer-less roots are rect-packed too. */
+const MID_PACK_BLOCK_THRESHOLD = 8;
+/** Multipliers of the requested ratio tried when rect-packing blocks. */
+const PACK_ASPECT_CANDIDATES = [0.6, 1, 1.5];
+/** Above this many blocks the packing-candidate search is skipped. */
+const MAX_CANDIDATE_BLOCKS = 30;
+/** Canvas ratio band a packed candidate should stay inside to be preferred. */
+const PACK_BAND_MIN = 0.7;
+const PACK_BAND_MAX = 2.2;
+/** Gap between blocks: wide enough for several routing lanes. */
+const BLOCK_SPACING = 64;
+/** Clearance ELK keeps between an edge and a node / another edge inside a block. */
+const EDGE_NODE_SPACING = 12;
+const EDGE_EDGE_SPACING = 10;
+/** A layered block with at least this many nodes at lower density is repacked. */
+const SPARSE_MIN_NODES = 30;
+/** Vertical distance (px) between node centres beyond which they sit on different layers. */
+const FLOW_LAYER_GAP = 24;
+/** Dense graphs pack their blocks taller so the placed blocks do not stretch the canvas. */
+const DENSE_SHELF_ASPECT_SCALE = 0.6;
+/** Block rows aim for the canvas ratio itself: wider rows stretch the canvas past what the layers above can balance. */
+const SHELF_ASPECT_SCALE = 1.25;
+/**
+ * A repacked block wider than this is packed again at a lower ratio (see
+ * [[SHELF_NARROW_SCALES]]): one wide block sets the canvas width of the whole diagram.
+ */
+const SHELF_MAX_WIDTH = 1600;
+const SHELF_NARROW_SCALES = [1.0, 0.8];
+/** Node gap of a repacked block: wide enough channels for several edge lanes. */
+const SHELF_GAP = 72;
+/** Unconnected boxes from this many up are laid out as an equal-column grid. */
+const GRID_MIN_NODES = 6;
+/** Canvas ratio an equal-column grid aims for, and the gap between its cells. */
+const GRID_ASPECT = 1.3;
+const GRID_GAP = 24;
+/** Dense (very large) graphs keep the uniform grid: the looser blocks pack into a smaller canvas. */
+const DENSE_GRID_GAP = 40;
+const DENSE_GRID_ROW_GAP = 50;
+/** Row gap, as tight as the column gap: the grid router finds its lanes between rows either way. */
+const GRID_ROW_GAP = 24;
+const SHELF_PADDING = { top: 26, side: 10, bottom: 10 };
+const SPARSE_DENSITY = 0.16;
+/** Hub rail: gap between hubs / columns, and the shortest column height before wrapping. */
+const HUB_RAIL_GAP = 16;
+const HUB_RAIL_MIN_HEIGHT = 400;
+/** Border kept free around the whole canvas for outer routing lanes. */
+const CANVAS_MARGIN = 40;
+/** Node gap inside packed blocks of a dense (very large) graph; leaves one routing lane. */
+const DENSE_NODE_SPACING = 36;
+/** Tightest gap between neighbouring stubs on the rail, px. */
+const RAIL_MIN_GAP = 24;
+/** Lattice cost of crossing a wire in a view with stub rails (their fans are crossing-prone), and elsewhere. */
+const STUB_CROSSING_COST = 40;
+const CROSSING_COST = 12;
+/** Cost per px a rail runs past the frame side it follows (in px of target distance). */
+const RAIL_OVERFLOW_WEIGHT = 0.5;
+export const DEFAULT_STUB_ORBIT = { gap: 48, spacing: 120, anchor: 'centroid' };
+function packageMinWidth(name) {
+    return measureTextWidth(name, PACKAGE_LABEL.fontSize) + PACKAGE_LABEL.tabPadding + 20;
+}
+export async function compoundLayout(elk, model, options) {
+    const pkgById = new Map(model.packages.map((p) => [p.id, p]));
+    const topOfPackage = new Map();
+    const topPackageOf = (id) => {
+        const cached = topOfPackage.get(id);
+        if (cached !== undefined)
+            return cached;
+        let cur = pkgById.get(id);
+        const seen = new Set([cur.id]);
+        while (cur.parentId !== undefined && pkgById.has(cur.parentId) && !seen.has(cur.parentId)) {
+            cur = pkgById.get(cur.parentId);
+            seen.add(cur.id);
+        }
+        topOfPackage.set(id, cur.id);
+        return cur.id;
+    };
+    /** Block key of an entity: its top-level package, or itself when it has none. */
+    const blockOfEntity = new Map();
+    for (const entity of model.entities) {
+        const pkgId = entity.packageId !== undefined && pkgById.has(entity.packageId) ? entity.packageId : undefined;
+        blockOfEntity.set(entity.id, pkgId !== undefined ? PACKAGE_PREFIX + topPackageOf(pkgId) : entity.id);
+    }
+    // Group model parts by block.
+    const entitiesByBlock = new Map();
+    for (const entity of model.entities) {
+        const key = blockOfEntity.get(entity.id);
+        const list = entitiesByBlock.get(key);
+        if (list)
+            list.push(entity);
+        else
+            entitiesByBlock.set(key, [entity]);
+    }
+    const packagesByBlock = new Map();
+    for (const pkg of model.packages) {
+        const key = PACKAGE_PREFIX + topPackageOf(pkg.id);
+        const list = packagesByBlock.get(key);
+        if (list)
+            list.push(pkg);
+        else
+            packagesByBlock.set(key, [pkg]);
+    }
+    const blockKeys = [];
+    for (const pkg of model.packages) {
+        if (topPackageOf(pkg.id) === pkg.id)
+            blockKeys.push(PACKAGE_PREFIX + pkg.id);
+    }
+    for (const entity of model.entities) {
+        const key = blockOfEntity.get(entity.id);
+        if (!key.startsWith(PACKAGE_PREFIX) || !packagesByBlock.has(key)) {
+            if (!blockKeys.includes(key))
+                blockKeys.push(key);
+        }
+    }
+    const relationsByBlock = new Map();
+    const crossRelations = [];
+    model.relations.forEach((relation, index) => {
+        const sb = blockOfEntity.get(relation.source);
+        const tb = blockOfEntity.get(relation.target);
+        if (sb === undefined || tb === undefined)
+            return;
+        if (sb === tb) {
+            const list = relationsByBlock.get(sb);
+            if (list)
+                list.push(index);
+            else
+                relationsByBlock.set(sb, [index]);
+        }
+        else {
+            crossRelations.push(index);
+        }
+    });
+    // 1. Lay each block out on its own.
+    const blocks = new Map();
+    for (const key of blockKeys) {
+        const entities = entitiesByBlock.get(key) ?? [];
+        const packages = packagesByBlock.get(key) ?? [];
+        blocks.set(key, await layoutBlock(elk, model, key, entities, packages, relationsByBlock.get(key) ?? [], options));
+    }
+    // 2. Place the blocks.
+    const placed = await placeBlocks(elk, model, blocks, crossRelations, blockOfEntity, options);
+    // 3. Absolute geometry.
+    const nodes = [];
+    const packagesOut = [];
+    const edgePoints = new Map();
+    for (const key of blockKeys) {
+        const block = blocks.get(key);
+        const at = placed.positions.get(key) ?? { x: CANVAS_MARGIN, y: CANVAS_MARGIN };
+        for (const n of block.nodes)
+            nodes.push({ ...n, x: n.x + at.x, y: n.y + at.y });
+        for (const p of block.packages)
+            packagesOut.push({ ...p, x: p.x + at.x, y: p.y + at.y });
+        for (const index of block.unrouted ?? [])
+            crossRelations.push(index);
+        for (const [index, points] of block.edges) {
+            edgePoints.set(index, points.map((p) => ({ x: p.x + at.x, y: p.y + at.y })));
+        }
+    }
+    // 4. Route the edges that cross blocks.
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const requests = [];
+    for (const index of crossRelations) {
+        const relation = model.relations[index];
+        const source = nodeById.get(relation.source);
+        const target = nodeById.get(relation.target);
+        if (source && target)
+            requests.push({ id: String(index), source, target });
+    }
+    const drawn = [...edgePoints].map(([index, points]) => ({
+        source: model.relations[index].source,
+        target: model.relations[index].target,
+        points,
+    }));
+    const routed = routeOrthogonal(requests, nodes, {
+        width: placed.width,
+        height: placed.height,
+        frames: packagesOut,
+        existing: drawn,
+        ripupPasses: options.ripupPasses,
+        crossingCost: model.entities.some((e) => e.stub) ? STUB_CROSSING_COST : CROSSING_COST,
+    });
+    for (const [id, points] of routed)
+        edgePoints.set(Number(id), points);
+    const edges = model.relations.map((relation, index) => ({
+        id: `rel-${index}`,
+        source: relation.source,
+        target: relation.target,
+        points: edgePoints.get(index) ?? [],
+    }));
+    return { nodes, edges, packages: packagesOut, width: placed.width, height: placed.height };
+}
+/** ELK-layout one block (a top-level package subtree, or a single bare entity). */
+async function layoutBlock(elk, model, key, entities, packages, relationIndexes, options) {
+    if (!key.startsWith(PACKAGE_PREFIX) || packages.length === 0) {
+        const entity = entities[0];
+        const size = estimateEntitySize(entity);
+        return {
+            key,
+            width: size.width,
+            height: size.height,
+            nodes: [{ id: entity.id, x: 0, y: 0, width: size.width, height: size.height }],
+            packages: [],
+            edges: new Map(),
+        };
+    }
+    const topId = key.slice(PACKAGE_PREFIX.length);
+    const pkgNodes = new Map();
+    for (const pkg of packages) {
+        if (pkg.id === topId)
+            continue;
+        pkgNodes.set(pkg.id, {
+            id: PACKAGE_PREFIX + pkg.id,
+            children: [],
+            layoutOptions: mergeElkOptions({
+                'elk.padding': '[top=26,left=10,bottom=10,right=10]',
+                'elk.nodeSize.constraints': '[MINIMUM_SIZE]',
+                'elk.nodeSize.minimum': `[${packageMinWidth(pkg.name).toFixed(1)}, ${PACKAGE_LABEL.tabHeight + 36}]`,
+            }, {}, options.elk),
+        });
+    }
+    const rootChildren = [];
+    const touched = new Set();
+    for (const r of model.relations) {
+        touched.add(r.source);
+        touched.add(r.target);
+    }
+    // Summarised hubs without any drawn edge are not part of the layered graph:
+    // they get a rail along the package side instead of a row on top of it.
+    const hubs = [];
+    for (const entity of entities) {
+        const size = estimateEntitySize(entity);
+        if (entity.packageId === topId && (entity.usageCount ?? 0) > 0 && !touched.has(entity.id)) {
+            hubs.push(entity);
+            continue;
+        }
+        const leaf = { id: entity.id, width: size.width, height: size.height };
+        const owner = entity.packageId !== undefined && entity.packageId !== topId ? pkgNodes.get(entity.packageId) : undefined;
+        if (owner)
+            owner.children.push(leaf);
+        else
+            rootChildren.push(leaf);
+    }
+    for (const pkg of packages) {
+        if (pkg.id === topId)
+            continue;
+        const node = pkgNodes.get(pkg.id);
+        const parent = pkg.parentId !== undefined && pkg.parentId !== topId ? pkgNodes.get(pkg.parentId) : undefined;
+        if (parent)
+            parent.children.push(node);
+        else
+            rootChildren.push(node);
+    }
+    const edges = relationIndexes.map((index) => {
+        const relation = model.relations[index];
+        const reversed = relationSemantics(relation.type).isReversed();
+        return {
+            id: `rel-${index}`,
+            sources: [reversed ? relation.target : relation.source],
+            targets: [reversed ? relation.source : relation.target],
+        };
+    });
+    const pkg = packages.find((p) => p.id === topId);
+    const hasNested = packages.length > 1;
+    const defaults = {
+        'elk.algorithm': 'layered',
+        'elk.direction': 'DOWN',
+        'elk.edgeRouting': options.edgeRouting ?? 'ORTHOGONAL',
+        'elk.spacing.nodeNode': '40',
+        'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+        'elk.layered.portConstraints': 'FIXED_SIDE',
+        'elk.aspectRatio': '1.6',
+        'elk.separateConnectedComponents': 'true',
+        'elk.layered.nodePlacement.strategy': 'INTERACTIVE',
+        'elk.spacing.edgeNode': String(EDGE_NODE_SPACING),
+        'elk.spacing.edgeEdge': String(EDGE_EDGE_SPACING),
+        'elk.padding': '[top=26,left=10,bottom=10,right=10]',
+    };
+    const named = {};
+    if (options.edgeRouting !== undefined)
+        named['elk.edgeRouting'] = options.edgeRouting;
+    if (options.aspectRatio !== undefined)
+        named['elk.aspectRatio'] = String(options.aspectRatio);
+    if (hasNested)
+        defaults['elk.hierarchyHandling'] = 'INCLUDE_CHILDREN';
+    const layoutOptions = mergeElkOptions(defaults, named, options.elk);
+    const graph = { id: 'block', layoutOptions, children: rootChildren, edges };
+    let result = await elk.layout(graph);
+    // Dependency order of the plain layered run (layer by layer, left to right):
+    // a repack keeps it so dependents stay above what they consume.
+    const flowOrder = flowOrderOf(result.children ?? []);
+    let repacked = false;
+    let aspect = (result.width ?? 0) / Math.max(1, result.height ?? 1);
+    const wide = (result.width ?? 0) > NESTED_SPLIT_WIDTH;
+    if (hasNested && wide && (aspect > BLOCK_MAX_ASPECT || aspect < 1 / BLOCK_MAX_ASPECT)) {
+        return splitNestedBlock(elk, model, key, entities, packages, relationIndexes, options);
+    }
+    let sparse = !hasNested && rootChildren.length >= SPARSE_MIN_NODES && blockDensity(rootChildren, result) < SPARSE_DENSITY;
+    if (sparse) {
+        // Fold the long layer chain into several rows before giving up on layering.
+        const wrapped = await elk.layout({
+            ...graph,
+            layoutOptions: { ...layoutOptions, 'elk.layered.wrapping.strategy': 'MULTI_EDGE' },
+        });
+        if (blockDensity(rootChildren, wrapped) > blockDensity(rootChildren, result)) {
+            result = wrapped;
+            sparse = blockDensity(rootChildren, result) < SPARSE_DENSITY;
+        }
+    }
+    const gridable = !hasNested && relationIndexes.length === 0 && rootChildren.length >= GRID_MIN_NODES;
+    const flowRank = new Map(flowOrder.map((id, index) => [id, index]));
+    const ordered = rootChildren
+        .slice()
+        .sort((a, b) => (flowRank.get(a.id) ?? 0) - (flowRank.get(b.id) ?? 0));
+    if (gridable) {
+        // Unconnected boxes have no flow to follow: an equal-column grid reads
+        // better than ragged shelf rows.
+        const placement = await runPlacementStrategies([gridPackPlacementStrategy], {
+            boxes: ordered,
+            order: flowOrder,
+            aspect: GRID_ASPECT,
+            gap: options.dense ? DENSE_GRID_GAP : GRID_GAP,
+            rowGap: options.dense ? DENSE_GRID_ROW_GAP : GRID_ROW_GAP,
+            tight: !options.dense,
+        });
+        result = elkNodeFromPlacement('block', requirePlacement(placement, 'grid packing'), ordered);
+        repacked = true;
+    }
+    else if (!hasNested && (options.dense || sparse || aspect > BLOCK_MAX_ASPECT || aspect < 1 / BLOCK_MAX_ASPECT)) {
+        // A single wide layer cannot be wrapped by the layered algorithm; pack the
+        // boxes into a balanced rectangle, rows in dependency order, and let the
+        // grid router draw the edges.
+        result =
+            options.dense && options.rectPackDense
+                ? await elk.layout({
+                    id: 'block',
+                    layoutOptions: mergeElkOptions({
+                        'elk.algorithm': 'rectpacking',
+                        'elk.aspectRatio': '1.6',
+                        'elk.spacing.nodeNode': String(DENSE_NODE_SPACING),
+                        'elk.padding': '[top=26,left=10,bottom=10,right=10]',
+                    }, options.aspectRatio !== undefined ? { 'elk.aspectRatio': String(options.aspectRatio) } : {}, options.elk),
+                    children: rootChildren,
+                })
+                : elkNodeFromPlacement('block', await packShelves(ordered, flowOrder, options, (h) => (hubs.length > 0 ? placeHubRail(hubs, h).width : 0)), ordered);
+        repacked = true;
+    }
+    const nodes = [];
+    const packagesOut = [];
+    const offsets = new Map([['block', { x: 0, y: 0 }]]);
+    const flatten = (node, ox, oy) => {
+        const x = (node.x ?? 0) + ox;
+        const y = (node.y ?? 0) + oy;
+        offsets.set(node.id, { x, y });
+        if (node.id.startsWith(PACKAGE_PREFIX)) {
+            packagesOut.push({ id: node.id.slice(PACKAGE_PREFIX.length), x, y, width: node.width ?? 0, height: node.height ?? 0 });
+            for (const child of node.children ?? [])
+                flatten(child, x, y);
+        }
+        else {
+            nodes.push({ id: node.id, x, y, width: node.width ?? 0, height: node.height ?? 0 });
+        }
+    };
+    for (const child of result.children ?? [])
+        flatten(child, 0, 0);
+    let width = Math.max(result.width ?? 0, packageMinWidth(pkg.name));
+    let height = Math.max(result.height ?? 0, PACKAGE_LABEL.tabHeight + 36);
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const edgeMap = new Map();
+    if (!repacked) {
+        for (const edge of result.edges ?? []) {
+            const index = Number((edge.id ?? '').slice('rel-'.length));
+            const relation = model.relations[index];
+            const reversed = relationSemantics(relation.type).isReversed();
+            const points = elkEdgePoints(edge, nodeById, offsets);
+            edgeMap.set(index, reversed ? points.slice().reverse() : points);
+        }
+    }
+    if (hubs.length > 0) {
+        const rail = placeHubRail(hubs, height);
+        for (const n of nodes) {
+            n.x += rail.width;
+        }
+        for (const p of packagesOut) {
+            p.x += rail.width;
+        }
+        for (const points of edgeMap.values())
+            for (const pt of points)
+                pt.x += rail.width;
+        nodes.push(...rail.nodes);
+        width += rail.width;
+        height = Math.max(height, rail.height);
+    }
+    packagesOut.push({ id: topId, x: 0, y: 0, width, height });
+    return repacked
+        ? { key, width, height, nodes, packages: packagesOut, edges: edgeMap, unrouted: relationIndexes }
+        : { key, width, height, nodes, packages: packagesOut, edges: edgeMap };
+}
+/** Ids of `children` in layer order (top layer first), left to right within a layer. */
+function flowOrderOf(children) {
+    const sorted = children
+        .map((c) => ({ id: c.id, cx: (c.x ?? 0) + (c.width ?? 0) / 2, cy: (c.y ?? 0) + (c.height ?? 0) / 2 }))
+        .sort((a, b) => a.cy - b.cy || a.cx - b.cx);
+    const out = [];
+    let layer = [];
+    let layerY = -Infinity;
+    const flush = () => {
+        layer.sort((a, b) => a.cx - b.cx);
+        for (const n of layer)
+            out.push(n.id);
+        layer = [];
+    };
+    for (const n of sorted) {
+        if (n.cy - layerY > FLOW_LAYER_GAP) {
+            flush();
+            layerY = n.cy;
+        }
+        layer.push(n);
+    }
+    flush();
+    return out;
+}
+/**
+ * Shelf-pack `children` row by row in `order`, choosing the row width whose
+ * result is closest to `aspect`. Unlike rect packing the row order follows the
+ * dependency order, so an upstream node never lands below its dependency.
+ */
+function orderedShelfPack(children, order, aspect, gap) {
+    const rank = new Map(order.map((id, i) => [id, i]));
+    const items = children.slice().sort((a, b) => (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0));
+    const { top, side, bottom } = SHELF_PADDING;
+    const widest = Math.max(0, ...items.map((c) => c.width ?? 0));
+    const total = items.reduce((sum, c) => sum + (c.width ?? 0) + gap, 0);
+    let best;
+    let bestMiss = Infinity;
+    for (let inner = widest; inner <= total; inner += Math.max(8, (total - widest) / 40)) {
+        const rows = [[]];
+        const rowH = [0];
+        let used = 0;
+        let width = 0;
+        for (const c of items) {
+            const w = c.width ?? 0;
+            if (used > 0 && used + gap + w > inner) {
+                rows.push([]);
+                rowH.push(0);
+                used = 0;
+            }
+            rows[rows.length - 1].push(c);
+            rowH[rowH.length - 1] = Math.max(rowH[rowH.length - 1], c.height ?? 0);
+            used += (used > 0 ? gap : 0) + w;
+            width = Math.max(width, used);
+        }
+        const w = width + 2 * side;
+        const h = top + bottom + rowH.reduce((a, b) => a + b, 0) + gap * (rows.length - 1);
+        const miss = Math.abs(Math.log(w / Math.max(1, h) / aspect)) + (w * h) / 1e9;
+        if (miss < bestMiss) {
+            bestMiss = miss;
+            best = { rows, rowH, width: w, height: h };
+        }
+    }
+    if (!best)
+        return { id: 'block', width: 2 * side, height: top + bottom, children: [] };
+    let y = top;
+    best.rows.forEach((row, r) => {
+        let x = side;
+        for (const c of row) {
+            c.x = x;
+            c.y = y + (best.rowH[r] - (c.height ?? 0)) / 2;
+            x += (c.width ?? 0) + gap;
+        }
+        y += best.rowH[r] + gap;
+    });
+    return { id: 'block', width: best.width, height: best.height, children: items };
+}
+/**
+ * Equal-column grid for unconnected boxes: the column width is the widest box,
+ * rows are as tall as their tallest box and boxes are top-left aligned, so
+ * columns and rows line up. The column count is the one whose block lands
+ * closest to `aspect`; the last row alone may be short. `tight` sizes each column
+ * to its own widest box and hands the narrowest boxes to the first columns; without
+ * it every column is as wide as the widest box overall and the flow order is kept.
+ */
+export function gridPack(children, order, aspect, gap, rowGap = gap, tight = true) {
+    const rank = new Map(order.map((id, i) => [id, i]));
+    const byFlow = children.slice().sort((a, b) => (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0));
+    // Narrowest first: filling the columns top-down in that order keeps similar
+    // widths together, so each column is only as wide as its own widest box.
+    const byWidth = tight ? byFlow.slice().sort((a, b) => (a.width ?? 0) - (b.width ?? 0)) : byFlow;
+    const widest = Math.max(0, ...byFlow.map((c) => c.width ?? 0));
+    const { top, side, bottom } = SHELF_PADDING;
+    const arrange = (cols) => {
+        // Slots fill row by row (only the last row may be short) but are handed
+        // out column by column.
+        const slots = byWidth.map((_, i) => ({ r: Math.floor(i / cols), c: i % cols }));
+        slots.sort((p, q) => p.c - q.c || p.r - q.r);
+        const cells = byWidth.map((item, i) => ({ item, ...slots[i] }));
+        const colW = Array.from({ length: cols }, () => 0);
+        const rowH = [];
+        for (const { item, r, c } of cells) {
+            colW[c] = tight ? Math.max(colW[c], item.width ?? 0) : widest;
+            rowH[r] = Math.max(rowH[r] ?? 0, item.height ?? 0);
+        }
+        return {
+            cells,
+            colW,
+            rowH,
+            width: 2 * side + colW.reduce((a, b) => a + b, 0) + (cols - 1) * gap,
+            height: top + bottom + rowH.reduce((a, b) => a + b, 0) + rowGap * (rowH.length - 1),
+        };
+    };
+    let best = { cols: 1, miss: Infinity };
+    for (let cols = 1; cols <= byWidth.length; cols++) {
+        const g = arrange(cols);
+        const miss = Math.abs(Math.log(g.width / Math.max(1, g.height) / aspect));
+        if (miss < best.miss - 1e-9)
+            best = { cols, miss };
+    }
+    const g = arrange(best.cols);
+    const colX = [];
+    let x = side;
+    for (const w of g.colW) {
+        colX.push(x);
+        x += w + gap;
+    }
+    const rowY = [];
+    let y = top;
+    for (const h of g.rowH) {
+        rowY.push(y);
+        y += h + rowGap;
+    }
+    for (const { item, r, c } of g.cells) {
+        item.x = colX[c];
+        item.y = rowY[r];
+    }
+    return { id: 'block', width: g.width, height: g.height, children: byFlow };
+}
+/** Box placement strategies: the equal-column grid and the ordered shelf pack. */
+export const gridPackPlacementStrategy = {
+    name: 'grid-pack',
+    place(ctx) {
+        const packed = gridPack([...ctx.boxes], [...ctx.order], ctx.aspect, ctx.gap, ctx.rowGap ?? ctx.gap, ctx.tight ?? true);
+        return placementOfElkNode(packed);
+    },
+};
+export const orderedShelfPackPlacementStrategy = {
+    name: 'ordered-shelf-pack',
+    place(ctx) {
+        const packed = orderedShelfPack([...ctx.boxes], [...ctx.order], ctx.aspect, ctx.gap);
+        return placementOfElkNode(packed);
+    },
+};
+/** Positions of an arranged ELK node's children, plus the node's own size. */
+function placementOfElkNode(node) {
+    const positions = new Map();
+    for (const child of node.children ?? []) {
+        positions.set(child.id, { x: child.x ?? 0, y: child.y ?? 0 });
+    }
+    return { positions, width: node.width ?? 0, height: node.height ?? 0 };
+}
+/** Materialise a placement as the ELK node result the block layout flattens. */
+function elkNodeFromPlacement(id, placement, children) {
+    return {
+        id,
+        width: placement.width,
+        height: placement.height,
+        children: children.map((c) => {
+            const at = placement.positions.get(c.id);
+            return at === undefined ? { ...c } : { ...c, x: at.x, y: at.y };
+        }),
+    };
+}
+function requirePlacement(placement, what) {
+    if (placement === undefined)
+        throw new Error(`compound: ${what} strategy declined`);
+    return placement;
+}
+/** Ordered shelf packing of a flat block; a block that comes out too wide is repacked taller. */
+async function packShelves(children, order, options, railWidth) {
+    const aspect = options.aspectRatio ?? 1.6;
+    const gap = options.dense ? DENSE_NODE_SPACING : SHELF_GAP;
+    const pack = async (ratio) => requirePlacement(await runPlacementStrategies([orderedShelfPackPlacementStrategy], { boxes: children, order, aspect: ratio, gap }), 'ordered shelf packing');
+    if (options.dense)
+        return pack(aspect * DENSE_SHELF_ASPECT_SCALE);
+    let packed = await pack(aspect * SHELF_ASPECT_SCALE);
+    for (const scale of SHELF_NARROW_SCALES) {
+        if (packed.width + railWidth(packed.height) <= SHELF_MAX_WIDTH)
+            break;
+        packed = await pack(aspect * scale);
+    }
+    return packed;
+}
+/** Node area ÷ block area of a layered result; low means a sparse, mostly empty block. */
+function blockDensity(children, result) {
+    const area = (result.width ?? 0) * (result.height ?? 0);
+    if (area <= 0)
+        return 1;
+    return children.reduce((sum, c) => sum + (c.width ?? 0) * (c.height ?? 0), 0) / area;
+}
+/**
+ * Stack summarised hubs in column(s) on the package's left side, below the label
+ * tab. Columns wrap at the block height (at least [[HUB_RAIL_MIN_HEIGHT]]).
+ * `width` is the space the rail takes from the left edge, gap included.
+ */
+function placeHubRail(hubs, blockHeight) {
+    const top = 26;
+    const limit = Math.max(blockHeight - 10, HUB_RAIL_MIN_HEIGHT);
+    const nodes = [];
+    let x = 10;
+    let y = top;
+    let colWidth = 0;
+    let bottom = top;
+    for (const entity of hubs) {
+        const size = estimateEntitySize(entity);
+        if (y > top && y + size.height > limit) {
+            x += colWidth + HUB_RAIL_GAP;
+            y = top;
+            colWidth = 0;
+        }
+        nodes.push({ id: entity.id, x, y, width: size.width, height: size.height });
+        colWidth = Math.max(colWidth, size.width);
+        y += size.height + HUB_RAIL_GAP;
+        bottom = Math.max(bottom, y - HUB_RAIL_GAP);
+    }
+    return { nodes, width: x + colWidth + HUB_RAIL_GAP * 2 - 10, height: bottom + 10 };
+}
+/**
+ * Pack a lopsided nested block proportionally: every child package becomes a
+ * block of its own (recursively split when it is lopsided too), and the child
+ * blocks plus the package's own entities are rect-packed into a balanced
+ * rectangle. Edges inside a child keep their ELK routes; edges between
+ * children are left for the grid router.
+ */
+async function splitNestedBlock(elk, model, key, entities, packages, relationIndexes, options) {
+    const topId = key.slice(PACKAGE_PREFIX.length);
+    const top = packages.find((p) => p.id === topId);
+    const pkgById = new Map(packages.map((p) => [p.id, p]));
+    const childOf = new Map(); // package id → direct child of top
+    for (const pkg of packages) {
+        if (pkg.id === topId)
+            continue;
+        let cur = pkg;
+        while (cur.parentId !== undefined && cur.parentId !== topId && pkgById.has(cur.parentId)) {
+            cur = pkgById.get(cur.parentId);
+        }
+        childOf.set(pkg.id, cur.id);
+    }
+    const children = packages.filter((p) => p.parentId === topId);
+    const entityChild = (e) => e.packageId !== undefined ? childOf.get(e.packageId) : undefined;
+    const entityIds = new Map(entities.map((e) => [e.id, e]));
+    const subBlocks = [];
+    const claimed = new Set();
+    for (const child of children) {
+        const subKey = PACKAGE_PREFIX + child.id;
+        const subPackages = packages.filter((p) => p.id === child.id || childOf.get(p.id) === child.id);
+        const subEntities = entities.filter((e) => entityChild(e) === child.id);
+        const subRelations = relationIndexes.filter((i) => {
+            const r = model.relations[i];
+            const a = entityIds.get(r.source);
+            const b = entityIds.get(r.target);
+            return a !== undefined && b !== undefined && entityChild(a) === child.id && entityChild(b) === child.id;
+        });
+        for (const i of subRelations)
+            claimed.add(i);
+        subBlocks.push(await layoutBlock(elk, model, subKey, subEntities, subPackages, subRelations, { ...options, dense: false }));
+    }
+    const unrouted = relationIndexes.filter((i) => !claimed.has(i));
+    const own = entities.filter((e) => entityChild(e) === undefined);
+    const elkChildren = [
+        ...subBlocks.map((b) => ({ id: b.key, width: b.width, height: b.height })),
+        ...own.map((e) => {
+            const size = estimateEntitySize(e);
+            return { id: e.id, width: size.width, height: size.height };
+        }),
+    ];
+    // Layered placement over the child boxes keeps linked packages adjacent (few
+    // crossings between them); wrapping bounds the aspect ratio.
+    const itemOf = (id) => {
+        const e = entityIds.get(id);
+        const c = e === undefined ? undefined : entityChild(e);
+        return c === undefined ? id : PACKAGE_PREFIX + c;
+    };
+    const seen = new Set();
+    const linkEdges = [];
+    for (const i of unrouted) {
+        const a = itemOf(model.relations[i].source);
+        const b = itemOf(model.relations[i].target);
+        if (a === b || seen.has(`${a}\u0000${b}`))
+            continue;
+        seen.add(`${a}\u0000${b}`);
+        linkEdges.push({ id: `lnk-${linkEdges.length}`, sources: [a], targets: [b] });
+    }
+    const packed = await elk.layout({
+        id: 'block',
+        layoutOptions: mergeElkOptions({
+            'elk.algorithm': 'layered',
+            'elk.direction': 'DOWN',
+            'elk.aspectRatio': '1.6',
+            'elk.spacing.nodeNode': String(DENSE_NODE_SPACING),
+            'elk.layered.spacing.nodeNodeBetweenLayers': String(BLOCK_SPACING),
+            'elk.layered.wrapping.strategy': 'MULTI_EDGE',
+            'elk.separateConnectedComponents': 'true',
+            'elk.padding': '[top=26,left=10,bottom=10,right=10]',
+        }, options.aspectRatio !== undefined ? { 'elk.aspectRatio': String(options.aspectRatio) } : {}, options.elk),
+        children: elkChildren,
+        edges: linkEdges,
+    });
+    const nodes = [];
+    const packagesOut = [];
+    const edges = new Map();
+    for (const c of packed.children ?? []) {
+        const at = { x: c.x ?? 0, y: c.y ?? 0 };
+        const sub = subBlocks.find((b) => b.key === c.id);
+        if (!sub) {
+            nodes.push({ id: c.id, x: at.x, y: at.y, width: c.width ?? 0, height: c.height ?? 0 });
+            continue;
+        }
+        for (const n of sub.nodes)
+            nodes.push({ ...n, x: n.x + at.x, y: n.y + at.y });
+        for (const p of sub.packages)
+            packagesOut.push({ ...p, x: p.x + at.x, y: p.y + at.y });
+        for (const i of sub.unrouted ?? [])
+            unrouted.push(i);
+        for (const [i, pts] of sub.edges)
+            edges.set(i, pts.map((q) => ({ x: q.x + at.x, y: q.y + at.y })));
+    }
+    const width = Math.max(packed.width ?? 0, packageMinWidth(top.name));
+    const height = Math.max(packed.height ?? 0, PACKAGE_LABEL.tabHeight + 36);
+    packagesOut.push({ id: topId, x: 0, y: 0, width, height });
+    return { key, width, height, nodes, packages: packagesOut, edges, unrouted };
+}
+function elkEdgePoints(edge, nodeById, offsets) {
+    const base = offsets.get(edge.container ?? 'block') ?? { x: 0, y: 0 };
+    const points = [];
+    for (const section of edge.sections ?? []) {
+        for (const p of sectionPoints(section)) {
+            const shifted = { x: p.x + base.x, y: p.y + base.y };
+            const last = points[points.length - 1];
+            if (!last || Math.abs(last.x - shifted.x) > 0.01 || Math.abs(last.y - shifted.y) > 0.01) {
+                points.push(shifted);
+            }
+        }
+    }
+    if (points.length >= 2)
+        return points;
+    const source = nodeById.get(edge.sources?.[0] ?? '');
+    const target = nodeById.get(edge.targets?.[0] ?? '');
+    if (!source || !target)
+        return [];
+    return [
+        { x: source.x + source.width / 2, y: source.y + source.height / 2 },
+        { x: target.x + target.width / 2, y: target.y + target.height / 2 },
+    ];
+}
+function sectionPoints(section) {
+    const pts = [];
+    if (section.startPoint)
+        pts.push(section.startPoint);
+    for (const b of section.bendPoints ?? [])
+        pts.push(b);
+    if (section.endPoint)
+        pts.push(section.endPoint);
+    return pts;
+}
+/** Arrange blocks as fixed-size nodes; block-level edges bias the order. */
+async function placeBlocks(elk, model, blocks, crossRelations, blockOfEntity, options) {
+    const strategies = [...(options.placementStrategies ?? []), ...DEFAULT_PLACEMENT_STRATEGIES];
+    const ctx = { elk, model, blocks, crossRelations, blockOfEntity, options, strategies };
+    return requirePlacement(await runPlacementStrategies(strategies, ctx), 'block placement');
+}
+/** Blocks as the fixed-size nodes ELK places. */
+function blockChildren(ctx) {
+    return [...ctx.blocks.values()].map((b) => ({ id: b.key, width: b.width, height: b.height }));
+}
+/** Number of distinct block pairs linked by a cross-block relation. */
+function blockEdgeCount(ctx) {
+    return new Set(ctx.crossRelations.map((i) => `${ctx.blockOfEntity.get(ctx.model.relations[i].source)}\u0000${ctx.blockOfEntity.get(ctx.model.relations[i].target)}`)).size;
+}
+/**
+ * Mid-scale root layers (a dozen-ish packages) with few block-level edges gain
+ * nothing from layering: it strings them into a column. Pack them instead.
+ */
+function isSparseMidScale(ctx) {
+    return (ctx.blocks.size >= MID_PACK_BLOCK_THRESHOLD &&
+        ctx.options.partitions.size === 0 &&
+        blockEdgeCount(ctx) * 2 < ctx.blocks.size);
+}
+function shouldPackBlocks(ctx) {
+    return ctx.blocks.size > PACK_BLOCK_THRESHOLD || isSparseMidScale(ctx);
+}
+/** Block-level edges biasing ELK's block order (one edge per linked pair). */
+function blockEdges(ctx) {
+    const seen = new Set();
+    const edges = [];
+    for (const index of ctx.crossRelations) {
+        const relation = ctx.model.relations[index];
+        const a = ctx.blockOfEntity.get(relation.source);
+        const b = ctx.blockOfEntity.get(relation.target);
+        if (!ctx.blocks.has(a) || !ctx.blocks.has(b))
+            continue; // an orbiting stub: placed after the main blocks
+        const pair = `${a}\u0000${b}`;
+        if (seen.has(pair))
+            continue;
+        seen.add(pair);
+        edges.push({ id: `blk-${edges.length}`, sources: [a], targets: [b] });
+    }
+    return edges;
+}
+function rectPackLayoutOptions(ctx) {
+    const named = {};
+    if (ctx.options.aspectRatio !== undefined)
+        named['elk.aspectRatio'] = String(ctx.options.aspectRatio);
+    return mergeElkOptions({
+        'elk.algorithm': 'rectpacking',
+        'elk.aspectRatio': '1.6',
+        'elk.spacing.nodeNode': String(BLOCK_SPACING),
+        'elk.padding': `[top=${CANVAS_MARGIN},left=${CANVAS_MARGIN},bottom=${CANVAS_MARGIN},right=${CANVAS_MARGIN}]`,
+    }, named, ctx.options.elk);
+}
+function layeredLayoutOptions(ctx) {
+    const named = {};
+    if (ctx.options.aspectRatio !== undefined)
+        named['elk.aspectRatio'] = String(ctx.options.aspectRatio);
+    return mergeElkOptions({
+        'elk.algorithm': 'layered',
+        'elk.direction': 'DOWN',
+        'elk.aspectRatio': '1.6',
+        'elk.edgeRouting': 'ORTHOGONAL',
+        'elk.spacing.nodeNode': String(BLOCK_SPACING),
+        'elk.layered.spacing.nodeNodeBetweenLayers': String(BLOCK_SPACING),
+        'elk.layered.wrapping.strategy': 'MULTI_EDGE',
+        'elk.separateConnectedComponents': 'true',
+        'elk.padding': `[top=${CANVAS_MARGIN},left=${CANVAS_MARGIN},bottom=${CANVAS_MARGIN},right=${CANVAS_MARGIN}]`,
+    }, named, ctx.options.elk);
+}
+/** Stubs orbit the placed main blocks instead of taking part in their placement. */
+export const stubOrbitPlacementStrategy = {
+    name: 'stub-orbit',
+    async place(ctx) {
+        const stubKeys = new Set([...ctx.blocks.keys()].filter((k) => ctx.model.entities.find((e) => e.id === k)?.stub === true));
+        if (stubKeys.size === 0 || stubKeys.size >= ctx.blocks.size)
+            return undefined;
+        const main = new Map([...ctx.blocks].filter(([k]) => !stubKeys.has(k)));
+        const strategies = ctx.strategies.filter((s) => s !== stubOrbitPlacementStrategy);
+        const mainPlacement = await runPlacementStrategies(strategies, { ...ctx, blocks: main, strategies });
+        if (mainPlacement === undefined)
+            return undefined;
+        return placeStubsNearTargets(ctx.model, ctx.blocks, stubKeys, mainPlacement, ctx.crossRelations, ctx.blockOfEntity, ctx.options.stubOrbit ?? DEFAULT_STUB_ORBIT);
+    },
+};
+/** Semantic layers as stacked bands of blocks. */
+export const layerRowsPlacementStrategy = {
+    name: 'layer-rows',
+    place(ctx) {
+        if (ctx.options.partitions.size === 0 || shouldPackBlocks(ctx))
+            return undefined;
+        return stackLayerRows(ctx.blocks, ctx.options);
+    },
+};
+/**
+ * Height-sorted shelf packing of the blocks; [[packedBlocksPlacementStrategy]]
+ * keeps it as one candidate beside ELK's own rect-packing runs.
+ */
+export const shelfPackBlocksPlacementStrategy = {
+    name: 'shelf-pack-blocks',
+    place(ctx) {
+        if (!shouldPackBlocks(ctx))
+            return undefined;
+        const target = ctx.options.aspectRatio ?? 1.6;
+        return placementOfElkNode(shelfPackBlocks(blockChildren(ctx), target));
+    },
+};
+/**
+ * Rect packing of the blocks: height-sorted shelves are tried beside ELK's own
+ * rectpacking at a few ratios, and the tightest canvas near the target wins.
+ */
+export const packedBlocksPlacementStrategy = {
+    name: 'packed-blocks',
+    async place(ctx) {
+        if (!shouldPackBlocks(ctx))
+            return undefined;
+        const children = blockChildren(ctx);
+        const layoutOptions = rectPackLayoutOptions(ctx);
+        if (ctx.blocks.size > MAX_CANDIDATE_BLOCKS) {
+            // Very many blocks: a single rectpacking run (the candidates below only pay off at mid scale).
+            return placementOfElkNode(await ctx.elk.layout({ id: 'blocks', layoutOptions, children, edges: [] }));
+        }
+        // rectpacking only honours a target ratio loosely and can leave a lone block
+        // on the last row; also try height-sorted shelves and keep the tightest
+        // canvas whose ratio stays near the target.
+        const target = ctx.options.aspectRatio ?? 1.6;
+        const shelf = await runPlacementStrategies([shelfPackBlocksPlacementStrategy], ctx);
+        const candidates = shelf === undefined ? [] : [shelf];
+        for (const ratio of PACK_ASPECT_CANDIDATES.map((f) => target * f)) {
+            candidates.push(placementOfElkNode(await ctx.elk.layout({
+                id: 'blocks',
+                layoutOptions: { ...layoutOptions, 'elk.aspectRatio': String(ratio) },
+                children: children.map((c) => ({ ...c })),
+                edges: [],
+            })));
+        }
+        const area = (n) => n.width * n.height;
+        const inBand = (n) => {
+            const a = n.width / Math.max(1, n.height);
+            return a >= PACK_BAND_MIN && a <= PACK_BAND_MAX;
+        };
+        if (ctx.options.aspectRatio !== undefined) {
+            // An explicit caller ratio wins over compactness: closest candidate.
+            const miss = (n) => Math.abs(Math.log(n.width / Math.max(1, n.height) / target));
+            return candidates.reduce((best, c) => (miss(c) < miss(best) ? c : best));
+        }
+        const pool = candidates.some(inBand) ? candidates.filter(inBand) : candidates;
+        return pool.reduce((best, c) => (area(c) < area(best) ? c : best));
+    },
+};
+/** Blocks placed by ELK's layered algorithm (no partitions, few enough to layer). */
+export const elkLayeredPlacementStrategy = {
+    name: 'elk-layered-blocks',
+    async place(ctx) {
+        if (shouldPackBlocks(ctx) || ctx.options.partitions.size > 0)
+            return undefined;
+        return placementOfElkNode(await ctx.elk.layout({
+            id: 'blocks',
+            layoutOptions: layeredLayoutOptions(ctx),
+            children: blockChildren(ctx),
+            edges: blockEdges(ctx),
+        }));
+    },
+};
+/** Built-in block placement chain, tried after any injected strategies. */
+export const DEFAULT_PLACEMENT_STRATEGIES = [
+    stubOrbitPlacementStrategy,
+    layerRowsPlacementStrategy,
+    packedBlocksPlacementStrategy,
+    elkLayeredPlacementStrategy,
+];
+/**
+ * Orbit stub nodes (external packages of a single-package view) around the
+ * placed blocks: each stub joins the side of the main bounding box nearest to
+ * the nodes it connects to, and slides along that side to its targets' own
+ * coordinate (sweeping apart where stubs would overlap). Edges then stay short
+ * instead of running across the whole frame to a far-away stub column.
+ */
+function placeStubsNearTargets(model, blocks, stubKeys, main, crossRelations, blockOfEntity, orbit) {
+    const centre = new Map();
+    for (const [key, at] of main.positions) {
+        for (const n of blocks.get(key)?.nodes ?? []) {
+            centre.set(n.id, { x: at.x + n.x + n.width / 2, y: at.y + n.y + n.height / 2 });
+        }
+    }
+    const stubs = [];
+    for (const key of [...stubKeys].sort()) {
+        let sx = 0;
+        let sy = 0;
+        const targets = [];
+        for (const index of crossRelations) {
+            const r = model.relations[index];
+            const other = blockOfEntity.get(r.source) === key ? r.target : blockOfEntity.get(r.target) === key ? r.source : undefined;
+            const c = other === undefined ? undefined : centre.get(other);
+            if (c) {
+                sx += c.x;
+                sy += c.y;
+                targets.push(c);
+            }
+        }
+        const count = targets.length;
+        stubs.push({
+            key,
+            centroid: { x: count > 0 ? sx / count : main.width / 2, y: count > 0 ? sy / count : main.height / 2 },
+            targets,
+        });
+    }
+    // All stubs form one rail along a single side of the frame. The side is the
+    // one that is nearest to the stubs' targets overall; a side too short to hold
+    // the whole rail only wins when the others are even shorter.
+    const sides = ['right', 'left', 'top', 'bottom'];
+    const depthOf = (side, c) => side === 'left' ? c.x : side === 'right' ? main.width - c.x : side === 'top' ? c.y : main.height - c.y;
+    const railLength = (side) => {
+        const vertical = side === 'left' || side === 'right';
+        return stubs.reduce((sum, { key }) => sum + (vertical ? blocks.get(key).height : blocks.get(key).width) + RAIL_MIN_GAP, 0);
+    };
+    const sideCost = (side) => {
+        const extent = side === 'left' || side === 'right' ? main.height : main.width;
+        const overflow = Math.max(0, railLength(side) - extent);
+        return stubs.reduce((sum, s) => sum + depthOf(side, s.centroid), 0) / Math.max(1, stubs.length) + overflow * RAIL_OVERFLOW_WEIGHT;
+    };
+    // Left/right sides are preferred on ties: side stubs keep text horizontal.
+    const side = stubs.length === 0 ? 'right' : sides.reduce((a, b) => (sideCost(b) < sideCost(a) - 1e-6 ? b : a));
+    const positions = new Map(main.positions);
+    let minX = 0;
+    let minY = 0;
+    let maxX = main.width;
+    let maxY = main.height;
+    if (stubs.length > 0) {
+        const vertical = side === 'left' || side === 'right';
+        const extent = vertical ? main.height : main.width;
+        const lenOf = (key) => (vertical ? blocks.get(key).height : blocks.get(key).width);
+        const thickOf = (key) => (vertical ? blocks.get(key).width : blocks.get(key).height);
+        const alongOf = (s) => {
+            const anchor = orbit.anchor === 'nearest'
+                ? s.targets.reduce((a, c) => (depthOf(side, c) < depthOf(side, a) ? c : a), s.targets[0] ?? s.centroid)
+                : s.centroid;
+            return vertical ? anchor.y : anchor.x;
+        };
+        // Ordered by where their targets lie along the side, then spaced evenly.
+        const ordered = stubs
+            .map((s) => ({ s, along: alongOf(s) }))
+            .sort((a, b) => a.along - b.along || a.s.key.localeCompare(b.s.key));
+        const lengths = ordered.reduce((sum, { s }) => sum + lenOf(s.key), 0);
+        const slack = ordered.length > 1 ? (extent - lengths) / (ordered.length - 1) : 0;
+        const gap = Math.max(RAIL_MIN_GAP, Math.min(orbit.spacing, slack));
+        const total = lengths + gap * (ordered.length - 1);
+        const meanAlong = ordered.reduce((sum, o) => sum + o.along, 0) / ordered.length;
+        const start = Math.max(0, Math.min(meanAlong - total / 2, extent - total));
+        let cursor = start;
+        const thick = Math.max(...ordered.map(({ s }) => thickOf(s.key)));
+        const offset = orbit.gap - CANVAS_MARGIN;
+        for (const { s } of ordered) {
+            const b = blocks.get(s.key);
+            let x;
+            let y;
+            if (vertical) {
+                y = cursor;
+                x = side === 'left' ? CANVAS_MARGIN - offset - thick + (thick - b.width) : main.width - CANVAS_MARGIN + offset;
+            }
+            else {
+                x = cursor;
+                y = side === 'top' ? CANVAS_MARGIN - offset - thick + (thick - b.height) : main.height - CANVAS_MARGIN + offset;
+            }
+            cursor += lenOf(s.key) + gap;
+            positions.set(s.key, { x, y });
+            minX = Math.min(minX, x - CANVAS_MARGIN);
+            minY = Math.min(minY, y - CANVAS_MARGIN);
+            maxX = Math.max(maxX, x + b.width + CANVAS_MARGIN);
+            maxY = Math.max(maxY, y + b.height + CANVAS_MARGIN);
+        }
+    }
+    for (const [key, at] of positions)
+        positions.set(key, { x: at.x - minX, y: at.y - minY });
+    return { positions, width: maxX - minX, height: maxY - minY };
+}
+/**
+ * Height-sorted shelf packing of fixed-size blocks: rows hold blocks of similar
+ * height, so a row leaves little dead space beside its shorter members. The row
+ * width scanned for is the one with the smallest canvas near `aspect`.
+ */
+function shelfPackBlocks(children, aspect) {
+    const items = children.map((c) => ({ ...c })).sort((a, b) => (b.height ?? 0) - (a.height ?? 0) || a.id.localeCompare(b.id));
+    const gap = BLOCK_SPACING;
+    const widest = Math.max(0, ...items.map((c) => c.width ?? 0));
+    const total = items.reduce((sum, c) => sum + (c.width ?? 0) + gap, 0);
+    let best;
+    let bestScore = Infinity;
+    const step = Math.max(8, (total - widest) / 200);
+    for (let inner = widest; inner <= total + step; inner += step) {
+        const placed = [];
+        let x = 0;
+        let y = 0;
+        let rowH = 0;
+        let width = 0;
+        for (const c of items) {
+            const w = c.width ?? 0;
+            if (x > 0 && x + gap + w > inner) {
+                y += rowH + gap;
+                x = 0;
+                rowH = 0;
+            }
+            if (x > 0)
+                x += gap;
+            placed.push({ ...c, x: CANVAS_MARGIN + x, y: CANVAS_MARGIN + y });
+            x += w;
+            rowH = Math.max(rowH, c.height ?? 0);
+            width = Math.max(width, x);
+        }
+        const w = width + 2 * CANVAS_MARGIN;
+        const h = y + rowH + 2 * CANVAS_MARGIN;
+        const score = w * h * (1 + Math.abs(Math.log(w / h / aspect)) * 0.03);
+        if (score < bestScore) {
+            bestScore = score;
+            best = { items: placed, width: w, height: h };
+        }
+    }
+    return { id: 'blocks', width: best?.width ?? 0, height: best?.height ?? 0, children: best?.items ?? [] };
+}
+/** Row width beyond which a layer's blocks wrap onto a further row. */
+const MAX_ROW_WIDTH = 2000;
+/** Blocks up to this tall count as small and may share a row with other small blocks. */
+const SMALL_BLOCK_HEIGHT = 600;
+/**
+ * Semantic-layer placement: every layer is a horizontal band, bands stack in
+ * partition order, and the blocks of one band sit side by side (wrapping when
+ * the band would grow wider than [[MAX_ROW_WIDTH]]). Each row is centred on the
+ * widest one. Unlike a layered run over the blocks this cannot drag a wide
+ * block sideways to sit under its parents, so the canvas stays as narrow as
+ * its widest block.
+ */
+function stackLayerRows(blocks, options) {
+    const bands = new Map();
+    for (const block of blocks.values()) {
+        const partition = options.partitions.get(block.key.slice(PACKAGE_PREFIX.length));
+        const band = partition ?? Number.MAX_SAFE_INTEGER;
+        const list = bands.get(band);
+        if (list)
+            list.push(block);
+        else
+            bands.set(band, [block]);
+    }
+    const rows = [];
+    for (const band of [...bands.keys()].sort((a, b) => a - b)) {
+        let row = [];
+        let rowWidth = 0;
+        for (const block of bands.get(band)) {
+            if (row.length > 0 && rowWidth + BLOCK_SPACING + block.width > MAX_ROW_WIDTH) {
+                rows.push(row);
+                row = [];
+                rowWidth = 0;
+            }
+            rowWidth += (row.length > 0 ? BLOCK_SPACING : 0) + block.width;
+            row.push(block);
+        }
+        if (row.length > 0)
+            rows.push(row);
+    }
+    const widthOf = (row) => row.reduce((sum, b) => sum + b.width, 0) + BLOCK_SPACING * (row.length - 1);
+    const inner = Math.max(0, ...rows.map(widthOf));
+    // Neighbouring rows of small blocks share one row (in layer order, left to
+    // right) instead of stacking into a narrow column above the big layer.
+    const isSmall = (row) => row.every((b) => b.height <= SMALL_BLOCK_HEIGHT);
+    for (let i = 0; i + 1 < rows.length;) {
+        const merged = [...rows[i], ...rows[i + 1]];
+        if (isSmall(rows[i]) && isSmall(rows[i + 1]) && widthOf(merged) <= inner) {
+            rows.splice(i, 2, merged);
+        }
+        else {
+            i++;
+        }
+    }
+    const positions = new Map();
+    let y = CANVAS_MARGIN;
+    for (const row of rows) {
+        let x = CANVAS_MARGIN; // rows share one left edge
+        for (const block of row) {
+            positions.set(block.key, { x, y });
+            x += block.width + BLOCK_SPACING;
+        }
+        y += Math.max(...row.map((b) => b.height)) + BLOCK_SPACING;
+    }
+    return {
+        positions,
+        width: inner + CANVAS_MARGIN * 2,
+        height: Math.max(0, y - BLOCK_SPACING) + CANVAS_MARGIN,
+    };
+}