dsh-model-everything 0.4.1 → 0.5.1

package/lib/types/diagram-render-tool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The drawing tool: source text in, SVG out.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+export declare const DIAGRAM_TOOL_NAME = "diagram_render";
+export declare const diagramRenderTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/diagram-review-tool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The structural review tool: budgets against one drawing.
+ *
+ * One job per file: this module declares the tool and nothing else, so the documentation generator that walks
+ * `*-tool` modules finds it, and so a change to the drawing never touches the reviewing.
+ */
+export declare const DIAGRAM_REVIEW_TOOL_NAME = "diagram_review";
+export declare const diagramReviewTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/diagram.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The diagram component: one row, one switch, three tools.
+ *
+ * A separate component rather than a feature of the tools above it, because drawing has nothing to do with
+ * verifying. It can be on while the tools are off, off while they are on, and it carries no engine: a
+ * deployment that only wants pictures of its Mermaid diagrams installs the same package and leaves the rest of
+ * it alone.
+ *
+ * The switch is `config.enabled`, live, exactly like the routing gate: a deployment can turn the drawing off at
+ * boot, from the Plugins page, or by disabling this row, and none of those touches the tools or the skills.
+ */
+import z from '@deepseek-ai/schemastery';
+export interface Config {
+    /** Whether the diagram tools are registered. Read through {@link enabledOf}. */
+    enabled: unknown;
+    /** The title a drawing carries when the caller did not name one. */
+    defaultTitle: string;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+    defaultTitle: z<string, string, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+    defaultTitle: z<string, string, "defined">;
+}>>, "plain">;
+/** Read the switch as a boolean, whichever shape this host produced. */
+export declare function enabledOf(config: Config): boolean;
+export interface ComponentContext {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+}
+export declare function apply(ctx: ComponentContext, config: Config): void;
+export declare const inject: string[];

package/lib/types/presentation.d.ts

@@ -77,6 +77,13 @@ export interface ReportCard {
         facts: number;
         skipped: number;
     };
