@runbooks/design 0.1.0

package/dist/mark.js

@@ -0,0 +1,102 @@
+/**
+ * The catalog's mark, and the picture a link to it shows.
+ *
+ * Both are drawn from the tokens for the same reason everything else here is: a mark
+ * hand-drawn beside the palette is a second copy of a decision, and it is the copy that
+ * goes stale — which is exactly what happened to every graph on the site the day the
+ * catalog turned dark.
+ *
+ * The mark is the product's own claim in one shape: a procedure is a graph, and the thing
+ * that matters about it is where it branches and which branch is dangerous. Three nodes
+ * and a fork, with the fork's far branch in the destructive hue — the same colour, from
+ * the same scale, that a reader will meet on a record page.
+ */
+import { PALETTES, RISK_COLORS, FONT_STACKS } from "./tokens.js";
+import { wrap } from "./text.js";
+/**
+ * The icon, square, at any size.
+ *
+ * No text: at 16px a word is a smudge, and a favicon is read at 16px more often than
+ * anywhere else. The shape has to survive that, so it is three filled dots and two
+ * strokes and nothing finer.
+ */
+export function markSvg(theme, size = 64) {
+    const palette = PALETTES[theme];
+    const danger = RISK_COLORS[theme].destructive;
+    const s = (n) => (n * size) / 64;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 64 64" role="img" aria-label="runbooks.directory">`,
+        `<rect width="64" height="64" rx="${s(14)}" fill="${palette.background}"/>`,
+        // The path: in, then a fork. Straight lines only, which is what the graphs are.
+        `<path d="M 16 32 H 30" stroke="${palette.textSecondary}" stroke-width="3" fill="none"/>`,
+        `<path d="M 30 32 H 36 L 44 20" stroke="${palette.textSecondary}" stroke-width="3" fill="none"/>`,
+        `<path d="M 36 32 L 44 44" stroke="${danger}" stroke-width="3" fill="none"/>`,
+        `<circle cx="16" cy="32" r="5" fill="${palette.trust}"/>`,
+        `<circle cx="45" cy="19" r="5" fill="${palette.textSecondary}"/>`,
+        `<circle cx="45" cy="45" r="5" fill="${danger}"/>`,
+        `</svg>`,
+    ].join("");
+}
+export const PREVIEW_WIDTH = 1200;
+export const PREVIEW_HEIGHT = 630;
+/**
+ * The card a link shows in a chat, a search result or a timeline.
+ *
+ * A record's preview carries that record's own graph, because the graph *is* the summary —
+ * a reader who sees it has already been told whether the procedure branches and whether
+ * there is red in it. Drawing something else for the preview would be a second opinion
+ * about the procedure, which is the thing this repository refuses everywhere else.
+ */
+export function previewSvg(options) {
+    const palette = PALETTES[options.theme];
+    const margin = 72;
+    const room = PREVIEW_WIDTH - margin * 2;
+    // Measured rather than counted. A character budget is a guess about an average, and the
+    // guess was wrong by a word — the summary ran off the right edge of the card.
+    const title = wrap(options.title, 58, room, 1);
+    const summary = options.summary ? wrap(options.summary, 27, room, 2) : undefined;
+    const summaryLines = (summary?.lines ?? []).map((line, index) => `<text x="${margin}" y="${264 + index * 36}" fill="${palette.textSecondary}" font-size="27" font-family='${FONT_STACKS.sans}'>${escape(line)}</text>`);
+    /**
+     * The graph scaled to the space left under the summary.
+     *
+     * Drawn at its own size and scaled here rather than re-rendered small: it is the same
+     * picture the record page shows, which is the whole reason it is on the card.
+     */
+    const graphTop = 300 + (summary?.lines.length ?? 0) * 36;
+    const graphRoom = { w: room, h: PREVIEW_HEIGHT - graphTop - 90 };
+    const size = options.graph ? measureSvg(options.graph) : undefined;
+    const scale = size
+        ? Math.min(graphRoom.w / size.width, graphRoom.h / size.height, 3)
+        : 1;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${PREVIEW_WIDTH}" height="${PREVIEW_HEIGHT}" viewBox="0 0 ${PREVIEW_WIDTH} ${PREVIEW_HEIGHT}">`,
+        `<rect width="${PREVIEW_WIDTH}" height="${PREVIEW_HEIGHT}" fill="${palette.background}"/>`,
+        `<g transform="translate(${margin} 64)">${markSvg(options.theme, 56)}</g>`,
+        `<text x="${margin + 68}" y="104" fill="${palette.textSecondary}" font-size="26" font-family='${FONT_STACKS.mono}'>runbooks.directory</text>`,
+        `<text x="${margin}" y="212" fill="${palette.text}" font-size="58" font-weight="500" font-family='${FONT_STACKS.sans}'>${escape(title.lines[0] ?? options.title)}</text>`,
+        ...summaryLines,
+        options.graph
+            ? `<g transform="translate(${margin} ${graphTop}) scale(${round(scale)})">${options.graph}</g>`
+            : "",
+        options.footer
+            ? `<text x="${margin}" y="${PREVIEW_HEIGHT - 44}" fill="${palette.textSecondary}" font-size="24" font-family='${FONT_STACKS.mono}'>${escape(options.footer)}</text>`
+            : "",
+        `</svg>`,
+    ].join("");
+}
+/** The drawing's own size, read off the SVG it came with. */
+function measureSvg(svg) {
+    const width = /width="(\d+(?:\.\d+)?)"/.exec(svg)?.[1];
+    const height = /height="(\d+(?:\.\d+)?)"/.exec(svg)?.[1];
+    return width && height ? { width: Number(width), height: Number(height) } : undefined;
+}
+function round(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function escape(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/primitives.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Graph visual primitives.
+ *
+ * §18.2's channel table is what keeps a graph readable: each channel encodes exactly one
+ * property and is never reused. Shape carries `kind`, colour carries `risk`, edge style
+ * carries transition semantics, badges carry discrete flags.
+ *
+ * The table is enforced structurally here, not by discipline. `nodeShape` returns
+ * geometry and knows nothing about colour — it cannot encode risk even by accident.
+ * `stateStyle` returns stroke weight and fill opacity and no hue, so simulation state
+ * cannot take the channel risk owns. A rule kept by construction survives a refactor;
+ * one kept by review does not.
+ */
+import type { Risk } from "@runbooks/schema";
+import type { NodeKind, EdgeKind } from "@runbooks/graph";
+export interface Box {
+    readonly width: number;
+    readonly height: number;
+}
+export interface Shape {
+    /** SVG path data. Geometry only — no colour, by construction. */
+    readonly path: string;
+    /** Extra geometry drawn inside the outline: the check indicator bar, the flag. */
+    readonly detail?: string;
+    /** `wait` is the only dashed outline; it is a property of the kind, not of state. */
+    readonly outlineDashed: boolean;
+}
+/**
+ * One shape per kind, distinguishable by silhouette alone — which is what makes a
+ * mini-graph on a card legible at 3-7 nodes, and what keeps the graph readable in
+ * greyscale and in print.
+ */
+export declare function nodeShape(kind: NodeKind, box: Box): Shape;
+export interface EdgeStyle {
+    readonly width: number;
+    /** SVG stroke-dasharray, or undefined for solid. */
+    readonly dash?: string;
+    /** Drawn as two parallel lines with a lock in the gap. */
+    readonly doubled: boolean;
+    /** Arrowhead points against the flow, as a rollback does. */
+    readonly reversed: boolean;
+    /** A returning arc rather than a straight run. */
+    readonly arc: boolean;
+    /** Whether the edge must carry a label (§6). */
+    readonly labelRequired: boolean;
+}
+export declare function edgeStyle(kind: EdgeKind): EdgeStyle;
+export type SimulationState = "not-reached" | "current" | "passed";
+export interface StateStyle {
+    readonly strokeWidth: number;
+    readonly fillOpacity: number;
+}
+/**
+ * Simulation and run state, expressed by stroke weight and fill only.
+ *
+ * There is deliberately no colour here and no way to add one through this type. Risk
+ * owns the hue channel; if state took it, a reader could no longer tell a destructive
+ * step from a step that happens to be current — which is the one confusion the whole
+ * colour system exists to prevent.
+ */
+export declare function stateStyle(state: SimulationState): StateStyle;
+/**
+ * Trust, as saturation, in the catalog only (§18.2). Never on the canvas: an author
+ * editing a draft would see their own work dimmed for not yet being verified, which
+ * says nothing useful and reads as a fault.
+ */
+export declare function trustSaturation(trust: "T0" | "T1" | "T2" | "T3" | "T4"): number;
+/**
+ * Hatching for print and for anyone who cannot rely on hue. Distinct per risk, so the
+ * scale survives a black-and-white printout even where lightness alone is close.
+ */
+export declare const RISK_HATCH: Readonly<Record<Risk, string>>;
+export type BadgeKind = "approval" | "untrusted" | "capability-mcp" | "capability-cli" | "capability-iam";
+/** 16px grid, 1.5px stroke, no fills (§18.2). */
+export declare function badge(kind: BadgeKind): string;

package/dist/primitives.js

@@ -0,0 +1,126 @@
+import { NODE_RADIUS } from "./tokens.js";
+const r = NODE_RADIUS;
+/**
+ * One shape per kind, distinguishable by silhouette alone — which is what makes a
+ * mini-graph on a card legible at 3-7 nodes, and what keeps the graph readable in
+ * greyscale and in print.
+ */
+export function nodeShape(kind, box) {
+    const { width: w, height: h } = box;
+    switch (kind) {
+        case "start":
+        case "end": {
+            // Capsule: fully rounded ends, unmistakable at any zoom.
+            const rad = h / 2;
+            return {
+                path: `M ${rad} 0 H ${w - rad} A ${rad} ${rad} 0 0 1 ${w - rad} ${h} H ${rad} A ${rad} ${rad} 0 0 1 ${rad} 0 Z`,
+                outlineDashed: false,
+            };
+        }
+        case "check": {
+            // Rectangle with an indicator bar down the left edge.
+            const bar = 4;
+            return {
+                path: roundedRect(w, h, r),
+                detail: `M 0 ${r} H ${bar} V ${h - r} H 0 Z`,
+                outlineDashed: false,
+            };
+        }
+        case "action":
+            return { path: roundedRect(w, h, r), outlineDashed: false };
+        case "decision": {
+            // Clipped right corner — the branch is visible before the label is read.
+            const cut = Math.min(h * 0.5, w * 0.3);
+            return {
+                path: `M ${r} 0 H ${w - cut} L ${w} ${cut} V ${h - r} A ${r} ${r} 0 0 1 ${w - r} ${h} H ${r} A ${r} ${r} 0 0 1 0 ${h - r} V ${r} A ${r} ${r} 0 0 1 ${r} 0 Z`,
+                outlineDashed: false,
+            };
+        }
+        case "wait": {
+            const rad = h / 2;
+            return {
+                path: `M ${rad} 0 H ${w - rad} A ${rad} ${rad} 0 0 1 ${w - rad} ${h} H ${rad} A ${rad} ${rad} 0 0 1 ${rad} 0 Z`,
+                outlineDashed: true,
+            };
+        }
+        case "escalate": {
+            // Flag corner on the right: terminal, and visibly a way out.
+            const flag = Math.min(h * 0.45, 12);
+            return {
+                path: roundedRect(w, h, r),
+                detail: `M ${w - flag - 6} ${h / 2 - flag / 2} L ${w - 6} ${h / 2} L ${w - flag - 6} ${h / 2 + flag / 2} Z`,
+                outlineDashed: false,
+            };
+        }
+    }
+}
+function roundedRect(w, h, rad) {
+    return `M ${rad} 0 H ${w - rad} A ${rad} ${rad} 0 0 1 ${w} ${rad} V ${h - rad} A ${rad} ${rad} 0 0 1 ${w - rad} ${h} H ${rad} A ${rad} ${rad} 0 0 1 0 ${h - rad} V ${rad} A ${rad} ${rad} 0 0 1 ${rad} 0 Z`;
+}
+export function edgeStyle(kind) {
+    switch (kind) {
+        case "next":
+            return { width: 1.5, doubled: false, reversed: false, arc: false, labelRequired: false };
+        case "branch":
+            return { width: 1.5, doubled: false, reversed: false, arc: false, labelRequired: true };
+        case "on_fail":
+            return { width: 1.5, dash: "6 4", doubled: false, reversed: false, arc: false, labelRequired: false };
+        case "rollback":
+            return { width: 1.5, dash: "1 4", doubled: false, reversed: true, arc: false, labelRequired: false };
+        case "approval":
+            return { width: 1.5, doubled: true, reversed: false, arc: false, labelRequired: true };
+        case "retry":
+            return { width: 1.5, doubled: false, reversed: false, arc: true, labelRequired: true };
+    }
+}
+/**
+ * Simulation and run state, expressed by stroke weight and fill only.
+ *
+ * There is deliberately no colour here and no way to add one through this type. Risk
+ * owns the hue channel; if state took it, a reader could no longer tell a destructive
+ * step from a step that happens to be current — which is the one confusion the whole
+ * colour system exists to prevent.
+ */
+export function stateStyle(state) {
+    switch (state) {
+        case "not-reached":
+            return { strokeWidth: 1, fillOpacity: 0 };
+        case "current":
+            return { strokeWidth: 3, fillOpacity: 0.18 };
+        case "passed":
+            return { strokeWidth: 1.5, fillOpacity: 0.08 };
+    }
+}
+/**
+ * Trust, as saturation, in the catalog only (§18.2). Never on the canvas: an author
+ * editing a draft would see their own work dimmed for not yet being verified, which
+ * says nothing useful and reads as a fault.
+ */
+export function trustSaturation(trust) {
+    return { T0: 0.35, T1: 0.5, T2: 1, T3: 1, T4: 1 }[trust];
+}
+/**
+ * Hatching for print and for anyone who cannot rely on hue. Distinct per risk, so the
+ * scale survives a black-and-white printout even where lightness alone is close.
+ */
+export const RISK_HATCH = {
+    "read-only": "none",
+    "reversible-write": "diagonal-thin",
+    destructive: "diagonal-dense",
+    irreversible: "cross",
+};
+/** 16px grid, 1.5px stroke, no fills (§18.2). */
+export function badge(kind) {
+    switch (kind) {
+        case "approval":
+            return "M 4 7 V 5 a 4 4 0 0 1 8 0 v 2 M 3 7 h 10 v 7 H 3 Z";
+        case "untrusted":
+            return "M 8 2 L 15 14 H 1 Z M 8 6 v 4 M 8 12 v 0.5";
+        case "capability-mcp":
+            return "M 2 12 V 4 l 6 5 6 -5 v 8";
+        case "capability-cli":
+            return "M 3 4 l 4 4 -4 4 M 9 12 h 5";
+        case "capability-iam":
+            return "M 8 2 l 6 3 v 4 c 0 3 -3 5 -6 6 -3 -1 -6 -3 -6 -6 V 5 Z";
+    }
+}

package/dist/primitives.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RISK_ORDER } from "@runbooks/schema";
+import { nodeShape, edgeStyle, stateStyle, trustSaturation, badge, RISK_HATCH } from "./primitives.js";
+import { specimenSheet } from "./specimen.js";
+import { riskColor, PALETTES, meetsStrokeFloor } from "./tokens.js";
+const KINDS = ["start", "check", "action", "decision", "wait", "escalate", "end"];
+const EDGES = ["next", "branch", "on_fail", "rollback", "approval", "retry"];
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * §18.2's channel table, enforced structurally. Shape carries kind and must therefore
+ * be unable to carry anything else — a rule kept by construction survives a refactor,
+ * one kept by review does not.
+ */
+describe("shape encodes kind, and nothing else", () => {
+    it.each(KINDS)("%s produces geometry with no colour in it", (kind) => {
+        const shape = nodeShape(kind, { width: 120, height: 32 });
+        const serialized = JSON.stringify(shape);
+        expect(serialized).not.toMatch(/#[0-9a-f]{3,6}/i);
+        expect(serialized).not.toMatch(/\b(fill|stroke|rgb|hsl|colou?r)\b/i);
+    });
+    // A silhouette only works if the silhouettes differ — but "silhouette" is the whole
+    // mark, not the outline alone. Outlines are shared on purpose (§18.2): check is a
+    // rectangle with an indicator bar, escalate a rectangle with a flag, wait a dashed
+    // capsule. Sharing an outline and differing in detail is the design, so distinctness
+    // is measured over the full shape.
+    it("gives every kind a distinct mark", () => {
+        const marks = KINDS.map((k) => JSON.stringify(nodeShape(k, { width: 120, height: 32 })));
+        // start and end are deliberately identical — both are terminal capsules, and the
+        // label is what tells them apart.
+        expect(new Set(marks).size).toBe(KINDS.length - 1);
+    });
+    it("shares an outline only where a detail distinguishes the kinds", () => {
+        const box = { width: 120, height: 32 };
+        const byOutline = new Map();
+        for (const kind of KINDS) {
+            const { path } = nodeShape(kind, box);
+            byOutline.set(path, [...(byOutline.get(path) ?? []), kind]);
+        }
+        for (const [, kinds] of byOutline) {
+            if (kinds.length < 2)
+                continue;
+            const marks = kinds.map((k) => JSON.stringify(nodeShape(k, box)));
+            // start/end are the one permitted collision.
+            const collisions = new Set(marks).size;
+            expect(collisions, `${kinds.join(", ")} share an outline`).toBe(kinds.includes("start") && kinds.includes("end") ? kinds.length - 1 : kinds.length);
+        }
+    });
+    it("keeps check and escalate apart by their inner detail", () => {
+        const check = nodeShape("check", { width: 120, height: 32 });
+        const escalate = nodeShape("escalate", { width: 120, height: 32 });
+        expect(check.path).toBe(escalate.path);
+        expect(check.detail).not.toBe(escalate.detail);
+    });
+    it("dashes only the wait outline, because that is a property of the kind", () => {
+        for (const kind of KINDS) {
+            expect(nodeShape(kind, { width: 120, height: 32 }).outlineDashed).toBe(kind === "wait");
+        }
+    });
+    // Legible at card scale: 3-7 nodes in a RunbookCard mini-graph.
+    it.each(KINDS)("%s still produces a valid path at mini-graph scale", (kind) => {
+        const shape = nodeShape(kind, { width: 24, height: 8 });
+        expect(shape.path).toMatch(/^M [\d.]+ [\d.]+/);
+        expect(shape.path).not.toMatch(/NaN|Infinity|-\d+\.?\d* [A-Z]/);
+    });
+});
+describe("state encodes progress, and never takes the hue channel", () => {
+    // If state took colour, a reader could not tell a destructive step from a step that
+    // happens to be current. That is the one confusion the colour system exists to stop.
+    it.each(["not-reached", "current", "passed"])("%s carries weight and fill only", (state) => {
+        expect(Object.keys(stateStyle(state)).sort()).toEqual(["fillOpacity", "strokeWidth"]);
+    });
+    it("separates the three states by stroke weight alone", () => {
+        const widths = ["not-reached", "current", "passed"].map((s) => stateStyle(s).strokeWidth);
+        expect(new Set(widths).size).toBe(3);
+    });
+});
+describe("edge style encodes transition semantics", () => {
+    it("gives every edge kind a distinct rendering", () => {
+        const signatures = EDGES.map((k) => JSON.stringify(edgeStyle(k)));
+        expect(new Set(signatures).size).toBe(EDGES.length);
+    });
+    it("points a rollback against the flow", () => {
+        expect(edgeStyle("rollback").reversed).toBe(true);
+        expect(EDGES.filter((k) => edgeStyle(k).reversed)).toEqual(["rollback"]);
+    });
+    it("requires a label exactly where §6 does", () => {
+        expect(EDGES.filter((k) => edgeStyle(k).labelRequired).sort())
+            .toEqual(["approval", "branch", "retry"]);
+    });
+});
+describe("the scale survives without colour", () => {
+    it("gives each risk a distinct hatch for print and black and white", () => {
+        expect(new Set(RISK_ORDER.map((r) => RISK_HATCH[r])).size).toBe(RISK_ORDER.length);
+    });
+    it("dims only unverified records, and never to invisibility", () => {
+        expect(trustSaturation("T0")).toBeLessThan(trustSaturation("T2"));
+        expect(trustSaturation("T0")).toBeGreaterThan(0.3);
+        expect(trustSaturation("T2")).toBe(1);
+    });
+    it("draws badges as strokes on a 16px grid with no fills", () => {
+        for (const kind of ["approval", "untrusted", "capability-mcp", "capability-cli", "capability-iam"]) {
+            const d = badge(kind);
+            expect(d).toMatch(/^M /);
+            const coords = [...d.matchAll(/-?\d+(\.\d+)?/g)].map((m) => Number(m[0]));
+            expect(Math.max(...coords)).toBeLessThanOrEqual(16);
+        }
+    });
+});
+describe("node strokes clear the contrast floor on the ground they are drawn on", () => {
+    it.each(["dark", "light"])("%s", (theme) => {
+        for (const risk of RISK_ORDER) {
+            expect(meetsStrokeFloor(riskColor(risk, theme), PALETTES[theme].surface)).toBe(true);
+        }
+    });
+});
+describe("the specimen sheet is a baseline, not decoration", () => {
+    it.each(["dark", "light"])("%s matches the checked-in file", (theme) => {
+        const baseline = readFileSync(join(HERE, "..", "specimen", `${theme}.svg`), "utf8");
+        expect(specimenSheet(theme)).toBe(baseline);
+    });
+    it("is deterministic", () => {
+        expect(specimenSheet("dark")).toBe(specimenSheet("dark"));
+    });
+    it("shows every kind, every risk, every state and every edge", () => {
+        const sheet = specimenSheet("light");
+        for (const kind of KINDS)
+            expect(sheet).toContain(`>${kind}<`);
+        for (const edge of EDGES)
+            expect(sheet).toContain(`>${edge}<`);
+    });
+});

package/dist/render.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Graph rendering: a pure function from a graph to markup.
+ *
+ * A string rather than a component, because the same renderer serves the runbook page,
+ * a card's mini-graph, the full-screen view and the CLI's SVG export. A React-only
+ * renderer would need a second implementation for the export, and two renderers drift.
+ *
+ * Server-rendered by construction: nothing here touches a DOM or waits for hydration.
+ * §18.4 puts the graph above the fold, and a graph that appears only after JavaScript
+ * loads is invisible to a crawler and to a reader on a slow connection during an
+ * incident — which is exactly when this page is opened.
+ *
+ * **What this draws, and why it is drawn that way.** The picture has one job: a reader
+ * finds the dangerous step and the way back from it in about two seconds, before reading
+ * a word. Three decisions carry that, and each replaced something that did not:
+ *
+ *  - **Every box is as wide as its own label.** Labels were not measured — the box was a
+ *    constant 168px and the title was cut at 28 characters, which is wider — so the
+ *    longest titles ran out past both edges of their outline.
+ *  - **Connectors are orthogonal.** A straight line between two boxes in different
+ *    columns crosses whatever is between them; an elbow that drops, turns once and
+ *    arrives from above never does, and it reads as a route rather than as a chord.
+ *  - **Edge labels sit on a plate of the background.** `unreachable`, `responding` and
+ *    `default` were drawn straight onto the strokes they name, at the same height, so
+ *    the three overlapped each other and the lines under them.
+ */
+import type { Graph } from "@runbooks/graph";
+import { type Theme } from "./tokens.js";
+import { type SimulationState } from "./primitives.js";
+export type RenderMode = "page" | "mini" | "fullscreen";
+/**
+ * Which way the procedure runs.
+ *
+ * Vertical by default, which is a reversal. Horizontal was chosen when the graph was a
+ * fixed picture that had to fit above the fold on a landscape screen; the graph now has a
+ * viewer with zoom, panning and a full-screen mode, so height costs a scroll rather than
+ * a third of the drawing, and the argument that decided it no longer holds.
+ *
+ * What decided it the second time is reading order. A procedure is a sequence of steps
+ * and every reader of one already reads top to bottom; laid out that way the happy path
+ * is a straight vertical line and a branch is a visible departure from it. Sideways, the
+ * happy path was the line the eye had to learn.
+ *
+ * It also buys room. Sideways, parallel branches stack into the short axis and the
+ * routing has to thread lanes between them; downwards they spread into the width, which
+ * is the axis with space to spare — which is most of why the crossings this renderer used
+ * to have were where they were.
+ *
+ * The axis assignments turn with it: the happy path is the centre axis either way,
+ * `on_fail` and `escalate` leave it on one side and `rollback` on the other.
+ */
+export type Direction = "horizontal" | "vertical";
+export interface RenderOptions {
+    readonly theme: Theme;
+    readonly mode?: RenderMode;
+    /** Per-node simulation or run state. Absent nodes render as not-reached. */
+    readonly states?: Readonly<Record<string, SimulationState>>;
+    /** Prefix for element ids, so two graphs on one page do not collide. */
+    readonly idPrefix?: string;
+    /**
+     * Positions to draw at, instead of this graph's own layout (W-17).
+     *
+     * A diff draws two versions over the coordinates of their union, which is what makes
+     * "unchanged regions do not shift" true rather than nearly true: laying each version out
+     * separately moves everything below an inserted step, and the reader compares two
+     * pictures that disagree about where the procedure is.
+     */
+    readonly positions?: Readonly<Record<string, {
+        readonly x: number;
+        readonly y: number;
+    }>>;
+    /** Defaults to vertical. See `Direction`. */
+    readonly direction?: Direction;
+}
+export interface GraphRender {
+    /** The picture. Hidden from assistive technology — the list carries the content. */
+    readonly svg: string;
+    /**
+     * Where each node was drawn, in the picture's own coordinates.
+     *
+     * Returned because the geometry is the part worth asserting: that a label fits inside
+     * its outline, and that no connector crosses a box it is not attached to, are claims
+     * about rectangles, and reading them back out of path data would be a second renderer.
+     */
+    readonly boxes: Readonly<Record<string, {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly h: number;
+    }>>;
+    /** The same procedure as an ordered list. A procedure that cannot be read linearly
+     *  is inaccessible, and this is what a screen reader and a no-CSS reader get. */
+    readonly list: string;
+    readonly width: number;
+    readonly height: number;
+}
+export declare function renderGraph(graph: Graph, options: RenderOptions): GraphRender;