s-app-scoder-agent 0.9.10 → 0.9.15

package/dist/tui/markdown/graph.js

@@ -0,0 +1,1021 @@
+/**
+ * Flowchart layout engine — real graph rendering in the terminal (P9).
+ *
+ * Pipeline: mermaid source → parse (nodes, shapes, arrows) → rank (longest
+ * path, cycle-safe) → order (barycenter sweeps) → size boxes → place →
+ * rasterize into a cell grid that carries a per-cell *kind*, so the Ink layer
+ * can color box borders, labels and edges separately.
+ *
+ * Two placement modes:
+ *  - `layered` — Sugiyama-style bands, one layer per rank. Used whenever the
+ *    graph fits the pane (the common case for branching flowcharts).
+ *  - `strip`   — topological order flowed into wrapped rows of boxes joined by
+ *    `──▶`, with a `┌───┘` connector where the chain wraps. Used for long
+ *    chains (version timelines) that would be taller than the viewport.
+ *
+ * Pure module: no Ink, no I/O, never throws. Every failure path returns null
+ * so diagram.tsx falls back to the structured summary — the TUI shows a
+ * complete graph or an honest summary, never a clipped drawing.
+ *
+ * Known approximations (documented in src/tui/README.md):
+ *  - mermaid shapes collapse to three corner styles (rect / round / chamfer);
+ *  - subgraphs are flattened into their nodes (a note names them);
+ *  - edges that close a cycle are listed as notes instead of drawn;
+ *  - an edge label with no free run wide enough is dropped and noted.
+ */
+import { charset } from "../charset.js";
+import { clipCells, measure, wrapCells } from "../text-width.js";
+// ── Geometry budget ─────────────────────────────────────────────────────────
+const GAP = 2; // cross-axis gap between sibling boxes
+const MARGIN = 2; // cross-axis gutters reserved for detour channels
+const BAND = 3; // routing rows between layers (elbows + labels)
+const STRIP_GAP = 3; // gap between strip boxes — wide enough for `──▶`
+const STRIP_BAND = 2; // rows between strip rows — holds the wrap connector
+const MAX_NODES = 80;
+const MAX_EDGES = 200;
+/** Label width caps, widest first: the first one that fits the pane wins. */
+const LAYERED_CAPS = [22, 16, 12, 10];
+const STRIP_CAPS = [26, 20, 14, 10];
+/** Height budget for a drawn graph — anything taller degrades to the summary. */
+export const MAX_GRAPH_ROWS = 40;
+// ── 1. Label cleanup (shared with the summary renderer) ─────────────────────
+const HTML_BREAK_RX = /<\s*br\s*\/?\s*>/gi;
+const HTML_TAG_RX = /<\s*\/?\s*[a-z][^>]*>/gi;
+const ENTITY_RX = /&(#x?[0-9a-f]+|[a-z]+);/gi;
+const NAMED_ENTITIES = {
+    amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ",
+};
+/**
+ * Mermaid label → display text. `<br/>` is a LINE BREAK inside a mermaid node,
+ * so printing it literally is wrong: it becomes a space. Other tags are
+ * dropped, numeric/named entities decoded, quotes and repeated spaces
+ * collapsed.
+ */
+export function cleanMermaidLabel(raw) {
+    let out = raw.trim().replace(HTML_BREAK_RX, " ").replace(HTML_TAG_RX, "");
+    out = out.replace(ENTITY_RX, (whole, entity) => {
+        if (entity[0] !== "#")
+            return NAMED_ENTITIES[entity.toLowerCase()] ?? whole;
+        const hex = entity[1] === "x" || entity[1] === "X";
+        const code = Number.parseInt(hex ? entity.slice(2) : entity.slice(1), hex ? 16 : 10);
+        return Number.isFinite(code) && code > 31 ? String.fromCharCode(code) : whole;
+    });
+    return out.replace(/^["']|["']$/g, "").replace(/\s+/g, " ").trim();
+}
+// ── 2. Parsing ──────────────────────────────────────────────────────────────
+/** Shape wrappers, longest opener first so `[[x]]` never parses as `[x]`. */
+const SHAPE_DEFS = [
+    ["[[", "]]", "rect"],
+    ["([", ")]", "round"],
+    ["[(", ")]", "cylinder"],
+    ["((", "))", "circle"],
+    ["{{", "}}", "hex"],
+    ["[", "]", "rect"],
+    ["(", ")", "round"],
+    ["{", "}", "diamond"],
+    [">", "]", "flag"],
+];
+const ARROW_SPECS = [
+    { text: "<-.->", style: "dotted", head: "both" },
+    { text: "<-->", style: "solid", head: "both" },
+    { text: "<==>", style: "thick", head: "both" },
+    { text: "x--x", style: "solid", head: "open" },
+    { text: "o--o", style: "solid", head: "open" },
+    { text: "<--x", style: "solid", head: "back" },
+    { text: "--->", style: "solid", head: "fwd" },
+    { text: "-.->", style: "dotted", head: "fwd" },
+    { text: "==>", style: "thick", head: "fwd" },
+    { text: "-->", style: "solid", head: "fwd" },
+    { text: "<--", style: "solid", head: "back" },
+    { text: "---", style: "solid", head: "open" },
+    { text: "===", style: "thick", head: "open" },
+    { text: "-.-", style: "dotted", head: "open" },
+    { text: "->", style: "solid", head: "fwd" },
+    { text: "=>", style: "thick", head: "fwd" },
+    { text: "--", style: "solid", head: "open" },
+    { text: "<-", style: "solid", head: "back" },
+];
+const ID_RX = /^[\p{L}\p{N}_][\p{L}\p{N}_\-.]*/u;
+function skipSpace(line, i) {
+    while (i < line.length && (line[i] === " " || line[i] === "\t"))
+        i++;
+    return i;
+}
+function readShape(line, i) {
+    for (const [open, close, shape] of SHAPE_DEFS) {
+        if (!line.startsWith(open, i))
+            continue;
+        const end = line.indexOf(close, i + open.length);
+        if (end === -1)
+            continue;
+        return { text: line.slice(i + open.length, end), shape, end: end + close.length };
+    }
+    return null;
+}
+function matchArrow(line, i) {
+    for (const spec of ARROW_SPECS) {
+        if (line.startsWith(spec.text, i))
+            return { spec, start: i, end: i + spec.text.length };
+    }
+    return null;
+}
+/** Next arrow at/after `from`, skipping node shapes so `-->` inside a label is safe. */
+function findNextArrow(line, from) {
+    for (let i = from; i < line.length; i++) {
+        const shape = readShape(line, i);
+        if (shape) {
+            i = shape.end - 1;
+            continue;
+        }
+        const hit = matchArrow(line, i);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Scan one statement into alternating node/edge tokens (`A --> B --> C` works). */
+function scanStatement(line) {
+    const toks = [];
+    let i = 0;
+    for (;;) {
+        i = skipSpace(line, i);
+        const id = ID_RX.exec(line.slice(i))?.[0];
+        if (!id)
+            return toks.length >= 2 ? toks : null;
+        i += id.length;
+        const shape = readShape(line, i);
+        if (shape) {
+            toks.push({ t: "node", id, label: shape.text, shape: shape.shape });
+            i = shape.end;
+        }
+        else {
+            const cls = /^:::[\w-]+/.exec(line.slice(i)); // `A:::someClass`
+            if (cls)
+                i += cls[0].length;
+            toks.push({ t: "node", id });
+        }
+        i = skipSpace(line, i);
+        let arrow = matchArrow(line, i);
+        if (!arrow)
+            break;
+        i = arrow.end;
+        let label = "";
+        const bar = skipSpace(line, i);
+        if (line[bar] === "|") {
+            const close = line.indexOf("|", bar + 1);
+            if (close !== -1) {
+                label = line.slice(bar + 1, close);
+                i = close + 1;
+            }
+        }
+        else if (arrow.spec.head === "open") {
+            // `A -- yes --> B`: open arrow, label text, then the real arrow head.
+            const next = findNextArrow(line, i);
+            if (next && next.start > i) {
+                label = line.slice(i, next.start).trim();
+                arrow = next;
+                i = next.end;
+            }
+        }
+        toks.push({ t: "edge", spec: arrow.spec, label: cleanMermaidLabel(label) });
+    }
+    return toks.length >= 2 ? toks : null;
+}
+function stripComment(line) {
+    const i = line.indexOf("%%");
+    return (i === -1 ? line : line.slice(0, i)).trim();
+}
+/** Parse a mermaid `graph`/`flowchart` block; null for anything else. */
+export function parseFlowchart(lines) {
+    const rows = lines.map(stripComment).filter((l) => l !== "");
+    if (rows.length === 0)
+        return null;
+    const header = /^(?:graph|flowchart)(?:\s+(TB|BT|TD|RL|LR))?\b/i.exec(rows[0]);
+    if (!header)
+        return null;
+    const direction = (header[1] ?? "TD").toUpperCase();
+    const nodes = new Map();
+    const edges = [];
+    const notes = [];
+    const seen = new Set();
+    const touch = (id, label, shape) => {
+        const node = nodes.get(id) ?? { id, label: id, shape: "rect" };
+        if (label !== undefined && label !== "") {
+            node.label = cleanMermaidLabel(label);
+            node.shape = shape ?? node.shape;
+        }
+        nodes.set(id, node);
+    };
+    for (let li = 1; li < rows.length; li++) {
+        const line = rows[li];
+        if (/^subgraph\b/i.test(line)) {
+            const title = cleanMermaidLabel(line.replace(/^subgraph\b/i, "").replace(/\[[^\]]*\]|\([^)]*\)/g, ""));
+            if (title)
+                notes.push(`subgraph flattened: ${title}`);
+            continue;
+        }
+        if (/^end\b/i.test(line))
+            continue;
+        // Styling / interaction statements do not change the graph shape.
+        if (/^(direction|style|classDef|class|linkStyle|click|callback|accTitle|accDescr)\b/i.test(line))
+            continue;
+        const toks = scanStatement(line);
+        if (!toks)
+            continue;
+        let prev = null;
+        let pending = null;
+        for (const tok of toks) {
+            if (tok.t === "edge") {
+                pending = tok;
+                continue;
+            }
+            touch(tok.id, tok.label, tok.shape);
+            if (pending && prev) {
+                if (prev === tok.id) {
+                    notes.push(`self-loop omitted: ${nodes.get(prev)?.label ?? prev}`);
+                }
+                else if (edges.length < MAX_EDGES) {
+                    const reverse = pending.spec.head === "back";
+                    const from = reverse ? tok.id : prev;
+                    const to = reverse ? prev : tok.id;
+                    const key = `${from}\u0000${to}\u0000${pending.label}\u0000${pending.spec.style}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        edges.push({ from, to, label: pending.label, style: pending.spec.style });
+                    }
+                }
+            }
+            prev = tok.id;
+            pending = null;
+        }
+    }
+    if (nodes.size === 0 || nodes.size > MAX_NODES)
+        return null;
+    return { direction, nodes: [...nodes.values()], edges, notes: dedupe(notes).slice(0, 4) };
+}
+/** Longest-path ranking with DFS cycle breaking, then barycenter ordering. */
+function rankLayers(g) {
+    const ids = g.nodes.map((n) => n.id);
+    const out = new Map(ids.map((id) => [id, []]));
+    for (const e of g.edges)
+        out.get(e.from)?.push(e);
+    // 1. mark back edges (target still on the DFS stack ⇒ cycle closer)
+    const state = new Map(); // 0 unseen · 1 on stack · 2 done
+    const back = new Set();
+    const stack = [];
+    for (const root of ids) {
+        if (state.get(root))
+            continue;
+        state.set(root, 1);
+        stack.push({ id: root, i: 0 });
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const list = out.get(frame.id) ?? [];
+            if (frame.i >= list.length) {
+                state.set(frame.id, 2);
+                stack.pop();
+                continue;
+            }
+            const edge = list[frame.i++];
+            const mark = state.get(edge.to) ?? 0;
+            if (mark === 1)
+                back.add(edge);
+            else if (mark === 0) {
+                state.set(edge.to, 1);
+                stack.push({ id: edge.to, i: 0 });
+            }
+        }
+    }
+    // 2. Kahn topological order + longest-path rank over the acyclic part
+    const indeg = new Map(ids.map((id) => [id, 0]));
+    const fwd = new Map(ids.map((id) => [id, []]));
+    for (const e of g.edges) {
+        if (back.has(e))
+            continue;
+        fwd.get(e.from)?.push(e.to);
+        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+    }
+    const rank = new Map(ids.map((id) => [id, 0]));
+    const queue = ids.filter((id) => (indeg.get(id) ?? 0) === 0);
+    const topo = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        topo.push(id);
+        for (const next of fwd.get(id) ?? []) {
+            rank.set(next, Math.max(rank.get(next) ?? 0, (rank.get(id) ?? 0) + 1));
+            const left = (indeg.get(next) ?? 1) - 1;
+            indeg.set(next, left);
+            if (left === 0)
+                queue.push(next);
+        }
+    }
+    for (const id of ids)
+        if (!topo.includes(id))
+            topo.push(id);
+    const depth = ids.reduce((max, id) => Math.max(max, (rank.get(id) ?? 0) + 1), 0);
+    const layers = Array.from({ length: depth }, () => []);
+    for (const id of topo)
+        layers[rank.get(id) ?? 0].push(id);
+    // 3. barycenter sweeps to reduce crossings
+    const neighbors = new Map(ids.map((id) => [id, []]));
+    for (const e of g.edges) {
+        if (back.has(e))
+            continue;
+        neighbors.get(e.from)?.push(e.to);
+        neighbors.get(e.to)?.push(e.from);
+    }
+    for (let sweep = 0; sweep < 4; sweep++) {
+        const down = sweep % 2 === 0;
+        const order = [];
+        for (let i = 1; i < depth; i++)
+            order.push(down ? i : depth - 1 - i);
+        for (const li of order) {
+            const ref = layers[down ? li - 1 : li + 1];
+            if (!ref || ref.length === 0)
+                continue;
+            const pos = new Map(ref.map((id, idx) => [id, idx]));
+            layers[li] = layers[li]
+                .map((id, idx) => {
+                const near = (neighbors.get(id) ?? [])
+                    .map((n) => pos.get(n))
+                    .filter((p) => p !== undefined);
+                const b = near.length > 0 ? near.reduce((s, p) => s + p, 0) / near.length : idx;
+                return { id, idx, b };
+            })
+                .sort((a, b) => a.b - b.b || a.idx - b.idx)
+                .map((x) => x.id);
+        }
+    }
+    return { layers: layers.filter((L) => L.length > 0), back };
+}
+// ── 4. Canvas ───────────────────────────────────────────────────────────────
+const UP = 1, RIGHT = 2, DOWN = 4, LEFT = 8;
+function lineGlyph(mask, style) {
+    const horizontal = (mask & (RIGHT | LEFT)) !== 0 && (mask & (UP | DOWN)) === 0;
+    const vertical = (mask & (UP | DOWN)) !== 0 && (mask & (RIGHT | LEFT)) === 0;
+    if (style === "thick") {
+        if (horizontal)
+            return charset.hHeavy;
+        if (vertical)
+            return charset.vHeavy;
+    }
+    else if (style === "dotted") {
+        if (horizontal)
+            return charset.hDotted;
+        if (vertical)
+            return charset.vDotted;
+    }
+    return charset.line[mask] ?? "+";
+}
+class Canvas {
+    w;
+    h;
+    chars;
+    kinds;
+    masks;
+    styles;
+    constructor(w, h) {
+        this.w = w;
+        this.h = h;
+        this.chars = Array.from({ length: h }, () => new Array(w).fill(" "));
+        this.kinds = Array.from({ length: h }, () => new Array(w).fill("empty"));
+        this.masks = Array.from({ length: h }, () => new Array(w).fill(0));
+        this.styles = Array.from({ length: h }, () => new Array(w).fill("solid"));
+    }
+    ok(x, y) {
+        return x >= 0 && y >= 0 && x < this.w && y < this.h;
+    }
+    busy(x, y) {
+        return this.ok(x, y) && this.kinds[y][x] !== "empty";
+    }
+    /**
+     * Can a channel be drawn through this cell? `allowShared` lets a second
+     * edge merge into an existing line (junction) instead of giving up — used
+     * only after every clean route is exhausted, so the picture stays readable.
+     */
+    passable(x, y, allowShared) {
+        if (!this.ok(x, y))
+            return false;
+        const kind = this.kinds[y][x];
+        return kind === "empty" || (allowShared && kind === "edge");
+    }
+    freeH(y, x1, x2, allowShared = false) {
+        const [a, b] = x1 <= x2 ? [x1, x2] : [x2, x1];
+        for (let x = a; x <= b; x++)
+            if (!this.passable(x, y, allowShared))
+                return false;
+        return true;
+    }
+    freeV(x, y1, y2, allowShared = false) {
+        const [a, b] = y1 <= y2 ? [y1, y2] : [y2, y1];
+        for (let y = a; y <= b; y++)
+            if (!this.passable(x, y, allowShared))
+                return false;
+        return true;
+    }
+    /**
+     * Free run along the RANK axis at a fixed cross coordinate. TD: rank is
+     * vertical (a column); LR: rank is horizontal (a row).
+     */
+    freeRank(atCross, r1, r2, rankVertical, allowShared = false) {
+        return rankVertical ? this.freeV(atCross, r1, r2, allowShared) : this.freeH(atCross, r1, r2, allowShared);
+    }
+    /** Free run along the CROSS axis at a fixed rank coordinate. */
+    freeCross(atRank, c1, c2, rankVertical, allowShared = false) {
+        return rankVertical ? this.freeH(atRank, c1, c2, allowShared) : this.freeV(atRank, c1, c2, allowShared);
+    }
+    put(x, y, ch, kind) {
+        if (!this.ok(x, y))
+            return;
+        this.chars[y][x] = ch;
+        this.kinds[y][x] = kind;
+        this.masks[y][x] = 0;
+    }
+    /** Add connection arms to a cell; crossing lines merge into one glyph. */
+    line(x, y, mask, style) {
+        if (!this.ok(x, y))
+            return;
+        const kind = this.kinds[y][x];
+        if (kind === "box" || kind === "label" || kind === "arrow")
+            return;
+        this.kinds[y][x] = "edge";
+        this.masks[y][x] |= mask;
+        if (style !== "solid")
+            this.styles[y][x] = style;
+    }
+    hLine(y, x1, x2, style) {
+        const [a, b] = x1 <= x2 ? [x1, x2] : [x2, x1];
+        for (let x = a; x <= b; x++) {
+            const mask = a === b ? RIGHT | LEFT : x === a ? RIGHT : x === b ? LEFT : RIGHT | LEFT;
+            this.line(x, y, mask, style);
+        }
+    }
+    vLine(x, y1, y2, style) {
+        const [a, b] = y1 <= y2 ? [y1, y2] : [y2, y1];
+        for (let y = a; y <= b; y++) {
+            const mask = a === b ? UP | DOWN : y === a ? DOWN : y === b ? UP : UP | DOWN;
+            this.line(x, y, mask, style);
+        }
+    }
+    arrow(x, y, dir) {
+        if (!this.ok(x, y))
+            return;
+        if (this.kinds[y][x] === "box" || this.kinds[y][x] === "label")
+            return;
+        const ch = dir === "up" ? charset.arrowUp : dir === "right" ? charset.arrowRight
+            : dir === "down" ? charset.arrowDown : charset.arrowLeft;
+        this.put(x, y, ch, "arrow");
+    }
+    /**
+     * Write text at a cell. Busy cells are skipped unless `overwriteLines`,
+     * which lets an edge label break a line (mermaid draws labels on the
+     * connector) while never touching box borders or other text.
+     */
+    text(x, y, str, kind, overwriteLines = false) {
+        let cx = x;
+        for (const seg of new Intl.Segmenter("en", { granularity: "grapheme" }).segment(str)) {
+            const width = measure(seg.segment);
+            if (cx < 0) {
+                cx += width;
+                continue;
+            }
+            if (cx + width > this.w)
+                break;
+            const existing = this.ok(cx, y) ? this.kinds[y][cx] : "empty";
+            const blocked = existing !== "empty" && !(overwriteLines && existing === "edge");
+            if (!blocked) {
+                this.put(cx, y, seg.segment, kind);
+                for (let k = 1; k < width; k++)
+                    this.put(cx + k, y, " ", kind);
+            }
+            cx += width;
+        }
+    }
+    /** Node box: border from `cornersFor(shape)` + centered label lines. */
+    box(rect, lines, shape) {
+        const { x, y, w, h } = rect;
+        if (w < 5 || h < 3) {
+            this.text(x, y, clipCells(lines[0] ?? "", Math.max(1, w)), "label");
+            return;
+        }
+        const [tl, tr, br, bl] = cornersFor(shape);
+        this.put(x, y, tl, "box");
+        this.put(x + w - 1, y, tr, "box");
+        this.put(x + w - 1, y + h - 1, br, "box");
+        this.put(x, y + h - 1, bl, "box");
+        for (let i = x + 1; i < x + w - 1; i++) {
+            this.put(i, y, charset.h, "box");
+            this.put(i, y + h - 1, charset.h, "box");
+        }
+        for (let j = y + 1; j < y + h - 1; j++) {
+            this.put(x, j, charset.v, "box");
+            this.put(x + w - 1, j, charset.v, "box");
+        }
+        const inner = w - 4;
+        lines.forEach((line, i) => {
+            const row = y + 1 + i;
+            if (row >= y + h - 1)
+                return;
+            const pad = Math.max(0, Math.floor((inner - measure(line)) / 2));
+            this.text(x + 2 + pad, row, line, "label");
+        });
+    }
+    /** Resolve glyphs from masks, trim trailing blanks, group runs into segments. */
+    toRows() {
+        const rows = [];
+        for (let y = 0; y < this.h; y++) {
+            const segs = [];
+            let text = "";
+            let kind = "empty";
+            let last = -1;
+            for (let x = 0; x < this.w; x++) {
+                const cellKind = this.kinds[y][x];
+                const ch = cellKind === "edge" ? lineGlyph(this.masks[y][x], this.styles[y][x]) : this.chars[y][x];
+                if (cellKind !== kind) {
+                    if (text !== "")
+                        segs.push({ text, kind });
+                    kind = cellKind;
+                    text = "";
+                }
+                text += ch;
+                if (cellKind !== "empty")
+                    last = x;
+            }
+            if (text !== "")
+                segs.push({ text, kind });
+            rows.push(cutToLast(segs, last));
+        }
+        return rows;
+    }
+}
+/** Drop the trailing empty run so rows carry no padding spaces. */
+function cutToLast(segs, last) {
+    if (last < 0)
+        return [];
+    const out = [];
+    let used = 0;
+    for (const seg of segs) {
+        if (used > last)
+            break;
+        const width = measure(seg.text);
+        if (used + width > last + 1)
+            out.push({ text: seg.text.slice(0, last + 1 - used), kind: seg.kind });
+        else
+            out.push(seg);
+        used += width;
+    }
+    return out;
+}
+function cornersFor(shape) {
+    if (shape === "diamond")
+        return charset.cornerDiamond;
+    if (shape === "round" || shape === "circle" || shape === "hex")
+        return charset.cornerRound;
+    return charset.cornerRect;
+}
+/** Wrap each label into ≤ maxLines lines of ≤ cap-4 cells, then size its box. */
+function sizeBoxes(g, cap, maxLines) {
+    const sizes = new Map();
+    const inner = Math.max(1, cap - 4);
+    for (const node of g.nodes) {
+        let lines = wrapCells(node.label || node.id, inner);
+        if (lines.length > maxLines) {
+            lines = lines.slice(0, maxLines);
+            lines[maxLines - 1] = clipCells(lines[maxLines - 1], inner);
+        }
+        const widest = lines.reduce((max, l) => Math.max(max, measure(l)), 1);
+        sizes.set(node.id, { lines, w: widest + 4, h: lines.length + 2 });
+    }
+    return sizes;
+}
+function toXY(p, rankVertical) {
+    return rankVertical ? { x: p.c, y: p.r } : { x: p.r, y: p.c };
+}
+function finalize(cv, meta) {
+    const rows = crop(cv.toRows());
+    const width = rows.reduce((max, segs) => Math.max(max, segs.reduce((s, seg) => s + measure(seg.text), 0)), 0);
+    return { ...meta, rows, width, height: rows.length, notes: dedupe(meta.notes).slice(0, 4) };
+}
+/**
+ * Drop the unused gutters: leading/trailing blank rows, and the blank column
+ * offset shared by every row (a detour channel that was never needed costs
+ * the reader nothing).
+ */
+function crop(rows) {
+    const empty = (segs) => segs.length === 0;
+    let top = 0, bottom = rows.length;
+    while (top < bottom && empty(rows[top]))
+        top++;
+    while (bottom > top && empty(rows[bottom - 1]))
+        bottom--;
+    const body = rows.slice(top, bottom);
+    let indent = Number.POSITIVE_INFINITY;
+    for (const segs of body) {
+        const first = segs[0];
+        const lead = first !== undefined && first.kind === "empty" ? measure(first.text) : 0;
+        indent = Math.min(indent, lead);
+    }
+    if (!Number.isFinite(indent) || indent <= 0)
+        return body;
+    return body.map((segs) => {
+        const [first, ...rest] = segs;
+        if (first === undefined || first.kind !== "empty")
+            return segs;
+        const left = measure(first.text) - indent;
+        return left > 0 ? [{ text: " ".repeat(left), kind: "empty" }, ...rest] : rest;
+    });
+}
+function dedupe(items) {
+    return [...new Set(items.filter((s) => s !== ""))];
+}
+/**
+ * One band per rank. `BT`/`RL` are laid out as `TD`/`LR` on reversed edges and
+ * the arrowheads are moved back to the upstream end, so the picture still
+ * reads in the direction the author asked for.
+ */
+function layeredLayout(g, opts) {
+    const rankVertical = g.direction !== "LR" && g.direction !== "RL";
+    const flip = g.direction === "BT" || g.direction === "RL";
+    const graph = flip
+        ? { ...g, edges: g.edges.map((e) => ({ ...e, from: e.to, to: e.from })) }
+        : g;
+    const { layers, back } = rankLayers(graph);
+    if (layers.length === 0)
+        return null;
+    // A cap that would split a WORD is rejected: boxes get taller, not chopped
+    // up. Chains with long single words fall through to strip layout, which has
+    // a wider cap and wraps at box level.
+    const wordsFit = graph.nodes.every((n) => {
+        const longest = (n.label || n.id).split(/\s+/).reduce((m, w) => Math.max(m, measure(w)), 0);
+        return longest <= opts.cap - 4;
+    });
+    if (!wordsFit)
+        return null;
+    const sizes = sizeBoxes(graph, opts.cap, 2);
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const crossOf = (id) => (rankVertical ? sizes.get(id).w : sizes.get(id).h);
+    const rankOf = (id) => (rankVertical ? sizes.get(id).h : sizes.get(id).w);
+    const layerCross = layers.map((L) => L.reduce((s, id) => s + crossOf(id), 0) + GAP * (L.length - 1));
+    const innerCross = layerCross.reduce((m, v) => Math.max(m, v), 0);
+    // Side gutters: a long edge that has to skip a layer detours through them
+    // instead of being dropped (see the Z-route candidates in `routeEdge`).
+    const totalCross = innerCross + MARGIN * 2;
+    const boxes = new Map();
+    let rank = 0;
+    layers.forEach((L, li) => {
+        let c = MARGIN + Math.floor((innerCross - layerCross[li]) / 2);
+        for (const id of L) {
+            const size = sizes.get(id);
+            const node = byId.get(id);
+            const cr = crossOf(id);
+            const rr = rankOf(id);
+            const p = toXY({ r: rank, c }, rankVertical);
+            boxes.set(id, {
+                node,
+                lines: size.lines,
+                rect: { x: p.x, y: p.y, w: size.w, h: size.h },
+                rank0: rank,
+                rank1: rank + rr - 1,
+                cross0: c,
+                cross1: c + cr,
+                crossMid: c + Math.floor(cr / 2),
+            });
+            c += cr + GAP;
+        }
+        rank += L.reduce((max, id) => Math.max(max, rankOf(id)), 0) + BAND;
+    });
+    const totalRank = rank - BAND;
+    const width = rankVertical ? totalCross : totalRank;
+    const height = rankVertical ? totalRank : totalCross;
+    if (width < 1 || height < 1 || width > opts.width || height > opts.maxRows)
+        return null;
+    const cv = new Canvas(width, height);
+    for (const b of boxes.values())
+        cv.box(b.rect, b.lines, b.node.shape);
+    const notes = [];
+    const dropped = { labels: 0 };
+    const ctx = { rankVertical, flip, crossMax: totalCross - 1, dropped };
+    let drawn = 0;
+    for (const e of graph.edges) {
+        if (back.has(e))
+            continue;
+        const a = boxes.get(e.from);
+        const b = boxes.get(e.to);
+        if (!a || !b)
+            continue;
+        if (routeEdge(cv, a, b, e, ctx))
+            drawn++;
+        else
+            notes.push(`edge not drawn: ${a.node.label} → ${b.node.label}`);
+    }
+    if (dropped.labels > 0)
+        notes.push(`${dropped.labels} edge label(s) omitted (no room)`);
+    for (const e of back) {
+        const fromId = flip ? e.to : e.from;
+        const toId = flip ? e.from : e.to;
+        notes.push(`${charset.loop} cycle edge: ${byId.get(fromId)?.label ?? fromId} → ${byId.get(toId)?.label ?? toId}`);
+    }
+    return finalize(cv, {
+        mode: "layered",
+        direction: g.direction,
+        nodes: boxes.size,
+        edges: drawn,
+        notes: [...g.notes, ...notes],
+    });
+}
+/**
+ * Candidate paths for `a → b`, best-looking first: straight shared channel,
+ * elbows next to either box, then Z routes through any column (including the
+ * side gutters, so long edges detour instead of disappearing).
+ */
+function edgePaths(a, b, from, to, crossMax) {
+    const candidates = [];
+    // 1. Straight channel: a column (TD) / row (LR) that touches both boxes,
+    //    so the edge never has to jog. Nearest the target center first — when
+    //    several edges enter the same box they take neighbouring ports instead
+    //    of fighting over one cell.
+    const lo = Math.max(a.cross0, b.cross0), hi = Math.min(a.cross1, b.cross1) - 1;
+    if (lo <= hi) {
+        const ports = [];
+        for (let c = lo; c <= hi; c++)
+            ports.push(c);
+        ports.sort((p, q) => Math.abs(p - to.c) - Math.abs(q - to.c));
+        for (const c of ports.slice(0, 6))
+            candidates.push([{ r: from.r, c }, { r: to.r, c }]);
+    }
+    if (from.c === to.c)
+        candidates.push([from, to]);
+    // 2. Elbow just above the target, then 3. just below the source.
+    candidates.push([from, { r: to.r, c: from.c }, to]);
+    candidates.push([from, { r: from.r, c: to.c }, to]);
+    // 4. Z route through a channel column, nearest the target first.
+    const columns = [];
+    for (let c = 0; c <= crossMax; c++)
+        if (c !== from.c && c !== to.c)
+            columns.push(c);
+    columns.sort((p, q) => Math.abs(p - to.c) - Math.abs(q - to.c));
+    for (const c of columns.slice(0, 40))
+        candidates.push([from, { r: from.r, c }, { r: to.r, c }, to]);
+    return candidates;
+}
+/**
+ * Route one edge. `a` is the upstream box in layout space; `flip` means the
+ * real arrow points upstream, so the arrowhead goes at `a` instead of `b`.
+ *
+ * Candidate paths are tried clean-first (nothing else drawn on them), then
+ * again allowing merges, so a busy diagram still shows every edge instead of
+ * silently dropping it.
+ */
+function routeEdge(cv, a, b, edge, ctx) {
+    const { rankVertical, flip, crossMax, dropped } = ctx;
+    const from = { r: a.rank1 + 1, c: a.crossMid };
+    const to = { r: b.rank0 - 1, c: b.crossMid };
+    if (to.r < from.r)
+        return false;
+    const headAtB = !flip;
+    const dir = rankVertical
+        ? (headAtB ? "down" : "up")
+        : (headAtB ? "right" : "left");
+    const candidates = edgePaths(a, b, from, to, crossMax);
+    for (const allowShared of [false, true]) {
+        for (const path of candidates) {
+            if (!pathClear(cv, path, rankVertical, allowShared))
+                continue;
+            for (let i = 0; i + 1 < path.length; i++)
+                drawAlong(cv, path[i], path[i + 1], edge.style, rankVertical);
+            const head = toXY(headAtB ? path[path.length - 1] : path[0], rankVertical);
+            cv.arrow(head.x, head.y, dir);
+            placeLabel(cv, path, edge.label, rankVertical, dropped);
+            return true;
+        }
+    }
+    return false;
+}
+/** Every segment of a candidate path is drawable. */
+function pathClear(cv, path, rankVertical, allowShared) {
+    for (let i = 0; i + 1 < path.length; i++) {
+        const p = path[i], q = path[i + 1];
+        if (p.c === q.c) {
+            if (!cv.freeRank(p.c, p.r, q.r, rankVertical, allowShared))
+                return false;
+        }
+        else if (p.r === q.r) {
+            if (!cv.freeCross(p.r, p.c, q.c, rankVertical, allowShared))
+                return false;
+        }
+        else {
+            return false; // not axis-aligned
+        }
+    }
+    return true;
+}
+/** Draw one axis-aligned abstract segment (rank or cross direction). */
+function drawAlong(cv, p, q, style, rankVertical) {
+    const A = toXY(p, rankVertical);
+    const B = toXY(q, rankVertical);
+    if (A.x === B.x)
+        cv.vLine(A.x, A.y, B.y, style);
+    else
+        cv.hLine(A.y, A.x, B.x, style);
+}
+/**
+ * Edge labels: prefer the longest horizontal run (the label sits on the line,
+ * like mermaid does); otherwise put it beside the longest vertical run, in the
+ * routing band that is free by construction. `dropped` counts labels that had
+ * no room, so the caller can say so instead of losing them silently.
+ */
+function placeLabel(cv, path, label, rankVertical, dropped) {
+    if (!label)
+        return;
+    const runs = [];
+    for (let i = 0; i + 1 < path.length; i++) {
+        const p = path[i], q = path[i + 1];
+        const A = toXY(p, rankVertical), B = toXY(q, rankVertical);
+        const horizontal = A.y === B.y;
+        const len = horizontal ? Math.abs(B.x - A.x) + 1 : Math.abs(B.y - A.y) + 1;
+        runs.push({ p, q, len, horizontal });
+    }
+    const byLen = (a, b) => b.len - a.len;
+    const labelW = measure(label);
+    const ordered = runs.slice().sort(byLen);
+    // Longest suitable run wins: the text stays away from the box the edge just
+    // left. Horizontal runs carry the label on the line, vertical runs carry it
+    // beside the line (mermaid's own convention).
+    const onLine = ordered.find((r) => r.horizontal && r.len >= labelW + 2);
+    if (onLine) {
+        const A = toXY(onLine.p, rankVertical), B = toXY(onLine.q, rankVertical);
+        const [x1, x2] = A.x <= B.x ? [A.x, B.x] : [B.x, A.x];
+        cv.text(x1 + Math.floor((x2 - x1 + 1 - labelW) / 2), A.y, label, "elabel", true);
+        return;
+    }
+    const beside = ordered.find((r) => !r.horizontal);
+    if (beside) {
+        const A = toXY(beside.p, rankVertical), B = toXY(beside.q, rankVertical);
+        const midY = A.y + Math.floor((B.y - A.y) / 2);
+        if (cv.freeH(midY, A.x + 1, A.x + labelW))
+            cv.text(A.x + 1, midY, label, "elabel");
+        else if (cv.freeH(midY, A.x - labelW, A.x - 1))
+            cv.text(A.x - labelW, midY, label, "elabel");
+        else
+            dropped.labels++;
+        return;
+    }
+    dropped.labels++;
+}
+// ── 7. Strip layout (long chains) ───────────────────────────────────────────
+/**
+ * Flow the topological order into wrapped rows of boxes. Chosen when layered
+ * placement cannot fit: a 20-node version timeline becomes 3 rows of boxes
+ * instead of 20 rows of boxes.
+ */
+function stripLayout(g, opts) {
+    const { layers, back } = rankLayers(g);
+    if (layers.length === 0)
+        return null;
+    const sizes = sizeBoxes(g, opts.cap, 3);
+    const order = [];
+    for (const L of layers)
+        order.push(...L);
+    const byId = new Map(g.nodes.map((n) => [n.id, n]));
+    const next = new Map();
+    for (const e of g.edges) {
+        if (back.has(e))
+            continue;
+        if (!next.has(e.from))
+            next.set(e.from, { id: e.to, style: e.style, label: e.label });
+    }
+    const rows = [];
+    let current = [];
+    let x = 0;
+    for (const id of order) {
+        const size = sizes.get(id);
+        const prev = current[current.length - 1];
+        const linked = prev !== undefined && next.get(prev.id)?.id === id;
+        const gap = linked ? STRIP_GAP : GAP;
+        if (current.length > 0 && x + gap + size.w > opts.width) {
+            rows.push(current);
+            current = [];
+            x = 0;
+        }
+        current.push({
+            id, row: rows.length, lines: size.lines, shape: byId.get(id).shape,
+            rect: { x, y: 0, w: size.w, h: size.h },
+        });
+        x += gap + size.w;
+    }
+    if (current.length > 0)
+        rows.push(current);
+    // Stack rows, vertically centering each box inside its row band.
+    let y = 0;
+    for (const row of rows) {
+        const h = row.reduce((max, p) => Math.max(max, p.rect.h), 0);
+        for (const p of row)
+            p.rect.y = y + Math.floor((h - p.rect.h) / 2);
+        y += h + STRIP_BAND;
+    }
+    const height = y - STRIP_BAND;
+    const width = rows.reduce((max, row) => {
+        const last = row[row.length - 1];
+        return Math.max(max, last ? last.rect.x + last.rect.w : 0);
+    }, 0);
+    if (width < 1 || height < 1 || width > opts.width || height > opts.maxRows)
+        return null;
+    const cv = new Canvas(width, height);
+    const placed = new Map();
+    for (const row of rows)
+        for (const p of row) {
+            placed.set(p.id, p);
+            cv.box(p.rect, p.lines, p.shape);
+        }
+    const notes = [];
+    let drawn = 0;
+    let labelsDropped = 0;
+    for (let i = 0; i + 1 < order.length; i++) {
+        const a = placed.get(order[i]);
+        const b = placed.get(order[i + 1]);
+        const link = next.get(order[i]);
+        if (!a || !b || !link || link.id !== order[i + 1])
+            continue;
+        if (a.row === b.row) {
+            // Same row: `──▶` across the gap, on the line joining the two box middles.
+            const midY = Math.floor((a.rect.y + Math.floor(a.rect.h / 2) + b.rect.y + Math.floor(b.rect.h / 2)) / 2);
+            const from = a.rect.x + a.rect.w;
+            const to = b.rect.x - 1;
+            cv.hLine(midY, from, to - 1, link.style);
+            cv.arrow(to, midY, "right");
+            if (link.label === "" || to - from >= measure(link.label) + 2) {
+                const start = from + Math.floor((to - from - measure(link.label)) / 2);
+                cv.text(start, midY - 1, link.label, "elabel");
+            }
+            else
+                labelsDropped++;
+            drawn++;
+            continue;
+        }
+        // Wrapped to the next row: down out of `a`, across the band, down into `b`.
+        const sx = a.rect.x + Math.floor(a.rect.w / 2);
+        const tx = b.rect.x + Math.floor(b.rect.w / 2);
+        const headY = Math.max(a.rect.y + a.rect.h, b.rect.y - 1);
+        const runY = Math.max(a.rect.y + a.rect.h, headY - 1);
+        cv.line(sx, runY, UP | LEFT, link.style);
+        cv.hLine(runY, tx + 1, sx - 1, link.style);
+        cv.line(tx, runY, DOWN | RIGHT, link.style);
+        cv.arrow(tx, headY, "down");
+        drawn++;
+    }
+    if (labelsDropped > 0)
+        notes.push(`${labelsDropped} edge label(s) omitted (no room)`);
+    for (const e of g.edges)
+        if (back.has(e)) {
+            notes.push(`${charset.loop} cycle edge: ${byId.get(e.from)?.label ?? e.from} → ${byId.get(e.to)?.label ?? e.to}`);
+        }
+    const skipped = g.edges.length - back.size - drawn;
+    if (skipped > 0)
+        notes.push(`${skipped} side edge(s) not drawn (chain order only)`);
+    return finalize(cv, {
+        mode: "strip",
+        direction: "chain",
+        nodes: placed.size,
+        edges: drawn,
+        notes: [...g.notes, ...notes],
+    });
+}
+// ── 8. Entry point ──────────────────────────────────────────────────────────
+const cache = new Map();
+const CACHE_MAX = 24;
+/**
+ * Render a mermaid flowchart into a raster, or null when the source is not a
+ * flowchart, is too large, or cannot fit the pane. Cached per source+width so
+ * the row estimator and the renderer share one layout pass.
+ */
+export function renderFlowchart(lines, width, maxRows = 40) {
+    const key = `${width}x${maxRows}\u0000${lines.join("\n")}`;
+    const hit = cache.get(key);
+    if (hit !== undefined)
+        return hit;
+    let result = null;
+    try {
+        const graph = parseFlowchart(lines);
+        if (graph) {
+            for (const cap of LAYERED_CAPS) {
+                result = layeredLayout(graph, { width, maxRows, cap });
+                if (result)
+                    break;
+            }
+            if (!result) {
+                for (const cap of STRIP_CAPS) {
+                    result = stripLayout(graph, { width, maxRows, cap });
+                    if (result)
+                        break;
+                }
+            }
+        }
+    }
+    catch {
+        result = null; // caller falls back to the summary box
+    }
+    if (cache.size >= CACHE_MAX)
+        cache.delete(cache.keys().next().value ?? "");
+    cache.set(key, result);
+    return result;
+}