+    /** `uml_structure_verify` with `repoPath`: what the scan itself resolved, and what it could not. */
+    scan?: {
+        files: number;
+        unresolved: number;
+        packages: number;
+        dynamic: number;
+    };
     /** `model_interleaving_scan`: how many claims were found, and in which families. */
     claims?: {
         absolute: number;

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

@@ -0,0 +1,55 @@
+/**
+ * Structural budgets for a diagram: the checks a drawing can fail without being wrong.
+ *
+ * A diagram is not verified the way a state machine is - there is no deadlock to find - but an architecture
+ * picture has properties a reader relies on, and they are checkable: a package that holds twenty things is not
+ * communicating anything, a boundary around one box is a layer the source did not mean, a group nothing points
+ * into and nothing leaves is a group that belongs on another page.
+ *
+ * Pure: a diagram and a set of limits in, findings out. The limits are arguments, not constants, because what
+ * counts as too wide depends on the medium - a slide holds less than a scrollable tab.
+ */
+import type { Diagram } from './model.js';
+export type Severity = 'error' | 'warning';
+export interface BudgetFinding {
+    code: string;
+    severity: Severity;
+    message: string;
+    /** The group the finding is about, when it is about one. */
+    group?: string;
+}
+export interface BudgetLimits {
+    /** How many direct children a boundary may hold: its own nodes plus the groups directly inside it. */
+    maxMembers: number;
+    /** How deep boundaries may nest. */
+    maxDepth: number;
+    /** How many nodes the whole drawing may hold. */
+    maxNodes: number;
+}
+/**
+ * Defaults, chosen for a drawing read in a conversation pane: a package with more than a handful of boxes stops
+ * being a package and becomes a diagram of its own, and three levels is what fits on one screen before a reader
+ * needs the source.
+ */
+export declare const DEFAULT_LIMITS: BudgetLimits;
+export interface BudgetReport {
+    verdict: 'pass' | 'pass_with_findings' | 'fail';
+    findings: BudgetFinding[];
+    /** What was measured, so a reader can tell "nothing to check" from "checked and clean". */
+    measured: {
+        nodes: number;
+        groups: number;
+        deepest: number;
+        widest: {
+            group: string;
+            size: number;
+        } | null;
+    };
+}
+/**
+ * Measure a drawing against its limits.
+ *
+ * Every finding names the group it is about, because a budget report that says "a group is too wide" without
+ * saying which one is a report nobody can act on.
+ */
+export declare function checkBudget(diagram: Diagram, limits?: Partial<BudgetLimits>): BudgetReport;

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

@@ -0,0 +1,63 @@
+/**
+ * Channel assignment: where the vertical lanes and the horizontal runs between two rows go.
+ *
+ * The stages before this one decide where the boxes are, and the painter decides what a box looks like. What is left
+ * is the space between two rows, and an edge that decides that space alone will collide with the next one: every long
+ * edge has to cross a row somewhere, and every edge whose two ends are not vertically aligned needs one horizontal run
+ * inside the gap it crosses. Chosen independently, two runs land on one height and read as a junction, and a run
+ * sweeps across a vertical another edge is already using.
+ *
+ * So this stage assigns both, after the boxes have settled and before anything is drawn:
+ *
+ * - **A lane's x.** A long edge owns one vertical lane through the rows it crosses. The x is a position no box
+ *   occupies in any of those rows, and lanes keep the order their dummies have in the ordering, so two lanes never
+ *   share an x inside one gap. Alignment is worth a detour: a lane that lands inside a box's own port span turns a
+ *   four-bend staircase into a straight drop, so alignment comes before distance from the proposed position.
+ * - **A run's y.** The horizontal runs inside one gap are stacked at distinct heights - Graphviz's virtual nodes - so
+ *   two runs never lie on one line, and a nested run stays near the box it leaves.
+ *
+ * Pure: rows, chains and coordinates in; lane positions and run heights out.
+ */
+import type { Chain } from './dummy.js';
+/** A box, as far as routing is concerned: only a box can move a lane. */
+export interface ChannelBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ChannelInput {
+    /** The ordered rows, dummies included: a lane keeps its dummy's order. */
+    layers: string[][];
+    /** Every edge's chain, from the layout source to the layout target. */
+    chains: Chain[];
+    /** A dummy instance, and the lane it belongs to. */
+    chainOf: ReadonlyMap<string, string>;
+    /** The boxes that block a lane. A dummy has none. */
+    boxes: ReadonlyMap<string, ChannelBox>;
+    /** The top of each row, and how tall it is. */
+    layerY: number[];
+    layerHeight: number[];
+    /** What coordinate assignment proposed for each lane. */
+    laneX: ReadonlyMap<string, number>;
+}
+export interface ChannelOptions {
+    /** How far a lane stays from a box in a row it crosses. */
+    clearance: number;
+    /** The narrowest two lanes sharing a gap may be. */
+    spacing: number;
+}
+/** One long edge's lane: the x of its vertical run, and the height of a run in each gap it crosses. */
+export interface LaneChannel {
+    x: number;
+    y: number[];
+}
+export interface ChannelPlan {
+    /** By diagram edge index: the lane a long edge reserved, with one corridor height per gap it crosses. */
+    lanes: Map<number, LaneChannel>;
+    /** By diagram edge index: the height of the one run an edge between two adjacent rows needs. */
+    runs: Map<number, number>;
+}
+/** How far a port sits from a box's corner. The painter places ports from this same number. */
+export declare const PORT_INSET = 10;
+export declare function assignChannels(input: ChannelInput, options: ChannelOptions): ChannelPlan;

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

@@ -0,0 +1,23 @@
+/**
+ * Collapsing a group: the drawing with one boundary folded into a single box.
+ *
+ * A fold is a transform on the model, not a mode of the painter. That keeps the painter's rules unchanged -
+ * it still draws boxes and edges it is given - and it makes the behaviour testable without a browser: feed a
+ * diagram in, assert what came out.
+ *
+ * Folding is what makes a hierarchy usable: a reader who has understood a package wants it out of the way, and
+ * an architecture diagram that cannot be folded is read at one zoom level forever.
+ */
+import type { Diagram } from './model.js';
+/**
+ * Fold the named groups.
+ *
+ * A folded group becomes a node carrying its name and how many nodes it holds; its members - and every group
+ * inside it - leave the drawing. An edge that pointed at something inside the fold is re-aimed at the fold's
+ * box, and an edge between two members of the same fold disappears: both ends are now the same box, and a
+ * self-loop would be a claim the source never made.
+ *
+ * Ids nobody declared are ignored, and folding a group whose contents are already gone changes nothing, so the
+ * function is total on any diagram and any set of names.
+ */
+export declare function collapse(diagram: Diagram, folded: Iterable<string>): Diagram;

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

@@ -0,0 +1,57 @@
+/**
+ * The two decompositions a drawing needs before it can be packed.
+ *
+ * **Weakly connected components.** Two subgraphs with no edge between them are two drawings that happen to share a
+ * page. Laying them out together makes them share one set of layers, so the wider one sets every column width and
+ * the narrower one is squeezed beside it; moving one moves the other. Split first, lay each out on its own, then pack
+ * the rectangles.
+ *
+ * **Packing.** A pile of rectangles has to become a page. The target is the aspect ratio a page and a screen share -
+ * 1.6 - and a shelf packer is enough to get there: sort by height, fill a shelf until the next rectangle would make
+ * the drawing wider than the page it is aiming at, then start the next shelf. No overlap, and a deterministic order,
+ * so the same rectangles always pack the same way.
+ *
+ * Pure, and asserted on the rectangles themselves.
+ */
+export interface SizedRectangle {
+    width: number;
+    height: number;
+}
+export interface PackedRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The nodes of each weakly connected component, in the order the nodes were written.
+ *
+ * An isolated node is a component of its own: it is not noise, it is a drawing with nothing joining it, and the
+ * packer is what decides where it goes.
+ */
+export declare function weakComponents(nodes: ReadonlyArray<{
+    id: string;
+}>, edges: ReadonlyArray<{
+    from: string;
+    to: string;
+}>): string[][];
+export interface PackOptions {
+    /** The empty strip kept between two rectangles, on both axes. */
+    gap?: number;
+    /** The page the packer aims at; the drawing comes out as close to it as the rectangles allow. */
+    aspect?: number;
+}
+/**
+ * Pack rectangles into a page of roughly `aspect`, using shelves.
+ *
+ * The shelf width is derived from the total area and the target aspect: that is the width at which a perfect grid
+ * would have the wanted shape, so a shelf that fills it lands near the target. Rectangles are taken tallest first,
+ * which is what keeps a shelf from being mostly empty air above a short rectangle.
+ */
+export declare function packRectangles(rectangles: ReadonlyArray<SizedRectangle>, options?: PackOptions): {
+    placements: PackedRectangle[];
+    width: number;
+    height: number;
+};
+/** The aspect ratio of a box, as a number a reader can compare against the page's. */
+export declare function aspectOf(width: number, height: number): number;

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

@@ -0,0 +1,64 @@
+/**
+ * Coordinate assignment: how far right each box sits. Brandes-Kopf.
+ *
+ * The layers are rows and the order inside them is settled; the only freedom left is the x of each box. Three
+ * properties make a drawing readable:
+ *
+ * - A box sits over what it is connected to, and a chain of boxes sits on one vertical line. Brandes and Kopf get
+ *   this by *aligning*: every box is offered the median of its neighbours in the layer just above (or just below) and
+ *   is joined to that neighbour's block when the join crosses no other edge. A block is then one node of a smaller
+ *   graph, and a box that aligned downwards through five rows comes out as one straight segment.
+ * - Nothing overlaps, and the empty strip between two boxes in a row is the same everywhere. The blocks are compacted
+ *   against each other by the least distance their rows allow, which is a longest path over the block graph: a block
+ *   sits as far left as the block to its left permits, and no further.
+ * - The drawing is balanced rather than packed to one side. Aligning downwards alone would lean everything left, so
+ *   the same two passes are run from the bottom up, and each pair is run once more mirrored left to right. The four
+ *   layouts are then averaged. Averaging is a convex combination, and the separation constraints are linear, so the
+ *   average of four layouts that keep the boxes apart also keeps them apart - the balance is free of overlaps by
+ *   construction. A pass that starts at the top and one that starts at the bottom compact their blocks from opposite
+ *   ends, so each side is first slid onto the origin of the first pass of that side, and only then averaged.
+ *
+ * Three things this module owes the rest of the pipeline rather than the paper:
+ *
+ * - A long edge's dummies share one x. They are one lane, not one point per row, so each lane is collapsed to the mean
+ *   of the x its two ends want - the straight drop a reader follows. Collapsing can put a lane where a box already is,
+ *   so the last pass spends the lane's space: boxes are pushed right past it and never the other way, and a row keeps
+ *   the width its placeholders were given, which is the width a corridor needs when the lane has to go around a box.
+ *   The lane is a proposal either way - the channel stage moves a lane into a free corridor when routing needs it, and
+ *   a box never moves for a lane.
+ * - A lane is not a neighbour to be aligned with. A box that aligned itself to a lane passing through its row would be
+ *   pulled off the boxes it does connect to, which is how a decision with one long edge comes out as a staircase. Lanes
+ *   are placed by the compaction and then by the channel stage, which is where a lane belongs.
+ * - The empty strip between two rows is the caller's, not this module's: the y of a row is a running sum with one gap.
+ *
+ * Pure: layers and chains in, coordinates out.
+ */
+import type { Chain } from './dummy.js';
+export interface Sized {
+    width: number;
+    height: number;
+}
+export interface CoordInput {
+    layers: string[][];
+    chains: Chain[];
+    sizeOf: (id: string) => Sized;
+    /** A dummy instance, and the shared lane it belongs to. */
+    chainOf: ReadonlyMap<string, string>;
+}
+export interface CoordOptions {
+    /** The empty space between two side-by-side boxes. */
+    gap: number;
+    /** The empty strip between two layers. */
+    layerGap: number;
+}
+export interface Coordinates {
+    /** Centre x, keyed by node id and by lane id. A long edge's dummies share one entry. */
+    x: Map<string, number>;
+    /** The top y of each layer. */
+    layerY: number[];
+    layerHeight: number[];
+    layerWidth: number[];
+    width: number;
+    height: number;
+}
+export declare function assignCoordinates(input: CoordInput, options: CoordOptions): Coordinates;

package/lib/types/render/cycle-break.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cycle breaking, in the order a layered layout does it.
+ *
+ * A layered drawing is a drawing of a DAG: an edge that runs back up the page has no layer to go to. The fix is to
+ * lay such an edge out backwards and draw its arrow the way the source wrote it - but *which* edges to turn around
+ * is a decision, and deciding it edge by edge is what makes two back edges of one cycle end up pointing opposite
+ * ways.
+ *
+ * So the graph is decomposed first. Tarjan's algorithm finds the strongly connected components; contracting each to
+ * a node gives the condensation, which is a DAG, so every edge between components already points one way and nothing
+ * between them needs reversing. Only inside a component - where by definition every edge lies on a cycle - is there
+ * an order to choose: the nodes are ranked once, greedily, and every edge inside the component is oriented along that
+ * single ranking. One ranking per component is what "consistently" means: after the pass, every surviving edge of a
+ * component points from a lower rank to a higher one, so the component cannot contain a cycle any more.
+ *
+ * The initial state is a special case: it is layer zero by definition, so an edge that runs into it is a back edge
+ * before the decomposition even starts. Turning those around leaves the state with no predecessor, so the ranking
+ * of its component puts it first and nothing is ever oriented back into it.
+ *
+ * Pure: the same graph in, the same edge directions out.
+ */
+import type { LayoutEdge, LayoutGraph } from './layout.js';
+/** One strongly connected component: a set of nodes that can all reach each other. */
+export interface Component {
+    /** The component's index in the condensation, numbered in topological order. */
+    id: number;
+    members: string[];
+}
+export interface BrokenGraph {
+    /** The same edges, in the same order, with the ones that close a cycle turned around. */
+    edges: LayoutEdge[];
+    /** The diagram edges whose direction the layout changed. */
+    reversed: Set<number>;
+    /** The strongly connected components, numbered in topological order. */
+    components: Component[];
+    componentOf: Map<string, number>;
+    /** Each node's rank inside its own component: every intra-component edge points from a lower rank to a higher. */
+    rank: Map<string, number>;
+    /** The condensation: an edge per pair of components that has at least one edge between them. Always acyclic. */
+    condensation: Array<{
+        from: number;
+        to: number;
+    }>;
+}
+export declare function breakCycles(graph: LayoutGraph): BrokenGraph;

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

@@ -0,0 +1,44 @@
+/**
+ * Structural diff between two drawings.
+ *
+ * A text diff of two diagrams tells a reader that a line moved; it does not tell them that `Cache` left the
+ * `Platform` package, or that `Core` gained a nested boundary. Those are the changes a design review is about,
+ * and they are decided by comparing the containment tree, not the source.
+ *
+ * The diff judges movement, not merit: a group that moved, a member that changed owner, a boundary added or
+ * removed. Whether the new arrangement is better is the reader's call, so the verdict only says whether anything
+ * changed and whether the comparison could run at all.
+ */
+import type { Diagram } from './model.js';
+export type ChangeKind = 'added' | 'removed' | 'renamed' | 'moved' | 'regrouped';
+export interface StructuralChange {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    kind: ChangeKind;
+    /** What changed, by id: a group id or a node id. */
+    subject: string;
+    message: string;
+}
+export interface DiffReport {
+    verdict: 'pass' | 'pass_with_findings' | 'fail';
+    changes: StructuralChange[];
+    /** Both sides, so an empty change list cannot be confused with a comparison that never ran. */
+    measured: {
+        before: {
+            nodes: number;
+            groups: number;
+        };
+        after: {
+            nodes: number;
+            groups: number;
+        };
+    };
+}
+/**
+ * Compare the containment structure of two drawings.
+ *
+ * Renames are reported by id: a group that kept its id but changed its text is a rename, while a group whose id
+ * is gone and another whose id is new are an unrelated removal and addition, because the ids are what a caller
+ * tracks across versions.
+ */
+export declare function diffStructure(before: Diagram, after: Diagram): DiffReport;

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

@@ -0,0 +1,32 @@
+/**
+ * Dummy nodes: the placeholders a long edge stands on.
+ *
+ * An edge from layer 0 to layer 3 has to cross layers 1 and 2. The router can go around whatever is in the way, but a
+ * drawing reads better if the edge owns a lane through those layers: then ordering can keep other edges off it, and
+ * coordinate assignment can give the whole lane one x. A dummy node is that lane: one per layer the edge crosses.
+ *
+ * A lane is one variable, not one variable per layer. The instances keep their own id (`#d<edge>_<layer>`) so the
+ * ordering stage can sort them inside their layer, and they all point at one lane id (`#e<edge>`) so coordinate
+ * assignment cannot give the same edge three different x values.
+ *
+ * Pure: the layers, the chains, and the map between the two.
+ */
+import type { LayoutEdge } from './layout.js';
+import type { Layering } from './layer.js';
+/** One edge, as the id it passes through in each layer it crosses. */
+export interface Chain {
+    /** The diagram edge's index. */
+    index: number;
+    /** The ids from the layout source to the layout target: the endpoints plus one dummy per crossed layer. */
+    path: string[];
+}
+export interface Augmented {
+    /** The layers with the dummies inserted; each dummy sits in the layer it crosses. */
+    layers: string[][];
+    chains: Chain[];
+    /** A dummy instance's lane id: the variable coordinate assignment shares between a long edge's dummies. */
+    chainOf: Map<string, string>;
+    /** The lane id of every edge that needed dummies. */
+    laneOf: Map<number, string>;
+}
+export declare function addDummies(layering: Layering, edges: LayoutEdge[]): Augmented;

package/lib/types/render/from-mermaid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Mermaid text to a diagram, for the subset this renderer can actually draw.
+ *
+ * The subset is chosen by what a reader of an architecture document writes: a flowchart of boxes and
+ * arrows, a state diagram with a start marker, and the group syntax that turns a flat graph into a layered
+ * one. Everything outside it is refused **with its line number** rather than half-drawn: a picture that
+ * silently drops a lifeline or an interaction is worse than no picture, because it looks complete.
+ *
+ * Supported:
+ *
+ * - `graph TD|TB|LR` and `flowchart TD|TB|LR`, with direction carried into the layout as a hint;
+ * - node declarations `A[text]`, `A(text)`, `A{text}`, `A((text))`, and a bare `A`;
+ * - edges `-->`, `---`, `-.->`, `==>`, with a label as `-->|text|` or `-- text -->`;
+ * - `stateDiagram` / `stateDiagram-v2`: `[*] --> A`, `A --> B: event`, `state "text" as id`;
+ * - `subgraph name ... end`, which becomes a group;
+ * - `%%` comments and blank lines.
+ *
+ * Refused, by name: `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`,
+ * `timeline`, `quadrantChart`, `gitGraph`, `C4Context`, and `click`/`style`/`classDef` directives.
+ */
+import { type Diagram } from './model.js';
+export interface Parsed {
+    diagram: Diagram;
+    /** Lines the parser refused to interpret, with the reason. Empty when the whole source was understood. */
+    refused: string[];
+}
+export declare function fromMermaid(source: string, title?: string): Parsed;

package/lib/types/render/from-plantuml.d.ts

@@ -0,0 +1,33 @@
+/**
+ * PlantUML text to a diagram, for the subset this renderer can actually draw.
+ *
+ * PlantUML is a large language, and a renderer that accepted all of it would be a re-implementation of
+ * PlantUML. This one accepts what an architecture document actually contains - boxes, groups and arrows -
+ * and refuses the rest **by line**, because a component diagram that quietly loses a lifeline reads as
+ * complete and is not.
+ *
+ * Supported:
+ *
+ * - `@startuml` / `@enduml` (optional) and `title ...`;
+ * - elements: `component`, `node`, `rectangle`, `artifact` and `state` (a rectangle), `database` and
+ *   `entity` (a cylinder), `usecase` (an ellipse), `[text]`, each with a `"text"` label and `as` alias;
+ * - boundaries: `package`, `folder`, `node`, `component`, `rectangle` and `artifact` blocks, closed by `}`;
+ * - arrows, either direction: association `-->`/`<--`, dependency `..>`/`<..`, generalisation `--|>`/`<|--`,
+ *   realisation `..|>`/`<|..`, composition `*--`/`--*`, aggregation `o--`/`--o`, labelled after `:`;
+ * - an edge end that names a declared block attaches to that block's rectangle, the way an external
+ *   dependency on a package is drawn; a name that is not a declared block is an implicit element;
+ * - `[*] --> X` for a start marker;
+ * - `'` comments and `skinparam`/`!theme` directives.
+ *
+ * Refused, by line and by name: the element keywords this renderer has no symbol for (`actor`, `class`,
+ * `cloud`, ...), the diagram kinds it does not draw (`sequence`), and an edge it cannot draw as written (a
+ * line with no arrow end, a mark at both ends, a dotted diamond, an edge between two boundaries, or an edge
+ * into a boundary that is nested or empty).
+ */
+import { type Diagram } from './model.js';
+export interface Parsed {
+    diagram: Diagram;
+    /** Lines the parser refused to interpret, with the reason. Empty when the whole source was understood. */
+    refused: string[];
+}
+export declare function fromPlantUml(source: string, title?: string): Parsed;

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

@@ -0,0 +1,38 @@
+/**
+ * The renderer's front door: whatever notation arrived, one drawing comes out.
+ *
+ * Three containers read this - the tool card, the full-screen view and the sidebar whiteboard - and each of
+ * them wants the same two things: shapes to draw and markup to embed. Neither knows which notation produced
+ * them, and neither needs to.
+ *
+ * Pure: no filesystem, because the same module is bundled into the page for the whiteboard.
+ */
+import type { Diagram } from './model.js';
+import { type Canvas } from './paint.js';
+import type { Palette, PaletteOptions } from './palette.js';
+export type Notation = 'mermaid' | 'plantuml';
+export interface RenderInput {
+    /** The notation, or `auto` to read it off the first non-empty line. */
+    notation?: Notation | 'auto';
+    source: string;
+    title?: string;
+    /** Groups folded to a single box. Ids nobody declared are ignored. */
+    folded?: Iterable<string>;
+}
+export interface Rendered {
+    diagram: Diagram;
+    canvas: Canvas;
+    /** The colours the drawing was made with, so a container can paint the same surface behind it. */
+    colours: Palette;
+    /** Ready to embed: an `<svg>` with a viewBox and no fixed pixel size of its own. */
+    markup: string;
+    /** Which notation the source turned out to be. */
+    notation: Notation;
+    /** Lines the parser refused, with their reason. Empty when the whole source was understood. */
+    refused: string[];
+    /** Shapes the SVG writer had no case for. Must be zero; reported rather than hidden. */
+    dropped: number;
+}
+/** Read the notation off the source: PlantUML starts with `@startuml` or `@startmindmap`-style markers. */
+export declare function detectNotation(source: string): Notation;
+export declare function render(input: RenderInput, overrides?: Partial<Palette>, options?: PaletteOptions): Rendered;

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

@@ -0,0 +1,28 @@
+/**
+ * Layering: which row each box is in.
+ *
+ * The graph is acyclic by the time it gets here. A layered drawing needs every edge to span at least one layer, so it
+ * always travels downwards, and it wants the total of the layers every edge spans beyond one to be as small as
+ * possible: those are the edges that have to be drawn through a row of placeholders instead of going straight down a
+ * gap.
+ *
+ * Longest paths are the first guess: every source on the top row, every other node one layer below its latest
+ * predecessor. It is feasible and it is not optimal, because it puts every node as high as it can go - a node whose
+ * edges leave it with slack above the boxes it points at is a node that could have moved down and shortened them.
+ * `network-simplex.ts` solves the program the mature layering implementations solve: the ranking that minimises the
+ * total length, found by exchanging edges in a tight tree until no exchange is left that shortens it.
+ *
+ * The initial state is layer zero. It is a node with no predecessor - cycle breaking has turned around every edge
+ * that ran into it - so a source, and every source is a candidate for the top row. The pin is passed to the solver as
+ * a constraint, so the search never trades it away: an initial state that moved down the page would be a machine
+ * diagram read from the wrong end.
+ *
+ * Pure: the graph in, one layer per node out.
+ */
+import type { LayoutEdge, LayoutGraph } from './layout.js';
+export interface Layering {
+    /** The ids of each layer, top to bottom. A layer holds at least one node. */
+    layers: string[][];
+    layerOf: Map<string, number>;
+}
+export declare function layer(graph: LayoutGraph, edges: LayoutEdge[]): Layering;

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

@@ -0,0 +1,54 @@
+/**
+ * The graph the layout stages agree on, and the order they start from.
+ *
+ * A layout stage has no business knowing what a diagram is: it sees boxes with a size and edges
+ * between them. That is what `LayoutGraph` is, and it is the whole vocabulary the pipeline shares -
+ * cycle breaking reads it, layering writes layers, ordering and coordinate assignment read those.
+ *
+ * `rankStates` stays: it is the breadth-first order a source's own reading suggests, and it seeds
+ * the ordering stage with the discovery order instead of whatever order the parser happened to
+ * collect. It no longer decides which row a state is in - `layer.ts` does that now - so the rows it
+ * returns are only a first guess at the left-to-right order.
+ *
+ * Pure, and asserted on the answer itself.
+ */
+/** A box to place: an id, and the space its text needs. */
+export interface LayoutNode {
+    id: string;
+    width: number;
+    height: number;
+}
+/** An edge to draw: which two boxes it joins, and which diagram edge it came from. */
+export interface LayoutEdge {
+    /** The index in the diagram's own edge list, so the drawing can report a lane back for it. */
+    index: number;
+    from: string;
+    to: string;
+}
+/** One level of a nested drawing: what is placed together in a single pass of the pipeline. */
+export interface LayoutGraph {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    /** The box that must stay on layer zero, when the source named one. */
+    init?: string;
+}
+export interface Ranked {
+    /** The state ids of each row, top to bottom, already ordered left to right. */
+    rows: string[][];
+    /** States no edge reaches from the initial one. */
+    unreachable: string[];
+}
+export declare function rankStates(nodes: ReadonlyArray<{
+    id: string;
+}>, edges: ReadonlyArray<{
+    from: string;
+    to: string;
+}>, init: string | undefined): Ranked;
+/**
+ * The left-to-right seed the ordering stage starts from.
+ *
+ * Breadth-first discovery is what a reader expects a drawing to follow, so it is a better first
+ * guess than the order the parser collected. A state nothing reaches has no discovery order and
+ * keeps the order it was written in, after everything that was reached.
+ */
+export declare function seedOrder(graph: LayoutGraph): Map<string, number>;