@yalehwang/plantuml-js 0.2.0 → 0.3.0

package/dist/layout/elk.js

@@ -21,107 +21,125 @@
  *   edges share an in/out side and spread across distinct ports instead of
  *   piling onto one point.
  *
- * Cross-package edges would otherwise come back from ELK without any routing
- * section (the `INHERIT` hierarchy mode leaves them unresolved), so when the
- * model contains edges that cross *between two different packages* the engine
- * switches that layout to `INCLUDE_CHILDREN` — that is what lets ELK route
- * those edges around unrelated boxes and keeps `edgeNodeIntersections` at zero.
+ * Edges that cross a container boundary (package↔package, or package↔top-level
+ * stub) would otherwise come back from ELK without any routing section (the
+ * `INHERIT` hierarchy mode leaves them unresolved, and they degrade to straight
+ * diagonals), so when the model contains such edges the engine switches that
+ * layout to `INCLUDE_CHILDREN`, which routes them around unrelated boxes.
  *
- * A package↔top-level edge (e.g. a single-package view whose neighbours are
- * top-level stubs) deliberately does *not* switch the hierarchy handling:
- * `INCLUDE_CHILDREN` flattens a package with disconnected children into a
- * single-row strip instead of a packed grid, which is exactly the failure the
- * Tests Layer view used to show (`package-pkg-Tests_Layer` at aspect 14.9).
+ * `INCLUDE_CHILDREN` is one layered run over the whole nested graph, so it can
+ * flatten a package into a strip or stack a big graph into a sliver. When the
+ * result is badly proportioned (or the graph is very large) the engine falls
+ * back to the compound layout in [[./compound]]: each top-level package is laid
+ * out as its own block, blocks are packed, and cross-block edges are routed by
+ * the grid router in [[./grid-router]].
  */
 import ELKDefault from 'elkjs';
-import { PACKAGE_LABEL, estimateEntitySize, } from '../layout.js';
-import { measureTextWidth } from '../text-measure.js';
+import { alignRows, alignIsolatedFrames } from '../foundation/layout.js';
+import { compoundLayout } from './compound.js';
+import { computeLayoutMetrics, computeMaxEmptyBlockRatio } from './layout-metrics.js';
+import { resolveLayerOrder, assignPartitions } from '../foundation/layers.js';
+import { buildElkGraph } from './elk-graph.js';
+import { clipPackageEndpoints } from './package-endpoints.js';
+import { mapElkResult } from './elk-result.js';
+import { spreadParallelLanes } from './lane-spread.js';
+import { straightenTrunkDetours, liftFlushSegments, uncoilWraps } from './trunk-lanes.js';
+import { mergeFanoutTrunks } from './fanout-trunk.js';
+import { runStrategies } from './strategy.js';
 // elkjs ships a `typeof import(...)` default-export type under NodeNext; pin the
 // real constructor shape so `new` type-checks and the layout result stays typed.
 const ElkConstructor = ELKDefault;
-const PACKAGE_PREFIX = 'pkg::';
-/** Relation types whose layout direction is reversed so the arrow target sits above the source. */
-const REVERSED_RELATION_TYPES = new Set(['inheritance', 'implementation']);
-/** Name convention: `"X Layer"` declares a semantic layer `X`. */
-const LAYER_SUFFIX = /^(.*)\s+Layer$/i;
-/** Resolve a package's semantic layer from its explicit field or its name. */
-function packageLayer(pkg) {
-    if (pkg.layer !== undefined)
-        return pkg.layer;
-    const m = LAYER_SUFFIX.exec(pkg.name);
-    if (!m)
-        return undefined;
-    const core = m[1].trim();
-    return core === '' ? undefined : core;
-}
 /**
- * Order semantic layers by dependency topology instead of puml declaration
- * order: a layer that depends on another (`A ..> B` across layers) sits *above*
- * its dependency, so entry layers (Tests, Examples) stack over the base they
- * consume (Src) and independent layers (Templates) fall out of the sandwich.
- *
- * A Kahn topological sort places in-degree-zero layers (nothing depends on
- * them) first, breaking ties in declaration order for determinism. Layers left
- * over because of a dependency cycle are appended in declaration order, so a
- * cyclic graph still yields a stable (if not strictly topological) order; the
- * renderer marks the offending back-edges as feedback arcs.
+ * Entity count above which the single hierarchical ELK run is skipped in favour
+ * of the compound layout (per-package blocks + packing + grid routing).
  */
