@yalehwang/plantuml-js 0.2.2 → 0.3.1

package/dist/layout/trunk-lanes.js

@@ -0,0 +1,308 @@
+/**
+ * Trunk lanes. A router that has to dodge a cluster of nodes can leave an edge
+ * that overshoots — out sideways, down, back across, down again — and stacked
+ * edges doing this draw the concentric rectangles of a coil. When the two end
+ * segments run the same axis, the edge is re-drawn as a Z: leave the source,
+ * cross over on a lane between the rows (the gap between the two end points),
+ * and enter the target. It runs after lane spreading and fan-out merging, so only
+ * what those passes left as an overshoot is touched. A Z replaces a detour only when it is shorter, passes
+ * no unrelated node or package frame, and adds at most [[EXTRA_CROSSINGS]] crossings.
+ */
+import { routeOrthogonal } from './grid-router.js';
+import { findParallelBundles } from '../metrics/layout-metrics.js';
+/** Path length ÷ Manhattan distance above which an edge is considered for a Z. */
+const DETOUR_FACTOR = 2;
+/** Clearance between a Z segment and an unrelated node box. */
+const NODE_CLEARANCE = 10;
+/** The lane must sit at least this far from both end points along the main axis. */
+const END_MARGIN = 14;
+/** Extra crossings a straightened route may add: a few crossings read better than a coil. */
+const EXTRA_CROSSINGS = 2;
+/** Spacing of the candidate lanes tried between the end points. */
+const LANE_STEP = 10;
+/** Spacing of the candidate channels tried for an overshooting S-route. */
+const CHANNEL_STEP = 6;
+const length = (pts) => pts.slice(1).reduce((sum, p, i) => sum + Math.abs(p.x - pts[i].x) + Math.abs(p.y - pts[i].y), 0);
+/** Segment touches the box inflated by `pad` (axis-aligned segments only). */
+function hitsBox(a, b, r, pad) {
+    const x0 = Math.min(a.x, b.x);
+    const x1 = Math.max(a.x, b.x);
+    const y0 = Math.min(a.y, b.y);
+    const y1 = Math.max(a.y, b.y);
+    return x1 > r.x - pad && x0 < r.x + r.width + pad && y1 > r.y - pad && y0 < r.y + r.height + pad;
+}
+function crosses(a, b, c, d) {
+    const o = (p, q, r) => Math.sign((q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x));
+    return o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0;
+}
+function segmentsOf(pts) {
+    return pts.slice(1).map((p, i) => [pts[i], p]);
+}
+function crossingCount(route, others) {
+    let n = 0;
+    for (const s of segmentsOf(route)) {
+        for (const other of others)
+            for (const t of segmentsOf(other))
+                if (crosses(s[0], s[1], t[0], t[1]))
+                    n++;
+    }
+    return n;
+}
+const centreInside = (n, f) => {
+    const cx = n.x + n.width / 2;
+    const cy = n.y + n.height / 2;
+    return cx > f.x && cx < f.x + f.width && cy > f.y && cy < f.y + f.height;
+};
+/** Z-route with its lane at `lane` on the main axis; `vertical` = the end segments are vertical. */
+function zRoute(a, b, lane, vertical) {
+    return vertical
+        ? [a, { x: a.x, y: lane }, { x: b.x, y: lane }, b]
+        : [a, { x: lane, y: a.y }, { x: lane, y: b.y }, b];
+}
+export function straightenTrunkDetours(layout) {
+    const nodeById = new Map(layout.nodes.map((n) => [n.id, n]));
+    const frames = layout.packages ?? [];
+    const routes = layout.edges.map((e) => e.points);
+    let changed = false;
+    layout.edges.forEach((edge, index) => {
+        const pts = edge.points;
+        if (pts.length < 5)
+            return;
+        const a = pts[0];
+        const b = pts[pts.length - 1];
+        const manhattan = Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+        if (length(pts) <= DETOUR_FACTOR * Math.max(manhattan, 1))
+            return;
+        const verticalEnds = Math.abs(pts[0].x - pts[1].x) < 1e-6 && Math.abs(pts[pts.length - 2].x - b.x) < 1e-6;
+        const horizontalEnds = Math.abs(pts[0].y - pts[1].y) < 1e-6 && Math.abs(pts[pts.length - 2].y - b.y) < 1e-6;
+        if (verticalEnds === horizontalEnds)
+            return;
+        const vertical = verticalEnds;
+        const from = vertical ? a.y : a.x;
+        const to = vertical ? b.y : b.x;
+        const lo = Math.min(from, to) + END_MARGIN;
+        const hi = Math.max(from, to) - END_MARGIN;
+        if (hi < lo)
+            return;
+        const source = nodeById.get(edge.source);
+        const target = nodeById.get(edge.target);
+        const endFrames = frames.filter((f) => (source && centreInside(source, f)) || (target && centreInside(target, f)));
+        const obstacles = layout.nodes.filter((n) => n.id !== edge.source && n.id !== edge.target);
+        const others = routes.filter((_, i) => i !== index);
+        const oldCrossings = crossingCount(pts, others);
+        const mid = (lo + hi) / 2;
+        const lanes = [];
+        for (let d = 0; mid - d >= lo || mid + d <= hi; d += LANE_STEP) {
+            if (mid - d >= lo)
+                lanes.push(mid - d);
+            if (d > 0 && mid + d <= hi)
+                lanes.push(mid + d);
+        }
+        const candidates = lanes.map((lane) => zRoute(a, b, lane, vertical));
+        if (pts.length === 6) {
+            // Overshoot through a gap in the row between: keep the two cross-over
+            // lanes and slide the channel to the gap nearest the end points.
+            const c0 = vertical ? pts[2].x : pts[2].y;
+            const span = [vertical ? a.x : a.y, vertical ? b.x : b.y, c0];
+            for (let c = Math.min(...span); c <= Math.max(...span); c += CHANNEL_STEP) {
+                candidates.push(vertical
+                    ? [a, pts[1], { x: c, y: pts[1].y }, { x: c, y: pts[3].y }, { x: b.x, y: pts[3].y }, b]
+                    : [a, pts[1], { x: pts[1].x, y: c }, { x: pts[3].x, y: c }, { x: pts[3].x, y: b.y }, b]);
+            }
+        }
+        let best;
+        for (const route of candidates) {
+            if (best && length(route) >= length(best.route))
+                continue;
+            const segs = segmentsOf(route);
+            if (obstacles.some((n) => segs.some(([p, q]) => hitsBox(p, q, n, NODE_CLEARANCE))))
+                continue;
+            // a frame that neither end sits in must stay unentered
+            if (frames.some((f) => !endFrames.includes(f) && segs.some(([p, q]) => hitsBox(p, q, f, -1))))
+                continue;
+            const crossings = crossingCount(route, others);
+            if (crossings > oldCrossings + EXTRA_CROSSINGS)
+                continue;
+            best = { route, crossings };
+        }
+        if (!best || length(best.route) >= length(pts))
+            return;
+        routes[index] = best.route;
+        changed = true;
+    });
+    if (!changed)
+        return layout;
+    return { ...layout, edges: layout.edges.map((e, i) => ({ ...e, points: routes[i] })) };
+}
+/** A segment this close to a side of an end node (and at least [[FLUSH_MIN_LENGTH]] long) hugs the box. */
+const FLUSH_DISTANCE = 4;
+const FLUSH_MIN_LENGTH = 40;
+/** Distances off the node side tried for a lifted segment, nearest first. */
+const FLUSH_LIFTS = Array.from({ length: 36 }, (_, i) => i + 8);
+/** A lifted segment keeps this far from other edges' parallel segments it runs beside. */
+const FLUSH_LANE_CLEARANCE = 9;
+/** Another route has a segment parallel to a–b, closer than [[FLUSH_LANE_CLEARANCE]] and overlapping it in extent. */
+function besideParallel(a, b, other) {
+    const horizontal = Math.abs(a.y - b.y) < 1e-6;
+    for (let j = 0; j + 1 < other.length; j++) {
+        const c = other[j];
+        const d = other[j + 1];
+        if (horizontal) {
+            if (Math.abs(c.y - d.y) > 1e-6 || Math.abs(c.y - a.y) >= FLUSH_LANE_CLEARANCE)
+                continue;
+            if (Math.min(Math.max(a.x, b.x), Math.max(c.x, d.x)) - Math.max(Math.min(a.x, b.x), Math.min(c.x, d.x)) > 1e-6)
+                return true;
+        }
+        else {
+            if (Math.abs(c.x - d.x) > 1e-6 || Math.abs(c.x - a.x) >= FLUSH_LANE_CLEARANCE)
+                continue;
+            if (Math.min(Math.max(a.y, b.y), Math.max(c.y, d.y)) - Math.max(Math.min(a.y, b.y), Math.min(c.y, d.y)) > 1e-6)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Lift segments that run flush along the side of a node the edge belongs to —
+ * hard to tell from the box outline — a few pixels off that side. The segment
+ * moves outwards; when it was the first or last one, the original end point is
+ * kept and joined by a short stub. The nearest lift that clears every node and
+ * every parallel neighbour edge is used; none, and the segment stays.
+ */
+export function liftFlushSegments(layout) {
+    const nodeById = new Map(layout.nodes.map((n) => [n.id, n]));
+    let changed = false;
+    const edges = layout.edges.map((edge) => {
+        let pts = edge.points;
+        for (let i = 0; i + 1 < pts.length; i++) {
+            const a = pts[i];
+            const b = pts[i + 1];
+            const horizontal = Math.abs(a.y - b.y) < 1e-6;
+            const vertical = Math.abs(a.x - b.x) < 1e-6;
+            if (horizontal === vertical || Math.abs(a.x - b.x) + Math.abs(a.y - b.y) < FLUSH_MIN_LENGTH)
+                continue;
+            for (const id of [edge.source, edge.target]) {
+                const n = nodeById.get(id);
+                if (!n)
+                    continue;
+                const lo = horizontal ? Math.min(a.x, b.x) : Math.min(a.y, b.y);
+                const hi = horizontal ? Math.max(a.x, b.x) : Math.max(a.y, b.y);
+                const n0 = horizontal ? n.x : n.y;
+                const n1 = horizontal ? n.x + n.width : n.y + n.height;
+                if (Math.min(hi, n1) - Math.max(lo, n0) <= 1e-6)
+                    continue;
+                const at = horizontal ? a.y : a.x;
+                const side0 = horizontal ? n.y : n.x;
+                const side1 = horizontal ? n.y + n.height : n.x + n.width;
+                const nearLow = Math.abs(at - side0) < FLUSH_DISTANCE;
+                const nearHigh = Math.abs(at - side1) < FLUSH_DISTANCE;
+                if (!nearLow && !nearHigh)
+                    continue;
+                let lifted;
+                // First pass keeps clear of every neighbouring lane; the second takes the
+                // nearest lift that merely clears the nodes — a lane beside another lane
+                // reads better than a line that is part of a box outline.
+                for (const strict of [true, false])
+                    for (const lift of lifted ? [] : FLUSH_LIFTS) {
+                        const to = nearLow ? side0 - lift : side1 + lift;
+                        const a2 = horizontal ? { x: a.x, y: to } : { x: to, y: a.y };
+                        const b2 = horizontal ? { x: b.x, y: to } : { x: to, y: b.y };
+                        if (layout.nodes.some((o) => hitsBox(a2, b2, o, 2)))
+                            continue;
+                        if (strict && layout.edges.some((o) => o !== edge && besideParallel(a2, b2, o.points)))
+                            continue;
+                        lifted = [...pts.slice(0, i), ...(i === 0 ? [a] : []), a2, b2, ...(i + 2 === pts.length ? [b] : []), ...pts.slice(i + 2)];
+                        break;
+                    }
+                if (!lifted)
+                    continue;
+                pts = lifted;
+                changed = true;
+                break;
+            }
+        }
+        return pts === edge.points ? edge : { ...edge, points: pts };
+    });
+    return changed ? { ...layout, edges } : layout;
+}
+/** Crossing prices an un-coil re-route is tried with, dearest first, and the crossings it may add. */
+const UNCOIL_CROSSING_COSTS = [6, 3, 1.5];
+const UNCOIL_EXTRA_CROSSINGS = 5;
+/** Nodes (other than its ends) enclosed by the boxes of the route's U-turns (outer segments opposite), summed. */
+function wrapCount(pts, nodes, ends) {
+    let wrapped = 0;
+    for (let i = 0; i + 3 < pts.length; i++) {
+        const [p0, p1, p2, p3] = pts.slice(i, i + 4);
+        const vertical = Math.abs(p0.x - p1.x) < 1e-6 && Math.abs(p0.y - p1.y) > 1e-6;
+        const horizontal = Math.abs(p0.y - p1.y) < 1e-6 && Math.abs(p0.x - p1.x) > 1e-6;
+        if (!vertical && !horizontal)
+            continue;
+        const d1 = vertical ? p1.y - p0.y : p1.x - p0.x;
+        const d3 = vertical ? p3.y - p2.y : p3.x - p2.x;
+        const middleOk = vertical ? Math.abs(p1.y - p2.y) < 1e-6 : Math.abs(p1.x - p2.x) < 1e-6;
+        const lastOk = vertical ? Math.abs(p2.x - p3.x) < 1e-6 : Math.abs(p2.y - p3.y) < 1e-6;
+        if (!middleOk || !lastOk || d1 * d3 >= 0)
+            continue;
+        const x0 = Math.min(p0.x, p1.x, p2.x, p3.x);
+        const x1 = Math.max(p0.x, p1.x, p2.x, p3.x);
+        const y0 = Math.min(p0.y, p1.y, p2.y, p3.y);
+        const y1 = Math.max(p0.y, p1.y, p2.y, p3.y);
+        wrapped += nodes.filter((n) => !ends.includes(n.id) && n.x > x0 && n.x + n.width < x1 && n.y > y0 && n.y + n.height < y1).length;
+    }
+    return wrapped;
+}
+/**
+ * Un-coil: an edge whose route wraps round other nodes (the U of a trunk that
+ * circles a cluster — stacked, the concentric rectangles of a coil) is routed
+ * again on the lattice with cheaper crossings, against every other edge as a
+ * fixed wire. The new route is kept when it wraps fewer nodes, adds at most
+ * [[UNCOIL_EXTRA_CROSSINGS]] crossings and opens no new comb at either end.
+ * Runs after fan-out merging, so a hub's trunk has been settled by then.
+ */
+export function uncoilWraps(layout) {
+    const nodeById = new Map(layout.nodes.map((n) => [n.id, n]));
+    const routes = layout.edges.map((e) => e.points);
+    const combKeys = () => new Set(findParallelBundles(layout.edges.map((e, i) => ({ ...e, points: routes[i] }))).map((b) => `${b.end}\u0000${b.node}`));
+    const combsBefore = combKeys();
+    let changed = false;
+    layout.edges.forEach((edge, index) => {
+        const pts = routes[index];
+        const source = nodeById.get(edge.source);
+        const target = nodeById.get(edge.target);
+        const ends = [edge.source, edge.target];
+        const wrapped = source && target && pts.length >= 4 ? wrapCount(pts, layout.nodes, ends) : 0;
+        if (!source || !target || wrapped === 0)
+            return;
+        const others = routes.filter((_, i) => i !== index);
+        const oldCrossings = crossingCount(pts, others);
+        const existing = layout.edges
+            .map((e, i) => ({ source: e.source, target: e.target, points: routes[i] }))
+            .filter((_, i) => i !== index);
+        for (const crossingCost of UNCOIL_CROSSING_COSTS) {
+            const route = routeOrthogonal([{ id: 'uncoil', source, target }], layout.nodes, {
+                width: layout.width,
+                height: layout.height,
+                frames: layout.packages,
+                existing,
+                crossingCost,
+                ripupPasses: 0,
+            }).get('uncoil');
+            if (!route || route.length < 2 || wrapCount(route, layout.nodes, ends) >= wrapped)
+                continue;
+            if (crossingCount(route, others) > oldCrossings + UNCOIL_EXTRA_CROSSINGS)
+                continue;
+            const previous = routes[index];
+            routes[index] = route;
+            const opened = [...combKeys()].some((k) => !combsBefore.has(k));
+            if (opened) {
+                routes[index] = previous;
+                continue;
+            }
+            changed = true;
+            break;
+        }
+    });
+    if (!changed)
+        return layout;
+    return { ...layout, edges: layout.edges.map((e, i) => ({ ...e, points: routes[i] })) };
+}

package/dist/layout/viz.d.ts

@@ -11,9 +11,9 @@
  * bounding-box origin so the result matches the top-down pixel space the ELK
  * engine and the SVG renderer already speak.
  */
-import { PlantUmlModel } from '../model.js';
-import { LayoutEngine, LayoutResult } from '../layout.js';
-import { GraphvizEngine } from '../render-dot.js';
+import { PlantUmlModel } from '../foundation/model.js';
+import { LayoutEngine, LayoutResult } from '../foundation/layout.js';
+import { GraphvizEngine } from './render-dot.js';
 export declare class VizLayoutEngine implements LayoutEngine {
     private readonly graphvizEngine;
     constructor(graphvizEngine?: GraphvizEngine);

package/dist/layout/viz.js

@@ -11,9 +11,10 @@
  * bounding-box origin so the result matches the top-down pixel space the ELK
  * engine and the SVG renderer already speak.
  */
-import { PACKAGE_LABEL, displayName, estimateEntitySize, } from '../layout.js';
-import { getViz } from '../render-dot.js';
-import { measureTextWidth } from '../text-measure.js';
+import { PACKAGE_LABEL, displayName, estimateEntitySize, } from '../foundation/layout.js';
+import { getViz } from './render-dot.js';
+import { measureTextWidth } from '../foundation/text-measure.js';
+import { relationSemantics } from '../foundation/relation-semantics.js';
 const POINTS_PER_INCH = 72;
 const CLUSTER_PREFIX = 'cluster_';
 export class VizLayoutEngine {
@@ -159,28 +160,23 @@ function clusterIndex(name) {
         return null;
     return Number(tail);
 }
+/** Translate the relation's semantic facts into Graphviz DOT attributes. */
 function edgeAttrs(relation) {
     const attrs = [];
-    switch (relation.type) {
-        case 'inheritance':
+    const semantics = relationSemantics(relation.type);
+    switch (semantics.arrowKind()) {
+        case 'triangle':
             attrs.push('arrowhead="empty"');
             break;
-        case 'implementation':
-            attrs.push('arrowhead="empty"', 'style="dashed"');
-            break;
-        case 'dependency':
-            attrs.push('arrowhead="vee"', 'style="dashed"');
-            break;
-        case 'association':
+        case 'chevron':
             attrs.push('arrowhead="vee"');
             break;
-        case 'aggregation':
-            attrs.push('arrowhead="odiamond"');
-            break;
-        case 'composition':
-            attrs.push('arrowhead="diamond"');
+        case 'diamond':
+            attrs.push(`arrowhead="${semantics.isFilled() ? 'diamond' : 'odiamond'}"`);
             break;
     }
+    if (semantics.isDashed())
+        attrs.push('style="dashed"');
     if (relation.label)
         attrs.push(`label=${quoteDotLabel(relation.label)}`);
     return attrs.length > 0 ? ` [${attrs.join(', ')}]` : '';

package/dist/metrics/layout-metrics.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Layout quality metrics. Pure functions from (model, layout) to numbers, so a
+ * layout strategy change can be judged by a diff in figures rather than by eye.
+ *
+ * Edge polylines are taken at face value: for the viz engine they are bezier
+ * control points, which is a coarse but consistent approximation. Every metric
+ * is deterministic — the same (model, layout) always yields the same numbers —
+ * so a run can be committed as `rendered/metrics.baseline.json` and diffed
+ * against a later run to prove an improvement or a regression.
+ */
+import { PlantUmlModel } from '../foundation/model.js';
+import { LayoutResult, EdgeLayout, Point } from '../foundation/layout.js';
+export interface LayoutMetrics {
+    /** Proper crossings between segments of two different edges. */
+    edgeCrossings: number;
+    /** Edge segments passing through the interior of an unrelated node. */
+    edgeNodeIntersections: number;
+    /**
+     * Edges drawn with at least one diagonal segment (or no usable polyline at
+     * all) — the straight-line fallback an engine takes when its router returns
+     * no route. Zero means every edge is an orthogonal polyline.
+     */
+    nonOrthogonalEdgeCount: number;
+    /** Summed polyline length of every edge, in canvas pixels. */
+    totalEdgeLength: number;
+    /** Sum of node areas divided by canvas area (0..1). */
+    areaUtilization: number;
+    /** Canvas width / height. */
+    aspectRatio: number;
+    /** Entity text lines wider than the box they are drawn in. */
+    textOverflowCount: number;
+    /** Package label tabs that overlap content or are narrower than their text. */
+    labelOverlapCount: number;
+    /**
+     * Summed overlap length of *nearly* parallel segments from different edges —
+     * segments within [[PARALLEL_PROXIMITY]] px of each other. The orthogonal
+     * router's "parallel-line wall" is invisible to [[edgeCrossings]] (segments
+     * that merely run alongside never *cross*), so this counts that hidden
+     * clutter in canvas pixels.
+     */
+    overlappingEdgeLength: number;
+    /** Hub badges whose circle covers any of the owning node's text. */
+    badgeLabelOverlap: number;
+    /**
+     * Edge labels (`×N` weights and plain labels) that overlap another edge label
+     * or sit on top of a node box.
+     */
+    edgeLabelOverlap: number;
+    /** Edge labels whose rectangle intersects any node rectangle (should be 0). */
+    labelNodeOverlap: number;
+    /** Edge labels whose rectangle is crossed by a segment of an edge other than their own. */
+    labelEdgeOverlap: number;
+    /** Pairs of edge-label rectangles that intersect each other. */
+    labelLabelOverlap: number;
+    /**
+     * Incoming arrowheads stacked beyond a threshold on the same side of the
+     * same node — the "everything points at this hub" pile-up that
+     * [[edgeCrossings]] cannot see either.
+     */
+    hubArrowStack: number;
+    /**
+     * Area of the largest axis-aligned rectangle on the canvas that holds neither
+     * a node nor a package frame, divided by the canvas area (0..1). A big value
+     * is the "empty quadrant" a row-packed root layer leaves behind.
+     */
+    maxEmptyBlockRatio: number;
+    /**
+     * Edge segments running parallel to, and within [[EDGE_FLUSH_DISTANCE]] px
+     * of, a side of a node they do not end at or of a package frame border they
+     * do not end at — the edge then reads as part of the box outline.
+     */
+    edgeFlushCount: number;
+    /**
+     * "Combs": groups of at least [[BUNDLE_MIN_EDGES]] edges that share a source
+     * (or a target), run the same way, and have segments laid side by side
+     * within [[BUNDLE_LATERAL_DISTANCE]] px for at least [[BUNDLE_MIN_RUN]] px.
+     * Edges drawn exactly on top of each other (a merged trunk) are one line and
+     * do not form a comb. [[overlappingEdgeLength]] cannot see these: the lines
+     * sit just outside its proximity.
+     */
+    parallelBundleCount: number;
+    /**
+     * Edges that pass through the interior of a package frame neither endpoint
+     * belongs to (counted once per edge and frame) — a corridor should run in the
+     * gutters between frames, not across unrelated packages.
+     */
+    edgeFrameCrossings: number;
+    /**
+     * Edges whose polyline is longer than [[TRUNK_DETOUR_FACTOR]] times the
+     * Manhattan distance between their end points — a trunk that wanders round a
+     * cluster instead of running the lane between the rows.
+     */
+    trunkDetourCount: number;
+    /**
+     * Nested rectangular loops inside one package frame (edges between two nodes of the same frame): U-turns (three segments,
+     * the outer two running in opposite directions) whose bounding box encloses a
+     * node the edge does not end at (the route wraps a cluster) and lies inside
+     * another such U-turn's — counted once per inner loop. The concentric "coil" a trunk makes when it keeps
+     * circling the nodes it avoids.
+     */
+    nestedLoopCount: number;
+    /**
+     * Edge segments at least [[EDGE_NODE_FLUSH_MIN_LENGTH]] px long running
+     * parallel to a side of the node they end at, within
+     * [[EDGE_NODE_FLUSH_DISTANCE]] px — the line hugs the box it belongs to and
+     * is hard to tell from its outline.
+     */
+    edgeNodeFlush: number;
+    /**
+     * Smallest node-area ÷ frame-area over the package frames holding at least
+     * [[FRAME_FILL_MIN_NODES]] nodes (1 when no frame qualifies): low means a
+     * stretched, mostly empty frame.
+     */
+    frameFillRatio: number;
+    /**
+     * Smallest distance from any edge point to a canvas side (the shorter canvas
+     * side when there are no edges): a line hugging the canvas edge is easily
+     * cropped.
+     */
+    edgeCanvasMargin: number;
+    /**
+     * Layout-engine wall time in milliseconds (layout only: no transforms, SVG
+     * or rasterisation). Present only when the caller passes the measured time.
+     */
+    layoutMs?: number;
+}
+/**
+ * A named, pure measurement over a layout. The metrics registry is the single
+ * source of truth for which measurements [[computeLayoutMetrics]] reports:
+ * adding a metric means registering a `Metric`, not editing the function's
+ * return literal.
+ */
+export interface Metric {
+    /** Key the value is exposed under on [[LayoutMetrics]]. */
+    readonly name: string;
+    compute(model: PlantUmlModel, layout: LayoutResult): number;
+}
+/** Register a metric; the next [[computeLayoutMetrics]] call reports it. */
+export declare function registerMetric(metric: Metric): void;
+/** Remove a registered metric by name; returns whether one was removed. */
+export declare function unregisterMetric(name: string): boolean;
+/** Names of the currently registered metrics, in evaluation order. */
+export declare function listMetrics(): readonly string[];
+/**
+ * Computes every registered metric. The registry drives the assembly, so a new
+ * measurement participates without touching this function; [[LayoutMetrics]]
+ * remains the strong, hand-written shape the registered names must cover.
+ * `layoutMs` is not a measurement of the layout — it is the caller's wall-time
+ * reading — so it is attached directly rather than registered.
+ */
+export declare function computeLayoutMetrics(model: PlantUmlModel, layout: LayoutResult, layoutMs?: number): LayoutMetrics;
+/** Polyline length ÷ Manhattan distance above which an edge counts as a detour. */
+export declare const TRUNK_DETOUR_FACTOR = 2;
+/** Distance (px) and run (px) for [[LayoutMetrics.edgeNodeFlush]]. */
+export declare const EDGE_NODE_FLUSH_DISTANCE = 4;
+export declare const EDGE_NODE_FLUSH_MIN_LENGTH = 40;
+/** Frames with at least this many nodes count for [[LayoutMetrics.frameFillRatio]]. */
+export declare const FRAME_FILL_MIN_NODES = 6;
+/** For each polyline, the number of crossings it takes part in (each crossing counts for both edges). */
+export declare function perEdgeCrossings(polylines: Point[][]): number[];
+/** Lateral distance (px) within which two parallel segments count as overlapping. */
+export declare const PARALLEL_PROXIMITY = 8;
+/** Edge-to-box distance (px) below which a parallel segment counts as flush. */
+export declare const EDGE_FLUSH_DISTANCE = 6;
+/**
+ * Rasterises nodes and package frames onto a coarse grid and returns the
+ * largest all-empty rectangle (maximal-rectangle-in-histogram) over the canvas.
+ */
+export declare function computeMaxEmptyBlockRatio(layout: LayoutResult): number;
+/** Edges per comb needed to count it. */
+export declare const BUNDLE_MIN_EDGES = 5;
+/** Lateral distance (px) within which two same-way segments sit "side by side". */
+export declare const BUNDLE_LATERAL_DISTANCE = 16;
+/** Shared run (px) two side-by-side segments need to count. */
+export declare const BUNDLE_MIN_RUN = 120;
+/** One comb: the shared end node and the ids of the edges laid side by side. */
+export interface ParallelBundle {
+    end: 'source' | 'target';
+    node: string;
+    edges: string[];
+}
+/** Lists source-sharing and target-sharing combs; see [[LayoutMetrics.parallelBundleCount]]. */
+export declare function findParallelBundles(edges: EdgeLayout[]): ParallelBundle[];