dsh-model-everything 0.5.1 → 0.6.0

package/lib/types/annotation.d.ts

@@ -0,0 +1,128 @@
+/**
+ * An annotation: the reader points at a node in a drawing and says something about it.
+ *
+ * The note has to reach the session as an ordinary message, because the session log is the only record a
+ * replay, a fork or a resumed agent can rebuild from. Two transports can carry it, and they consume the
+ * same text: a host command that turns the note into a follow-up (planned; the interface is
+ * `annotationMessage`), and the composer, which hands the text to the reader's own input box (works today).
+ *
+ * Splitting the text from the transport is what keeps the two interchangeable, and what lets this module be
+ * tested without a browser.
+ */
+/** What the reader said, and where. */
+export interface Annotation {
+    /** The node's id, as it appears in the markup the renderer wrote. */
+    nodeId: string;
+    /** The node's label, when it differs from the id: a reader points at words, not at identifiers. */
+    label?: string;
+    /** The note itself. Empty is meaningful: the reader marked the node and said nothing. */
+    note?: string;
+    /** Which drawing, when the reader is looking at more than one. A single source line is enough. */
+    caption?: string;
+}
+/**
+ * The text that travels to the session: what was marked, and what was said, and nothing invented.
+ *
+ * A blank note is not dropped - it says the node was marked - because "the reader pointed here" and "the
+ * reader pointed here and said this" are different messages, and only one of them survives a silent trim.
+ */
+/**
+ * The text that travels to the session: what was marked, what was said, and nothing invented.
+ *
+ * One message for N notes, with a fixed opening so both the reader and the model know what they are looking
+ * at: a note arrives without the picture, so the block says what it is about, which drawing, and that every
+ * numbered item is a separate answer. The shape follows the annotation plugin this harness already ships -
+ * an opening sentence, numbered items, a question line - and it stays English: this is protocol between
+ * reader and model, not interface chrome that follows the page's language.
+ *
+ * Plain lines, not a markdown quote: the reader's bubble is rendered as one text node, so a quote never
+ * becomes a quote there - it would only show its own `>` characters. The bubble is folded afterwards.
+ * A blank note is not dropped: 'marked, no note' and 'marked with this note' are different messages.
+ */
+export declare function annotationBlock(annotations: Annotation[]): string;
+/** One annotation, in the same block shape: a caller with a single note should not get a second format. */
+export declare function annotationMessage(annotation: Annotation): string;
+/** The parts of the page this module touches, so the client bundle needs no DOM lib and a test can fake them. */
+export interface ElementLike {
+    value?: unknown;
+    querySelector?: (selector: string) => unknown;
+    textContent?: unknown;
+    focus?: () => void;
+    dispatchEvent?: (event: unknown) => boolean;
+    getAttribute?: (name: string) => string | null;
+    tagName?: unknown;
+}
+export interface DocumentLike {
+    querySelector: (selector: string) => unknown;
+    querySelectorAll?: (selector: string) => ArrayLike<unknown>;
+}
+export declare function findComposer(doc: DocumentLike | undefined): ElementLike | undefined;
+/**
+ * What the page has, for a status line: a probe with no console needs one place to report from.
+ *
+ * Counts only. A reader's draft is never read into the report.
+ */
+export declare function pageCensus(doc: DocumentLike | undefined): string;
+/** What a write did, so the caller can say something true instead of something hopeful. */
+export type Placed = 'filled' | 'no-composer';
+/**
+ * Add the text to the composer, above whatever the reader has already typed.
+ *
+ * Appending rather than replacing is the only behavior that cannot lose work: a reader who was halfway
+ * through a message and clicked an annotation should find both halves in the box, not the annotation alone.
+ */
+export declare function fillComposer(doc: DocumentLike | undefined, text: string): Placed;
+/** Whether the page can take a Return key for the composer at all, so a button may promise it. */
+export declare function submitComposer(doc: DocumentLike | undefined): boolean;
+/**
+ * One note, two actions.
+ *
+ * Returns the sentence to show the reader: `sent` and `the box was not there` are different outcomes, and a
+ * button that reports the wrong one is worse than no button. The text is appended above a half-written draft,
+ * never in place of it.
+ */
+export declare function pushNote(document: DocumentLike | undefined, picked: {
+    id: string;
+} | null, note: string, caption: string, submit: boolean): string;
+/**
+ * The session a page is showing, read from its own address.
+ *
+ * The client services expose no "current session", and a slot's props are not guaranteed to carry one, but the
+ * page has to name the session in its URL to survive a reload - so the address is the one source that is always
+ * there. Both spellings are accepted: the `session-<uuid>` id this Harness mints and a bare uuid.
+ */
+export declare function sessionFromLocation(location: {
+    pathname?: string;
+    search?: string;
+    hash?: string;
+} | undefined): string | undefined;
+/**
+ * Put a whole annotation block in the composer, and say what happened.
+ *
+ * The block is one message for N notes: the model is told to answer each item, and the reader's input box sees
+ * the structured text rather than N raw fragments. The same failure vocabulary as a single note.
+ */
+export declare function pushBlock(document: DocumentLike | undefined, annotations: Annotation[], caption: string, submit: boolean): string;
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Where the reader's input box is, for a widget that has to sit right above it. */
+export declare function composerRect(doc: DocumentLike | undefined): Rect | undefined;
+/**
+ * Put the block above what the reader has already typed, and say what happened.
+ *
+ * Above, because the annotations introduce the message: the reader's own words are the point, and a block
+ * appended after them reads as an afterthought. A rich editor has no portable way to insert at the start, so
+ * it takes the same path as an empty box - the block becomes the message and the reader's text follows it.
+ */
+export declare function prependBlock(document: DocumentLike | undefined, annotations: Annotation[], caption: string): string;
+/**
+ * The block without its question line, for a message that has no question.
+ *
+ * The line is an invitation for the reader's own words; with the box empty it is the last thing the bubble shows
+ * and the only thing a chip would be folded away from, so it goes.
+ */
+export declare function withoutEmptyQuestion(block: string): string;