-function topologicalLayerOrder(model) {
-    const declared = [];
-    for (const pkg of model.packages) {
-        const layer = packageLayer(pkg);
-        if (layer !== undefined && !declared.includes(layer))
-            declared.push(layer);
-    }
-    if (declared.length <= 1)
-        return declared;
-    const pkgById = new Map(model.packages.map((p) => [p.id, p]));
-    const layerOf = new Map();
-    for (const entity of model.entities) {
-        const pkg = entity.packageId ? pkgById.get(entity.packageId) : undefined;
-        layerOf.set(entity.id, pkg ? packageLayer(pkg) : undefined);
-    }
-    const dependsOn = new Map();
-    const dependents = new Map();
-    for (const layer of declared) {
-        dependsOn.set(layer, new Set());
-        dependents.set(layer, 0);
-    }
-    for (const relation of model.relations) {
-        const source = layerOf.get(relation.source);
-        const target = layerOf.get(relation.target);
-        if (source === undefined || target === undefined || source === target)
-            continue;
-        const set = dependsOn.get(source);
-        if (!set.has(target)) {
-            set.add(target);
-            dependents.set(target, (dependents.get(target) ?? 0) + 1);
-        }
-    }
-    const order = [];
-    const done = new Set();
-    const queue = declared.filter((layer) => (dependents.get(layer) ?? 0) === 0);
-    for (let i = 0; i < queue.length; i++) {
-        const layer = queue[i];
-        order.push(layer);
-        done.add(layer);
-        for (const dep of dependsOn.get(layer) ?? []) {
-            const remaining = (dependents.get(dep) ?? 0) - 1;
-            dependents.set(dep, remaining);
-            if (remaining === 0 && !done.has(dep))
-                queue.push(dep);
-        }
-    }
-    // Cyclic remainder: keep declaration order so the output is stable.
-    for (const layer of declared) {
-        if (!done.has(layer))
-            order.push(layer);
-    }
-    return order;
+const COMPOUND_ENTITY_THRESHOLD = 250;
+/** Aspect ratio band and pixel budget a single hierarchical run must stay inside. */
+const MAX_ASPECT = 3;
+/** Stacked semantic layers are legitimately tall; only a sliver is rejected. */
+const MIN_ASPECT = 0.2;
+/** Narrowest aspect a width-driven switch to the compound layout may produce. */
+const PREFERRED_MIN_ASPECT = 0.6;
+/** Top-level package count from which a gappy flat run yields to packed blocks. */
+const MID_ROOT_PACKAGES = 8;
+/** Empty-block ratio above which a mid-scale flat run is considered gappy. */
+const MID_MAX_EMPTY_BLOCK = 0.15;
+const MAX_PIXELS = 40e6;
+/** Canvas area (px²) a dense compound layout with dependency-ordered rows may use. */
+const COMPOUND_AREA_BUDGET = 90e6;
+/** Canvas width beyond which a single hierarchical run is too wide to read. */
+const MAX_WIDTH = 2400;
+/** Alternative stub orbits tried after the default one (tuned on the archguard package views). */
+const STUB_ORBITS = [
+    { gap: 72, spacing: 112, anchor: 'nearest' },
+    { gap: 88, spacing: 120, anchor: 'nearest' },
+    { gap: 72, spacing: 136, anchor: 'nearest' },
+    { gap: 48, spacing: 112, anchor: 'centroid' },
+];
+/** Clutter cost under which no further stub orbit is tried. */
+const STUB_GOOD_ENOUGH = 400;
+/** Clutter of a stub view: border-hugging edges and parallel walls weigh most. */
+function stubViewCost(model, layout) {
+    const m = computeLayoutMetrics(model, layout);
+    return (m.edgeFlushCount * 500 +
+        m.edgeNodeIntersections * 1000 +
+        m.overlappingEdgeLength +
+        m.edgeCrossings * 4 +
+        m.maxEmptyBlockRatio * 2000);
+}
+function isProportionate(layout) {
+    if (layout.height <= 0 || layout.width <= 0)
+        return true;
+    const aspect = layout.width / layout.height;
+    return aspect <= MAX_ASPECT && aspect >= MIN_ASPECT && layout.width * layout.height <= MAX_PIXELS;
+}
+/** Compound result that respects the width budget and is not a tall sliver. */
+function isNarrowEnough(layout) {
+    if (layout.height <= 0 || layout.width <= 0)
+        return true;
+    return layout.width <= MAX_WIDTH && layout.width / layout.height >= PREFERRED_MIN_ASPECT;
 }
-/** Minimum frame width that keeps the package label tab readable. */
-function packageMinWidth(name) {
-    return measureTextWidth(name, PACKAGE_LABEL.fontSize) + PACKAGE_LABEL.tabPadding + 20;
+/** A tall single-column run: narrower than the preferred minimum aspect. */
+function isColumn(layout) {
+    return layout.height > 0 && layout.width / layout.height < PREFERRED_MIN_ASPECT;
+}
+/** Clear space kept between any edge point and the canvas side. */
+export const CANVAS_EDGE_MARGIN = 16;
+/**
+ * Translate and grow the canvas so no edge point (or node/frame) sits closer
+ * than [[CANVAS_EDGE_MARGIN]] to a canvas side — a line hugging the border is
+ * easily cropped.
+ */
+export function fitCanvas(layout) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const take = (x, y) => {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    };
+    for (const e of layout.edges ?? [])
+        for (const p of e.points)
+            take(p.x, p.y);
+    if (minX === Infinity)
+        return layout;
+    const dx = Math.max(0, CANVAS_EDGE_MARGIN - minX);
+    const dy = Math.max(0, CANVAS_EDGE_MARGIN - minY);
+    const width = Math.max(layout.width + dx, maxX + dx + CANVAS_EDGE_MARGIN);
+    const height = Math.max(layout.height + dy, maxY + dy + CANVAS_EDGE_MARGIN);
+    if (dx === 0 && dy === 0 && width === layout.width && height === layout.height)
+        return layout;
+    return {
+        ...layout,
+        nodes: layout.nodes.map((n) => ({ ...n, x: n.x + dx, y: n.y + dy })),
+        edges: layout.edges.map((e) => ({ ...e, points: e.points.map((p) => ({ x: p.x + dx, y: p.y + dy })) })),
+        packages: layout.packages?.map((p) => ({ ...p, x: p.x + dx, y: p.y + dy })),
+        width,
+        height,
+    };
 }
 export class ElkLayoutEngine {
     elk = new ElkConstructor();
@@ -130,247 +148,123 @@ export class ElkLayoutEngine {
         this.options = options;
     }
     async layout(model) {
-        const layers = this.resolveLayerOrder(model);
-        const partitions = this.assignPartitions(model, layers);
-        const partitionsActive = layers.length > 0;
-        const includeChildren = this.hasCrossPackageEdge(model);
-        const children = this.buildChildren(model, partitions);
-        const edges = model.relations.map((relation, i) => ({
-            id: `rel-${i}`,
-            sources: [this.layoutSource(relation)],
-            targets: [this.layoutTarget(relation)],
-        }));
-        const layoutOptions = {
-            'elk.algorithm': 'layered',
-            'elk.direction': 'DOWN',
-            'elk.edgeRouting': this.options.edgeRouting ?? 'ORTHOGONAL',
-            'elk.spacing.nodeNode': '40',
-            'elk.layered.spacing.nodeNodeBetweenLayers': '60',
-            // Ports keep a fixed side per edge, so same-direction edges fan out across
-            // one node edge instead of scattering onto every side (or one point).
-            'elk.layered.portConstraints': 'FIXED_SIDE',
-            // Soft targets: pack disconnected components into a balanced rectangle
-            // instead of a long horizontal strip. (hierarchyHandling stays INHERIT
-            // unless cross-package edges exist — see the header comment.)
-            'elk.aspectRatio': '1.6',
-            'elk.separateConnectedComponents': 'true',
-            // INTERACTIVE placement keeps each layer's boxes centred on the widest
-            // partition instead of fanning them out sideways, which is what lets a
-            // topologically-stacked package diagram stay compact (see
-            // docs/layout-routing-eval.md).
-            'elk.layered.nodePlacement.strategy': 'INTERACTIVE',
-        };
-        if (partitionsActive)
-            layoutOptions['elk.partitioning.activate'] = 'true';
-        if (includeChildren)
-            layoutOptions['elk.hierarchyHandling'] = 'INCLUDE_CHILDREN';
-        if (this.options.mergeEdges)
-            layoutOptions['elk.layered.mergeEdges'] = 'true';
-        const graph = {
-            id: 'root',
-            layoutOptions,
-            children,
-            edges,
-        };
-        const result = await this.elk.layout(graph);
-        const nodes = [];
-        const packages = [];
-        const offsets = new Map([['root', { x: 0, y: 0 }]]);
-        for (const child of result.children ?? []) {
-            this.flatten(child, 0, 0, nodes, packages, offsets);
-        }
-        this.enforcePackageMinWidth(model, packages);
-        const nodeById = new Map(nodes.map((n) => [n.id, n]));
-        const laidEdges = (result.edges ?? []).map((edge, i) => {
-            const relation = model.relations[i];
-            const reversed = relation !== undefined && REVERSED_RELATION_TYPES.has(relation.type);
-            const points = this.edgePoints(edge, nodeById, offsets);
-            return {
-                id: edge.id ?? `rel-${i}`,
-                // Keep the model's direction (not the possibly-reversed layout
-                // direction) so the renderer's arrowheads and the overlap counter both
-                // see the endpoints the author wrote.
-                source: relation?.source ?? (edge.sources?.[0] ?? ''),
-                target: relation?.target ?? (edge.targets?.[0] ?? ''),
-                points: reversed ? points.slice().reverse() : points,
-            };
-        });
-        return {
-            nodes,
-            edges: laidEdges,
-            packages,
-            width: result.width ?? 0,
-            height: result.height ?? 0,
-        };
-    }
-    /** Source endpoint of the edge *as laid out* (reversed for inheritance/implementation). */
-    layoutSource(relation) {
-        return REVERSED_RELATION_TYPES.has(relation.type) ? relation.target : relation.source;
-    }
-    /** Target endpoint of the edge *as laid out* (reversed for inheritance/implementation). */
-    layoutTarget(relation) {
-        return REVERSED_RELATION_TYPES.has(relation.type) ? relation.source : relation.target;
-    }
-    /** Ordered, de-duplicated list of semantic layers (dependency topology by default). */
-    resolveLayerOrder(model) {
-        if (this.options.layerOrder) {
-            return this.options.layerOrder.filter((layer, i, all) => all.indexOf(layer) === i);
-        }
-        return topologicalLayerOrder(model);
-    }
-    /** Map each package to its partition index (layers first, unlayered last). */
-    assignPartitions(model, layers) {
-        const partitions = new Map();
-        if (layers.length === 0)
-            return partitions;
-        for (const pkg of model.packages) {
-            const layer = packageLayer(pkg);
-            const index = layer !== undefined ? layers.indexOf(layer) : -1;
-            partitions.set(pkg.id, index >= 0 ? index : layers.length);
-        }
-        return partitions;
-    }
-    /** True when any relation connects entities in two *different* packages. */
-    hasCrossPackageEdge(model) {
-        const packageOf = new Map(model.entities.map((e) => [e.id, e.packageId]));
-        for (const relation of model.relations) {
-            const sourcePkg = packageOf.get(relation.source);
-            const targetPkg = packageOf.get(relation.target);
-            if (sourcePkg !== undefined && targetPkg !== undefined && sourcePkg !== targetPkg) {
-                return true;
+        const finish = (raw) => fitCanvas(liftFlushSegments(
+        // stub views price crossings high on purpose: their rail edges are not un-coiled
+        (model.entities.some((e) => e.stub) ? (l) => l : uncoilWraps)(straightenTrunkDetours(mergeFanoutTrunks(model, spreadParallelLanes(clipPackageEndpoints(model, alignIsolatedFrames(model, alignRows(model, raw)))))))));
+        if (!model.entities.some((e) => e.stub))
+            return finish((await this.layoutRaw(model)).layout);
+        // Where the orbiting stubs sit decides how the router weaves their edges
+        // through the frame; the outcome is chaotic enough that a handful of
+        // orbits is tried and the least cluttered picture kept. The trials skip the
+        // router's rip-up passes (the slow part); only the winner is routed in full.
+        const first = await this.layoutRaw(model, { quick: true });
+        if (!first.orbited)
+            return finish(first.layout);
+        let bestCost = stubViewCost(model, finish(first.layout));
+        let bestOrbit;
+        for (const orbit of STUB_ORBITS) {
+            if (bestCost <= STUB_GOOD_ENOUGH)
+                break;
+            const trial = await this.layoutRaw(model, { orbit, quick: true });
+            const cost = stubViewCost(model, finish(trial.layout));
+            if (cost < bestCost) {
+                bestCost = cost;
+                bestOrbit = orbit;
             }
         }
-        return false;
+        return finish((await this.layoutRaw(model, { orbit: bestOrbit })).layout);
     }
-    buildChildren(model, partitions) {
-        const pkgNodes = new Map();
-        for (const pkg of model.packages) {
-            // Padding at the top keeps the package label tab clear of the first
-            // entity; the minimum width keeps the tab wide enough for the label when
-            // a package holds only a single short-named entity.
-            const minWidth = packageMinWidth(pkg.name);
-            const minHeight = PACKAGE_LABEL.tabHeight + 26 + 10; // tab + top/bottom padding
-            const layoutOptions = {
-                'elk.padding': '[top=26,left=10,bottom=10,right=10]',
-                'elk.nodeSize.constraints': '[MINIMUM_SIZE]',
-                'elk.nodeSize.minimum': `[${minWidth.toFixed(1)}, ${minHeight.toFixed(1)}]`,
-            };
-            const partition = partitions.get(pkg.id);
-            if (partition !== undefined)
-                layoutOptions['elk.partitioning.partition'] = String(partition);
-            pkgNodes.set(pkg.id, {
-                id: PACKAGE_PREFIX + pkg.id,
-                children: [],
-                layoutOptions,
-            });
-        }
-        const top = [];
-        for (const entity of model.entities) {
-            const leaf = this.entityLeaf(entity);
-            const owner = entity.packageId ? pkgNodes.get(entity.packageId) : undefined;
-            if (owner)
-                owner.children.push(leaf);
-            else
-                top.push(leaf);
+    async layoutRaw(model, run = {}) {
+        const layers = resolveLayerOrder(model, this.options.layerOrder);
+        const partitions = assignPartitions(model, layers);
+        const injected = await runStrategies(this.options.strategies, model, { layers, partitions });
+        if (injected !== undefined)
+            return { layout: injected, orbited: false };
+        let flat;
+        const raw = (layout) => ({ layout, orbited: false });
+        // A large package-less graph has no blocks to pack: the compound layout
+        // degenerates into one block per entity, which is an order of magnitude
+        // slower and no better proportioned than the single layered run (measured:
+        // 789 flat nodes — 1.7s/608 crossings layered vs 40s/13625 compound). It
+        // also has no folded layer sequence, so a requested aspectRatio cannot
+        // reshape it either; take the layered run unconditionally instead.
+        if (model.packages.length === 0 && model.entities.length > COMPOUND_ENTITY_THRESHOLD) {
+            return raw(await this.hierarchicalLayout(model, layers, partitions));
         }
-        // Link nested packages into their parents; packages without a parent (or
-        // whose parent is unknown) sit at the top level.
-        for (const pkg of model.packages) {
-            const node = pkgNodes.get(pkg.id);
-            const parent = pkg.parentId ? pkgNodes.get(pkg.parentId) : undefined;
-            if (parent)
-                parent.children.push(node);
-            else
-                top.push(node);
+        // Very large graphs skip the single hierarchical run: it cannot keep the
+        // canvas proportioned, so it would only be thrown away.
+        const target = this.options.aspectRatio;
+        if (target !== undefined && target > 0)
+            return this.layoutToward(model, layers, partitions, target, run);
+        if (model.entities.length <= COMPOUND_ENTITY_THRESHOLD || model.packages.length === 0) {
+            flat = await this.hierarchicalLayout(model, layers, partitions);
+            if (isProportionate(flat) && flat.width <= MAX_WIDTH && !this.isGappyMidScale(model, flat))
+                return raw(flat);
         }
-        return top;
-    }
-    entityLeaf(entity) {
-        const size = estimateEntitySize(entity);
-        return { id: entity.id, width: size.width, height: size.height };
+        const compound = await this.compound(model, layers, partitions, run);
+        const packed = compound.layout;
+        if (flat !== undefined && this.isGappyMidScale(model, flat) && isProportionate(flat) && !isColumn(packed)
+            && computeMaxEmptyBlockRatio(packed) >= computeMaxEmptyBlockRatio(flat))
+            return raw(flat);
+        // A flat run kept only for being too wide gives way to the compound layout
+        // when that one fits the width budget without degenerating into a tall
+        // sliver; otherwise the wide-but-balanced flat run is the better picture.
+        // A flat run that degenerated into a single column (aspect under the
+        // preferred minimum) is never worth keeping over the packed blocks.
+        if (flat !== undefined && isProportionate(flat) && !isNarrowEnough(packed) && !isColumn(flat))
+            return raw(flat);
+        return compound;
     }
     /**
-     * INCLUDE_CHILDREN sizes a container from its content and does not honour the
-     * `elk.nodeSize.minimum` we give package frames, so a single short-named
-     * entity can leave the frame narrower than its label tab. Widen those frames
-     * in place (never shrink) so the tab stays readable.
+     * A mid-scale root layer (many top-level packages) whose single hierarchical
+     * run left a large hole: the packed compound blocks are tried instead.
      */
-    enforcePackageMinWidth(model, packages) {
-        const byId = new Map(packages.map((p) => [p.id, p]));
-        for (const pkg of model.packages) {
-            const box = byId.get(pkg.id);
-            if (!box)
-                continue;
-            const min = packageMinWidth(pkg.name);
-            if (box.width < min)
-                box.width = min;
-        }
+    isGappyMidScale(model, flat) {
+        const roots = model.packages.filter((p) => p.parentId === undefined).length;
+        return roots >= MID_ROOT_PACKAGES && computeMaxEmptyBlockRatio(flat) > MID_MAX_EMPTY_BLOCK;
     }
-    flatten(node, offsetX, offsetY, nodes, packages, offsets) {
-        const x = (node.x ?? 0) + offsetX;
-        const y = (node.y ?? 0) + offsetY;
-        offsets.set(node.id, { x, y });
-        if (node.id.startsWith(PACKAGE_PREFIX)) {
-            packages.push({
-                id: node.id.slice(PACKAGE_PREFIX.length),
-                x,
-                y,
-                width: node.width ?? 0,
-                height: node.height ?? 0,
-            });
-            for (const child of node.children ?? []) {
-                this.flatten(child, x, y, nodes, packages, offsets);
-            }
-        }
-        else {
-            nodes.push({
-                id: node.id,
-                x,
-                y,
-                width: node.width ?? 0,
-                height: node.height ?? 0,
-            });
+    /**
+     * Caller-requested canvas ratio: run both strategies and keep whichever lands
+     * closer (in log distance) to the target. The default path never gets here.
+     */
+    async layoutToward(model, layers, partitions, target, run) {
+        const compound = await this.compound(model, layers, partitions, run);
+        const candidates = [compound.layout];
+        if (model.entities.length <= COMPOUND_ENTITY_THRESHOLD || model.packages.length === 0) {
+            candidates.push(await this.hierarchicalLayout(model, layers, partitions));
         }
+        const miss = (l) => l.width > 0 && l.height > 0 ? Math.abs(Math.log(l.width / l.height / target)) : 0;
+        const winner = candidates.reduce((best, c) => (miss(c) < miss(best) ? c : best));
+        return { layout: winner, orbited: true };
     }
-    edgePoints(edge, nodeById, offsets) {
-        const sections = edge.sections ?? [];
-        if (sections.length === 0) {
-            return this.straightEdge(edge, nodeById);
-        }
-        const containerOffset = offsets.get(edge.container ?? 'root') ?? {
-            x: 0,
-            y: 0,
-        };
-        const points = [];
-        for (const section of sections) {
-            for (const p of this.sectionPoints(section)) {
-                const shifted = { x: p.x + containerOffset.x, y: p.y + containerOffset.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);
-                }
-            }
+    async compound(model, layers, partitions, { orbit, quick }) {
+        const dense = model.entities.length > COMPOUND_ENTITY_THRESHOLD;
+        const run = (rectPackDense) => compoundLayout(this.elk, model, {
+            edgeRouting: this.options.edgeRouting,
+            aspectRatio: this.options.aspectRatio,
+            elk: this.options.elk,
+            dense,
+            rectPackDense,
+            partitions: layers.length > 0 ? partitions : new Map(),
+            stubOrbit: orbit,
+            ripupPasses: quick ? 0 : undefined,
+        });
+        const ordered = await run(false);
+        // Dependency-ordered rows cost canvas on very large graphs; past the budget
+        // fall back to the tighter (order-blind) rect packing.
+        if (dense && ordered.width * ordered.height > COMPOUND_AREA_BUDGET) {
+            return { layout: await run(true), orbited: true };
         }
-        return points.length >= 2 ? points : this.straightEdge(edge, nodeById);
+        return { layout: ordered, orbited: true };
     }
-    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;
-    }
-    straightEdge(edge, nodeById) {
-        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 },
-        ];
+    /** One ELK run over the whole nested graph (`INCLUDE_CHILDREN`). */
+    async hierarchicalLayout(model, layers, partitions) {
+        const graph = buildElkGraph(model, layers, partitions, {
+            edgeRouting: this.options.edgeRouting,
+            mergeEdges: this.options.mergeEdges,
+            aspectRatio: this.options.aspectRatio,
+            elk: this.options.elk,
+        });
+        return mapElkResult(model, await this.elk.layout(graph));
     }
 }

package/dist/layout/fanout-trunk.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fan-out trunks. A node that sends (or receives) many edges the same way gets
+ * a "comb" from the routers: every edge takes its own port and its own bend
+ * level, so a dozen nested right-angle staircases run side by side. This pass
+ * redraws such a group as a tree: one shared trunk leaves the node, runs to a
+ * common branch level, and a shared bus there fans out to short drops that end
+ * at each target. Edges stay orthogonal and keep their endpoints' sides; a
+ * group is only rewritten when the new geometry stays clear of every other node.
+ *
+ * Only edges shaped "out, across, onward" (first and third segments along the
+ * same direction, the second across) take part — the shape both ELK and the
+ * grid router give a plain fan-out. Anything else in the group is left alone.
+ */
+import { LayoutResult } from '../foundation/layout.js';
+import { PlantUmlModel } from '../foundation/model.js';
+/** Edges leaving (or entering) one side that make a group worth merging. */
+export declare const TRUNK_MIN_EDGES = 5;
+export declare function mergeFanoutTrunks(model: PlantUmlModel, layout: LayoutResult): LayoutResult;