dsh-model-everything 0.4.1 → 0.5.1

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

@@ -0,0 +1,73 @@
+/**
+ * The diagram a renderer draws, in the notation it came from being nobody's business.
+ *
+ * Every source - a verification report, a Mermaid file, a PlantUML component diagram, a dependency scan -
+ * is reduced to this one shape before anything is laid out. A renderer that understood notations would have
+ * to be changed for each of them; a renderer that understands this does not.
+ *
+ * Pure data, no functions: a model can be serialised, compared and asserted.
+ */
+/** What a node is, as far as colour is concerned. */
+export type NodeRole = 'normal' | 'error' | 'warning' | 'muted';
+/** The symbol a node is drawn as. UML and Mermaid both distinguish these; the notation decides which one applies. */
+export type NodeShape = 'rect' | 'diamond' | 'cylinder' | 'stadium' | 'circle' | 'subroutine' | 'hexagon';
+export interface DiagramNode {
+    id: string;
+    /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
+    label?: string;
+    role: NodeRole;
+    /** Defaults to a rectangle: a node the source gave no shape has no shape to draw. */
+    shape?: NodeShape;
+}
+/**
+ * What an edge's head means, when the notation distinguished it.
+ *
+ * The painter draws the meaning: a plain arrow for an association, a hollow triangle for a generalisation or a
+ * realisation, a filled diamond at the source for a composition, a hollow one for an aggregation, and a dashed
+ * line for the two dependency-flavoured kinds.
+ */
+export type EdgeArrow = 'association' | 'dependency' | 'generalization' | 'realization' | 'composition' | 'aggregation';
+export interface DiagramEdge {
+    from: string;
+    to: string;
+    label: string;
+    /** A dashed edge, for notations that distinguish one. */
+    dashed?: boolean;
+    /**
+     * The arrow the notation stated. Absent means the plain arrow every edge has been drawn with: a Mermaid edge
+     * states no arrow type, so it carries no field and is drawn exactly as before.
+     */
+    arrow?: EdgeArrow;
+}
+export interface DiagramGroup {
+    id: string;
+    label: string;
+    /**
+     * The nodes declared directly inside it: a group is a box around boxes, and its own members are the ones a
+     * source named there. A node inside a nested group is that group's member, not this one's.
+     */
+    members: string[];
+    /**
+     * The group that contains this one, when the source said so.
+     *
+     * Only a parser can know this - nesting is a property of where the text put the boundary - so the layout does
+     * not guess it. Left absent, the painter falls back to inferring containment from member sets, which is the
+     * best a hand-written model can offer.
+     */
+    parent?: string;
+}
+export interface Diagram {
+    kind: 'machine' | 'graph' | 'none';
+    /** The state the machine starts in, when the source declared one. */
+    init?: string;
+    title: string;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    groups?: DiagramGroup[];
+    /** One line under the drawing: what was decided, in words the drawing cannot carry. */
+    caption: string;
+}
+/** An empty drawing, for a source that produced no nodes. */
+export declare function emptyDiagram(title: string, caption: string): Diagram;
+/** The label to draw for a node: its own label when the notation gave one, else its id. */
+export declare function labelOf(node: DiagramNode): string;

