mellos-mapping 0.20.0 → 0.20.2

package/lib/render/render.js

@@ -5,6 +5,22 @@
  * (colored, animated). Pure function of (map, options): no I/O, no clock —
  * animation is driven by the caller passing a spinner frame index.
  *
+ * This file is the COMPOSITION ROOT of the picture and holds the public
+ * surface; each stage lives beside it and knows nothing of the next:
+ *
+ *   width.ts          how many columns a string takes (the grid's foundation)
+ *   options.ts        what a caller asks for
+ *   canvas.ts         the drawing surface: cells, mask algebra, ANSI emission
+ *   skins.ts          status vocabulary -> this medium's borders and colors
+ *   zoom-geometry.ts  what one rung of the zoom ladder buys, in cells
+ *   layout.ts         where every box goes (columns, then rows)
+ *   routing.ts        how each edge gets there (columns and track rows)
+ *   draw.ts           transcription of all of the above onto the canvas
+ *
+ * The pipeline reads in that order and only forward: sizes and columns fix
+ * the width, routing needs the columns, the row layout needs routing's track
+ * counts, and drawing needs everything. Nothing drawn is ever decided.
+ *
  * Visual language — a dark circuit board:
  *   rank 0 renders at the BOTTOM of the picture ("primitives are the
  *   ground"). Wiring and band bars are FAINT; the glowing things are the
@@ -14,21 +30,10 @@
  *   planned      dashed dim rounded box, '·'  — a ghost: designed, not built
  *   in-progress  amber rounded box, spinner   — where attention currently is
  *   done         heavy green box, '■'         — built and verified
+ *   done, no evidence   the same box, hollow '□' in a dimmer green — the
+ *                ledger's fourth rule, made visible
  *   regressed    heavy red box, '✗'           — was done, foundation cracked
  *
- * Routing preference, in order:
- *   1. STRAIGHT — an adjacent-band edge whose box borders share a free
- *      column is one vertical line, no corners.
- *   2. DOGLEG — descend, run horizontally on a track row in the gap above
- *      the target band, descend. Tracks are PACKED: segments that do not
- *      overlap share a row, keeping bands close together.
- *   3. THREAD — a skip-level edge descends through the nearest column that
- *      is free of boxes in every intermediate band (threading the needle
- *      between boxes); only if no such column exists does it fall back to a
- *      private column on the right margin.
- * Crossings merge into proper junction characters via a direction-bitmask
- * union instead of any routing cleverness.
- *
  * Zoom — terminals cannot scale glyphs, so zooming out first COMPRESSES the
  * geometry (gaps, breathing rows, padding shrink; labels truncate toward a
  * scale-proportional budget) while boxes stay boxes. Only when a further
@@ -47,408 +52,20 @@
  * The same layout/routing machinery runs at every step; only the per-node
  * box spec (size, border, content) and the whitespace geometry change.
  */
-import { ZOOM_DEFAULT, aggregateMap, flipForSequence, isNeutralKind, zoomMode } from '../semantics/semantics.js';
-// The view-semantics vocabulary (zoom ladder, neutral-kind rule) is defined in
-// ../semantics and re-exported here so terminal consumers keep one import site.
-export { ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, clampZoom, isNeutralKind, zoomLabel } from '../semantics/semantics.js';
-// ---------------------------------------------------------------------------
-// display width — CJK-aware, because labels will often be Chinese
-// ---------------------------------------------------------------------------
-const WIDE_RANGES = [
-    [0x1100, 0x115f], // Hangul Jamo
-    [0x2e80, 0xa4cf], // CJK radicals .. Yi (covers CJK Unified Ideographs)
-    [0xa960, 0xa97f],
-    [0xac00, 0xd7a3], // Hangul syllables
-    [0xf900, 0xfaff], // CJK compatibility ideographs
-    [0xfe10, 0xfe19],
-    [0xfe30, 0xfe6f],
-    [0xff00, 0xff60], // fullwidth forms
-    [0xffe0, 0xffe6],
-    [0x20000, 0x3fffd], // CJK extension planes
-];
-function charWidth(cp) {
-    for (const [lo, hi] of WIDE_RANGES) {
-        if (cp >= lo && cp <= hi)
-            return 2;
-    }
-    return 1;
-}
-/** Terminal column width of a string (CJK chars occupy two columns). */
-export function displayWidth(text) {
-    let w = 0;
-    for (const ch of text)
-        w += charWidth(ch.codePointAt(0));
-    return w;
-}
-/** Truncate to a display width, ANSI-free input, appending … when cut. */
-export function fitWidth(s, width) {
-    if (displayWidth(s) <= width)
-        return s;
-    let out = '';
-    let w = 0;
-    for (const ch of s) {
-        const cw = displayWidth(ch);
-        if (w + cw > width - 1)
-            break;
-        out += ch;
-        w += cw;
-    }
-    return out + '…';
-}
-/** Hard word-wrap by display width (CJK-aware, splits anywhere). */
-export function wrapWidth(s, width) {
-    const lines = [];
-    let line = '';
-    let w = 0;
-    for (const ch of s.replace(/\r/g, '')) {
-        if (ch === '\n') {
-            lines.push(line);
-            line = '';
-            w = 0;
-            continue;
-        }
-        const cw = displayWidth(ch);
-        if (w + cw > width) {
-            lines.push(line);
-            line = '';
-            w = 0;
-        }
-        line += ch;
-        w += cw;
-    }
-    if (line !== '')
-        lines.push(line);
-    return lines;
-}
-// ---------------------------------------------------------------------------
-// line-character algebra — junctions emerge from direction bitmask unions
-// ---------------------------------------------------------------------------
-const UP = 1;
-const DOWN = 2;
-const LEFT = 4;
-const RIGHT = 8;
-const LIGHT_BY_MASK = {
-    [UP]: '│',
-    [DOWN]: '│',
-    [LEFT]: '─',
-    [RIGHT]: '─',
-    [UP | DOWN]: '│',
-    [LEFT | RIGHT]: '─',
-    [DOWN | RIGHT]: '┌',
-    [DOWN | LEFT]: '┐',
-    [UP | RIGHT]: '└',
-    [UP | LEFT]: '┘',
-    [UP | DOWN | RIGHT]: '├',
-    [UP | DOWN | LEFT]: '┤',
-    [DOWN | LEFT | RIGHT]: '┬',
-    [UP | LEFT | RIGHT]: '┴',
-    [UP | DOWN | LEFT | RIGHT]: '┼',
-};
-function maskChar(mask, heavyHorizontal, unicode) {
-    if (!unicode) {
-        const hasV = (mask & (UP | DOWN)) !== 0;
-        const hasH = (mask & (LEFT | RIGHT)) !== 0;
-        if (hasV && hasH)
-            return '+';
-        return hasV ? '|' : '-';
-    }
-    if (heavyHorizontal) {
-        if (mask === (LEFT | RIGHT))
-            return '━';
-        if (mask === (UP | DOWN | LEFT | RIGHT))
-            return '┿';
-    }
-    return LIGHT_BY_MASK[mask] ?? '┼';
-}
-/** SGR parameter per style; combined with bold ("1") at emit time. */
-const SGR = {
-    none: '',
-    dim: '2',
-    amber: '33',
-    green: '32',
-    red: '31',
-    faint: '90',
-};
-const ANSI_RESET = '\x1b[0m';
-/** Junction replacements when a routed line meets a literal border character. */
-const BORDER_JUNCTION = {
-    '─': { down: '┬', up: '┴' },
-    '╌': { down: '┬', up: '┴' },
-    '━': { down: '┯', up: '┷' },
-    '-': { down: '+', up: '+' },
-    '.': { down: '+', up: '+' },
-};
-class Canvas {
-    rows = [];
-    cell(x, y) {
-        while (this.rows.length <= y)
-            this.rows.push([]);
-        const row = this.rows[y];
-        while (row.length <= x)
-            row.push({ mask: 0, heavyHorizontal: false, bright: false, style: 'none', bold: false });
-        return row[x];
-    }
-    get height() {
-        return this.rows.length;
-    }
-    get width() {
-        return this.rows.reduce((max, row) => Math.max(max, row.length), 0);
-    }
-    /** Write literal text starting at (x, y). Returns the column just past it. */
-    text(x, y, s, style, bold = false) {
-        let cx = x;
-        for (const ch of s) {
-            const c = this.cell(cx, y);
-            c.literal = ch;
-            c.style = style;
-            c.bold = bold;
-            const w = charWidth(ch.codePointAt(0));
-            if (w === 2) {
-                // The second column of a wide character is a phantom cell: it must
-                // exist so later writes don't overlap, but it emits nothing.
-                const phantom = this.cell(cx + 1, y);
-                phantom.literal = '';
-                phantom.style = style;
-            }
-            cx += w;
-        }
-        return cx;
-    }
-    /** Merge a routed-line direction mask into (x, y). */
-    line(x, y, mask, heavyHorizontal = false, bright = false) {
-        const c = this.cell(x, y);
-        if (c.literal !== undefined) {
-            const junction = BORDER_JUNCTION[c.literal];
-            const replacement = mask & DOWN ? junction?.down : mask & UP ? junction?.up : undefined;
-            if (replacement !== undefined)
-                c.literal = replacement;
-            return; // literals other than borders (labels) are never overdrawn
-        }
-        c.mask |= mask;
-        c.heavyHorizontal = c.heavyHorizontal || heavyHorizontal;
-        c.bright = c.bright || bright;
-    }
-    /**
-     * Emit terminal lines, optionally windowed to a viewport. Slicing happens
-     * at the cell level so ANSI codes reopen correctly inside the window and a
-     * CJK character cut in half at either edge degrades to a space instead of
-     * shifting the whole row. Routed wiring (mask cells) emits FAINT — the
-     * circuit board recedes, the boxes glow.
-     */
-    emit(opts, viewport) {
-        const vp = viewport ?? { x: 0, y: 0, width: this.width, height: this.height };
-        const out = [];
-        for (let y = vp.y; y < vp.y + vp.height; y++) {
-            const row = this.rows[y] ?? [];
-            let line = '';
-            let open = '';
-            const end = Math.min(vp.x + vp.width, row.length);
-            for (let x = Math.max(0, vp.x); x < end; x++) {
-                const c = row[x];
-                const isWire = c.literal === undefined && c.mask !== 0;
-                let ch = c.literal !== undefined ? c.literal : isWire ? maskChar(c.mask, c.heavyHorizontal, opts.unicode) : ' ';
-                if (ch === '') {
-                    if (x !== Math.max(0, vp.x))
-                        continue; // phantom half inside the window: already emitted
-                    ch = ' '; // window starts on the right half of a wide character
-                }
-                else if (charWidth(ch.codePointAt(0)) === 2 && x + 1 >= vp.x + vp.width) {
-                    ch = ' '; // wide character whose right half would spill past the window
-                }
-                const params = ch === ' '
-                    ? ''
-                    : isWire
-                        ? c.bright
-                            ? '1' // spotlighted wire: bold default color against the faint board
-                            : SGR.faint
-                        : [SGR[c.style], c.bold ? '1' : ''].filter(Boolean).join(';');
-                if (opts.color && params !== open) {
-                    line += (open !== '' ? ANSI_RESET : '') + (params !== '' ? `\x1b[${params}m` : '');
-                    open = params;
-                }
-                line += ch;
-            }
-            if (opts.color && open !== '')
-                line += ANSI_RESET;
-            out.push(line.replace(/ +$/, ''));
-        }
-        return out;
-    }
-}
-/**
- * Draw an orthogonal polyline through `points` (consecutive points must share
- * an x or a y). Interior cells of a segment carry the segment's axis mask;
- * every point cell carries only the directions of the segments that actually
- * touch it — so path endpoints become clean junction stubs (e.g. ┬ when
- * entering a box border) and turning points become corner characters, all via
- * the same mask union. Zero-length segments vanish naturally.
- */
-function drawPath(canvas, points, bright = false) {
-    for (let i = 0; i + 1 < points.length; i++) {
-        const [x1, y1] = points[i];
-        const [x2, y2] = points[i + 1];
-        if (x1 === x2 && y1 === y2)
-            continue;
-        if (x1 === x2) {
-            const [lo, hi] = y1 < y2 ? [y1, y2] : [y2, y1];
-            for (let yy = lo + 1; yy < hi; yy++)
-                canvas.line(x1, yy, UP | DOWN, false, bright);
-            canvas.line(x1, y1, y2 > y1 ? DOWN : UP, false, bright);
-            canvas.line(x1, y2, y2 > y1 ? UP : DOWN, false, bright);
-        }
-        else {
-            const [lo, hi] = x1 < x2 ? [x1, x2] : [x2, x1];
-            for (let xx = lo + 1; xx < hi; xx++)
-                canvas.line(xx, y1, LEFT | RIGHT, false, bright);
-            canvas.line(x1, y1, x2 > x1 ? RIGHT : LEFT, false, bright);
-            canvas.line(x2, y1, x2 > x1 ? LEFT : RIGHT, false, bright);
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// status vocabulary -> visual vocabulary
-// ---------------------------------------------------------------------------
-const SPINNER_UNICODE = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const SPINNER_ASCII = ['|', '/', '-', '\\'];
-function skinFor(status, unicode) {
-    const style = status === 'planned' ? 'dim' : status === 'in-progress' ? 'amber' : status === 'done' ? 'green' : 'red';
-    if (!unicode) {
-        return status === 'planned'
-            ? { h: '.', v: ':', corners: ['+', '+', '+', '+'], style }
-            : { h: '-', v: '|', corners: ['+', '+', '+', '+'], style };
-    }
-    switch (status) {
-        case 'planned':
-            return { h: '╌', v: '╎', corners: ['╭', '╮', '╰', '╯'], style };
-        case 'in-progress':
-            return { h: '─', v: '│', corners: ['╭', '╮', '╰', '╯'], style };
-        case 'done':
-        case 'regressed':
-            return { h: '━', v: '┃', corners: ['┏', '┓', '┗', '┛'], style };
-    }
-}
-function glyphFor(status, opts) {
-    const spinner = opts.unicode ? SPINNER_UNICODE : SPINNER_ASCII;
-    switch (status) {
-        case 'planned':
-            return opts.unicode ? '·' : '.';
-        case 'in-progress':
-            return spinner[opts.spinnerFrame % spinner.length];
-        case 'done':
-            return opts.unicode ? '■' : '#';
-        case 'regressed':
-            return opts.unicode ? '✗' : 'X';
-    }
-}
-/**
- * Known node kinds -> [unicode, ascii] glyphs (all display width 1).
- * Behavior trees, dataflow and architecture vocabularies; an unknown kind
- * renders without a glyph and stays readable in the detail panel.
- */
-const NODE_KIND_GLYPHS = {
-    selector: ['?', '?'],
-    sequence: ['»', '>'],
-    parallel: ['‖', '='],
-    decorator: ['◌', 'o'],
-    condition: ['◇', 'c'],
-    action: ['·', '.'],
-    source: ['○', 'o'],
-    transform: ['◐', '%'],
-    sink: ['●', '*'],
-    service: ['◆', 'S'],
-    db: ['▤', 'D'],
-    queue: ['≣', 'Q'],
-    ui: ['▣', 'U'],
-};
-/** Glyph for a node kind, or undefined for unknown kinds. Shared with the watcher's panel. */
-export function kindGlyph(kind, unicode) {
-    const pair = NODE_KIND_GLYPHS[kind];
-    return pair === undefined ? undefined : unicode ? pair[0] : pair[1];
-}
-/** Plain solid box for documentation diagrams — presence, not progress. */
-function neutralSkin(unicode) {
-    return unicode
-        ? { h: '─', v: '│', corners: ['╭', '╮', '╰', '╯'], style: 'none' }
-        : { h: '-', v: '|', corners: ['+', '+', '+', '+'], style: 'none' };
-}
-// ---------------------------------------------------------------------------
-// layout
-// ---------------------------------------------------------------------------
-const BOX_H = 3;
-const BOX_GAP = 2;
-const LEFT_MARGIN = 2;
-/** +1: a readable unfold. +2: the box grows into a reading card. */
-const DETAIL_BUDGET = { innerMin: 22, innerMax: 32, noteRows: 3 };
-const DETAIL_PLUS_BUDGET = { innerMin: 30, innerMax: 48, noteRows: 12 };
-function zoomGeometry(zoom) {
-    // WHICH steps switch mode is semantics (zoomMode); this table owns only the
-    // whitespace and label budgets each step buys in terminal cells.
-    const m = zoomMode(zoom);
-    const mode = m === 'overview' ? 'constellation' : m;
-    switch (zoom) {
-        case 2:
-            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_PLUS_BUDGET };
-        case 1:
-            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_BUDGET };
-        case 0:
-            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
-        case -1:
-            return { mode, scale: 0.85, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
-        case -2:
-            return { mode, scale: 0.7, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: false };
-        case -3:
-            return { mode, scale: 0.55, pad: 0, boxGap: 1, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
-        case -4:
-            return { mode, scale: 0, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
-    }
-}
-const LABEL_BUDGET_MIN = 4;
-/** Size and content of one node's box under the given zoom geometry. */
-function boxSpec(node, geo, unicode, neutral) {
-    // On dev pages the glyph slot belongs to the status, so a known kind glyph
-    // joins the label text; on neutral pages the kind takes the slot itself.
-    // A node with a child map wears the dive badge at the end of its label —
-    // appended AFTER width fitting, so truncation can never eat the badge.
-    const glyph = node.kind !== undefined ? kindGlyph(node.kind, unicode) : undefined;
-    const badge = node.submap !== undefined ? (unicode ? ' ⊞' : ' +') : '';
-    const badgeW = displayWidth(badge);
-    const text = !neutral && glyph !== undefined ? `${glyph} ${node.label}` : node.label;
-    if (geo.mode === 'constellation') {
-        return { w: 3, h: 1, label: '', pad: 0, borderless: true, extra: [] };
-    }
-    if (geo.mode === 'detail' && geo.detail !== undefined) {
-        const budget = geo.detail;
-        const innerW = Math.min(Math.max(displayWidth(text) + badgeW + 4, budget.innerMin), budget.innerMax);
-        const extra = [];
-        if (node.evidence !== undefined)
-            extra.push({ text: fitWidth(` ${node.evidence}`, innerW), style: 'faint' });
-        if (node.detail !== undefined) {
-            const wrapped = wrapWidth(node.detail, innerW - 2);
-            for (let i = 0; i < Math.min(wrapped.length, budget.noteRows); i++) {
-                const cut = i === budget.noteRows - 1 && wrapped.length > budget.noteRows;
-                extra.push({ text: ` ${cut ? fitWidth(wrapped[i] + '…', innerW - 2) : wrapped[i]}`, style: 'none' });
-            }
-        }
-        return {
-            w: innerW + 2,
-            h: BOX_H + extra.length,
-            label: fitWidth(text, innerW - 4 - badgeW) + badge,
-            pad: 1,
-            borderless: false,
-            extra,
-        };
-    }
-    const budget = Math.max(LABEL_BUDGET_MIN, Math.ceil(displayWidth(text) * geo.scale));
-    const label = fitWidth(text, budget) + badge;
-    return {
-        w: displayWidth(label) + 4 + 2 * geo.pad,
-        h: BOX_H,
-        label,
-        pad: geo.pad,
-        borderless: false,
-        extra: [],
-    };
-}
+import { ZOOM_DEFAULT, aggregateMap, flipForSequence, isNeutralKind } from '../semantics/semantics.js';
+import { Canvas } from './canvas.js';
+import { drawBands, drawBox, drawEdges, drawLaneHeaders, drawLegend, drawTitle } from './draw.js';
+import { layoutColumns, layoutRows } from './layout.js';
+import { routeEdges } from './routing.js';
+import { unverifiedDoneIds } from './skins.js';
+import { displayWidth } from './width.js';
+import { AGGREGATE_GEO, zoomGeometry } from './zoom-geometry.js';
+export { displayWidth, fitWidth, wrapWidth } from './width.js';
+export { statusSgr } from './skins.js';
+// The medium-neutral vocabulary (zoom ladder, neutral-kind rule, status and
+// node-kind glyphs) is defined in ../semantics and re-exported here so
+// terminal consumers keep one import site.
+export { ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, clampZoom, isNeutralKind, kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph, zoomLabel, } from '../semantics/semantics.js';
 /** Render the whole map as terminal lines. */
 export function renderMap(map, opts) {
     const built = buildCanvas(map, opts);
@@ -464,362 +81,43 @@ export function renderMapWindow(map, opts, viewport) {
         hits: built.hits,
     };
 }
-/** Geometry for the aggregated far zoom: tight chrome, but FULL labels — the point is names. */
-const AGGREGATE_GEO = {
-    mode: 'boxes',
-    scale: 1,
-    pad: 0,
-    boxGap: 1,
-    breathe: 0,
-    titleGap: 0,
-    barGap: 1,
-    bandCounts: false,
-};
 function buildCanvas(map, opts) {
     const oriented = flipForSequence(map);
     const plainGeo = zoomGeometry(opts.zoom ?? ZOOM_DEFAULT);
+    // The far zoom does not shrink the map, it AGGREGATES it: groups become one
+    // box each. Which map is drawn is decided here, once.
     const aggregated = plainGeo.mode === 'constellation' ? aggregateMap(oriented) : undefined;
-    return buildCanvasWith(aggregated ?? oriented, opts, aggregated !== undefined ? AGGREGATE_GEO : plainGeo);
+    const drawn = aggregated ?? oriented;
+    return paint(drawn, opts, aggregated !== undefined ? AGGREGATE_GEO : plainGeo, unverifiedDoneIds(oriented, drawn));
 }
-function buildCanvasWith(map, opts, geo) {
+function paint(map, opts, geo, unverified) {
     const canvas = new Canvas();
-    const neutral = isNeutralKind(map);
-    const bands = [...map.layers].sort((a, b) => b.rank - a.rank); // index 0 = top band
-    if (bands.length === 0) {
+    if (map.layers.length === 0) {
         canvas.text(0, 0, map.title ?? 'mellos mapping', 'none', true);
         canvas.text(0, 2, '(empty map — declare layers and nodes to begin)', 'dim');
         return { canvas, hits: [] };
     }
-    // -- horizontal layout: one row of boxes per band --
-    const bandIndexOf = new Map(bands.map((l, i) => [l.id, i]));
-    const boxes = new Map();
-    const bandBoxes = bands.map(() => []);
-    for (const node of map.nodes) {
-        const band = bandIndexOf.get(node.layer);
-        const box = { node, ...boxSpec(node, geo, opts.unicode, neutral), x: LEFT_MARGIN, y: 0 };
-        bandBoxes[band].push(box);
-        boxes.set(node.id, box);
-    }
-    // Column assignment. Without lanes each band packs left-to-right in
-    // declaration order. With lanes every band is partitioned into the lane
-    // columns (plus a trailing off-lane region); a lane is as wide as its
-    // widest band row or its own header label, so members align vertically
-    // under their column across all bands.
-    const laneCount = map.lanes.length;
-    const laneX = [];
-    const laneW = [];
-    if (laneCount === 0) {
-        for (const row of bandBoxes) {
-            let x = LEFT_MARGIN;
-            for (const box of row) {
-                box.x = x;
-                x += box.w + geo.boxGap;
-            }
-        }
-    }
-    else {
-        const laneGap = geo.boxGap + 2;
-        const laneIndexOf = new Map(map.lanes.map((l, i) => [l.id, i]));
-        const regions = laneCount + 1; // trailing region for off-lane nodes
-        const grouped = bandBoxes.map((row) => {
-            const cells = Array.from({ length: regions }, () => []);
-            for (const box of row) {
-                const lane = box.node.lane;
-                cells[lane !== undefined ? laneIndexOf.get(lane) : regions - 1].push(box);
-            }
-            return cells;
-        });
-        const regionW = Array.from({ length: regions }, () => 0);
-        for (const cells of grouped) {
-            for (let i = 0; i < regions; i++) {
-                const rowW = cells[i].reduce((sum, b, k) => sum + b.w + (k > 0 ? geo.boxGap : 0), 0);
-                regionW[i] = Math.max(regionW[i], rowW);
-            }
-        }
-        for (let i = 0; i < laneCount; i++)
-            regionW[i] = Math.max(regionW[i], displayWidth(map.lanes[i].label) + 2);
-        let x0 = LEFT_MARGIN;
-        for (let i = 0; i < regions; i++) {
-            laneX.push(x0);
-            laneW.push(regionW[i]);
-            x0 += regionW[i] + laneGap;
-        }
-        for (const cells of grouped) {
-            for (let i = 0; i < regions; i++) {
-                let x = laneX[i];
-                for (const box of cells[i]) {
-                    box.x = x;
-                    x += box.w + geo.boxGap;
-                }
-            }
-        }
-    }
-    // Band bar labels; at small scales the boxes go mute, so the bars carry
-    // the aggregate progress (done/total) for their band instead. Neutral
-    // documentation kinds never count progress.
-    const bandLabel = bands.map((l, i) => {
-        const row = bandBoxes[i];
-        const done = row.filter((b) => b.node.status === 'done').length;
-        return geo.bandCounts && row.length > 0 && !neutral ? ` ${l.name} ${done}/${row.length}` : ` ${l.name}`;
-    });
-    let contentWidth = LEFT_MARGIN;
-    for (const row of bandBoxes) {
-        const last = row[row.length - 1];
-        if (last)
-            contentWidth = Math.max(contentWidth, last.x + last.w);
-    }
-    for (let i = 0; i < laneCount; i++)
-        contentWidth = Math.max(contentWidth, laneX[i] + laneW[i]);
-    for (const label of bandLabel)
-        contentWidth = Math.max(contentWidth, LEFT_MARGIN + displayWidth(label) + 7);
-    // -- edge analysis (see module header for the routing preference order) --
-    const routes = map.edges.map((e) => {
-        const fromBox = boxes.get(e.from);
-        const toBox = boxes.get(e.to);
-        return {
-            fromBox,
-            toBox,
-            fromBand: bandIndexOf.get(fromBox.node.layer),
-            toBand: bandIndexOf.get(toBox.node.layer),
-        };
-    });
-    // Attach columns already promised on a box's border (either side).
-    const claimedColumns = new Map();
-    const isFree = (box, x) => !(claimedColumns.get(box)?.has(x) ?? false);
-    const claim = (box, x) => {
-        let set = claimedColumns.get(box);
-        if (!set)
-            claimedColumns.set(box, (set = new Set()));
-        set.add(x);
-        return x;
-    };
-    // 1. STRAIGHT edges
-    const straightX = new Map();
-    for (const r of routes) {
-        if (r.toBand - r.fromBand !== 1)
-            continue;
-        const lo = Math.max(r.fromBox.x + 1, r.toBox.x + 1);
-        const hi = Math.min(r.fromBox.x + r.fromBox.w - 2, r.toBox.x + r.toBox.w - 2);
-        if (lo > hi)
-            continue; // no vertical overlap — a dogleg is genuinely needed
-        const mid = Math.floor((lo + hi) / 2);
-        for (let d = 0; d <= hi - lo && !straightX.has(r); d++) {
-            for (const x of d === 0 ? [mid] : [mid - d, mid + d]) {
-                if (x >= lo && x <= hi && isFree(r.fromBox, x) && isFree(r.toBox, x)) {
-                    straightX.set(r, claim(r.toBox, claim(r.fromBox, x)));
-                    break;
-                }
-            }
-        }
-    }
-    // 2. attach slots for the bent rest, nudged off claimed columns
-    const bent = routes.filter((r) => !straightX.has(r));
-    const outgoing = new Map();
-    const incoming = new Map();
-    for (const r of bent) {
-        outgoing.set(r.fromBox, [...(outgoing.get(r.fromBox) ?? []), r]);
-        incoming.set(r.toBox, [...(incoming.get(r.toBox) ?? []), r]);
-    }
-    const freeSlot = (box, k, n) => {
-        const lo = box.x + 1;
-        const hi = box.x + box.w - 2;
-        const ideal = box.x + Math.min(box.w - 2, Math.max(1, Math.round(((k + 1) * (box.w - 1)) / (n + 1))));
-        for (let d = 0; d <= hi - lo; d++) {
-            for (const x of d === 0 ? [ideal] : [ideal - d, ideal + d]) {
-                if (x >= lo && x <= hi && isFree(box, x))
-                    return claim(box, x);
-            }
-        }
-        return ideal; // every column claimed (extremely crowded box) — overlap and live with it
-    };
-    const attach = new Map();
-    for (const r of bent) {
-        const outs = outgoing.get(r.fromBox);
-        const ins = incoming.get(r.toBox);
-        attach.set(r, {
-            sx: freeSlot(r.fromBox, outs.indexOf(r), outs.length),
-            ex: freeSlot(r.toBox, ins.indexOf(r), ins.length),
-        });
-    }
-    // 3. THREAD descent columns for skip-level edges
-    const skipRoutes = bent.filter((r) => r.toBand - r.fromBand > 1);
-    const usedDescent = new Set();
-    const descentX = new Map();
-    let fallbackCount = 0;
-    const blockedByBox = (band, x) => bandBoxes[band].some((b) => x >= b.x && x <= b.x + b.w - 1);
-    for (const r of skipRoutes) {
-        const { ex } = attach.get(r);
-        let chosen;
-        for (let d = 0; d <= contentWidth && chosen === undefined; d++) {
-            for (const c of d === 0 ? [ex] : [ex - d, ex + d]) {
-                if (c < LEFT_MARGIN || c > contentWidth + 1 || usedDescent.has(c))
-                    continue;
-                let blocked = false;
-                for (let b = r.fromBand + 1; b < r.toBand && !blocked; b++)
-                    blocked = blockedByBox(b, c);
-                if (!blocked) {
-                    chosen = c;
-                    break;
-                }
-            }
-        }
-        if (chosen === undefined)
-            chosen = contentWidth + 2 + fallbackCount++ * 2; // margin fallback
-        usedDescent.add(chosen);
-        descentX.set(r, chosen);
-    }
-    const totalWidth = fallbackCount > 0 ? contentWidth + 2 + fallbackCount * 2 : contentWidth;
-    // 4. pack horizontal segments into shared track rows per gap
-    const gapCount = bands.length - 1;
-    const gapSegments = Array.from({ length: gapCount }, () => []);
-    const segmentOf = new Map();
-    for (const r of bent) {
-        const { sx, ex } = attach.get(r);
-        if (r.toBand - r.fromBand === 1) {
-            const landing = { route: r, kind: 'landing', lo: Math.min(sx, ex), hi: Math.max(sx, ex) };
-            gapSegments[r.toBand - 1].push(landing);
-            segmentOf.set(r, { landing });
-        }
-        else {
-            const c = descentX.get(r);
-            const exit = { route: r, kind: 'exit', lo: Math.min(sx, c), hi: Math.max(sx, c) };
-            const landing = { route: r, kind: 'landing', lo: Math.min(c, ex), hi: Math.max(c, ex) };
-            gapSegments[r.fromBand].push(exit);
-            gapSegments[r.toBand - 1].push(landing);
-            segmentOf.set(r, { exit, landing });
-        }
-    }
-    const segmentRow = new Map();
-    const gapRowCount = gapSegments.map((segments) => {
-        const rowEnds = []; // rightmost occupied column per packed row
-        for (const s of [...segments].sort((a, b) => a.lo - b.lo)) {
-            let row = rowEnds.findIndex((end) => s.lo > end + 1);
-            if (row === -1) {
-                rowEnds.push(s.hi);
-                row = rowEnds.length - 1;
-            }
-            else {
-                rowEnds[row] = Math.max(rowEnds[row], s.hi);
-            }
-            segmentRow.set(s, row);
-        }
-        return rowEnds.length;
-    });
-    // -- vertical layout --
-    let y = 0;
-    if (map.title !== undefined)
-        y += 1 + geo.titleGap;
-    let laneHeaderY;
-    if (laneCount > 0) {
-        laneHeaderY = y;
-        y += 1 + geo.barGap;
-    }
-    const barY = [];
-    const gapTrackStartY = [];
-    for (let b = 0; b < bands.length; b++) {
-        barY.push(y);
-        y += 1 + geo.barGap;
-        const row = bandBoxes[b];
-        for (const box of row)
-            box.y = y;
-        y += row.reduce((max, box) => Math.max(max, box.h), geo.mode === 'constellation' ? 1 : BOX_H);
-        if (b < gapCount) {
-            y += geo.breathe; // breathing row below the boxes
-            gapTrackStartY.push(y);
-            y += gapRowCount[b];
-            y += geo.breathe; // breathing row above the next bar
-        }
-    }
-    const legendY = y + 1;
-    const rowYOf = (gap, s) => gapTrackStartY[gap] + segmentRow.get(s);
-    // -- draw: title, lane headers, band bars, boxes --
+    const neutral = isNeutralKind(map);
+    const columns = layoutColumns(map, geo, opts.unicode, neutral);
+    const routing = routeEdges(map, columns);
+    const rows = layoutRows(columns, geo, routing.gapRowCount, map.title !== undefined, map.lanes.length > 0);
+    /** Everything a wire may occupy: the boxes, plus any margin corridor. */
+    const wiredWidth = routing.fallbackCount > 0 ? columns.contentWidth + 2 + routing.fallbackCount * 2 : columns.contentWidth;
+    /** Plus the band labels' own right margin, which nothing else may enter. */
+    const totalWidth = wiredWidth + Math.max(...columns.bandLabel.map(displayWidth));
     if (map.title !== undefined)
-        canvas.text(LEFT_MARGIN, 0, map.title, 'none', true);
-    if (laneHeaderY !== undefined) {
-        for (let i = 0; i < laneCount; i++) {
-            const label = fitWidth(map.lanes[i].label, laneW[i]);
-            const cx = laneX[i] + Math.max(0, Math.floor((laneW[i] - displayWidth(label)) / 2));
-            canvas.text(cx, laneHeaderY, label, 'faint', true);
-        }
-    }
-    for (let b = 0; b < bands.length; b++) {
-        const label = bandLabel[b];
-        for (let x = 0; x < totalWidth; x++)
-            canvas.line(x, barY[b], LEFT | RIGHT, true);
-        // flush right; only a margin-fallback column pushes it back to the content edge
-        const labelStart = (fallbackCount > 0 ? contentWidth : totalWidth) - displayWidth(label);
-        canvas.text(labelStart, barY[b], label, 'none', true);
-    }
-    for (const box of boxes.values()) {
-        drawBox(canvas, box, opts, neutral, opts.focus !== undefined && box.node.id === opts.focus);
-    }
-    // -- draw: edges (wires touching the focused node render bright) --
-    for (const r of routes) {
-        const sy = r.fromBox.y + r.fromBox.h - 1; // bottom border row of the source box
-        const ey = r.toBox.y; // top border row of the target box
-        const bright = opts.focus !== undefined &&
-            (r.fromBox.node.id === opts.focus || r.toBox.node.id === opts.focus);
-        const direct = straightX.get(r);
-        if (direct !== undefined) {
-            drawPath(canvas, [
-                [direct, sy],
-                [direct, ey],
-            ], bright);
-            continue;
-        }
-        const { sx, ex } = attach.get(r);
-        const segments = segmentOf.get(r);
-        const landingY = rowYOf(r.toBand - 1, segments.landing);
-        if (r.toBand - r.fromBand === 1) {
-            drawPath(canvas, [
-                [sx, sy],
-                [sx, landingY],
-                [ex, landingY],
-                [ex, ey],
-            ], bright);
-        }
-        else {
-            const c = descentX.get(r);
-            const exitY = rowYOf(r.fromBand, segments.exit);
-            drawPath(canvas, [
-                [sx, sy],
-                [sx, exitY],
-                [c, exitY],
-                [c, landingY],
-                [ex, landingY],
-                [ex, ey],
-            ], bright);
-        }
-    }
-    // -- legend: status vocabulary on dev pages, kind vocabulary on neutral pages --
-    let lx = LEFT_MARGIN;
-    if (neutral) {
-        lx = canvas.text(lx, legendY, map.kind, 'faint');
-        const seen = new Set();
-        for (const n of map.nodes) {
-            const k = n.kind;
-            if (k === undefined || seen.has(k) || kindGlyph(k, opts.unicode) === undefined)
-                continue;
-            seen.add(k);
-            lx = canvas.text(lx, legendY, '   ', 'none');
-            lx = canvas.text(lx, legendY, `${kindGlyph(k, opts.unicode)} ${k}`, 'none');
-        }
-    }
-    else {
-        const legendOpts = { ...opts, spinnerFrame: 0 };
-        const legendEntries = [
-            ['planned', 'dim'],
-            ['in-progress', 'amber'],
-            ['done', 'green'],
-            ['regressed', 'red'],
-        ];
-        for (const [status, style] of legendEntries) {
-            if (lx > LEFT_MARGIN)
-                lx = canvas.text(lx, legendY, '   ', 'none');
-            lx = canvas.text(lx, legendY, `${glyphFor(status, legendOpts)} ${status}`, style);
-        }
-    }
-    const hits = [...boxes.values()].map((b) => ({
+        drawTitle(canvas, map.title);
+    drawLaneHeaders(canvas, map, columns, rows);
+    drawBands(canvas, columns, rows, wiredWidth, totalWidth);
+    /** The face a node presents: its status, or the hollow face of an unbacked done. */
+    const faceOf = (id, status) => (unverified.has(id) ? 'done-unverified' : status);
+    for (const box of rows.boxOf.values()) {
+        const id = box.node.id;
+        drawBox(canvas, box, opts, neutral, faceOf(id, box.node.status), opts.focus !== undefined && id === opts.focus);
+    }
+    drawEdges(canvas, routing.edges, rows, opts);
+    drawLegend(canvas, map, opts, rows.legendY, neutral, unverified.size > 0);
+    const hits = [...rows.boxOf.values()].map((b) => ({
         id: b.node.id,
         x: b.x,
         y: b.y,
@@ -828,32 +126,3 @@ function buildCanvasWith(map, opts, geo) {
     }));
     return { canvas, hits };
 }
-function drawBox(canvas, box, opts, neutral, focused = false) {
-    const { node, x, y, w } = box;
-    const skin = neutral ? neutralSkin(opts.unicode) : skinFor(node.status, opts.unicode);
-    // Neutral pages give the glyph slot to the node kind (a bullet when kindless).
-    const slotGlyph = neutral
-        ? (node.kind !== undefined ? kindGlyph(node.kind, opts.unicode) : undefined) ??
-            (opts.unicode ? '·' : '.')
-        : glyphFor(node.status, opts);
-    if (box.borderless) {
-        // Constellation mode: the node IS its glyph. Wires simply end
-        // beside it — a glyph is not a border, so no junction chars appear.
-        canvas.text(x + 1, y, slotGlyph, skin.style, true);
-        return;
-    }
-    const inner = w - 2;
-    const pad = box.pad === 1 ? ' ' : '';
-    canvas.text(x, y, skin.corners[0] + skin.h.repeat(inner) + skin.corners[1], skin.style, focused);
-    canvas.text(x, y + 1, skin.v, skin.style, focused);
-    canvas.text(x + 1, y + 1, `${pad}${slotGlyph} ${box.label}${pad}`, skin.style, true);
-    canvas.text(x + w - 1, y + 1, skin.v, skin.style, focused);
-    for (let i = 0; i < box.extra.length; i++) {
-        const row = box.extra[i];
-        const yy = y + 2 + i;
-        canvas.text(x, yy, skin.v, skin.style, focused);
-        canvas.text(x + 1, yy, row.text, row.style);
-        canvas.text(x + w - 1, yy, skin.v, skin.style, focused);
-    }
-    canvas.text(x, y + box.h - 1, skin.corners[2] + skin.h.repeat(inner) + skin.corners[3], skin.style, focused);
-}