mellos-mapping 0.20.0 → 0.20.2

package/lib/render/canvas.js

@@ -0,0 +1,210 @@
+/**
+ * Layer 4a — the drawing surface: a grid of cells that knows how to merge
+ * crossing lines, and how to emit itself as terminal rows.
+ *
+ * Two kinds of ink live in a cell. A LITERAL is a character somebody chose (a
+ * label, a box border); a MASK is a set of directions a routed line passes
+ * through, and the character comes out of the mask at emit time. That is what
+ * makes junctions free: two wires crossing simply union their masks, and ┼
+ * appears without anyone routing around anything.
+ *
+ * The surface knows nothing about maps, statuses or zoom — it takes a Style
+ * (the ink palette below) and coordinates, and it is the only place ANSI is
+ * produced.
+ */
+import { charWidth } from './width.js';
+/** SGR parameter per style; combined with bold ("1") at emit time. */
+export const SGR = {
+    none: '',
+    dim: '2',
+    amber: '33',
+    green: '32',
+    greenDim: '32;2', // done, but nothing behind the claim: green, not fully lit
+    red: '31',
+    faint: '90',
+};
+export const ANSI_RESET = '\x1b[0m';
+// ---------------------------------------------------------------------------
+// line-character algebra — junctions emerge from direction bitmask unions
+// ---------------------------------------------------------------------------
+export const UP = 1;
+export const DOWN = 2;
+export const LEFT = 4;
+export 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] ?? '┼';
+}
+/** Junction replacements when a routed line meets a literal border character. */
+const BORDER_JUNCTION = {
+    '─': { down: '┬', up: '┴' },
+    '╌': { down: '┬', up: '┴' },
+    '━': { down: '┯', up: '┷' },
+    '-': { down: '+', up: '+' },
+    '.': { down: '+', up: '+' },
+};
+export 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 w = charWidth(ch.codePointAt(0));
+            if (w === 0) {
+                // A combining mark, a variation selector or a skin tone takes no
+                // column of its own: it rides on the cell it modifies. Given one, it
+                // would overwrite the base character and the row would shift left.
+                const base = this.cell(Math.max(0, cx - 1), y);
+                const target = base.literal === '' ? this.cell(Math.max(0, cx - 2), y) : base; // skip a wide char's phantom half
+                target.literal = (target.literal ?? '') + ch;
+                continue;
+            }
+            const c = this.cell(cx, y);
+            c.literal = ch;
+            c.style = style;
+            c.bold = bold;
+            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.
+ */
+export 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);
+        }
+    }
+}

package/lib/render/draw.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Layer 4a — putting the decided picture onto the canvas.
+ *
+ * Everything here is the LAST stage: positions, columns and track rows are
+ * already values by the time these functions run, so drawing is a
+ * transcription and never a decision. Order matters in exactly one way — the
+ * band bars go down before the boxes and the wires, so a wire crossing a band
+ * merges into it as ┿ instead of being refused by a literal.
+ */
+import type { MellosMap } from '../domain/types.js';
+import { Canvas } from './canvas.js';
+import type { ColumnLayout, PlacedBox, RowLayout } from './layout.js';
+import type { RenderOptions } from './options.js';
+import { type RoutedEdge } from './routing.js';
+import { type StatusFace } from './skins.js';
+/** The map's title, at the top left of the picture. */
+export declare function drawTitle(canvas: Canvas, title: string): void;
+/** Lane headers, centered over their column region. */
+export declare function drawLaneHeaders(canvas: Canvas, map: MellosMap, columns: ColumnLayout, rows: RowLayout): void;
+/**
+ * The band bars and their labels. A bar spans everything a wire may occupy;
+ * the label lives in a margin of its own to the right of that, because a
+ * label written over the bar REPLACES cells, and the canvas refuses to
+ * overdraw a literal — a wire crossing under a label was simply cut.
+ */
+export declare function drawBands(canvas: Canvas, columns: ColumnLayout, rows: RowLayout, wiredWidth: number, totalWidth: number): void;
+/** One node's box: border, glyph, label, and any unfolded detail rows. */
+export declare function drawBox(canvas: Canvas, box: PlacedBox, opts: RenderOptions, neutral: boolean, face: StatusFace, focused?: boolean): void;
+/** Every wire. Those touching the focused node render bright. */
+export declare function drawEdges(canvas: Canvas, edges: readonly RoutedEdge[], rows: RowLayout, opts: RenderOptions): void;
+/**
+ * The legend under the picture: the status vocabulary on a dev page, the kind
+ * vocabulary on a documentation page. The hollow "done, no evidence" face is
+ * named only where the picture shows one — the four statuses are the
+ * vocabulary, that one is a rule being broken in THIS map.
+ */
+export declare function drawLegend(canvas: Canvas, map: MellosMap, opts: RenderOptions, legendY: number, neutral: boolean, anyUnverified: boolean): void;