package/lib/types/render/network-simplex.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimum-length ranking: the network simplex of Gansner, Koutsofios, North and Vo (1993).
+ *
+ * The ranking problem: give every node a layer such that each edge spans at least its minimum length, and make the
+ * total of all the slack - the layers every edge spans beyond its minimum - as small as it can be. Slack is what a
+ * reader pays for: an edge that spans three layers has to be drawn through two of them.
+ *
+ * Longest paths are one feasible answer and they are not the best one. They put every node as high as it can
+ * possibly go, which leaves a node whose edges leave it with nothing to do above the boxes it points at. The best
+ * answer is the solution of a linear program, and network simplex is how the mature layering implementations solve
+ * it: hold a *feasible tree* - a spanning tree every edge of which is tight - and a ranking that tightens it, attach
+ * a *cut value* to each tree edge (the weight flowing one way across that cut minus the weight flowing the other),
+ * and while some tree edge has a negative cut value, take it out, let the cheapest edge across its cut in, and move
+ * the ranks so the new edge is tight. The cut value is the rate at which the total length falls as the tree edge is
+ * left out, so every exchange shortens the drawing, and a tree with no negative cut value is the optimum: no single
+ * exchange is left that would shorten it, and for this program that is the definition of optimal.
+ *
+ * Three things are done differently from the paper, each because this graph is not the paper's graph:
+ *
+ * - **Components are solved one at a time.** The ranking is translation invariant, so two components that share no
+ *   edge can be laid out apart from each other; each is solved on its own and its top row is then numbered zero.
+ * - **A node may be pinned to the top.** A state machine has an initial state and a reader expects it first, so the
+ *   stage can name one node that must be on the topmost layer: a zero-length, zero-weight constraint edge runs from
+ *   it to every other node of its component (`rank(v) >= rank(pinned)`), and the ranking is minimised subject to that.
+ *   The constraint costs length when the free optimum would have put the pinned node below another source, and that
+ *   price is what "the initial state is first" means.
+ * - **The iteration is capped.** A degenerate exchange (one that moves nothing) is legal and in theory can go round
+ *   in circles. The cap turns that into a ranking that is feasible and no worse than where it started.
+ *
+ * Pure, and generic in the ranking program: no ids, no sizes, no drawing.
+ */
+/** One edge of the ranking program: two layers, how far apart they may be, and what one layer of slack costs. */
+export interface RankEdge {
+    from: number;
+    to: number;
+    /** The least number of layers this edge may span. One for an edge that is drawn, zero for a constraint. */
+    minLength: number;
+    /** What one extra layer on this edge costs. Zero for a constraint, which must hold but is not worth shortening. */
+    weight: number;
+}
+export interface RankProblem {
+    count: number;
+    edges: RankEdge[];
+    /** A feasible ranking to start from: it already gives every edge at least its minimum length. */
+    start: number[];
+    /**
+     * The node that has to sit on the topmost layer, when the source named one.
+     *
+     * It has to be a node nothing points at, or no ranking can hold it at the top - a predecessor forces it down. The
+     * constraint is dropped when the start ranking cannot satisfy it.
+     */
+    pinned?: number;
+}
+export declare function minimumLength(problem: RankProblem): number[];

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

@@ -0,0 +1,27 @@
+/**
+ * Ordering: the left-to-right order of each layer.
+ *
+ * The layer a box is in is fixed by now; the only freedom left is the order inside each layer, and that order decides
+ * how many edges cross. A crossing is counted on a pair of adjacent layers: two edges between the same two layers
+ * cross when their end points are in opposite order on the top and the bottom.
+ *
+ * The method is the one every layered layout uses. A median sweep takes each layer in turn and sorts it by the median
+ * position of its neighbours in the layer just visited - down the drawing, then up. A down sweep alone settles each
+ * layer against the one above it and can be undone by the next; alternating is what makes the passes converge.
+ *
+ * The median is a good guess, not a search. Greedy switch is the search: try swapping two neighbours in a layer, keep
+ * the swap if the total crossing count falls, and stop when a whole pass finds nothing. That is where a crossing the
+ * median cannot see gets removed.
+ *
+ * Pure: layers of ids in, layers of ids out, plus the crossing count that justified them.
+ */
+import type { Chain } from './dummy.js';
+export interface Ordered {
+    /** The same layers, each in its final order. */
+    layers: string[][];
+    /** The number of crossings between adjacent layers left by the ordering. */
+    crossings: number;
+}
+/** How many pairs of edges between adjacent layers cross. */
+export declare function countCrossings(layers: string[][], chains: Chain[]): number;
+export declare function order(seedLayers: string[][], chains: Chain[], seed?: Map<string, number>): Ordered;

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