package/lib/types/client.d.ts

@@ -12,9 +12,11 @@
  * compiled output in `window.__ModuleLoader__.load(...)`, which is the loader contract itself.
  */
 import { type Palette, type PaletteMode } from './render/palette.js';
+import { type DocumentLike } from './annotation.js';
 export interface ReactLike {
     createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
-    useState?: <T>(initial: T) => [T, (next: T) => void];
+    useState?: <T>(initial: T) => [T, (next: T | ((previous: T) => T)) => void];
+    useEffect?: (effect: () => void | (() => void), deps?: ReadonlyArray<unknown>) => void;
 }
 export interface SlotContext {
     slots: {
@@ -29,7 +31,6 @@ export interface PluginShape {
     /** The whiteboard mount, with its scheduler injectable. `apply` calls this with the default. */
     mount: (ctx: SlotContext, options?: MountOptions) => unknown;
 }
-/** A settled tool call, as the host hands it to a view. */
 export interface ToolCallProps {
     phase?: string;
     toolName?: string;
@@ -53,12 +54,93 @@ export declare const WHITEBOARD_ID = "model-everything-diagram";
 /** What the whiteboard opens with: a diagram the reader can edit rather than an empty box. */
 export declare const WHITEBOARD_SAMPLE: string;
 /**
- * The view for one tool name.
+ * The card for a drawing: the source the call carried, drawn by the renderer that wrote the file.
  *
- * The drawing is emitted as markup, so React receives it through `dangerouslySetInnerHTML`. That is safe
- * only because the writer escapes every value that came from a report or a model, which the render suite
- * pins with an injection case.
+ * Drawing it here rather than replaying the SVG means the card and the file are one picture from one
+ * engine, and it costs the result nothing. Lines the renderer refused are listed under the drawing: a
+ * card that hid them would show a picture that is missing something, which is the failure the tool
+ * exists to prevent.
  */
+/** A create-element function with this package's calling convention, so a shared builder fits both seats. */
+type H = (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+/** What an annotation editor shows, shared by the two surfaces that offer one. */
+export interface AnnotationState {
+    picked: {
+        id: string;
+    } | null;
+    note: string;
+    pending: Array<{
+        nodeId: string;
+        note: string;
+    }>;
+    status: string;
+    /** Whether the pending list is expanded under the count. */
+    open?: boolean;
+    /** Where the editor sits, in the drawing's own coordinates: beside the node the reader picked. */
+    anchor?: {
+        left: number;
+        top: number;
+    };
+    /** The correction the dock applied after measuring where the chip actually landed. */
+    dockFix?: {
+        dx: number;
+        dy: number;
+    };
+}
+export interface AnnotationActions {
+    onNote: (value: string) => void;
+    onAdd: () => void;
+    onAddAndSend: () => void;
+    onSend: () => void;
+    onClear: () => void;
+    onCancel: () => void;
+    onToggle: () => void;
+    onRemove: (index: number) => void;
+}
+/**
+ * The annotation surface: a floating editor over the drawing, and a count of what is waiting.
+ *
+ * Floating rather than inline, because the reader is looking at a picture and the editor must not move it.
+ * The notes stay in a list until one message is composed from them: the reader's input box is theirs, and N raw
+ * fragments in it would be exactly the mess this feature is meant to avoid. Colours come from the host's tokens,
+ * so light and dark themes need no separate code.
+ */
+export declare function annotationPanel(h: H, state: AnnotationState, actions: AnnotationActions, options?: {
+    floating?: boolean;
+    document?: DocumentLike;
+    dockFix?: {
+        dx: number;
+        dy: number;
+    };
+    dockChip?: boolean;
+}): unknown;
+/** Remember what would leave with the next message, and start watching for that message. */
+export declare function setPendingBlock(text: string): void;
+/**
+ * The dock, as a layer on `document.body`.
+ *
+ * A `position: fixed` node still positions against the nearest transformed ancestor, and the composer sits
+ * inside one - which is why every coordinate this plugin computed landed inside the box. The shipped
+ * annotation plugin sidesteps it the same way: its chip is a body-level layer, so fixed means the viewport.
+ * Size and place come from the composer card's own rectangle, measured after every layout change.
+ */
+interface DockHandlers {
+    onToggle: () => void;
+    onSend: () => void;
+    onRemove: (index: number) => void;
+}
+/** Keep the docked count in step with the pending list. Called from a render path, so it cannot throw. */
+export declare function updateDockLayer(items: Array<{
+    nodeId: string;
+    note: string;
+}>, open: boolean, handlers: DockHandlers): void;
+/**
+ * Tell this module when a message leaves, by watching the one signal the host gives: the draft empties.
+ *
+ * A note that was committed is in the draft, so after the send there is nothing left to keep - and a chip still
+ * counting a note that has already gone out is the plugin lying about its own state.
+ */
+export declare function onMessageSent(listener: () => void): () => void;
 export declare function viewFor(React: ReactLike, overrides?: Partial<Palette>): (props: ToolCallProps) => unknown;
 /**
  * The whiteboard: paste a diagram, get a drawing, zoom it.
@@ -81,3 +163,4 @@ export interface MountOptions {
  */
 export declare function mountWhiteboard(React: ReactLike, ctx: SlotContext, options?: MountOptions): unknown;
 export default function factory(require: (name: string) => unknown): PluginShape;
+export {};

package/lib/types/diagram.d.ts

@@ -31,4 +31,11 @@ export interface ComponentContext {
     };
 }
 export declare function apply(ctx: ComponentContext, config: Config): void;
+/**
+ * Offer an annotation as a session command, so a page can send one without a composer.
+ *
+ * Optional on purpose, and failure-tolerant on purpose: a host without the commands service keeps the
+ * composer path, and a registration that throws must not take the drawing tools down with it.
+ */
+export declare function registerAnnotateCommand(ctx: unknown): void;
 export declare const inject: string[];

package/lib/types/gate.d.ts

@@ -10,13 +10,15 @@
  *
  * Why it is a separate row. The plugin's doctrine is that a capability is discoverable
  * through its own tool description or skill text. Injection departs from that, so it is
- * opt-in and mounted as its own component: install it, disable it, or never enable it,
- * without touching the tools or the skills. `enabled` is a live switch, so the Web Plugins
- * page flips it inside a running host.
+ * mounted as its own component: the bundle's patch enables it, and the row can be turned off
+ * or removed without touching the tools or the skills. `enabled` is a live switch, so the Web
+ * Plugins page flips it inside a running host.
  *
- * Why it is off by default. It costs tokens in every session that turns it on, to fix a
- * problem text-only routing was measured not to have once the session engages. A deployment
- * that wants it says so; the default pays nothing.
+ * Why the bundle turns it on. Measured: a session that never decides to load a skill is never
+ * routed, and the catalog line is cut at 500 characters, so a domain the request names can be
+ * invisible at the moment of choosing. The cost is a fixed message in every session, which is
+ * why the switch is live and documented: turn it off where the bundle's default is wrong. The
+ * component's own `enabled` script default is off, so a bare `app.add(gate)` injects nothing.
  *
  * What it does not do. It routes; it checks nothing. It cannot make a skill load, and it
  * does not restate the doctrine - the skill bodies carry that, and duplicating them here

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 {
@@ -33,6 +44,8 @@ export interface Point {
 }
 export interface BoxShape {
     kind: 'box';
+    /** Which node this box is. It travels into the markup, so a reader can target one node by delegation. */
+    id: string;
     x: number;
     y: number;
     width: number;
@@ -45,6 +58,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 +89,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 +102,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 +145,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 +189,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;