package/lib/render/draw.js

@@ -0,0 +1,111 @@
+/**
+ * Layer 4a — putting the decided picture onto the canvas.
+ *
+ * Everything here is the LAST stage: positions, columns and track rows are
+ * already values by the time these functions run, so drawing is a
+ * transcription and never a decision. Order matters in exactly one way — the
+ * band bars go down before the boxes and the wires, so a wire crossing a band
+ * merges into it as ┿ instead of being refused by a literal.
+ */
+import { kindGlyph } from '../semantics/semantics.js';
+import { LEFT, RIGHT, drawPath } from './canvas.js';
+import { edgePolyline } from './routing.js';
+import { glyphFor, neutralGlyph, neutralSkin, skinFor, styleFor } from './skins.js';
+import { displayWidth, fitWidth } from './width.js';
+import { LEFT_MARGIN } from './zoom-geometry.js';
+/** The map's title, at the top left of the picture. */
+export function drawTitle(canvas, title) {
+    canvas.text(LEFT_MARGIN, 0, title, 'none', true);
+}
+/** Lane headers, centered over their column region. */
+export function drawLaneHeaders(canvas, map, columns, rows) {
+    if (rows.laneHeaderY === undefined)
+        return;
+    for (let i = 0; i < map.lanes.length; i++) {
+        const region = columns.lanes[i];
+        const label = fitWidth(map.lanes[i].label, region.w);
+        const cx = region.x + Math.max(0, Math.floor((region.w - displayWidth(label)) / 2));
+        canvas.text(cx, rows.laneHeaderY, label, 'faint', true);
+    }
+}
+/**
+ * The band bars and their labels. A bar spans everything a wire may occupy;
+ * the label lives in a margin of its own to the right of that, because a
+ * label written over the bar REPLACES cells, and the canvas refuses to
+ * overdraw a literal — a wire crossing under a label was simply cut.
+ */
+export function drawBands(canvas, columns, rows, wiredWidth, totalWidth) {
+    for (let b = 0; b < columns.bands.length; b++) {
+        const label = columns.bandLabel[b];
+        for (let x = 0; x < wiredWidth; x++)
+            canvas.line(x, rows.barY[b], LEFT | RIGHT, true);
+        canvas.text(totalWidth - displayWidth(label), rows.barY[b], label, 'none', true);
+    }
+}
+/** One node's box: border, glyph, label, and any unfolded detail rows. */
+export function drawBox(canvas, box, opts, neutral, face, focused = false) {
+    const { node, x, y, w } = box;
+    const skin = neutral ? neutralSkin(opts.unicode) : skinFor(face, opts.unicode);
+    // Neutral pages give the glyph slot to the node kind (a bullet when kindless).
+    const slotGlyph = neutral ? neutralGlyph(node, opts.unicode) : glyphFor(face, 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);
+}
+/** Every wire. Those touching the focused node render bright. */
+export function drawEdges(canvas, edges, rows, opts) {
+    for (const edge of edges) {
+        const bright = opts.focus !== undefined &&
+            (edge.from.node.id === opts.focus || edge.to.node.id === opts.focus);
+        drawPath(canvas, edgePolyline(edge, rows), bright);
+    }
+}
+/**
+ * The legend under the picture: the status vocabulary on a dev page, the kind
+ * vocabulary on a documentation page. The hollow "done, no evidence" face is
+ * named only where the picture shows one — the four statuses are the
+ * vocabulary, that one is a rule being broken in THIS map.
+ */
+export function drawLegend(canvas, map, opts, legendY, neutral, anyUnverified) {
+    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');
+        }
+        return;
+    }
+    const legendOpts = { ...opts, spinnerFrame: 0 };
+    const faces = ['planned', 'in-progress', 'done', 'regressed'];
+    if (anyUnverified)
+        faces.push('done-unverified');
+    for (const face of faces) {
+        if (lx > LEFT_MARGIN)
+            lx = canvas.text(lx, legendY, '   ', 'none');
+        const word = face === 'done-unverified' ? 'done, no evidence' : face;
+        lx = canvas.text(lx, legendY, `${glyphFor(face, legendOpts)} ${word}`, styleFor(face));
+    }
+}