@@ -0,0 +1,127 @@
+/**
+ * Geometry: what a diagram turns into, in coordinates.
+ *
+ * A drawing has to survive three containers - inline in a conversation, full-screen, and a persistent
+ * sidebar tab - so nothing here knows about pixel size. It emits a content-sized canvas and lets the
+ * container scale it: the same numbers serve a 360px card and a 1200px whiteboard.
+ *
+ * The drawing is placed by the layered pipeline (`place.ts`), which also says which lane a long edge reserved.
+ * Edges are drawn from where the boxes ended up, in two ways only: a long edge follows its lane as one polyline,
+ * and everything else goes through the orthogonal router. Which side of a box an edge leaves by is read off the
+ * 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.
+ *
+ * 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.
+ *
+ * Pure: a diagram in, shapes out, every decision assertable.
+ */
+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 {
+    x: number;
+    y: number;
+}
+export interface BoxShape {
+    kind: 'box';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The lines to draw, already wrapped; `label` keeps the whole text for anything that reads the shape. */
+    label: string;
+    lines: string[];
+    /** The symbol to draw. Undefined means a rectangle. */
+    shape?: NodeShape;
+    colour: ColourRole;
+    initial: boolean;
+}
+export interface LinkShape {
+    kind: 'link';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
+    labelX: number;
+    labelY: number;
+    colour: ColourRole;
+    /** A dashed line, when the notation distinguished one. */
+    dashed?: boolean;
+    /** The arrow the source edge stated. Undefined means the plain arrow every edge has been drawn with. */
+    arrow?: EdgeArrow;
+}
+export interface PathShape {
+    kind: 'path';
+    points: Point[];
+    label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
+    labelX: number;
+    labelY: number;
+    colour: ColourRole;
+    dashed?: boolean;
+    arrow?: EdgeArrow;
+}
+/** A boundary around several states: a package, a layer, a subgraph. */
+export interface GroupShape {
+    kind: 'group';
+    /** The group's own id, so a container can fold it without guessing from the label. */
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label: string;
+    colour: ColourRole;
+}
+export interface CaptionShape {
+    kind: 'caption';
+    x: number;
+    y: number;
+    lines: string[];
+    colour: ColourRole;
+}
+export interface TitleShape {
+    kind: 'title';
+    x: number;
+    y: number;
+    text: string;
+    colour: ColourRole;
+}
+export type Shape = GroupShape | BoxShape | LinkShape | PathShape | CaptionShape | TitleShape;
+export interface Canvas {
+    width: number;
+    height: number;
+    shapes: Shape[];
+}
+/**
+ * How far apart two edges that join the same pair are drawn.
+ *
+ * Wider than the least two ports may sit: two statements about one pair have to read as two lines, and a gap the
+ * port packer would allow is a gap a reader sees as one thick line. Exported so a test can name the pattern.
+ */
+export declare const MULTI_EDGE_SPACING = 20;
+/** Which colour a box earns from its role. One mapping, used by every container. */
+export declare function roleOfNode(node: DiagramNode): ColourRole;
+/**
+ * How tall the mask an edge label is drawn over is.
+ *
+ * Exported because two modules must agree on it: the painter reserves the rectangle when it looks for a clear
+ * 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;
+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;

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

@@ -0,0 +1,41 @@
+/**
+ * Verdict to colour, in the two surfaces the page can be in, and in the scheme a reader prefers.
+ *
+ * A drawing is read before it is parsed, so the first thing it says is the answer. The roles are named rather
+ * than coloured: a scheme maps a role to a value, and every scheme is chosen so the drawing survives both a
+ * light and a dark page - the reader never has to fix a palette to read a result.
+ *
+ * The mode is read at render time from the page's own background (see `client.ts`). The host publishes its
+ * palette as CSS variables whose names are private to it, and a drawing that hard-coded them would break on
+ * the next theme; the luminance of the surface is the one fact that cannot drift.
+ *
+ * Pure, and tested: a wrong role is a wrong verdict shown as a shape.
+ */
+export type ColourRole = 'pass' | 'findings' | 'fail' | 'undecided' | 'muted' | 'text' | 'edge' | 'surface' | 'background';
+export type Palette = Record<ColourRole, string>;
+/** Which surface the drawing will sit on. */
+export type PaletteMode = 'light' | 'dark';
+/** A named set of colours. A scheme with both variants follows the page; one with only light does not. */
+export type PaletteScheme = 'default' | 'github' | 'high-contrast' | 'print';
+export interface PaletteOptions {
+    mode?: PaletteMode;
+    scheme?: PaletteScheme;
+}
+/**
+ * Resolve a palette.
+ *
+ * `overrides` win over everything, so a caller can retheme one role without inventing a scheme. A scheme with
+ * a dark variant follows the surface; one without stays as declared - high-contrast and print are what they
+ * say they are, on purpose. An unknown name falls back to the default palette rather than throwing, because
+ * the value can arrive from a DOM control.
+ */
+export declare function palette(overrides?: Partial<Palette>, options?: PaletteOptions): Palette;
+/**
+ * The role a verdict earns.
+ *
+ * `pass_with_findings` is deliberately not `pass`: it reads as the middle band, because a card that paints a
+ * report with warnings the same colour as a clean one has stopped carrying the answer.
+ */
+export declare function roleForVerdict(verdict: string | undefined): ColourRole;
+/** Every scheme by name, so a picker does not hard-code the list. */
+export declare function schemeNames(): PaletteScheme[];

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

