dsh-model-everything 0.5.1 → 0.5.2

package/lib/render/svg.js

@@ -104,6 +104,9 @@ const writers = {
             edgeMarks(first, after, before, last, shape.arrow, stroke, colours.background) +
             edgeLabel(shape.label, shape.labelX, shape.labelY, colours));
     },
+    // A junction dot: the visible answer to "is this a join or a crossing?". Filled in the line's own colour, so it
+    // reads as the line thickening where a branch meets it rather than as a new mark on the page.
+    junction: (shape, colours) => '<circle cx="' + n(shape.x) + '" cy="' + n(shape.y) + '" r="2.5" fill="' + colours[shape.colour] + '" />',
     title: (shape, colours) => {
         return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>';
     },

package/lib/render/trunk.js

@@ -0,0 +1,213 @@
+/**
+ * Fan-in trunks: a batch of arrows into one box from one side, drawn as one bundle.
+ *
+ * A node that four relations point at is drawn as four ports along its side and four lines converging on it. Each
+ * line is right on its own, and the picture is wrong: the bundle reads as a comb, and a reader counts ports to count
+ * arrows. The mature layered implementations solve this by merging the edges - ELK's *Merge Edges* with junction
+ * points, Graphviz's `concentrate` - and the shape they produce is one straight run outside the node, with a branch
+ * joining it wherever a separate edge arrives, and one shared stub into the node.
+ *
+ * This module decides only which ends may merge, where the shared run sits and which of the branches becomes the
+ * shared entry. It is pure geometry over boxes and ports, so the rules can be asserted without a canvas; the painter
+ * draws the answer.
+ *
+ * The rules, and why each one exists:
+ *
+ * - **One target, one entry side.** Edges that arrive from different sides are travelling in different directions,
+ *   and a trunk that changed axis would be two trunks.
+ * - **The exit faces the trunk.** A branch arrives at the trunk along the direction its own port leaves by, so the
+ *   trunk is outside the source as well as outside the target. An end that does not face the trunk is not merged: it
+ *   would have to turn before it got there, which is the bend the merge was supposed to save.
+ * - **Distinct sources, three or more.** Two merged edges read as one thick line. A pair of relations about one pair
+ *   has its own, older rule - they stay visibly apart - and that rule is the distinct-source rule here: two
+ *   statements about one pair share their source, so they can never both be a branch of one trunk.
+ * - **One arrow semantics.** A composition and an association are different statements about the relation; drawn on
+ *   one trunk they would be read as one statement. Ends that disagree on their arrow are not merged with each other.
+ * - **Clear of every box.** A trunk that crosses a box is the same defect as a route that does, and it is worse here
+ *   because it is drawn once for the whole bundle.
+ * - **One trunk per line.** Two groups whose trunks would be drawn on one line would read as one bundle between two
+ *   unrelated targets, so the later group is refused.
+ *
+ * The shared entry is the middle of the target's side. A bundle enters the target through one port, and a side that
+ * carries one port is centred on it, so the trunk runs to the middle and every branch joins it there: the branches
+ * that are not in the middle bend, which is the price of one entry that reads as centred rather than one that leans
+ * towards whichever branch happened to arrive straightest.
+ *
+ * Merging forces every branch but one to bend twice, so an unmerged drawing of `k` straight branches costs
+ * `2 * (n - k)` bends and a merged one costs `2 * (n - 1)`; the branch nearest the middle is the lead because it is
+ * the only one that can still reach the shared port without a horizontal leg, and on a target whose middle happens
+ * to fall on a branch's own line that branch is free, as before.
+ *
+ * What this module does not decide: the colour of a branch, the text of its label, and how a branch's own route
+ * reaches the trunk. Those belong to the painter.
+ */
+import { crossesBox, normalOf, ROUTE_STUB } from './route.js';
+/** The least a trunk is worth drawing for: two merged edges read as one thick line. */
+const TRUNK_MIN_EDGES = 3;
+/** Does this side move along the page's vertical axis? A run on it is horizontal. */
+function isVerticalSide(side) {
+    return side === 'top' || side === 'bottom';
+}
+/**
+ * Where the trunk outside a box sits.
+ *
+ * The same stub the router leaves before it turns, so the bundle starts exactly where a single route would have
+ * turned: about `ROUTE_STUB` outside the target, square to the side it enters.
+ */
+function trunkAt(box, side) {
+    if (side === 'top')
+        return box.y - ROUTE_STUB;
+    if (side === 'bottom')
+        return box.y + box.height + ROUTE_STUB;
+    if (side === 'left')
+        return box.x - ROUTE_STUB;
+    return box.x + box.width + ROUTE_STUB;
+}
+/** The coordinate a point takes along the side it sits on: where along that side the port is. */
+function alongSide(point, side) {
+    return isVerticalSide(side) ? point.x : point.y;
+}
+/** The coordinate a point takes on its side's outward normal: the axis a trunk outside that side moves on. */
+function alongNormal(point, side) {
+    return isVerticalSide(side) ? point.y : point.x;
+}
+/** Does the port on `side` travel toward the trunk at `at`? A branch only merges into a trunk it moves toward. */
+function facesTrunk(point, side, at) {
+    const normal = normalOf(side);
+    const outward = isVerticalSide(side) ? normal.y : normal.x;
+    return (at - alongNormal(point, side)) * outward > 0.5;
+}
+/** The group an edge end belongs to: its target, the side it enters by, and the arrow it means. */
+function keyOf(end) {
+    return end.to + '\u0000' + end.entry + '\u0000' + (end.arrow ?? '');
+}
+/** Is this axis-aligned segment clear of every box it does not attach to? */
+function clearSegment(boxes, skip, x1, y1, x2, y2) {
+    for (const box of boxes) {
+        if (skip.includes(box))
+            continue;
+        if (crossesBox(x1, y1, x2, y2, box))
+            return false;
+    }
+    return true;
+}
+/** Would this run lie on the line of an accepted trunk and share a stretch of it? */
+function onOneLine(group, side, at, low, high) {
+    if (isVerticalSide(group.side) !== isVerticalSide(side))
+        return false;
+    if (group.at !== at)
+        return false;
+    return Math.min(group.to, high) - Math.max(group.from, low) > 0.5;
+}
+/**
+ * Decide which ends merge, and where each accepted trunk runs.
+ *
+ * Ends that cannot merge are simply absent from the plan; the painter draws them as it always has. Groups are
+ * ordered by the first member the source wrote, so the answer does not depend on map iteration order.
+ */
+export function planTrunks(input) {
+    const groups = [];
+    const groupOf = new Map();
+    // Per edge first: the cheap rules. An end that fails one of them cannot join any group, so it never reaches the
+    // count that decides whether a group is worth drawing.
+    const buckets = new Map();
+    for (const end of input.ends) {
+        if (end.runY === undefined)
+            continue;
+        // The branch approaches the trunk along its own exit normal, so the two ends must move on one axis: a mixed pair
+        // would have to turn before it reached the trunk, which is the bend the merge exists to save.
+        if (isVerticalSide(end.exit) !== isVerticalSide(end.entry))
+            continue;
+        const source = input.boxOf(end.from);
+        const target = input.boxOf(end.to);
+        if (source === undefined || target === undefined)
+            continue;
+        if (source === target)
+            continue;
+        const exit = input.exitPortOf(end.index);
+        if (exit === undefined)
+            continue;
+        const at = trunkAt(target, end.entry);
+        if (!facesTrunk(exit, end.exit, at))
+            continue;
+        const candidate = { end, source, target, at, exit, branch: alongSide(exit, end.exit) };
+        const key = keyOf(end);
+        const list = buckets.get(key);
+        if (list === undefined)
+            buckets.set(key, [candidate]);
+        else
+            list.push(candidate);
+    }
+    for (const list of buckets.values()) {
+        // A pair of relations about one node is not two branches: the pair's own rule keeps them visibly apart, and both
+        // of them name the same source, so dropping the duplicated source drops the whole pair. Neither joins, and the
+        // group keeps the singles.
+        const bySource = new Map();
+        for (const candidate of list) {
+            const seen = bySource.get(candidate.end.from);
+            if (seen === undefined)
+                bySource.set(candidate.end.from, [candidate]);
+            else
+                seen.push(candidate);
+        }
+        const members = list.filter((candidate) => bySource.get(candidate.end.from).length === 1);
+        if (members.length < TRUNK_MIN_EDGES)
+            continue;
+        const target = members[0].target;
+        const side = members[0].end.entry;
+        const at = members[0].at;
+        // The shared entry is the middle of the target's side. A side that carries one port is centred on it, and a bundle
+        // enters through one port, so the run reaches the middle rather than whichever branch asked for the middle first.
+        const entryAlong = isVerticalSide(side) ? target.x + target.width / 2 : target.y + target.height / 2;
+        // The lead is the branch nearest that middle: the only member that can reach the shared port without a lateral
+        // leg. The source's order breaks a tie, so the answer does not depend on map iteration.
+        let lead = members[0];
+        for (const candidate of members) {
+            if (Math.abs(candidate.branch - entryAlong) < Math.abs(lead.branch - entryAlong) - 1e-9)
+                lead = candidate;
+        }
+        // The run: the whole stretch the branches and the one port span, so every branch joins a line that reaches it.
+        let low = entryAlong;
+        let high = entryAlong;
+        for (const candidate of members) {
+            low = Math.min(low, candidate.branch);
+            high = Math.max(high, candidate.branch);
+        }
+        // Clearance. The run is checked against every box but the target; each branch's own drop is checked against every
+        // box but its source and the target. The drop leaves a port square to its side, so those are the only two boxes it
+        // can legitimately touch.
+        const vertical = isVerticalSide(side);
+        const run = vertical ? [low, at, high, at] : [at, low, at, high];
+        if (!clearSegment(input.boxes, [target], run[0], run[1], run[2], run[3]))
+            continue;
+        let blocked = false;
+        for (const candidate of members) {
+            // The drop: from the branch's own port to the point where it meets the trunk, along its exit normal.
+            const drop = vertical
+                ? [candidate.branch, candidate.exit.y, candidate.branch, at]
+                : [candidate.exit.x, candidate.branch, at, candidate.branch];
+            if (!clearSegment(input.boxes, [candidate.source, target], drop[0], drop[1], drop[2], drop[3]))
+                blocked = true;
+        }
+        if (blocked)
+            continue;
+        // Two trunks on one line would be drawn as one bundle. The first group keeps the line; the later one travels alone.
+        if (groups.some((group) => onOneLine(group, side, at, low, high)))
+            continue;
+        const id = groups.length;
+        groups.push({
+            id,
+            target: members[0].end.to,
+            side,
+            at,
+            entryAlong,
+            from: low,
+            to: high,
+            lead: lead.end.index,
+            members: members.map((candidate) => candidate.end.index),
+        });
+        for (const candidate of members)
+            groupOf.set(candidate.end.index, id);
+    }
+    return { groups, groupOf };
+}