package/lib/render/layout.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Layer 4a — where everything goes, decided before anything is drawn.
+ *
+ * Two stages, because the picture's height cannot be known until the wires
+ * are routed: first COLUMNS (how wide each box is and which column it starts
+ * at, which fixes the picture's width), then — once routing has said how many
+ * track rows each band gap needs — ROWS. Nothing here draws; nothing here
+ * mutates a box after placing it, so a position is a value another stage can
+ * hold on to.
+ *
+ * Bands are the map's layers, top band first: rank 0 renders at the BOTTOM
+ * ("primitives are the ground"), so the sort is descending.
+ */
+import type { MapLayer, MapNode, MellosMap } from '../domain/types.js';
+import type { Style } from './canvas.js';
+import { type ZoomGeometry } from './zoom-geometry.js';
+/** In-box rows below the label row (detail mode only). */
+export interface ExtraRow {
+    readonly text: string;
+    readonly style: Style;
+}
+/** A box sized for the zoom — content and extent, no position yet. */
+export interface BoxSpec {
+    readonly node: MapNode;
+    readonly w: number;
+    readonly h: number;
+    /** Label truncated to the zoom's budget; '' in constellation mode. */
+    readonly label: string;
+    readonly pad: 0 | 1;
+    readonly borderless: boolean;
+    readonly extra: readonly ExtraRow[];
+}
+/** A sized box with its column decided. */
+export interface ColumnedBox extends BoxSpec {
+    readonly x: number;
+}
+/** A box on the picture. */
+export interface PlacedBox extends ColumnedBox {
+    readonly y: number;
+}
+/** A lane's column region (the last one holds the boxes in no lane at all). */
+export interface LaneRegion {
+    readonly x: number;
+    readonly w: number;
+}
+/** The picture's horizontal decisions. */
+export interface ColumnLayout {
+    /** Layers sorted top band first (descending rank). */
+    readonly bands: readonly MapLayer[];
+    readonly bandIndexOf: ReadonlyMap<string, number>;
+    /** Boxes per band, in declaration order (which is also left-to-right without lanes). */
+    readonly bandBoxes: readonly (readonly ColumnedBox[])[];
+    /** Every box by node id, in declaration order. */
+    readonly boxOf: ReadonlyMap<string, ColumnedBox>;
+    /** Lane regions, empty when the map declares no lanes. */
+    readonly lanes: readonly LaneRegion[];
+    /** The text each band bar carries, one per band. */
+    readonly bandLabel: readonly string[];
+    /** Rightmost column any box or lane occupies, plus the left margin. */
+    readonly contentWidth: number;
+}
+/** The picture's vertical decisions. */
+export interface RowLayout {
+    readonly boxOf: ReadonlyMap<string, PlacedBox>;
+    readonly bandBoxes: readonly (readonly PlacedBox[])[];
+    /** Row of each band's bar. */
+    readonly barY: readonly number[];
+    /** First track row of each band gap; a segment's row index is added to it. */
+    readonly gapTrackStartY: readonly number[];
+    /** Row of the lane header strip, when the map has lanes. */
+    readonly laneHeaderY: number | undefined;
+    readonly legendY: number;
+}
+/** Size and content of one node's box under the given zoom geometry. */
+export declare function boxSpec(node: MapNode, geo: ZoomGeometry, unicode: boolean, neutral: boolean): Omit<BoxSpec, 'node'>;
+/**
+ * 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 region for boxes in no lane); 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.
+ */
+export declare function layoutColumns(map: MellosMap, geo: ZoomGeometry, unicode: boolean, neutral: boolean): ColumnLayout;
+/**
+ * Row assignment, once routing has said how many track rows each band gap
+ * needs: title, lane headers, then band after band — bar, breathing row,
+ * boxes, breathing row, tracks — and the legend under everything.
+ */
+export declare function layoutRows(columns: ColumnLayout, geo: ZoomGeometry, gapRowCount: readonly number[], hasTitle: boolean, hasLanes: boolean): RowLayout;

package/lib/render/layout.js

@@ -0,0 +1,200 @@
+/**
+ * Layer 4a — where everything goes, decided before anything is drawn.
+ *
+ * Two stages, because the picture's height cannot be known until the wires
+ * are routed: first COLUMNS (how wide each box is and which column it starts
+ * at, which fixes the picture's width), then — once routing has said how many
+ * track rows each band gap needs — ROWS. Nothing here draws; nothing here
+ * mutates a box after placing it, so a position is a value another stage can
+ * hold on to.
+ *
+ * Bands are the map's layers, top band first: rank 0 renders at the BOTTOM
+ * ("primitives are the ground"), so the sort is descending.
+ */
+import { kindGlyph } from '../semantics/semantics.js';
+import { BAR_MIN_RUN, BOX_H, LEFT_MARGIN } from './zoom-geometry.js';
+import { displayWidth, fitWidth, wrapWidth } from './width.js';
+const LABEL_BUDGET_MIN = 4;
+/** Size and content of one node's box under the given zoom geometry. */
+export 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: [],
+    };
+}
+/**
+ * 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 region for boxes in no lane); 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.
+ */
+export function layoutColumns(map, geo, unicode, neutral) {
+    const bands = [...map.layers].sort((a, b) => b.rank - a.rank); // index 0 = top band
+    const bandIndexOf = new Map(bands.map((l, i) => [l.id, i]));
+    const sized = new Map();
+    const bandSized = bands.map(() => []);
+    for (const node of map.nodes) {
+        const spec = { node, ...boxSpec(node, geo, unicode, neutral) };
+        bandSized[bandIndexOf.get(node.layer)].push(spec);
+        sized.set(node.id, spec);
+    }
+    const columnOf = new Map();
+    const lanes = [];
+    if (map.lanes.length === 0) {
+        for (const row of bandSized) {
+            let x = LEFT_MARGIN;
+            for (const spec of row) {
+                columnOf.set(spec, x);
+                x += spec.w + geo.boxGap;
+            }
+        }
+    }
+    else {
+        const laneCount = map.lanes.length;
+        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 = bandSized.map((row) => {
+            const cells = Array.from({ length: regions }, () => []);
+            for (const spec of row) {
+                const lane = spec.node.lane;
+                cells[lane !== undefined ? laneIndexOf.get(lane) : regions - 1].push(spec);
+            }
+            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;
+        // Every region gets an entry, the trailing off-lane one included: it holds
+        // real boxes (a group node carries no lane, and aggregateMap emits those
+        // first), and a picture that forgets its last region measures short.
+        for (let i = 0; i < regions; i++) {
+            lanes.push({ x: x0, w: regionW[i] });
+            x0 += regionW[i] + laneGap;
+        }
+        for (const cells of grouped) {
+            for (let i = 0; i < regions; i++) {
+                let x = lanes[i].x;
+                for (const spec of cells[i]) {
+                    columnOf.set(spec, x);
+                    x += spec.w + geo.boxGap;
+                }
+            }
+        }
+    }
+    // One instance per box, shared by both views of it: later stages key maps
+    // on the box itself, and two copies of one box are two boxes to them.
+    const placed = new Map();
+    for (const [, spec] of sized)
+        placed.set(spec, { ...spec, x: columnOf.get(spec) ?? LEFT_MARGIN });
+    const bandBoxes = bandSized.map((row) => row.map((spec) => placed.get(spec)));
+    // Declaration order, which is the order boxes are drawn and reported as hits.
+    const boxOf = new Map();
+    for (const node of map.nodes)
+        boxOf.set(node.id, placed.get(sized.get(node.id)));
+    // 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}`;
+    });
+    // The RIGHTMOST box, not the last-declared one: lanes reorder a band into
+    // its lane regions, so declaration order says nothing about position, and a
+    // measurement taken from the wrong box left every band bar short.
+    let contentWidth = LEFT_MARGIN + BAR_MIN_RUN;
+    for (const row of bandBoxes)
+        for (const box of row)
+            contentWidth = Math.max(contentWidth, box.x + box.w);
+    for (const lane of lanes)
+        contentWidth = Math.max(contentWidth, lane.x + lane.w);
+    return { bands, bandIndexOf, bandBoxes, boxOf, lanes, bandLabel, contentWidth };
+}
+/**
+ * Row assignment, once routing has said how many track rows each band gap
+ * needs: title, lane headers, then band after band — bar, breathing row,
+ * boxes, breathing row, tracks — and the legend under everything.
+ */
+export function layoutRows(columns, geo, gapRowCount, hasTitle, hasLanes) {
+    let y = 0;
+    if (hasTitle)
+        y += 1 + geo.titleGap;
+    let laneHeaderY;
+    if (hasLanes) {
+        laneHeaderY = y;
+        y += 1 + geo.barGap;
+    }
+    const barY = [];
+    const gapTrackStartY = [];
+    const bandBoxes = [];
+    const placed = new Map();
+    const gapCount = columns.bands.length - 1;
+    for (let b = 0; b < columns.bands.length; b++) {
+        barY.push(y);
+        y += 1 + geo.barGap;
+        const row = columns.bandBoxes[b];
+        for (const box of row)
+            placed.set(box, { ...box, y });
+        bandBoxes.push(row.map((box) => placed.get(box)));
+        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
+        }
+    }
+    // Declaration order again — the columns layout already holds it.
+    const boxOf = new Map();
+    for (const [id, box] of columns.boxOf)
+        boxOf.set(id, placed.get(box));
+    return { boxOf, bandBoxes, barY, gapTrackStartY, laneHeaderY, legendY: y + 1 };
+}