@@ -0,0 +1,55 @@
+/**
+ * Where the boxes go.
+ *
+ * The drawing is placed by the layered pipeline, in the order the mature implementations run it: cycle breaking turns
+ * the graph into a DAG, layering gives every box a row, dummy nodes give every long edge a lane, ordering reduces the
+ * crossings, and coordinate assignment decides the x of each lane and box. This module composes those stages; it does
+ * not decide any of them itself. Each stage is a pure module next door, so it can be asserted without a canvas.
+ *
+ * Two decompositions sit around the pipeline. A level - the top of the drawing, or the inside of a boundary - is
+ * split into weakly connected components, each laid out on its own and then packed onto the page, so a wide
+ * subgraph cannot squeeze an unrelated one. A boundary is a node in its parent's layer whose size is whatever its
+ * contents need, and its inside is laid out by the same pipeline; that is how nesting is drawn.
+ *
+ * What comes out is geometry only: a box per node, a rectangle per boundary, and - for a long edge - the lane its
+ * dummies reserved, so the painter can draw one polyline through it instead of searching around the boxes.
+ */
+import { type Measured as TextBox } from './text.js';
+import type { Diagram, DiagramNode } from './model.js';
+/** Geometry of one placed box, before anything is drawn. */
+export type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** A point in the drawing's own coordinates. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** The lane a long edge's dummies reserved, in layout order: from the layout source down to the layout target. */
+export interface Lane {
+    /** One point per gap the edge crosses, at the lane's own x: it keeps its own order, and the painter walks it. */
+    points: Point[];
+    /** True when the layout runs opposite to the source's arrow, so the painter walks the lane backwards. */
+    reversed: boolean;
+}
+/** What a placement returns: every box, every drawn boundary, every reserved lane, and how wide the content is. */
+export interface Placement {
+    boxes: Map<string, Box>;
+    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. */
+    across: Set<number>;
+}
+/** Geometry constants in one place: a container with different proportions changes these, not the rules. */
+export declare const MARGIN = 20;
+/** The text a node will draw, measured from its label - the id is what the source called it, not what it says. */
+export declare function textOf(node: DiagramNode): TextBox;
+export declare function place(diagram: Diagram, top: number): Placement;
+/** The aspect ratio of a placement, for the tests that check a drawing is a page and not a strip. */
+export declare function placementAspect(placement: Placement): number;

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