package/lib/types/render/paint.d.ts

@@ -11,20 +11,31 @@
  * route, not picked by comparing the boxes' centres: a route between two rows arrives vertically, so the endpoint
  * is snapped onto the top or bottom perimeter in the direction the route approaches. Where along that side it sits
  * follows the symbol: a rectangle spreads its ports along the side, a cylinder's top port sits on its cap curve, and a
- * diamond or a circle has four legal points and no side to spread along at all.
+ * diamond or a circle has four legal points and no side to spread along at all. A side that carries one port is
+ * centred on it, and a side that carries several spreads them symmetrically about the middle; the bend budget comes
+ * first, so a port that is the end of a straight run or of a lane keeps the coordinate its route asked for.
  *
  * A symbol with discrete points gives each of its edges a point of its own: the point whose outward normal faces the
  * box at the other end is the one that edge takes, and an edge only shares a point when all four are spoken for. A
  * node with a run on its side keeps doing what it always did, because there the ports are places on the run and not
  * points at all. Sharing is the fallback, not the rule: two labelled branches of a decision leave by two vertices.
  *
- * An edge's name is drawn on the edge, not beside it: it is anchored at the midpoint of the edge's longest straight
- * run, over a rectangle in the page colour that masks the line behind the text, and it slides along that run when
- * something is in the way. Labels are placed after every edge is drawn, because what a label has to avoid is the
- * whole picture.
+ * An edge's name is drawn on the edge, not beside it: it is anchored at the midpoint of one of the edge's own straight
+ * runs, over a rectangle in the page colour that masks the line behind the text, and it slides along that run when
+ * something is in the way. It tries every run - the longest first - because on a dense drawing the longest one can be
+ * crowded for its whole length while a shorter run of the same edge is clear. A label that can clear nothing still
+ * stays on its edge, takes the place with the fewest collisions, and records what it could not avoid. Labels are
+ * placed after every edge is drawn, because what a label has to avoid is the whole picture.
+ *
+ * Every route is checked before it is drawn, and the assembled drawing is checked once more: a segment may touch no
+ * box except the two the edge terminates at. A route is a proposal - a channel run, a lane, a trunk branch, a wrapped
+ * column's sideways read - and any proposal that would cross a box is handed to the router instead. When even the
+ * router cannot clear a box, the failure is reported on the canvas rather than hidden: a drawing that says which edge
+ * could not be routed is worth more than one that quietly draws it through a box.
  *
  * Pure: a diagram in, shapes out, every decision assertable.
  */
