dsh-model-everything 0.4.1 → 0.5.0

package/lib/types/client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The Client half: a lazy factory the page binds to this package's name.
+ *
+ * Everything that decides anything lives in `render/`; this file only turns shapes into React elements and
+ * registers them where the page offers a seat. Two seats are used, and they fail independently:
+ *
+ * - `tool.call.toolview` replaces the card of a tool whose result this package can draw;
+ * - `sidebar.right.pane.tab` is the whiteboard: a tab that renders whatever the reader pastes, with no tool
+ *   and no host data at all, so it keeps working when the card seat does not.
+ *
+ * This module is not a page script: it exports the factory, and `scripts/build-client.mjs` wraps the
+ * compiled output in `window.__ModuleLoader__.load(...)`, which is the loader contract itself.
+ */
+import { type Palette, type PaletteMode } from './render/palette.js';
+export interface ReactLike {
+    createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+    useState?: <T>(initial: T) => [T, (next: T) => void];
+}
+export interface SlotContext {
+    slots: {
+        inject: (slot: string, callback: () => unknown) => unknown;
+        register: (options: Record<string, unknown>, component: unknown) => unknown;
+    };
+    get?: (service: string) => unknown;
+}
+export interface PluginShape {
+    inject: string[];
+    apply: (ctx: SlotContext) => void;
+    /** 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;
+    block?: {
+        args?: unknown;
+        result?: unknown;
+    };
+}
+/** Tool names this package answers. A key that never dispatches simply never renders. */
+export declare const TOOL_NAMES: string[];
+/**
+ * Which surface the page is painting the drawing on.
+ *
+ * The host publishes its palette as private CSS variables, so naming them here would break on the next theme.
+ * The one fact that cannot drift is the rendered background: read it, and fall back to the media query, then
+ * to light. Never throws - a view that cannot read the document still draws.
+ */
+export declare function themeMode(): PaletteMode;
+/** The whiteboard's seat key, in both the tab registry and the body slot. */
+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 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.
+ */
+export declare function viewFor(React: ReactLike, overrides?: Partial<Palette>): (props: ToolCallProps) => unknown;
+/**
+ * The whiteboard: paste a diagram, get a drawing, zoom it.
+ *
+ * It holds no host data, which is the point: it is a place to think about a diagram while writing one, and
+ * it cannot be broken by a change to any tool's result shape. The source it draws is whatever is in its own
+ * box.
+ */
+export declare function whiteboardFor(React: ReactLike, overrides?: Partial<Palette>): () => unknown;
+export interface MountOptions {
+    /** Injected so the suite can drive the poll without waiting. Defaults to `setTimeout`. */
+    schedule?: (run: () => void, delay: number) => unknown;
+}
+/**
+ * Register the whiteboard tab once the sidebar's optional services are ready.
+ *
+ * The slot can be declared before `sidebarRightTabs` exists - the host composes services and seats in an
+ * order this plugin does not control - and a single `ctx.get` there is a race that loses the tab silently.
+ * So it polls, like the reference implementation does, and stops after a bounded number of attempts.
+ */
+export declare function mountWhiteboard(React: ReactLike, ctx: SlotContext, options?: MountOptions): unknown;
+export default function factory(require: (name: string) => unknown): PluginShape;

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

@@ -0,0 +1,8 @@
+/**
+ * The structural diff tool: two drawings, compared by containment.
+ *
+ * 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_DIFF_TOOL_NAME = "diagram_diff";
+export declare const diagramDiffTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

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/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/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/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,27 @@
+/**
+ * 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 ...`;
+ * - `component X`, `component "text" as X`, `[text] as X`, `[text]`;
+ * - `package "text" { ... }`, `node`, `folder`, `cloud`, `database` - a group, closed by `}`;
+ * - `X --> Y`, `X ---> Y`, `X ..> Y`, `X --> Y : label`, arrow either direction;
+ * - `state X`, `state "text" as X`, and `[*] --> X` for a start marker;
+ * - `'` comments and `skinparam`/`!theme` directives.
+ *
+ * Refused, by name: `sequence`, `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`,
+ * `alt`/`opt`/`loop`/`par` and any other fragment keyword.
+ */
+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/layout.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ranks for a machine, and the order of states within each rank.
+ *
+ * Breadth-first from the initial state decides the row: the layout a reader expects, and the one a layered
+ * drawing asks for - edges mostly flow down, and a state's row is how far it is from the start. A state
+ * nothing reaches goes in a block of its own rather than being dropped.
+ *
+ * Within a row, states keep the order breadth-first found them in: a row is filled by walking the row above
+ * left to right, so a state already sits under the parent that discovered it. A barycentre pass was written
+ * and removed - with breadth-first insertion it could never move a state, so it was complexity without an
+ * observable effect.
+ *
+ * Pure, and asserted on the rows themselves.
+ */
+import type { DiagramEdge, DiagramNode } from './model.js';
+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: DiagramNode[], edges: DiagramEdge[], init: string | undefined): Ranked;

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

