@runbooks/design 0.1.0

package/dist/render.js

@@ -0,0 +1,1085 @@
+import { layout, topologicalOrder } from "@runbooks/graph";
+import { PALETTES, riskColor, RISK_LABELS, FONT_STACKS } from "./tokens.js";
+import { nodeShape, edgeStyle, stateStyle, RISK_HATCH } from "./primitives.js";
+import { measure, wrap } from "./text.js";
+/**
+ * Risk on paper (§18.2, D-02).
+ *
+ * Hue is risk's channel and print does not have it. `RISK_HATCH` has always named a
+ * pattern per level and `data-hatch` has always carried the name — and nothing ever drew
+ * one, while the print rule set `fill:none` on exactly those nodes. So a page printed from
+ * this catalog showed a destructive step and a read-only step as the same grey outline:
+ * the channel that carries the one property a reader must not miss was removed, and its
+ * declared substitute was never painted.
+ *
+ * Black on transparent, because the substitute exists for a sheet of paper that has no
+ * colour left to lose. Ids carry the graph's prefix: a catalog page holds twenty graphs
+ * and a bare id would make the twentieth borrow the first one's fill.
+ */
+function hatchPatterns(prefix) {
+    const pattern = (name, size, body) => `<pattern id="${prefix}-hatch-${name}" width="${size}" height="${size}" patternUnits="userSpaceOnUse">${body}</pattern>`;
+    return (pattern("diagonal-thin", 6, `<path d="M 0 6 L 6 0" stroke="#000" stroke-width="0.8" fill="none"/>`) +
+        pattern("diagonal-dense", 3, `<path d="M 0 3 L 3 0" stroke="#000" stroke-width="0.9" fill="none"/>`) +
+        pattern("cross", 4, `<path d="M 0 4 L 4 0 M 0 0 L 4 4" stroke="#000" stroke-width="0.9" fill="none"/>`));
+}
+/** Each level's fill on paper. `none` stays unfilled: read-only is the absence of hatching. */
+function hatchPrintRules(prefix) {
+    const filled = ["diagonal-thin", "diagonal-dense", "cross"]
+        .map((name) => `.runbook-graph [data-hatch="${name}"]{fill:url(#${prefix}-hatch-${name});fill-opacity:1}`)
+        .join("");
+    return `@media print{.runbook-graph [data-hatch="none"]{fill:none}${filled}}`;
+}
+/**
+ * Geometry per mode.
+ *
+ * `minW`/`maxW` bound the fitted width rather than fixing it. The gaps are what the
+ * elbows and the edge labels are routed in, so they are generous on purpose: a diagram
+ * that is 15% larger and legible beats a compact one nobody can read during an incident.
+ */
+const GEOM = {
+    page: { minW: 132, maxW: 260, padX: 18, lineH: 19, minH: 56, gapFlow: 104, gapCross: 72, font: 14, labels: true },
+    fullscreen: { minW: 152, maxW: 300, padX: 20, lineH: 21, minH: 64, gapFlow: 124, gapCross: 88, font: 15, labels: true },
+    mini: { minW: 26, maxW: 26, padX: 0, lineH: 0, minH: 9, gapFlow: 10, gapCross: 9, font: 0, labels: false },
+};
+/** How much of a node's width its own shape spends on something other than the label. */
+const SHAPE_INSET = {
+    check: { left: 8, right: 0 },
+    decision: { left: 0, right: 14 },
+    escalate: { left: 0, right: 22 },
+    action: { left: 0, right: 0 },
+    wait: { left: 0, right: 0 },
+    start: { left: 0, right: 0 },
+    end: { left: 0, right: 0 },
+};
+const MAX_LINES = 2;
+/**
+ * The length of the 45° cut at a turn.
+ *
+ * Every segment runs at 0° or 90°, and a corner is a corner: two segments meeting at a
+ * point. The first version cut each turn with a short 45° diagonal, on the theory that a
+ * mitre reads more deliberately than a right angle. At the sizes these are drawn it does
+ * not — an 8px cut on a 90° turn is too small to read as an angle and too big to read as
+ * a point, so every corner looked blunted rather than square, which is the one thing a
+ * right angle is for. The only diagonals left in the drawing are the bridge ramps, where
+ * 45° is doing actual work.
+ */
+/** How far short of the target a line stops, so the arrowhead sits beside the box. */
+/** The widest a card's silhouette may be drawn. A card is 320 and a graph does not set it. */
+const MINI_MAX_WIDTH = 320;
+/** How far two edge labels have to be before they read as two labels. */
+const LABEL_CLEAR = 9;
+/**
+ * How far a turn keeps from the box on either side of it.
+ *
+ * The same rule at both ends of a route. Six pixels of clearance on the way out drew a
+ * whisker on the underside of a box; six on the way in drew an arrowhead floating below
+ * one, because the last leg is trimmed by the arrow gap and three pixels of line under a
+ * head is not an arrival. A leg has to be long enough to have a direction.
+ */
+const TURN_CLEAR = 16;
+const ARROW_GAP = 3;
+/**
+ * The bridge drawn where two lines cross: half its width, and how far it steps aside.
+ *
+ * A square step, four right angles. It was a trapezoid — up a 45° ramp, a short flat, down
+ * another — which is a legal shape in a drawing of 0°, 45° and 90° and still the wrong one:
+ * at six pixels wide the flat is invisible, so the two ramps read as a single blunt kink
+ * rather than as anything deliberate, and three crossings in a row read as a torn edge. A
+ * right angle at this size is unambiguous, and the hop is the one place a reader has to
+ * see immediately that the line did not turn.
+ */
+const BRIDGE = 6;
+const RISE = 5;
+/** Kept inside a range, and tolerant of a range narrower than the value it is given. */
+function clamp(value, low, high) {
+    return low > high ? (low + high) / 2 : Math.min(Math.max(value, low), high);
+}
+const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+export function renderGraph(graph, options) {
+    const mode = options.mode ?? "page";
+    const g = GEOM[mode];
+    const theme = options.theme;
+    const base = PALETTES[theme];
+    /**
+     * Colours as custom properties, with the drawn theme's value as the fallback.
+     *
+     * One drawing serves both themes: inside a page it takes whatever `data-theme` is in
+     * force, and opened on its own — the SVG export, an embed — it keeps the colours it was
+     * rendered with. Without this, the graph is fixed at build time and a reader who
+     * switches the theme gets a white picture on a black page, which is exactly what
+     * happened the day the catalog turned dark.
+     */
+    const palette = {
+        background: `var(--rb-background, ${base.background})`,
+        surface: `var(--rb-surface, ${base.surface})`,
+        border: `var(--rb-border, ${base.border})`,
+        text: `var(--rb-text, ${base.text})`,
+        textSecondary: `var(--rb-text-secondary, ${base.textSecondary})`,
+        trust: `var(--rb-trust, ${base.trust})`,
+    };
+    const prefix = options.idPrefix ?? "g";
+    const direction = options.direction ?? "vertical";
+    const laid = options.positions ?? layout(graph).positions;
+    /**
+     * Horizontal is the same layering read along the other axis: the layer becomes the
+     * column and the off-axis rank becomes the row. Transposing here rather than in
+     * `layout()` keeps one layering — and keeps a diff's shared coordinates meaningful,
+     * since both versions are transposed the same way.
+     */
+    const positions = direction === "horizontal"
+        ? Object.fromEntries(Object.entries(laid).map(([id, p]) => [id, { x: p.y, y: p.x }]))
+        : { ...laid };
+    const order = topologicalOrder(graph);
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    /**
+     * Each node sized to its own label.
+     *
+     * A terminal says "start" or "success" and has no business being as wide as a step
+     * whose title is a sentence; a step whose title is a sentence has no business being
+     * cut. Both follow from measuring instead of assuming.
+     */
+    const fitted = new Map();
+    for (const node of graph.nodes) {
+        if (!g.labels) {
+            fitted.set(node.id, { lines: [], width: g.minW, height: g.minH });
+            continue;
+        }
+        const inset = SHAPE_INSET[node.kind] ?? { left: 0, right: 0 };
+        const room = g.maxW - g.padX * 2 - inset.left - inset.right;
+        const { lines, width } = wrap(node.title, g.font, room, MAX_LINES);
+        fitted.set(node.id, {
+            lines,
+            width: Math.min(g.maxW, Math.max(g.minW, Math.ceil(width) + g.padX * 2 + inset.left + inset.right)),
+            height: Math.max(g.minH, lines.length * g.lineH + 20),
+        });
+    }
+    // One row height per layer and one column width per column, so the grid stays square
+    // even though the boxes differ: a ragged grid is harder to scan than a wide one.
+    const xs = Object.values(positions).map((p) => p.x);
+    const minX = Math.min(...xs);
+    const cols = Math.max(...xs) - minX + 1;
+    const ys = Object.values(positions).map((p) => p.y);
+    const minY = Math.min(...ys);
+    const rows = Math.max(...ys) - minY + 1;
+    const colWidth = Array.from({ length: cols }, () => g.minW);
+    const rowHeight = Array.from({ length: rows }, () => g.minH);
+    for (const [id, p] of Object.entries(positions)) {
+        const box = fitted.get(id);
+        if (!box)
+            continue;
+        const column = p.x - minX;
+        colWidth[column] = Math.max(colWidth[column], box.width);
+        rowHeight[p.y - minY] = Math.max(rowHeight[p.y - minY], box.height);
+    }
+    // The flow gap is the one the lanes and the edge labels are routed in, so it is the
+    // generous one; the cross gap only holds branches apart.
+    const gapX = direction === "horizontal" ? g.gapFlow : g.gapCross;
+    const gapY = direction === "horizontal" ? g.gapCross : g.gapFlow;
+    const pad = mode === "mini" ? 4 : 24;
+    const colLeft = [];
+    let cursorX = pad;
+    for (let column = 0; column < cols; column++) {
+        colLeft.push(cursorX);
+        cursorX += colWidth[column] + gapX;
+    }
+    const rowTop = [];
+    let cursorY = pad;
+    for (let row = 0; row < rows; row++) {
+        rowTop.push(cursorY);
+        cursorY += rowHeight[row] + gapY;
+    }
+    const width = cursorX - gapX + pad;
+    const height = cursorY - gapY + pad;
+    /** A node's own box, centred in its column and its row. */
+    const boxOf = (id) => {
+        const p = positions[id];
+        const size = fitted.get(id) ?? { lines: [], width: g.minW, height: g.minH };
+        const column = p.x - minX;
+        const row = p.y - minY;
+        const x = colLeft[column] + (colWidth[column] - size.width) / 2;
+        const y = rowTop[row] + (rowHeight[row] - size.height) / 2;
+        return { x, y, w: size.width, h: size.height, lines: size.lines };
+    };
+    const labelPlates = [];
+    /**
+     * The edges worth drawing.
+     *
+     * `approval` is derived, not authored: the model adds one at every arrival into a gated
+     * step, alongside the transition that was already there. Drawn, that is a second line
+     * between the same two boxes in the same direction and a second arrowhead on the target
+     * — a picture that says "and this one needs approval" about a box that is already
+     * wearing a padlock. On the withdrawal record it was five of the fifteen lines.
+     *
+     * It is dropped only where the pair is already connected. An approval edge that stands
+     * alone is the only line saying those two steps are joined at all, and it stays.
+     */
+    const drawable = graph.edges.filter((e) => {
+        if (e.kind !== "approval")
+            return true;
+        if (mode === "mini")
+            return false;
+        return !graph.edges.some((other) => other.kind !== "approval" && other.from === e.from && other.to === e.to);
+    });
+    /**
+     * A lane per edge, so two edges leaving the same place do not draw over each other.
+     *
+     * Numbered within the group that shares a gutter — the column an edge leaves, for a
+     * forward edge — and in document order, so the picture is byte-identical across builds.
+     */
+    const laneOf = new Map();
+    const groups = new Map();
+    drawable.forEach((e, index) => {
+        const a = boxOf(e.from);
+        const b = boxOf(e.to);
+        const backwards = direction === "horizontal" ? b.x + b.w <= a.x + 1 : b.y + b.h <= a.y + 1;
+        const key = backwards
+            ? `back:${direction === "horizontal" ? (a.y <= b.y ? "up" : "down") : a.x <= b.x ? "left" : "right"}`
+            : `fwd:${direction === "horizontal" ? Math.round(a.x + a.w) : Math.round(a.y + a.h)}`;
+        const list = groups.get(key) ?? [];
+        list.push(index);
+        groups.set(key, list);
+    });
+    for (const list of groups.values()) {
+        list.forEach((index, position) => laneOf.set(index, { lane: position, lanes: list.length }));
+    }
+    // The extent of the boxes, so a lane can be put outside all of them.
+    const drawn = graph.nodes.map((n) => boxOf(n.id));
+    const drawnTop = Math.min(...drawn.map((b) => b.y));
+    const drawnBottom = Math.max(...drawn.map((b) => b.y + b.h));
+    const drawnLeft = Math.min(...drawn.map((b) => b.x));
+    const drawnRight = Math.max(...drawn.map((b) => b.x + b.w));
+    /**
+     * Where a route may travel: a horizontal strip, or a vertical one, that no box occupies.
+     *
+     * Computed from the boxes rather than from row indices. The first version asked which
+     * row a coordinate was in and took the gutter past it, which is right when every box
+     * fills its row and wrong the moment they differ in height — it returned a y inside a
+     * row, and a long edge then drew its horizontal run straight through three nodes. Boxes
+     * are what a line must miss, so boxes are what the answer is derived from.
+     */
+    const clearBand = (from, to, intervals) => {
+        const low = Math.min(from, to);
+        const high = Math.max(from, to);
+        if (high - low < 8)
+            return undefined;
+        // Every box edge between the two, as candidate boundaries.
+        const blocked = intervals
+            .filter((i) => i.end > low && i.start < high)
+            .sort((a, b) => a.start - b.start);
+        let cursor = low;
+        let best;
+        for (const interval of [...blocked, { start: high, end: high }]) {
+            const gap = interval.start - cursor;
+            if (gap > 6 && (!best || gap > best.width)) {
+                best = { start: cursor, width: gap };
+            }
+            cursor = Math.max(cursor, interval.end);
+        }
+        if (!best)
+            return undefined;
+        /**
+         * Each route that takes this band gets its own line inside it.
+         *
+         * The band used to answer with its midpoint, which is the same answer for every
+         * caller — so on a procedure where five steps all route to one place, five lines came
+         * out of five different boxes, converged onto one y six pixels apart, and arrived as
+         * a single thick stroke with five arrowheads on it. A band is a strip with width, and
+         * the routes are spread across it.
+         *
+         * Counted per band and in the order routes are computed, which is document order, so
+         * the same graph draws the same picture on every build.
+         */
+        const key = `${Math.round(best.start)}:${Math.round(best.width)}`;
+        const taken = used.get(key) ?? 0;
+        used.set(key, taken + 1);
+        /**
+         * Far enough from the box that leaving it is a segment, not a whisker.
+         *
+         * The first route to take a band used to get six pixels of clearance, so an edge
+         * dropped six pixels out of the underside of its box and then ran sideways — which at
+         * this scale does not read as "down, then across". It reads as a burr on the box, and
+         * three branches leaving one decision read as teeth. A turn has to be far enough from
+         * what it left for the eye to see two directions.
+         */
+        const clearance = Math.min(20, Math.max(10, best.width / 4));
+        const step = Math.max(14, Math.min(24, best.width / 5));
+        const room = Math.max(0, best.width - clearance * 2);
+        return best.start + clearance + (room > 0 ? ((taken * step) % room) : 0);
+    };
+    /**
+     * The middle of the widest-enough gap between the given intervals, nearest to `want`.
+     *
+     * Gaps at the ends count: outside the drawing is a legitimate place for a corridor, it
+     * is only a bad one when there is something closer.
+     */
+    const nearestGap = (want, intervals) => {
+        const sorted = [...intervals].sort((a, b) => a.start - b.start);
+        const candidates = [];
+        let cursor = -Infinity;
+        for (const interval of sorted) {
+            if (cursor > -Infinity && interval.start - cursor > 14) {
+                candidates.push(cursor + (interval.start - cursor) / 2);
+            }
+            cursor = Math.max(cursor, interval.end);
+        }
+        if (sorted.length > 0) {
+            candidates.push(sorted[0].start - 22, cursor + 22);
+        }
+        let best;
+        for (const candidate of candidates) {
+            if (best === undefined || Math.abs(candidate - want) < Math.abs(best - want))
+                best = candidate;
+        }
+        return best;
+    };
+    /** How many routes have already taken each band. See `clearBand`. */
+    const used = new Map();
+    const boxIntervals = drawn.map((b) => ({ start: b.y, end: b.y + b.h }));
+    const colIntervals = drawn.map((b) => ({ start: b.x, end: b.x + b.w }));
+    const channel = {
+        top: drawnTop,
+        bottom: drawnBottom,
+        left: drawnLeft,
+        right: drawnRight,
+        bandBetween: (fromY, toY) => clearBand(fromY, toY, boxIntervals),
+        /**
+         * The clear strip immediately to the left of `x`, from the boxes rather than the grid.
+         *
+         * This used to be the midpoint of the gutter between two *columns*, which is a
+         * different thing: a column is as wide as its widest box, so a narrow box centred in
+         * a wide column leaves space inside the column that the grid says is occupied and the
+         * drawing says is free — and the descent landed inside a node. What a line has to
+         * miss is a box.
+         */
+        gutterBefore: (x) => {
+            const leftOf = drawn.filter((b) => b.x + b.w <= x + 0.5).map((b) => b.x + b.w);
+            const edge = leftOf.length > 0 ? Math.max(...leftOf) : x - gapX;
+            return edge + Math.max(4, Math.min(gapX / 2, (x - edge) / 2));
+        },
+        bandBeside: (fromX, toX) => clearBand(fromX, toX, colIntervals),
+        nearestColumn: (x) => nearestGap(x, colIntervals),
+        nearestRow: (y) => nearestGap(y, boxIntervals),
+        columnClear: (x, from, to) => {
+            const low = Math.min(from, to);
+            const high = Math.max(from, to);
+            return !drawn.some((b) => x > b.x + 0.5 && x < b.x + b.w - 0.5 && b.y < high - 0.5 && b.y + b.h > low + 0.5);
+        },
+        rowClear: (y, from, to) => {
+            const low = Math.min(from, to);
+            const high = Math.max(from, to);
+            return !drawn.some((b) => y > b.y + 0.5 && y < b.y + b.h - 0.5 && b.x < high - 0.5 && b.x + b.w > low + 0.5);
+        },
+        /** The clear strip immediately above `y`. `gutterBefore` turned, and for its reason. */
+        gutterAbove: (y) => {
+            const above = drawn.filter((b) => b.y + b.h <= y + 0.5).map((b) => b.y + b.h);
+            const edge = above.length > 0 ? Math.max(...above) : y - gapY;
+            return edge + Math.max(4, Math.min(gapY / 2, (y - edge) / 2));
+        },
+    };
+    /**
+     * How many connections each node has on each side, and which one this is.
+     *
+     * Counted over the drawn edges in document order, so the spread is the same on every
+     * build. `reversed` edges are counted at the end they are drawn from, not the end the
+     * model names as the source: a rollback is drawn arriving at the step it undoes.
+     */
+    const outAt = new Map();
+    const inAt = new Map();
+    const outOf = new Map();
+    const intoOf = new Map();
+    drawable.forEach((e, index) => {
+        const style = edgeStyle(e.kind);
+        const tail = style.reversed ? e.to : e.from;
+        const head = style.reversed ? e.from : e.to;
+        (outOf.get(tail) ?? outOf.set(tail, []).get(tail)).push(index);
+        (intoOf.get(head) ?? intoOf.set(head, []).get(head)).push(index);
+    });
+    for (const list of outOf.values()) {
+        list.forEach((index, position) => outAt.set(index, { index: position, count: list.length }));
+    }
+    for (const list of intoOf.values()) {
+        list.forEach((index, position) => inAt.set(index, { index: position, count: list.length }));
+    }
+    const routes = drawable.map((e, index) => {
+        const style = edgeStyle(e.kind);
+        const a = boxOf(e.from);
+        const b = boxOf(e.to);
+        const [from, to] = style.reversed ? [b, a] : [a, b];
+        const { lane, lanes } = laneOf.get(index) ?? { lane: 0, lanes: 1 };
+        const out = outAt.get(index);
+        const into = inAt.get(index);
+        const anchors = { ...(out ? { out } : {}), ...(into ? { in: into } : {}) };
+        return direction === "horizontal"
+            ? connectorAcross(from, to, gapX, lane, lanes, channel, anchors)
+            : connectorDown(from, to, gapY, lane, lanes, channel, anchors);
+    });
+    const bumps = mode === "mini" ? new Map() : crossings(routes);
+    /**
+     * The canvas grown to hold the lanes, and everything shifted back inside it.
+     *
+     * A lane routed clear of every box is often outside the grid the boxes were placed on,
+     * so the picture has to make room for it — otherwise the connector that goes round is
+     * the one clipped off the edge of the SVG.
+     */
+    const routePoints = routes.flatMap((route) => route.points);
+    const extentLeft = Math.min(pad, ...routePoints.map((point) => point.x));
+    const extentTop = Math.min(pad, ...routePoints.map((point) => point.y));
+    const extentRight = Math.max(width - pad, ...routePoints.map((point) => point.x));
+    const extentBottom = Math.max(height - pad, ...routePoints.map((point) => point.y));
+    const shiftX = extentLeft < pad ? pad - extentLeft : 0;
+    const shiftY = extentTop < pad ? pad - extentTop : 0;
+    const canvasWidth = Math.ceil(extentRight + shiftX + pad);
+    const canvasHeight = Math.ceil(extentBottom + shiftY + pad);
+    /**
+     * Where a label goes, and then nudged apart where two of them landed together.
+     *
+     * Two branches out of one decision can reach their targets by different routes — one
+     * straight across the gutter, one round a band — and each route puts its label at the
+     * middle of its own first run, which for a shared stub is the same point twice. The
+     * routes are right and the reader needs both of them; it is only the two words that
+     * collide, so the words are what moves.
+     */
+    const labelSpots = routes.map((route) => ({ ...labelSpot(route) }));
+    const labelled = drawable
+        .map((e, index) => (g.labels && e.label ? index : -1))
+        .filter((index) => index >= 0);
+    for (const index of labelled) {
+        const spot = labelSpots[index];
+        const placed = labelled.filter((other) => other < index).map((other) => labelSpots[other]);
+        // Downwards until it is clear of every label already placed. A label pushed onto a
+        // third is not settled, so the check repeats rather than running once.
+        for (let guard = 0; guard < placed.length + 1; guard += 1) {
+            const hit = placed.find((other) => Math.abs(spot.x - other.x) <= LABEL_CLEAR && Math.abs(spot.y - other.y) <= LABEL_CLEAR);
+            if (!hit)
+                break;
+            spot.y = hit.y + LABEL_CLEAR + 1;
+        }
+    }
+    /**
+     * A silhouette is a fixed size, whatever the procedure's length.
+     *
+     * A card's mini-graph is a signature, not a diagram: it is read at a glance beside four
+     * others, and the thing it has to communicate — does this branch, is there red in it —
+     * survives being small. A nine-step procedure laid out at the same node size as a
+     * five-step one is simply wider than the card, so the drawing keeps its geometry and the
+     * element is given the card's width; the viewBox does the rest.
+     */
+    const scale = mode === "mini" ? Math.min(1, MINI_MAX_WIDTH / canvasWidth) : 1;
+    const drawnWidth = Math.round(canvasWidth * scale);
+    const drawnHeight = Math.round(canvasHeight * scale);
+    const edges = drawable
+        .map((e, index) => {
+        const style = edgeStyle(e.kind);
+        const route = routes[index];
+        const d = toPath(route.points, bumps.get(index) ?? []);
+        const stroke = palette.textSecondary;
+        if (g.labels && e.label) {
+            // On a plate of the background, so the word is readable over whatever it crosses.
+            const size = 11;
+            const at = labelSpots[index];
+            const w = measure(e.label, size) + 8;
+            labelPlates.push(`<g data-edge-label="${escape(e.label)}">` +
+                `<rect x="${round(at.x - w / 2)}" y="${round(at.y - size / 2 - 3)}" width="${round(w)}" height="${size + 6}" rx="3" fill="${palette.background}"/>` +
+                `<text x="${round(at.x)}" y="${round(at.y + 4)}" fill="${stroke}" font-size="${size}" text-anchor="middle" font-family='${FONT_STACKS.mono}'>${escape(e.label)}</text>` +
+                `</g>`);
+        }
+        return (`<g data-edge="${escape(e.from)}-${escape(e.to)}" data-edge-kind="${escape(e.kind)}" data-from="${escape(e.from)}" data-to="${escape(e.to)}">` +
+            // A wide transparent copy underneath: a 1px line is not a thing a pointer can
+            // find, and an edge you cannot point at cannot be highlighted.
+            (mode === "mini" ? "" : `<path d="${d}" fill="none" stroke="transparent" stroke-width="12" data-hit="1"/>`) +
+            `<path d="${d}" fill="none" stroke="${stroke}" stroke-width="${style.width}"` +
+            (style.dash ? ` stroke-dasharray="${style.dash}"` : "") +
+            ` marker-end="url(#${prefix}-arrow)" data-line="1"/>` +
+            (style.doubled
+                ? `<path d="${d}" fill="none" stroke="${stroke}" stroke-width="${style.width}" transform="translate(0 3)" data-line="1"/>`
+                : "") +
+            `</g>`);
+    })
+        .join("");
+    const nodes = order
+        .map((id, index) => {
+        const node = byId.get(id);
+        const box = boxOf(id);
+        const shape = nodeShape(node.kind, { width: box.w, height: box.h });
+        const state = options.states?.[id] ?? "not-reached";
+        const s = stateStyle(state);
+        const stroke = node.risk
+            ? `var(--rb-risk-${node.risk}, ${riskColor(node.risk, theme)})`
+            : palette.textSecondary;
+        const inset = SHAPE_INSET[node.kind] ?? { left: 0, right: 0 };
+        // Centred in the room the shape leaves, not in the shape: a decision's clipped
+        // corner and an escalation's flag are drawn over the right-hand edge, and text
+        // centred on the whole box slides underneath them.
+        const centre = inset.left + (box.w - inset.left - inset.right) / 2;
+        const first = box.h / 2 - ((box.lines.length - 1) * g.lineH) / 2 + 4;
+        const label = g.labels
+            ? box.lines
+                .map((line, lineIndex) => `<text x="${round(centre)}" y="${round(first + lineIndex * g.lineH)}" fill="${palette.text}" font-size="${g.font}" text-anchor="middle" font-family='${FONT_STACKS.sans}'>${escape(line)}</text>`)
+                .join("")
+            : "";
+        // The one property in the picture a reader must not miss, drawn as a shape that
+        // says what it is rather than as an unlabelled dot in a corner.
+        const badgeMark = g.labels && node.requiresApproval ? padlock(box.w - 19, 8, palette.text) : "";
+        return (`<g transform="translate(${round(box.x)} ${round(box.y)})" tabindex="${mode === "mini" ? -1 : 0}" data-node="${escape(id)}" data-order="${index}">` +
+            `<path d="${shape.path}" fill="${palette.text}" fill-opacity="${s.fillOpacity}" stroke="${stroke}" stroke-width="${s.strokeWidth}"` +
+            (shape.outlineDashed ? ' stroke-dasharray="5 3"' : "") +
+            (node.risk ? ` data-hatch="${RISK_HATCH[node.risk]}"` : "") +
+            `/>` +
+            (shape.detail ? `<path d="${shape.detail}" fill="${stroke}"/>` : "") +
+            label +
+            badgeMark +
+            `</g>`);
+    })
+        .join("");
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${canvasWidth} ${canvasHeight}" width="${drawnWidth}" height="${drawnHeight}" aria-hidden="true" focusable="false" class="runbook-graph runbook-graph--${mode}">` +
+        `<defs><marker id="${prefix}-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="6" markerHeight="6" orient="auto">` +
+        `<path d="M 0 0 L 8 4 L 0 8 z" fill="${palette.textSecondary}"/></marker>` +
+        hatchPatterns(prefix) +
+        `</defs>` +
+        // Motion only where it shows a change, and none at all when the reader asks for none.
+        `<style>@media (prefers-reduced-motion: reduce){.runbook-graph *{transition:none!important;animation:none!important}}` +
+        hatchPrintRules(prefix) +
+        // Pointing at something says which one thing it is. Weight and opacity only — hue is
+        // risk's channel and nothing else may borrow it (§18.2).
+        `.runbook-graph [data-edge]{cursor:default}` +
+        `.runbook-graph [data-edge]:hover [data-line]{stroke-width:2.6}` +
+        `.runbook-graph [data-node]:hover>path:first-of-type,.runbook-graph [data-node]:focus-visible>path:first-of-type{stroke-width:2.6}` +
+        `.runbook-graph [data-node]:focus-visible{outline:none}` +
+        `.runbook-graph:hover [data-edge]:not(:hover) [data-line]{stroke-opacity:.45}` +
+        `.runbook-graph:has([data-edge]:hover) [data-node]{opacity:.75}` +
+        /**
+         * Pointing at a step picks out everything that touches it.
+         *
+         * How many ways out a step has is the question a reader asks of a branch, and the
+         * lines are spread along its side so they can be counted — but only once the others
+         * are out of the way. `:has` is what makes that possible without script; a browser
+         * without it still gets the spread lines and the per-edge highlight.
+         */
+        nodeEdgeRules(graph) +
+        `</style>` +
+        `<rect width="${canvasWidth}" height="${canvasHeight}" fill="${palette.background}"/>` +
+        `<g transform="translate(${round(shiftX)} ${round(shiftY)})">` +
+        edges +
+        nodes +
+        // Above the nodes as well as the edges: a label belongs to the reader, not to a layer.
+        labelPlates.join("") +
+        `</g>` +
+        `</svg>`;
+    const boxes = Object.fromEntries(graph.nodes.map((node) => {
+        const box = boxOf(node.id);
+        return [node.id, { x: box.x + shiftX, y: box.y + shiftY, w: box.w, h: box.h }];
+    }));
+    return { svg, list: renderList(graph, order, byId), width: drawnWidth, height: drawnHeight, boxes };
+}
+/**
+ * A point on a box's side.
+ *
+ * One connection sits in the middle; several are spread evenly across the middle 70% of
+ * the side, which keeps them clear of the rounded ends of a capsule and of the clipped
+ * corner of a decision.
+ */
+function anchor(start, size, at) {
+    if (!at || at.count <= 1)
+        return start + size / 2;
+    const span = size * 0.7;
+    return start + size / 2 - span / 2 + (span * at.index) / (at.count - 1);
+}
+/**
+ * A route from one box to another, along free channels only.
+ *
+ * Every segment is horizontal or vertical, every turn is cut at 45°, and no segment ever
+ * enters a box: forward edges leave the right-hand side into the gutter between two
+ * columns, take a vertical lane there — gutters hold no nodes, which is what makes going
+ * around them structural rather than lucky — and arrive at the left-hand side of the
+ * target. Backward edges are the same idea turned: out of the top or bottom, along a
+ * lane clear of every row, and back in the same way.
+ *
+ * `lane` distributes the vertical runs across the gutter so two edges leaving the same
+ * column do not draw over each other.
+ */
+function connectorAcross(from, to, gap, lane_ = 0, lanes = 1, channel, anchors) {
+    /**
+     * Where on the box this edge leaves and arrives.
+     *
+     * Every edge used to leave from the middle of the side, so three branches out of one
+     * decision left the same point and a reader could not tell three from one without
+     * following each line to its end. Spread along the side, the count is the picture.
+     */
+    const fromCy = anchor(from.y, from.h, anchors?.out);
+    const toCy = anchor(to.y, to.h, anchors?.in);
+    const fromRight = from.x + from.w;
+    const backwards = to.x + to.w <= from.x + 1;
+    // The same case as `connectorDown`'s `sameRow`, turned: a retry, or a target in the
+    // same column. It goes round the right-hand side rather than under.
+    const sameColumn = to.x < from.x + from.w - 1 && to.x + to.w > from.x + 1;
+    if (sameColumn) {
+        const x = channel?.bandBeside(fromRight, fromRight + gap) ?? fromRight + gap / 2;
+        return {
+            points: [
+                { x: fromRight, y: fromCy },
+                { x, y: fromCy },
+                { x, y: toCy },
+                { x: to.x + to.w, y: toCy },
+            ],
+            labelAt: { x, y: (fromCy + toCy) / 2 },
+        };
+    }
+    if (!backwards && Math.abs(fromCy - toCy) < 2) {
+        /**
+         * Drawn at one height, not two.
+         *
+         * "Close enough to be straight" was treated as straight and then drawn between the two
+         * different heights, which is a line at about 2° — the one slope this drawing is not
+         * allowed to have. The anchors are spread along a node's side, so a pair can land
+         * within a pixel or two of each other and this became reachable the moment a record
+         * had more connections than the corpus used to.
+         */
+        const y = (fromCy + toCy) / 2;
+        return {
+            points: [
+                { x: fromRight, y },
+                { x: to.x, y },
+            ],
+            labelAt: { x: (fromRight + to.x) / 2, y: y - 9 },
+        };
+    }
+    if (!backwards) {
+        /**
+         * A strip no box occupies, divided so parallel edges keep apart.
+         *
+         * "The gutter between the two columns" was the wrong measure: a column is as wide as
+         * its widest box and boxes are centred in it, so a narrow box leaves space inside its
+         * own column that the grid calls a gutter and a taller sibling in another row is
+         * standing in. The clear strip is computed from the boxes; the lanes are spread inside
+         * it.
+         */
+        // See the note in `connectorDown`: the band separates, the lane spread is the fallback,
+        // and the result stays between the two boxes either way.
+        const strip = channel?.bandBeside(fromRight, to.x);
+        const spread = Math.max(10, Math.min(20, (gap - 28) / Math.max(lanes, 1)));
+        const wanted = strip ?? fromRight + Math.max(gap / 2, 8) + (lane_ - (lanes - 1) / 2) * spread;
+        const x = clamp(wanted, fromRight + TURN_CLEAR, to.x - TURN_CLEAR);
+        /**
+         * A run along the target's own row crosses whatever else is on it.
+         *
+         * That is only safe when the target is the next thing along. Reaching further — the
+         * `on_fail` from `Confirm the node is NotReady` to `Escalate to the cluster owner`, four
+         * columns away — put a horizontal line at the escalation's height straight through
+         * `Drain the node`. So a long edge travels in the band between two rows, which holds
+         * no boxes by construction, and only turns into the target's row in the gutter
+         * immediately before it.
+         */
+        // See `connectorDown`: the question is whether the run into the target passes a box,
+        // and it is asked rather than guessed at.
+        const band = channel?.bandBetween(fromCy, toCy);
+        const near = channel?.gutterBefore(to.x);
+        const adjacent = near === undefined ||
+            (channel?.rowClear(toCy, x, to.x) !== false && channel?.columnClear(x, fromCy, toCy) !== false);
+        if (adjacent) {
+            // The next column along: the run at the target's height crosses nothing, because
+            // there is nothing between them.
+            return {
+                points: [
+                    { x: fromRight, y: fromCy },
+                    { x, y: fromCy },
+                    { x, y: toCy },
+                    { x: to.x, y: toCy },
+                ],
+                /**
+                 * On this edge's own lane, and offset by which lane it is.
+                 *
+                 * Two branches leaving one decision leave it at the same point and at the same
+                 * height, so a label at the midpoint of the shared stub put them on top of each
+                 * other. The lanes are only a few pixels apart now that they have to fit a clear
+                 * strip, so the lane index separates the labels rather than the lane position.
+                 */
+                labelAt: { x, y: (fromCy + toCy) / 2 + (lane_ - (lanes - 1) / 2) * 15 },
+            };
+        }
+        /**
+         * Further than the next column, so the run has to travel somewhere empty.
+         *
+         * A band between the rows when there is one, and outside every box when there is not.
+         * What this must never do is fall back to a run at the target's own height: on a
+         * procedure where three checks all escalate to one step, that drew three horizontals
+         * straight through every node in between.
+         */
+        const lane = band ??
+            channel?.nearestRow((fromCy + toCy) / 2) ??
+            (fromCy <= toCy
+                ? Math.min(channel?.top ?? fromCy, fromCy, toCy) - 20 - lane_ * 12
+                : Math.max(channel?.bottom ?? fromCy, fromCy, toCy) + 20 + lane_ * 12);
+        return {
+            points: [
+                { x: fromRight, y: fromCy },
+                { x, y: fromCy },
+                { x, y: lane },
+                { x: near, y: lane },
+                { x: near, y: toCy },
+                { x: to.x, y: toCy },
+            ],
+            labelAt: { x, y: (fromCy + lane) / 2 + (lane_ - (lanes - 1) / 2) * 15 },
+        };
+    }
+    /**
+     * Against the flow: out of a side, up or down a clear vertical strip, and back in.
+     *
+     * The first version left by the top or bottom edge and descended at the box's own x to a
+     * lane outside everything — which crosses whatever sits below it in that column, and on
+     * two of the corpus's records it did. A vertical run has to be in a strip no box
+     * occupies, which is the same rule the forward routes follow and is now derived the same
+     * way: from the boxes.
+     */
+    const goingLeft = to.x + to.w <= from.x + 1;
+    const x1 = goingLeft ? from.x : from.x + from.w;
+    const x2 = goingLeft ? to.x + to.w : to.x;
+    const y1 = anchor(from.y, from.h, anchors?.out);
+    const y2 = anchor(to.y, to.h, anchors?.in);
+    if (Math.abs(y1 - y2) < 2) {
+        const y = (y1 + y2) / 2;
+        return {
+            points: [
+                { x: x1, y },
+                { x: x2, y },
+            ],
+            labelAt: { x: (x1 + x2) / 2, y: y - 9 },
+        };
+    }
+    const between = channel?.bandBeside(Math.min(x1, x2), Math.max(x1, x2));
+    const outside = goingLeft
+        ? Math.min(channel?.left ?? x1, x1, x2) - 24 - lane_ * 12
+        : Math.max(channel?.right ?? x1, x1, x2) + 24 + lane_ * 12;
+    // See `connectorDown`: a band is only usable if the legs that reach it are clear.
+    const banded = between === undefined
+        ? undefined
+        : clamp(between, Math.min(x1, x2) + TURN_CLEAR, Math.max(x1, x2) - TURN_CLEAR);
+    const reachable = banded !== undefined &&
+        channel?.rowClear(y1, x1, banded) !== false &&
+        channel?.rowClear(y2, banded, x2) !== false;
+    const laneX = reachable ? banded : outside;
+    return {
+        points: [
+            { x: x1, y: y1 },
+            { x: laneX, y: y1 },
+            { x: laneX, y: y2 },
+            { x: x2, y: y2 },
+        ],
+        labelAt: { x: laneX, y: (y1 + y2) / 2 },
+    };
+}
+/**
+ * The same, for a procedure laid out top to bottom — every rule of `connectorAcross`,
+ * turned.
+ *
+ * This was the naive version of that function for as long as horizontal was the default:
+ * lanes measured off the grid rather than off the boxes, no handling for a target further
+ * than the next row, and "close enough to straight" drawn between two different x. Making
+ * vertical the default made all three visible at once, on five of the corpus's records.
+ * Rather than a second set of ideas about routing, it is the same ones with the axes
+ * exchanged — there is one rule for how a line gets from one box to another and this is it
+ * sideways.
+ */
+function connectorDown(from, to, gap, lane_ = 0, lanes = 1, channel, anchors) {
+    const fromCx = anchor(from.x, from.w, anchors?.out);
+    const toCx = anchor(to.x, to.w, anchors?.in);
+    const fromBottom = from.y + from.h;
+    const backwards = to.y + to.h <= from.y + 1;
+    /**
+     * A step whose target shares its row, itself included.
+     *
+     * A retry edge goes from a step back to that same step, and two steps that were laid
+     * out side by side are the same distance down the page — either way there is no space
+     * *between* the boxes for a lane, because there is nothing between them. The forward
+     * route asked for one anyway and, finding the range inverted, put the line at the
+     * middle of it, which is the middle of a box.
+     *
+     * It goes under the row instead: out of the bottom, across the strip below — clear by
+     * construction, it is a band — and back up into the bottom of the target. A retry reads
+     * as a loop beneath the step, which is what it is.
+     */
+    const sameRow = to.y < from.y + from.h - 1 && to.y + to.h > from.y + 1;
+    if (sameRow) {
+        const y = channel?.bandBetween(fromBottom, fromBottom + gap) ?? fromBottom + gap / 2;
+        return {
+            points: [
+                { x: fromCx, y: fromBottom },
+                { x: fromCx, y },
+                { x: toCx, y },
+                { x: toCx, y: to.y + to.h },
+            ],
+            labelAt: { x: (fromCx + toCx) / 2, y },
+        };
+    }
+    if (!backwards && Math.abs(fromCx - toCx) < 2) {
+        // Drawn at one x, not two: two anchors a pixel apart make a line at about 89°.
+        const x = (fromCx + toCx) / 2;
+        return {
+            points: [
+                { x, y: fromBottom },
+                { x, y: to.y },
+            ],
+            labelAt: { x: x + 10, y: (fromBottom + to.y) / 2 },
+        };
+    }
+    if (!backwards) {
+        // A horizontal strip no box occupies, with the parallel edges spread inside it.
+        /**
+         * One line per route, and never outside the space between the two boxes.
+         *
+         * The band allocator already gives each route its own line, so spreading by lane index
+         * on top of it counts the same separation twice — and the two together pushed the
+         * first segment of `s1 → s9` four pixels *above* the bottom of `s1`, which is a line
+         * that starts inside its own source. The lane spread is the fallback for when there is
+         * no band to allocate from, and the result is clamped either way.
+         */
+        const strip = channel?.bandBetween(fromBottom, to.y);
+        const spread = Math.max(10, Math.min(20, (gap - 28) / Math.max(lanes, 1)));
+        const wanted = strip ?? fromBottom + Math.max(gap / 2, 8) + (lane_ - (lanes - 1) / 2) * spread;
+        const y = clamp(wanted, fromBottom + TURN_CLEAR, to.y - TURN_CLEAR);
+        /**
+         * A run down the target's own column crosses whatever else is standing in it.
+         *
+         * So the route asks whether it does, rather than guessing from how far away the target
+         * looks. The guess was "is this lane nearer the target than the gutter immediately
+         * above it", which was already only a proxy and became a wrong one when lanes moved off
+         * the middle of their band: two boxes one directly above the other failed it, and the
+         * edge between them went round three sides of the drawing.
+         */
+        const band = channel?.bandBeside(fromCx, toCx);
+        const near = channel?.gutterAbove(to.y);
+        const adjacent = near === undefined ||
+            (channel?.columnClear(toCx, y, to.y) !== false && channel?.rowClear(y, fromCx, toCx) !== false);
+        if (adjacent) {
+            return {
+                points: [
+                    { x: fromCx, y: fromBottom },
+                    { x: fromCx, y },
+                    { x: toCx, y },
+                    { x: toCx, y: to.y },
+                ],
+                labelAt: { x: (fromCx + toCx) / 2 + (lane_ - (lanes - 1) / 2) * 15, y },
+            };
+        }
+        // Further than the next row: travel in a column-gap, and turn into the target's
+        // column only in the strip immediately above it.
+        const lane = band ??
+            channel?.nearestColumn((fromCx + toCx) / 2) ??
+            (fromCx <= toCx
+                ? Math.min(channel?.left ?? fromCx, fromCx, toCx) - 20 - lane_ * 12
+                : Math.max(channel?.right ?? fromCx, fromCx, toCx) + 20 + lane_ * 12);
+        return {
+            points: [
+                { x: fromCx, y: fromBottom },
+                { x: fromCx, y },
+                { x: lane, y },
+                { x: lane, y: near },
+                { x: toCx, y: near },
+                { x: toCx, y: to.y },
+            ],
+            labelAt: { x: (fromCx + lane) / 2 + (lane_ - (lanes - 1) / 2) * 15, y },
+        };
+    }
+    /**
+     * Against the flow: out of a side, along a clear column, and back in.
+     *
+     * It used to leave by the top or bottom and travel along a clear horizontal band, which
+     * is the wrong shape for this layout: the long run of a backward edge here is vertical,
+     * so the legs that reach the band are the verticals — and they run up the boxes' own
+     * columns. On a record where a step retries an earlier one, the band chosen sat above the
+     * step in between and the line went straight through it. Going outside everything in `y`
+     * made it worse: the leg then passed through every box in the column.
+     *
+     * The long run belongs in a clear column, and the legs are the short horizontals that
+     * reach it. That is the same shape `connectorAcross` uses for its backward case, turned.
+     */
+    const yOut = anchor(from.y, from.h, anchors?.out);
+    const yIn = anchor(to.y, to.h, anchors?.in);
+    const wanted = channel?.nearestColumn((from.x + from.w / 2 + to.x + to.w / 2) / 2);
+    const outsideLeft = Math.min(channel?.left ?? from.x, from.x, to.x) - 24 - lane_ * 12;
+    const outsideRight = Math.max(channel?.right ?? from.x + from.w, from.x + from.w, to.x + to.w) + 24 + lane_ * 12;
+    const usable = (x) => channel?.rowClear(yOut, sideOf(from, x), x) !== false &&
+        channel?.rowClear(yIn, x, sideOf(to, x)) !== false;
+    const laneX = wanted !== undefined && usable(wanted)
+        ? wanted
+        : usable(outsideLeft)
+            ? outsideLeft
+            : outsideRight;
+    return {
+        points: [
+            { x: sideOf(from, laneX), y: yOut },
+            { x: laneX, y: yOut },
+            { x: laneX, y: yIn },
+            { x: sideOf(to, laneX), y: yIn },
+        ],
+        labelAt: { x: laneX, y: (yOut + yIn) / 2 },
+    };
+}
+/** The edge of a box facing a lane: a route leaves by the side the lane is on. */
+function sideOf(box, laneX) {
+    return laneX <= box.x + box.w / 2 ? box.x : box.x + box.w;
+}
+/**
+ * Where a horizontal run of one route is crossed by a vertical run of another.
+ *
+ * Two lines meeting at a point read as a junction — as though the procedure went that
+ * way — and a reader tracing a branch loses it at every intersection. Marking the
+ * crossing says which line is continuous. The mark is a bridge cut at 45° rather than the
+ * usual semicircular hop, so the drawing keeps to three directions throughout.
+ */
+function crossings(routes) {
+    const horizontals = [];
+    const verticals = [];
+    routes.forEach((route, index) => {
+        for (let i = 0; i + 1 < route.points.length; i++) {
+            const a = route.points[i];
+            const b = route.points[i + 1];
+            if (Math.abs(a.y - b.y) < 0.5 && Math.abs(a.x - b.x) > 1) {
+                horizontals.push({ route: index, y: a.y, x1: Math.min(a.x, b.x), x2: Math.max(a.x, b.x) });
+            }
+            else if (Math.abs(a.x - b.x) < 0.5 && Math.abs(a.y - b.y) > 1) {
+                verticals.push({ route: index, x: a.x, y1: Math.min(a.y, b.y), y2: Math.max(a.y, b.y) });
+            }
+        }
+    });
+    const bumps = new Map();
+    for (const h of horizontals) {
+        for (const v of verticals) {
+            if (v.route === h.route)
+                continue;
+            // Strictly inside both, so a shared corner is not reported as a crossing.
+            if (v.x <= h.x1 + 4 || v.x >= h.x2 - 4)
+                continue;
+            if (h.y <= v.y1 + 4 || h.y >= v.y2 - 4)
+                continue;
+            const list = bumps.get(h.route) ?? [];
+            if (!list.some((x) => Math.abs(x - v.x) < 6))
+                list.push(v.x);
+            bumps.set(h.route, list);
+        }
+    }
+    return bumps;
+}
+/**
+ * The polyline as path data: 45° cuts at the corners, 45° bridges at the crossings.
+ *
+ * The path stops `INSET` short of its last point so the arrowhead lands beside the box
+ * rather than on its outline, where it used to overlap the first letter of the label.
+ */
+function toPath(points, bumpsAt) {
+    if (points.length < 2)
+        return "";
+    const out = [];
+    const trimmed = [...points];
+    const last = trimmed[trimmed.length - 1];
+    const before = trimmed[trimmed.length - 2];
+    const dx = Math.sign(last.x - before.x);
+    const dy = Math.sign(last.y - before.y);
+    trimmed[trimmed.length - 1] = { x: last.x - dx * ARROW_GAP, y: last.y - dy * ARROW_GAP };
+    out.push(`M ${round(trimmed[0].x)} ${round(trimmed[0].y)}`);
+    for (let i = 1; i < trimmed.length; i++) {
+        const previous = trimmed[i - 1];
+        const current = trimmed[i];
+        const next = trimmed[i + 1];
+        const horizontal = Math.abs(previous.y - current.y) < 0.5;
+        const stop = current;
+        if (horizontal) {
+            const forwards = current.x > previous.x;
+            const inRange = bumpsAt
+                .filter((x) => (forwards ? x > previous.x + 6 && x < stop.x - 6 : x < previous.x - 6 && x > stop.x + 6))
+                .sort((a, b) => (forwards ? a - b : b - a));
+            for (const x of inRange) {
+                const side = forwards ? 1 : -1;
+                out.push(`L ${round(x - side * BRIDGE)} ${round(current.y)}`);
+                out.push(`L ${round(x - side * BRIDGE)} ${round(current.y - RISE)}`);
+                out.push(`L ${round(x + side * BRIDGE)} ${round(current.y - RISE)}`);
+                out.push(`L ${round(x + side * BRIDGE)} ${round(current.y)}`);
+            }
+        }
+        out.push(`L ${round(stop.x)} ${round(stop.y)}`);
+    }
+    return out.join(" ");
+}
+/**
+ * One rule per node: hovering it dims every line that does not touch it.
+ *
+ * Generated because CSS cannot ask "is this edge attached to the element under the
+ * pointer" — the relationship lives in the graph, so the rule is written out of the
+ * graph. Two selectors per node, and a catalog page draws one graph.
+ */
+/**
+ * A label goes on the longest run of its route, beside the line rather than on it.
+ *
+ * Each branch of the routers used to name its own spot, which was eight rules for one
+ * decision and produced two failures a reader sees immediately. The word sat *on* the
+ * line, and its background plate cut the line to make it readable — so a label as wide as
+ * the run it sits on erased the whole run, and `unreachable` on the k8s drain became a
+ * word floating between two two-pixel stubs. And the spot was often the shared stub two
+ * branches leave a decision by, so both words landed on the same pixel.
+ *
+ * The longest run is the one with room, and above it (or beside it, for a vertical run)
+ * is where a reader expects the name of a line.
+ */
+function labelSpot(route) {
+    let best;
+    for (let i = 0; i + 1 < route.points.length; i++) {
+        const a = route.points[i];
+        const b = route.points[i + 1];
+        const length = segmentLength(a, b);
+        if (!best || length > best.length)
+            best = { a, b, length };
+    }
+    if (!best)
+        return route.labelAt;
+    const middle = { x: (best.a.x + best.b.x) / 2, y: (best.a.y + best.b.y) / 2 };
+    const horizontal = Math.abs(best.a.y - best.b.y) < 0.5;
+    return horizontal ? { x: middle.x, y: middle.y - 10 } : { x: middle.x + 30, y: middle.y };
+}
+function nodeEdgeRules(graph) {
+    return graph.nodes
+        .map((node) => {
+        const id = cssEscape(node.id);
+        return (`.runbook-graph:has([data-node="${id}"]:hover) [data-edge]:not([data-from="${id}"]):not([data-to="${id}"]) [data-line]{stroke-opacity:.15}` +
+            `.runbook-graph:has([data-node="${id}"]:hover) [data-edge][data-from="${id}"] [data-line],` +
+            `.runbook-graph:has([data-node="${id}"]:hover) [data-edge][data-to="${id}"] [data-line]{stroke-width:2.6}`);
+    })
+        .join("");
+}
+/** Node ids are `s1`, `__end_success` and the like; this keeps a selector well-formed. */
+function cssEscape(id) {
+    return id.replace(/["\\]/g, "\\$&");
+}
+function segmentLength(a, b) {
+    return Math.hypot(b.x - a.x, b.y - a.y);
+}
+/** A padlock: a shackle over a body. Geometry only, in the text colour. */
+function padlock(x, y, colour) {
+    return (`<g transform="translate(${round(x)} ${round(y)})" data-badge="approval">` +
+        `<path d="M 3 5 V 3.2 A 2.8 2.8 0 0 1 8.6 3.2 V 5" fill="none" stroke="${colour}" stroke-width="1.3"/>` +
+        `<rect x="0.6" y="5" width="10.4" height="7.4" rx="1.6" fill="none" stroke="${colour}" stroke-width="1.3"/>` +
+        `</g>`);
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * The graph as an ordered list.
+ *
+ * Not a fallback but the accessible representation: the SVG is `aria-hidden`, and this
+ * is what a screen reader reads. Each entry states kind, risk and where the step can go,
+ * because those are the three things the picture conveys.
+ */
+function renderList(graph, order, byId) {
+    const items = order
+        .map((id) => {
+        const node = byId.get(id);
+        const out = graph.edges
+            .filter((e) => e.from === id && e.kind !== "approval")
+            .map((e) => `${e.kind === "branch" ? `if ${e.label}` : e.kind} to ${e.to}`);
+        const risk = node.risk ? `, ${RISK_LABELS[node.risk]} (${node.risk})` : "";
+        const approval = node.requiresApproval ? ", requires approval" : "";
+        const goes = out.length > 0 ? `. Goes ${out.join("; ")}` : ". Terminal";
+        return `<li id="step-${escape(id)}"><span class="step-kind">${node.kind}</span> <span class="step-title">${escape(node.title)}</span>${escape(risk + approval + goes)}</li>`;
+    })
+        .join("");
+    return `<ol class="runbook-graph-steps">${items}</ol>`;
+}