+import { type Box } from './place.js';
 import { type ColourRole, type Palette, type PaletteOptions } from './palette.js';
 import { type Diagram, type DiagramNode, type EdgeArrow, type NodeShape } from './model.js';
 export interface Point {
@@ -45,6 +56,22 @@ export interface BoxShape {
     colour: ColourRole;
     initial: boolean;
 }
+/**
+ * Why a label sits where it does.
+ *
+ * A clear label records `collisions: 0` and the run it chose. A label that could clear nothing records the collisions
+ * it could not avoid, so a reader of the drawing (or a test) can tell a crowded drawing from a placement bug. The
+ * label never leaves its own edge to earn any of these numbers.
+ */
+export interface LabelPlacement {
+    /** The straight run it sits on, 0 being the edge's longest. */
+    run: number;
+    /** Everything its mask overlaps: the other labels, boxes and edges it would have had to move off its line to clear. */
+    collisions: number;
+    boxes: number;
+    labels: number;
+    edges: number;
+}
 export interface LinkShape {
     kind: 'link';
     x1: number;
@@ -60,6 +87,8 @@ export interface LinkShape {
     dashed?: boolean;
     /** The arrow the source edge stated. Undefined means the plain arrow every edge has been drawn with. */
     arrow?: EdgeArrow;
+    /** Why the label sits where it does. Undefined on an edge with no label. */
+    labelPlacement?: LabelPlacement;
 }
 export interface PathShape {
     kind: 'path';
@@ -71,6 +100,22 @@ export interface PathShape {
     colour: ColourRole;
     dashed?: boolean;
     arrow?: EdgeArrow;
+    /** Why the label sits where it does. Undefined on an edge with no label. */
+    labelPlacement?: LabelPlacement;
+}
+/**
+ * A junction dot: the place one branch of a merged bundle meets the bundle's trunk.
+ *
+ * The dot is not decoration. Two lines that meet at a right angle read as a crossing unless one of them is marked as
+ * joining the other, and a bundle whose branches are not marked reads as a set of broken lines rather than a merge.
+ */
+export interface JunctionShape {
+    kind: 'junction';
+    x: number;
+    y: number;
+    colour: ColourRole;
+    /** The trunk the dot belongs to: one dot per branch, one trunk id per bundle. */
+    trunk: number;
 }
 /** A boundary around several states: a package, a layer, a subgraph. */
 export interface GroupShape {
@@ -98,11 +143,33 @@ export interface TitleShape {
     text: string;
     colour: ColourRole;
 }
-export type Shape = GroupShape | BoxShape | LinkShape | PathShape | CaptionShape | TitleShape;
+export type Shape = GroupShape | BoxShape | LinkShape | PathShape | JunctionShape | CaptionShape | TitleShape;
+/** One segment of a drawn route that could not be kept out of a box it does not terminate at. */
+export interface RoutingFailure {
+    /** The edge's index in the diagram. */
+    edge: number;
+    from: string;
+    to: string;
+    /** The box the segment passes through. */
+    box: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
 export interface Canvas {
     width: number;
     height: number;
     shapes: Shape[];
+    /**
+     * Every place a drawn segment still passes through a box it does not terminate at, after every route was checked.
+     *
+     * A drawing should carry none. The field exists for the case where no stage and no router could find a way around:
+     * a route that cannot be drawn honestly is reported here rather than silently drawn through a box.
+     */
+    routingFailures: RoutingFailure[];
+    /** How many edge labels could not be placed clear of every box, label and other edge. */
+    labelCollisions: number;
 }
 /**
  * How far apart two edges that join the same pair are drawn.
@@ -120,8 +187,55 @@ export declare function roleOfNode(node: DiagramNode): ColourRole;
  * place, and the writer draws the rectangle that was reserved. A label with two sizes is a label half masked.
  */
 export declare const LABEL_HEIGHT = 12;
+/** A straight piece of an edge, as the collision test needs it. */
+interface Segment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Where a label sits: the point it is centred on, and the rectangle its mask covers. */
+interface LabelSpot {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The point an edge's label is drawn at.
+ *
+ * A label is not furniture parked beside the line: it names the transition, so it sits on the line - anchored on one
+ * of its own straight runs - and the writer masks the stretch of line it covers. Text beside a line can be read as
+ * belonging to whatever it happens to sit next to; text that interrupts its own line reads as part of it.
+ *
+ * The anchor then has to be earned. A mask over a box hides a border, over another label it makes both unreadable,
+ * and over a third edge's line it hides that line. So the label walks along a run in small steps, in both directions
+ * and bounded so its rectangle stays on that run, and takes the first place that is clear. It tries the longest run
+ * first and then the shorter ones: on a dense drawing the longest run can be crowded for its whole length while a
+ * shorter run of the same edge is empty, and a label that gives up after one run leaves the drawing with a collision
+ * it did not have to accept.
+ *
+ * When no run offers a clear place, the label takes the place with the fewest collisions - boxes and other labels
+ * first, because text over a border hides the border and text over text is unreadable, then other edges, which a mask
+ * merely interrupts. It never leaves its own edge: a label moved onto a neighbouring edge is a label that names the
+ * wrong thing. The choice is returned with the label, so a crowded drawing can be told from a placement bug.
+ *
+ * Exported because the choice is pure and worth asserting without a layout: a test can hand it one polyline, one box
+ * and one other route, and read which run it took and what it could not clear.
+ */
+export declare function placeLabel(label: string, points: Point[], boxes: Iterable<Box>, placed: LabelSpot[], otherRoutes: Segment[][]): LabelPlacement & LabelSpot;
+/**
+ * The boxes a polyline passes through other than the two it terminates at.
+ *
+ * This is the drawing's one clearance rule, and it is deliberately written once: a channel run, a lane, a trunk
+ * branch, a wrapped column's sideways step and the router's fallback all have to obey the same test. A box is skipped
+ * only when it is one of the edge's own two ends, so a port that sits inside its own symbol (a cylinder's cap apex)
+ * is allowed and a segment that ends inside somebody else's box is not.
+ */
+export declare function boxesCrossedBy(points: Point[], from: Box, to: Box, boxes: Iterable<Box>): Box[];
 export declare function paintWith(diagram: Diagram, overrides?: Partial<Palette>, options?: PaletteOptions): {
     canvas: Canvas;
     colours: Palette;
 };
 export declare function paint(diagram: Diagram, overrides?: Partial<Palette>): Canvas;
+export {};

package/lib/types/render/place.d.ts

@@ -41,9 +41,14 @@ export interface Placement {
     groupRects: Map<string, Box>;
     width: number;
     lanes: Map<number, Lane>;
-    /** The height of the one horizontal run an edge between two adjacent rows needs. */
-    runs: Map<number, number>;
-    /** Edges whose two ends ended up in different wrapped columns: they are read across, not down. */
+    /**
+     * The height of the one horizontal run an edge between two adjacent rows needs.
+     *
+     * A run is measured between two rows of the level that produced it. When a row is a boundary, that strip is the space
+     * outside the boundary while the painter draws the boxes inside it, so the run is a proposal rather than a fact: the
+     * painter clears it against every box and hands the edge to the router when a leg would cross one.
+     */
+    runs: Map<number, number>; /** Edges whose two ends ended up in different wrapped columns: they are read across, not down. */
     across: Set<number>;
 }
 /** Geometry constants in one place: a container with different proportions changes these, not the rules. */

package/lib/types/render/trunk.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Fan-in trunks: a batch of arrows into one box from one side, drawn as one bundle.
+ *
+ * A node that four relations point at is drawn as four ports along its side and four lines converging on it. Each
+ * line is right on its own, and the picture is wrong: the bundle reads as a comb, and a reader counts ports to count
+ * arrows. The mature layered implementations solve this by merging the edges - ELK's *Merge Edges* with junction
+ * points, Graphviz's `concentrate` - and the shape they produce is one straight run outside the node, with a branch
+ * joining it wherever a separate edge arrives, and one shared stub into the node.
+ *
+ * This module decides only which ends may merge, where the shared run sits and which of the branches becomes the
+ * shared entry. It is pure geometry over boxes and ports, so the rules can be asserted without a canvas; the painter
+ * draws the answer.
+ *
+ * The rules, and why each one exists:
+ *
+ * - **One target, one entry side.** Edges that arrive from different sides are travelling in different directions,
+ *   and a trunk that changed axis would be two trunks.
+ * - **The exit faces the trunk.** A branch arrives at the trunk along the direction its own port leaves by, so the
+ *   trunk is outside the source as well as outside the target. An end that does not face the trunk is not merged: it
+ *   would have to turn before it got there, which is the bend the merge was supposed to save.
+ * - **Distinct sources, three or more.** Two merged edges read as one thick line. A pair of relations about one pair
+ *   has its own, older rule - they stay visibly apart - and that rule is the distinct-source rule here: two
+ *   statements about one pair share their source, so they can never both be a branch of one trunk.
+ * - **One arrow semantics.** A composition and an association are different statements about the relation; drawn on
+ *   one trunk they would be read as one statement. Ends that disagree on their arrow are not merged with each other.
+ * - **Clear of every box.** A trunk that crosses a box is the same defect as a route that does, and it is worse here
+ *   because it is drawn once for the whole bundle.
+ * - **One trunk per line.** Two groups whose trunks would be drawn on one line would read as one bundle between two
+ *   unrelated targets, so the later group is refused.
+ *
+ * The shared entry is the middle of the target's side. A bundle enters the target through one port, and a side that
+ * carries one port is centred on it, so the trunk runs to the middle and every branch joins it there: the branches
+ * that are not in the middle bend, which is the price of one entry that reads as centred rather than one that leans
+ * towards whichever branch happened to arrive straightest.
+ *
+ * Merging forces every branch but one to bend twice, so an unmerged drawing of `k` straight branches costs
+ * `2 * (n - k)` bends and a merged one costs `2 * (n - 1)`; the branch nearest the middle is the lead because it is
+ * the only one that can still reach the shared port without a horizontal leg, and on a target whose middle happens
+ * to fall on a branch's own line that branch is free, as before.
+ *
+ * What this module does not decide: the colour of a branch, the text of its label, and how a branch's own route
+ * reaches the trunk. Those belong to the painter.
+ */
+import { type Side } from './route.js';
+import type { Box } from './place.js';
+import type { EdgeArrow } from './model.js';
+/** One edge end, as the trunk planner reads it. */
+export interface TrunkEnd {
+    /** The edge's index in the diagram, so the painter can key its answer back to the edge. */
+    index: number;
+    from: string;
+    to: string;
+    /** The side the edge's port leaves by, and the side it arrives at, as the port stage decided them. */
+    exit: Side;
+    entry: Side;
+    /** The arrow the notation stated. Ends merge only when they agree on it; two unset arrows agree. */
+    arrow?: EdgeArrow;
+    /** The height of the run the channel stage gave the edge. An edge without one is not drawn by a run. */
+    runY?: number;
+}
+/** A port in the drawing's coordinates. Structural, so this module needs no import from the painter. */
+export interface TrunkPoint {
+    x: number;
+    y: number;
+}
+export interface TrunkInput {
+    ends: TrunkEnd[];
+    /** The box of a node, and nothing else: a boundary is not a trunk target, because an arrow points past it. */
+    boxOf: (id: string) => Box | undefined;
+    /** Every box the trunk and its branches must keep clear of. A boundary is not an obstacle, as on any route. */
+    boxes: Iterable<Box>;
+    /** Where an edge's own exit port sits, when it has one. The branch joins the trunk at that port's coordinate. */
+    exitPortOf: (index: number) => TrunkPoint | undefined;
+}
+/** One accepted bundle: what it merges, where its run sits, and which branch the target is entered by. */
+export interface TrunkGroup {
+    /** Position in `groups`, which is also the id a junction dot carries. */
+    id: number;
+    target: string;
+    side: Side;
+    /** The coordinate of the trunk line: a y when the trunk runs across, an x when it runs down. */
+    at: number;
+    /** The coordinate of the one port the bundle enters by: the middle of the target's side. */
+    entryAlong: number;
+    /** The two ends of the run, along the axis it moves on. A branch joins it between them. */
+    from: number;
+    to: number;
+    /** The member whose own exit is nearest the shared entry, and therefore the only branch that may still be a straight drop. */
+    lead: number;
+    /** The edges in the bundle, in the order the source wrote them. */
+    members: number[];
+}
+export interface TrunkPlan {
+    groups: TrunkGroup[];
+    /** By edge index: the id of the group it joined. An edge not in here travels alone. */
+    groupOf: Map<number, number>;
+}
+/**
+ * Decide which ends merge, and where each accepted trunk runs.
+ *
+ * Ends that cannot merge are simply absent from the plan; the painter draws them as it always has. Groups are
+ * ordered by the first member the source wrote, so the answer does not depend on map iteration order.
+ */
+export declare function planTrunks(input: TrunkInput): TrunkPlan;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-everything",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Modeling abstraction, architecture visualisation and automated review for designs and code, including a refactoring harness: draw a Mermaid or PlantUML source and measure its structure, executable verification of machines and protocols with before/after regression, data-model and migration checks, concurrency claim routing, export to external checkers, dependency-graph review, and report diffing. Native plugin for DeepSeek Harness (dsh).",
   "type": "module",
   "main": "lib/index.js",

package/skills/model-everything-diagram/SKILL.md

@@ -22,6 +22,7 @@ question is what the picture shows.
 | "what changed between these two diagrams", "did this package move" | `diagram_diff`: boundaries added, removed, renamed or re-parented, and nodes that changed owner |
 | A source in a notation the plugin does not draw | Refused with the line number; `diagram_render` still draws everything else and reports what it skipped |
 | An edge whose straight line would cross a component | Routed around it on a sparse grid (candidate lines from each box edge, A* with a bend penalty), so a line never reads as a connection that is not there |
+| A batch of arrows into one component from the same side | Drawn as one **bundle**: a straight run outside the target, one shared entry, and a junction dot where each branch joins. Only ends agreeing on target, entry side and arrow meaning merge, from distinct sources, and three is the least that does - so a decision's two branches stay two lines and two relations between one pair stay apart |
 | A label with a hard line break, or one too long for its box | `<br>`, `<br/>` and a real newline end a line; anything longer than the drawing's line width wraps. The box is sized from the lines it draws. An edge label is drawn on its edge - centred on the middle of the edge's longest straight run, over a mask in the page colour - and slides along that run to clear a box, another label or another edge's line |
 | A diagram already in a file, to link from a document | `diagram_render` with `out`, then link the SVG |