@@ -0,0 +1,56 @@
+/**
+ * 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';
+export interface DiagramNode {
+    id: string;
+    /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
+    label?: string;
+    role: NodeRole;
+}
+export interface DiagramEdge {
+    from: string;
+    to: string;
+    label: string;
+    /** A dashed edge, for notations that distinguish one. */
+    dashed?: boolean;
+}
+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/paint.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ *
+ * Two placements, chosen by the source:
+ *
+ * - **layered** (no groups): breadth-first rows, forward edges dropping straight down, back edges on a side
+ *   channel clear of every box, self loops as small loops. The shape a state machine wants.
+ * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block
+ *   inside its parent, and the top level stacks. The shape an architecture diagram wants, because a package
+ *   whose members float somewhere else on the page is not showing containment at all.
+ *
+ * Edges are placed from where the boxes ended up, so neither placement needs to tell the edge code which one
+ * ran: "below" is a straight line, "beside" is horizontal, "above" routes around.
+ *
+ * Pure: a diagram in, shapes out, every decision assertable.
+ */
+import { type ColourRole, type Palette, type PaletteOptions } from './palette.js';
+import { type Diagram, type DiagramNode } from './model.js';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface BoxShape {
+    kind: 'box';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label: string;
+    colour: ColourRole;
+    initial: boolean;
+}
+export interface LinkShape {
+    kind: 'link';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    label: string;
+    labelX: number;
+    labelY: number;
+    colour: ColourRole;
+}
+export interface PathShape {
+    kind: 'path';
+    points: Point[];
+    label: string;
+    labelX: number;
+    labelY: number;
+    colour: ColourRole;
+}
+/** 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[];
+}
+/** Which colour a box earns from its role. One mapping, used by every container. */
+export declare function roleOfNode(node: DiagramNode): ColourRole;
+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,39 @@
+/**
+ * Where the boxes go.
+ *
+ * Two placements, chosen by the source:
+ *
+ * - **layered** (no groups): breadth-first rows, centred, no containment - the shape a state machine wants.
+ * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block inside
+ *   its parent, and the top level stacks - the shape an architecture diagram wants, because a package whose
+ *   members float somewhere else on the page is not showing containment at all.
+ *
+ * Split out of the painter so the two questions stay separate: this module decides positions, `paint.ts` decides
+ * what to draw between them. A change to edge routing cannot move a box, and a change to nesting cannot move a
+ * line.
+ */
+import type { Diagram } from './model.js';
+/** Geometry of one placed box, before anything is drawn. */
+export type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** What a placement returns: every box, every drawn boundary, and how wide the content is. */
+export interface Placement {
+    boxes: Map<string, Box>;
+    groupRects: Map<string, Box>;
+    width: number;
+}
+/** Geometry constants shared by both placements. */
+export declare const MARGIN = 20;
+/** A box wide enough for its label, clamped so a long id cannot dominate the page. */
+export declare const nodeWidth: (label: string) => number;
+/**
+ * Place every box of a diagram.
+ *
+ * The choice of placement is a property of the source, not of the caller: a drawing that declares boundaries is
+ * read as containers and gets the tree; one that does not is read as a machine and gets the ranks.
+ */
+export declare function place(diagram: Diagram, top: number): Placement;

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;
+};