@@ -0,0 +1,77 @@
+/**
+ * Orthogonal edge routing around boxes.
+ *
+ * A straight line between two boxes is right until a third box sits between them; then it is a line drawn through a
+ * component, which reads as a connection that is not there. Graphviz solves this by routing along a visibility
+ * graph and then fitting splines; ELK, yFiles and mxGraph build a *sparse* grid from the boxes' own edges and run
+ * A* over it with a bend penalty. Sparse is the whole trick: a pixel grid is O(pixels²), while the candidate lines
+ * are the coordinate of every box edge plus a margin - O(boxes) per axis.
+ *
+ * So this module does exactly that, in the two steps those routers use:
+ *
+ * 1. **Candidate lines.** Every box contributes four: one lane just outside each side. Together with the anchor
+ *    coordinates they form the grid a route may travel on.
+ * 2. **A* with bends.** Moving along a candidate line costs its length; changing direction costs extra, because a
+ *    route that zig-zags to save three points is harder to follow than one that goes around.
+ *
+ * A route is only computed for an edge that needs it: the cheap straight segment is tried first, and routing is the
+ * fallback. That keeps the common case - a box directly above another - at two points and no search.
+ *
+ * The layered painter mostly does not ask: an edge between two rows and an edge with a lane are both built from the
+ * channel stage's answer, because a route searched on its own cannot know which lanes the other edges already hold.
+ * What is left for this router is the drawing the layers do not describe - an edge across two wrapped columns, an
+ * edge one of whose ends is a boundary - and the fallback when a channel route would meet a box.
+ */
+import type { Point } from './paint.js';
+/** A rectangle an edge may not cross. */
+export interface Obstacle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The four sides a route may leave a box from. */
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+/** The length of the straight run an edge takes before it is allowed to turn. */
+export declare const ROUTE_STUB = 16;
+/** The outward normal of a side: the direction an edge leaves along. */
+export declare function normalOf(side: Side): Point;
+/** A segment crossing a box at all, with a little slack so a route does not shave a corner. */
+export declare function crossesBox(x1: number, y1: number, x2: number, y2: number, box: Obstacle): boolean;
+/** The point on a side of a box, in the middle of that side. */
+export declare function anchor(box: Obstacle, side: Side): Point;
+/**
+ * Which side of `from` an edge leaves by, and which side of `to` it arrives at.
+ *
+ * The side is a property of the drawing, not of the distance between two centres. A layered drawing puts its boxes
+ * in horizontal rows, and an edge between two rows approaches vertically: out of the bottom, into the top, and the
+ * other way round for an edge drawn against the flow. Only two boxes in the same row are joined sideways, and then
+ * the direction of travel decides which side.
+ *
+ * This replaces the old rule, which compared the two centres' dx and dy and picked the larger axis - so an edge
+ * between two rows left through a box's side as soon as the target was far enough sideways, which is the hook a
+ * top-down drawing is read as a defect.
+ */
+export declare function approachSides(from: Obstacle, to: Obstacle): {
+    exit: Side;
+    entry: Side;
+};
+/**
+ * Route from one box to another, going around any box in the way.
+ *
+ * Returns the polyline to draw. When nothing blocks the straight segment, or when every candidate is blocked (a
+ * single box that fills the drawing), the straight line is returned and the caller keeps a two-point shape - an
+ * unroutable edge is still an edge, and drawing it straight is more honest than dropping it.
+ */
+export interface Ports {
+    exit: Point;
+    entry: Point;
+    exitSide: Side;
+    entrySide: Side;
+}
+export declare function routeEdge(from: Obstacle, to: Obstacle, obstacles: Obstacle[], anchors?: Ports): {
+    points: Point[];
+    routed: boolean;
+};
+/** Drop the points in the middle of a straight run: three collinear points are one segment. */
+export declare function simplify(points: Point[]): Point[];

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

@@ -0,0 +1,19 @@
+/**
+ * Shapes to SVG markup.
+ *
+ * The one module that knows tags, so it is also the one place where a shape can silently disappear if a
+ * writer forgets a case: the writer table has an entry per shape kind, and the caller counts the drops
+ * instead of hiding them.
+ *
+ * Three containers read this output - an inline card, a full-screen view, and a sidebar tab - so the markup
+ * carries no size of its own beyond its `viewBox`: the container decides how large the drawing is, and the
+ * same string serves a thumbnail and a whiteboard.
+ *
+ * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
+ */
+import { type Canvas } from './paint.js';
+import type { Palette } from './palette.js';
+export declare function toSvg(canvas: Canvas, colours: Palette, label?: string): {
+    markup: string;
+    dropped: number;
+};

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

@@ -0,0 +1,73 @@
+/**
+ * The geometry of a node's symbol, shared by the module that draws it and the module that attaches edges to it.
+ *
+ * A box is a rectangle, but a symbol is not: the diamond's side midpoints are its vertices, a circle has no side at
+ * all, and a cylinder's top is an arc. Any rule that decides where an edge may meet a node therefore needs the
+ * symbol's own points - and the module that draws the symbol needs the same numbers, or the anchor and the outline
+ * disagree and an edge ends in the air.
+ *
+ * So the arithmetic lives here once: the painter reads a port from it, the writer draws the shape from it, and a
+ * change to a symbol's outline moves both. Pure data and pure functions, no SVG markup.
+ */
+import type { Box, Point } from './place.js';
+import type { NodeShape } from './model.js';
+/** A cubic Bezier, as the writer draws a curve and the painter reads a point from it. */
+export interface Cubic {
+    from: Point;
+    c1: Point;
+    c2: Point;
+    to: Point;
+}
+/** Where the two caps of a cylinder start and end, and how deep each one is. */
+export interface CylinderCaps {
+    /** How far the cap reaches into the box: the writer's `min(10, h / 3)`. */
+    cap: number;
+    /** The top cap, drawn from its left shoulder to its right shoulder. */
+    top: Cubic;
+    /** The bottom cap, drawn from its right shoulder to its left shoulder. */
+    bottom: Cubic;
+}
+/** A point on a cubic Bezier at parameter `t`, which is what makes "the top of the cap" a shared fact. */
+export declare function cubicPoint(curve: Cubic, t: number): Point;
+/**
+ * A diamond's four points, in drawing order: top, right, bottom, left.
+ *
+ * These are the only four places an edge may meet a diamond: each side of the box meets the symbol at exactly that
+ * point, and every other point on the side is in the air inside or outside the outline.
+ */
+export declare function diamondPoints(box: Box): [Point, Point, Point, Point];
+/**
+ * Does this symbol meet each of its four sides at exactly one point?
+ *
+ * A diamond's side midpoints are its four vertices, and an ellipse's are its four cardinal points: both offer one legal
+ * port per side and no run to spread along. Every other symbol offers a run on at least one side - a rectangle along
+ * its whole side, a hexagon along the flat between its cut corners, a stadium between its end caps, a cylinder along
+ * its straight flank - so a port there has a place to sit rather than a point to take.
+ *
+ * This is the distinction the painter needs: a node with one legal point per side can give its edges a point each,
+ * and a node with a run can only give them places along it. The two points the discrete shapes offer are the same
+ * four points of the box, which is why one answer serves both.
+ */
+export declare function hasDiscretePorts(shape: NodeShape | undefined): boolean;
+/** How much of each end of a hexagon the corner cuts away. */
+export declare function hexagonCut(width: number): number;
+/**
+ * A hexagon's six points, in drawing order: top-left, top-right, right, bottom-right, bottom-left, left.
+ *
+ * The top and bottom are flat runs between the first two and the last two points; the left and right sides are the
+ * single points at index 5 and 2, because the corner cut removed everything else.
+ */
+export declare function hexagonPoints(box: Box): [Point, Point, Point, Point, Point, Point];
+/** The radius of a stadium's end caps: half its height, unless the box is narrower than that. */
+export declare function stadiumRadius(box: Box): number;
+/**
+ * A cylinder's two caps.
+ *
+ * The writer draws the top cap from the left shoulder to the right shoulder with the box's own top edge as the
+ * control line, and the bottom cap mirrored. The cap curve's apex - the point the painter attaches a top or bottom
+ * port to - is therefore a property of this curve, not a constant: it sits a quarter of the cap's depth inside the
+ * box, not `cap` inside it.
+ */
+export declare function cylinderCaps(box: Box): CylinderCaps;
+/** The apex of a cylinder's top or bottom cap: the only point on that side an edge meets the outline at. */
+export declare function cylinderApex(box: Box, side: 'top' | 'bottom'): Point;

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

@@ -0,0 +1,38 @@
+/**
+ * Text as the layout sees it: measured, broken into lines, and turned into a box.
+ *
+ * Mermaid and Graphviz both measure a label in the platform's own text engine and then lay out around that
+ * measurement - a node's size is its text plus padding, and a label too long for its maximum width is wrapped
+ * before anything is placed. There is no DOM here, so the measurement is an estimate over a per-character width
+ * table; what matters is that the *order* is the same: text first, geometry second. A renderer that fixes the box
+ * and pours text into it cannot help overflowing.
+ *
+ * Explicit breaks (`<br>`, `<br/>`, `<br />`, a real newline) are honoured as written, because a source that put
+ * one there wanted that line to end.
+ */
+/** A line longer than this wraps on a space, or breaks in the middle when it has none. */
+export declare const MAX_LINE_CHARS = 30;
+/** Height of one line of box text, and the breathing room around the block. */
+export declare const LINE_HEIGHT = 15;
+export declare const TEXT_PADDING = 12;
+/** The smallest and largest box a label may produce. */
+export declare const MIN_NODE_WIDTH = 88;
+export declare const MAX_NODE_WIDTH = 260;
+/** The lines a label asks for, before wrapping: an explicit break is a line end, not a space. */
+export declare function explicitLines(label: string): string[];
+/**
+ * Wrap one line to the maximum width.
+ *
+ * A word longer than the limit is broken rather than allowed to overflow: a single token with no spaces is the
+ * common case in identifiers, and letting it run off the box is the defect this function exists to prevent.
+ */
+export declare function wrapLine(line: string, limit?: number): string[];
+export interface Measured {
+    lines: string[];
+    width: number;
+    height: number;
+}
+/** The text block a label produces: its lines, and the box it needs. */
+export declare function measure(label: string): Measured;
+/** Rough width of a single-line piece of text, for placing an edge label without a box. */
+export declare function textWidth(text: string): number;

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

@@ -0,0 +1,20 @@
+/**
+ * What a tool card shows, reduced to a drawing.
+ *
+ * The input is what the host hands a settled tool view: a phase and a block whose shape differs per phase.
+ * A settled call carries the paired call's arguments as a **lazy view** (`PartialArguments`) and the result
+ * as content blocks, so nothing here reads `block.args.model`: the view is asked, and the report text is
+ * parsed for the two facts a drawing needs. Every reader is total - an absent field removes a shape rather
+ * than throwing, because the same view renders during streaming.
+ *
+ * Pure. Everything decided here is a fact a test can assert: which nodes exist, which edges, why they are
+ * coloured the way they are.
+ */
+import type { Diagram } from './model.js';
+export interface ViewInput {
+    phase?: unknown;
+    toolName?: unknown;
+    /** The whole block the host hands a view; its shape depends on the phase. */
+    block?: unknown;
+}
+export declare function viewModel(input: ViewInput): Diagram;

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

@@ -0,0 +1,27 @@
+/**
+ * Wrapping: turning one endless column into a page.
+ *
+ * A chain of twelve boxes has twelve layers, and layering alone draws it as a single column taller than anything a
+ * reader can take in - a strip, not a drawing. Graphviz and ELK both answer this with a wrapping pass: cut the layer
+ * sequence into bands and stand the bands side by side, so reading order becomes "down the page, then the next
+ * column", the way text wraps.
+ *
+ * The cut is chosen, not guessed: each candidate number of bands is scored by how close the packed page gets to the
+ * aspect ratio a page and a landscape screen share, and the best one wins. A drawing that is already close to that
+ * shape is left alone - wrapping exists for the strip, not for every tall drawing.
+ *
+ * Pure: layer sizes in, band ranges and offsets out. The caller applies them.
+ */
+export interface BandRange {
+    /** The first and last layer the band holds, inclusive. */
+    first: number;
+    last: number;
+    /** How far right the band stands, relative to the first one. */
+    offsetX: number;
+}
+export interface BandPlan {
+    bands: BandRange[];
+    width: number;
+    height: number;
+}
+export declare function planBands(layerWidth: number[], layerHeight: number[], gap: number, aspect?: number): BandPlan;

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

@@ -0,0 +1,14 @@
+/**
+ * Writing a drawing to disk: the CLI's job, kept out of the renderer.
+ *
+ * `render/index.ts` is bundled into the page as well as run in Node, so it may not import a filesystem;
+ * everything that touches one lives here, where only the host reaches it.
+ */
+import { type RenderInput, type Rendered } from './index.js';
+import type { Palette, PaletteOptions } from './palette.js';
+/** Write the drawing where a document can link to it. Returns the path, the byte count and the render. */
+export declare function writeSvg(input: RenderInput, path: string, overrides?: Partial<Palette>, options?: PaletteOptions): {
+    path: string;
+    bytes: number;
+    rendered: Rendered;
+};