mellos-mapping 0.19.0 → 0.20.2

package/lib/render/options.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Layer 4a — what a caller asks the renderer for.
+ *
+ * Every stage below (canvas, skins, layout, drawing) reads these, so they
+ * live in a module of their own rather than in whichever stage happens to
+ * touch them first: a picture's inputs are not the property of one stage.
+ *
+ * Pure types; no behavior.
+ */
+import type { ZoomStep } from '../semantics/semantics.js';
+export interface RenderOptions {
+    /** Emit ANSI color codes. */
+    readonly color: boolean;
+    /** Use box-drawing characters; false falls back to pure ASCII. */
+    readonly unicode: boolean;
+    /** Spinner frame index for in-progress nodes; caller advances it over time. */
+    readonly spinnerFrame: number;
+    /**
+     * Id of the BOX to spotlight: its border and every wire touching it render
+     * bright instead of faint. Color mode only — monochrome output ignores it.
+     *
+     * VIOLATION: no-primitive-obsession - a raw string where NodeId exists,
+     * because at the far zoom the boxes are aggregated GROUPS, so this is a
+     * NodeId or a GroupId and the caller (a hit test) cannot know which. See
+     * focusInfo in ../semantics/semantics.ts, which resolves the same value and
+     * carries the full reasoning; typing it here as a union would only move the
+     * cast to whichever side of the hit test names it first.
+     */
+    readonly focus?: string | undefined;
+    /** Position on the zoom ladder; omitted means ZOOM_DEFAULT (100%). */
+    readonly zoom?: ZoomStep | undefined;
+}
+/** A window over the rendered picture, in cell coordinates (0-based). */
+export interface Viewport {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}

package/lib/render/options.js

@@ -0,0 +1,10 @@
+/**
+ * Layer 4a — what a caller asks the renderer for.
+ *
+ * Every stage below (canvas, skins, layout, drawing) reads these, so they
+ * live in a module of their own rather than in whichever stage happens to
+ * touch them first: a picture's inputs are not the property of one stage.
+ *
+ * Pure types; no behavior.
+ */
+export {};

package/lib/render/render.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Layer 4 (presentation) — pure rendering of a MellosMap to terminal lines.
+ *
+ * Shared by the MCP `mmap_view` tool (monochrome) and the split-pane watcher
+ * (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
+ *   nodes. Junctions where a wire enters a box inherit the box's color,
+ *   like lit pins. Dependency lines only ever travel downward.
+ *
+ *   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
+ *
+ * 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
+ * step would leave labels too short to mean anything does the picture switch
+ * mode — to a borderless glyph constellation whose band bars carry
+ * done/total counts. Zooming in past 100% unfolds evidence and design notes
+ * inside the boxes; a second step widens the boxes and unfolds the notes
+ * further. The ladder, one wheel tick per step:
+ *   +2   detail+       wider boxes, design notes unfold almost fully
+ *   +1   detail        evidence + design notes unfold inside boxes
+ *    0   100%          the standard working view (default, unchanged)
+ *   -1   85%           labels truncated to 85%, geometry still roomy
+ *   -2   70%           padding and breathing rows collapse
+ *   -3   55%           tightest meaningful boxes; band bars gain done/total
+ *   -4   overview      MODE SWITCH: borderless status glyphs, pure topology
+ * The same layout/routing machinery runs at every step; only the per-node
+ * box spec (size, border, content) and the whitespace geometry change.
+ */
+import type { MellosMap } from '../domain/types.js';
+import type { RenderOptions, Viewport } from './options.js';
+export type { RenderOptions, Viewport } from './options.js';
+export { displayWidth, fitWidth, wrapWidth } from './width.js';
+export { statusSgr } from './skins.js';
+export { type ZoomStep, 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 declare function renderMap(map: MellosMap, opts: RenderOptions): string[];
+/** Where a box sits on the full (unwindowed) picture, for hit testing. */
+export interface BoxHit {
+    /**
+     * The box's id — a node id, or a GROUP id on the aggregated far zoom.
+     *
+     * VIOLATION: no-primitive-obsession - raw string where NodeId exists, for
+     * the reason spelled out at focusInfo (../semantics/semantics.ts): which of
+     * the two an id names is what the consumer of a hit calls that function to
+     * find out, so this type cannot promise either.
+     */
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface WindowedRender {
+    readonly lines: string[];
+    /** Full extent of the picture, for viewport clamping. */
+    readonly contentWidth: number;
+    readonly contentHeight: number;
+    /** Node hit regions in full-picture coordinates, for mouse interaction. */
+    readonly hits: readonly BoxHit[];
+}
+/** Render only the given viewport of the map, plus the full content extent. */
+export declare function renderMapWindow(map: MellosMap, opts: RenderOptions, viewport: Viewport): WindowedRender;

package/lib/render/render.js

@@ -0,0 +1,128 @@
+/**
+ * Layer 4 (presentation) — pure rendering of a MellosMap to terminal lines.
+ *
+ * Shared by the MCP `mmap_view` tool (monochrome) and the split-pane watcher
+ * (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
+ *   nodes. Junctions where a wire enters a box inherit the box's color,
+ *   like lit pins. Dependency lines only ever travel downward.
+ *
+ *   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
+ *
+ * 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
+ * step would leave labels too short to mean anything does the picture switch
+ * mode — to a borderless glyph constellation whose band bars carry
+ * done/total counts. Zooming in past 100% unfolds evidence and design notes
+ * inside the boxes; a second step widens the boxes and unfolds the notes
+ * further. The ladder, one wheel tick per step:
+ *   +2   detail+       wider boxes, design notes unfold almost fully
+ *   +1   detail        evidence + design notes unfold inside boxes
+ *    0   100%          the standard working view (default, unchanged)
+ *   -1   85%           labels truncated to 85%, geometry still roomy
+ *   -2   70%           padding and breathing rows collapse
+ *   -3   55%           tightest meaningful boxes; band bars gain done/total
+ *   -4   overview      MODE SWITCH: borderless status glyphs, pure topology
+ * 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 } 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);
+    return built.canvas.emit(opts);
+}
+/** Render only the given viewport of the map, plus the full content extent. */
+export function renderMapWindow(map, opts, viewport) {
+    const built = buildCanvas(map, opts);
+    return {
+        lines: built.canvas.emit(opts, viewport),
+        contentWidth: built.canvas.width,
+        contentHeight: built.canvas.height,
+        hits: built.hits,
+    };
+}
+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;
+    const drawn = aggregated ?? oriented;
+    return paint(drawn, opts, aggregated !== undefined ? AGGREGATE_GEO : plainGeo, unverifiedDoneIds(oriented, drawn));
+}
+function paint(map, opts, geo, unverified) {
+    const canvas = new Canvas();
+    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: [] };
+    }
+    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)
+        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,
+        w: b.w,
+        h: b.h,
+    }));
+    return { canvas, hits };
+}

package/lib/render/routing.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Layer 4a — how a dependency edge gets from one box to another.
+ *
+ * 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.
+ *
+ * The output is a value, not a drawing: every edge comes back as the columns
+ * and track rows it will use, and a separate step turns that into a polyline
+ * once the rows are placed. Crossings need no cleverness at all — the canvas
+ * merges masks, so two wires meeting become ┼ by construction.
+ */
+import type { MellosMap } from '../domain/types.js';
+import type { ColumnedBox, ColumnLayout, RowLayout } from './layout.js';
+/** An edge, resolved to the columns and rows it occupies. */
+export type RoutedEdge = {
+    readonly from: ColumnedBox;
+    readonly to: ColumnedBox;
+    readonly fromBand: number;
+    readonly toBand: number;
+} & ({
+    readonly kind: 'straight';
+    readonly x: number;
+} | {
+    readonly kind: 'dogleg';
+    readonly exitX: number;
+    readonly entryX: number;
+    readonly landingRow: number;
+} | {
+    readonly kind: 'thread';
+    readonly exitX: number;
+    readonly entryX: number;
+    readonly descentX: number;
+    readonly exitRow: number;
+    readonly landingRow: number;
+});
+export interface Routing {
+    readonly edges: readonly RoutedEdge[];
+    /** Track rows each band gap needs; the row layout turns these into space. */
+    readonly gapRowCount: readonly number[];
+    /** Skip edges that found no column between the boxes and took the margin. */
+    readonly fallbackCount: number;
+}
+export declare function routeEdges(map: MellosMap, columns: ColumnLayout): Routing;
+/**
+ * The polyline one edge draws, once the rows are placed: box bottom border,
+ * down the exit column, along a track row, and into the target's top border.
+ */
+export declare function edgePolyline(edge: RoutedEdge, rows: RowLayout): ReadonlyArray<readonly [number, number]>;

package/lib/render/routing.js

@@ -0,0 +1,244 @@
+/**
+ * Layer 4a — how a dependency edge gets from one box to another.
+ *
+ * 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.
+ *
+ * The output is a value, not a drawing: every edge comes back as the columns
+ * and track rows it will use, and a separate step turns that into a polyline
+ * once the rows are placed. Crossings need no cleverness at all — the canvas
+ * merges masks, so two wires meeting become ┼ by construction.
+ */
+import { LEFT_MARGIN } from './zoom-geometry.js';
+export function routeEdges(map, columns) {
+    const { bandIndexOf, bandBoxes, boxOf, contentWidth } = columns;
+    const pending = map.edges.map((e) => {
+        const from = boxOf.get(e.from);
+        const to = boxOf.get(e.to);
+        return {
+            from,
+            to,
+            fromBand: bandIndexOf.get(from.node.layer),
+            toBand: bandIndexOf.get(to.node.layer),
+        };
+    });
+    /**
+     * Columns already carrying a VERTICAL run inside each band gap, and the
+     * edge that owns each.
+     *
+     * Two edges given the same column in one gap do not cross there — they run
+     * on top of each other for the whole gap, and where the shorter one turns
+     * onto its track row the union of masks becomes ├ or ┤: one wire that
+     * appears to branch, which is a lie about the dependencies. Packing tracks
+     * by horizontal extent alone could not see this, because the collision is
+     * vertical. A wire may of course reuse a column it owns itself — a skip
+     * edge descending straight out of its own exit slot is the ideal route, not
+     * a collision — and horizontal segments still cross verticals freely, which
+     * is an honest ┼.
+     */
+    const gapVerticals = Array.from({ length: Math.max(0, columns.bands.length - 1) }, () => new Map());
+    const verticalFree = (gap, x, edge) => {
+        const owner = gapVerticals[gap]?.get(x);
+        return owner === undefined || owner === edge;
+    };
+    const takeVertical = (gap, x, edge) => {
+        gapVerticals[gap]?.set(x, edge);
+    };
+    // 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
+    for (const r of pending) {
+        if (r.toBand - r.fromBand !== 1)
+            continue;
+        const lo = Math.max(r.from.x + 1, r.to.x + 1);
+        const hi = Math.min(r.from.x + r.from.w - 2, r.to.x + r.to.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 && r.straightX === undefined; d++) {
+            for (const x of d === 0 ? [mid] : [mid - d, mid + d]) {
+                if (x >= lo && x <= hi && isFree(r.from, x) && isFree(r.to, x) && verticalFree(r.fromBand, x, r)) {
+                    r.straightX = claim(r.to, claim(r.from, x));
+                    takeVertical(r.fromBand, x, r);
+                    break;
+                }
+            }
+        }
+    }
+    // 2. attach slots for the bent rest, nudged off claimed columns
+    const bent = pending.filter((r) => r.straightX === undefined);
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const r of bent) {
+        outgoing.set(r.from, [...(outgoing.get(r.from) ?? []), r]);
+        incoming.set(r.to, [...(incoming.get(r.to) ?? []), r]);
+    }
+    const freeSlot = (box, k, n, edge, gap) => {
+        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) && verticalFree(gap, x, edge)) {
+                    takeVertical(gap, x, edge);
+                    return claim(box, x);
+                }
+            }
+        }
+        return ideal; // every column claimed (extremely crowded box) — overlap and live with it
+    };
+    for (const r of bent) {
+        const outs = outgoing.get(r.from);
+        const ins = incoming.get(r.to);
+        // The exit descends through the gap below the source band; the entry
+        // climbs out of the gap above the target band. For an adjacent edge those
+        // are one gap, so the entry column also avoids the exit column.
+        r.exitX = freeSlot(r.from, outs.indexOf(r), outs.length, r, r.fromBand);
+        r.entryX = freeSlot(r.to, ins.indexOf(r), ins.length, r, r.toBand - 1);
+    }
+    // 3. THREAD descent columns for skip-level edges
+    const usedDescent = new Set();
+    let fallbackCount = 0;
+    const blockedByBox = (band, x) => bandBoxes[band].some((b) => x >= b.x && x <= b.x + b.w - 1);
+    /** The descent runs through every gap from the source band to the target's. */
+    const descentGapsFree = (r, c) => {
+        for (let g = r.fromBand; g <= r.toBand - 1; g++) {
+            if (!verticalFree(g, c, r))
+                return false;
+        }
+        return true;
+    };
+    for (const r of bent.filter((e) => e.toBand - e.fromBand > 1)) {
+        const ex = r.entryX;
+        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;
+                if (!descentGapsFree(r, 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);
+        for (let g = r.fromBand; g <= r.toBand - 1; g++)
+            takeVertical(g, chosen, r);
+        r.descentX = chosen;
+    }
+    // 4. pack horizontal segments into shared track rows per gap
+    const gapCount = Math.max(0, columns.bands.length - 1);
+    const gapSegments = Array.from({ length: gapCount }, () => []);
+    for (const r of bent) {
+        const sx = r.exitX;
+        const ex = r.entryX;
+        if (r.descentX === undefined) {
+            gapSegments[r.toBand - 1].push({
+                edge: r,
+                kind: 'landing',
+                segment: { lo: Math.min(sx, ex), hi: Math.max(sx, ex) },
+            });
+        }
+        else {
+            const c = r.descentX;
+            gapSegments[r.fromBand].push({ edge: r, kind: 'exit', segment: { lo: Math.min(sx, c), hi: Math.max(sx, c) } });
+            gapSegments[r.toBand - 1].push({
+                edge: r,
+                kind: 'landing',
+                segment: { lo: Math.min(c, ex), hi: Math.max(c, ex) },
+            });
+        }
+    }
+    const exitRow = new Map();
+    const landingRow = new Map();
+    const gapRowCount = gapSegments.map((entries) => {
+        const rowEnds = []; // rightmost occupied column per packed row
+        for (const e of [...entries].sort((a, b) => a.segment.lo - b.segment.lo)) {
+            let row = rowEnds.findIndex((end) => e.segment.lo > end + 1);
+            if (row === -1) {
+                rowEnds.push(e.segment.hi);
+                row = rowEnds.length - 1;
+            }
+            else {
+                rowEnds[row] = Math.max(rowEnds[row], e.segment.hi);
+            }
+            (e.kind === 'exit' ? exitRow : landingRow).set(e.edge, row);
+        }
+        return rowEnds.length;
+    });
+    const edges = pending.map((r) => {
+        const common = { from: r.from, to: r.to, fromBand: r.fromBand, toBand: r.toBand };
+        if (r.straightX !== undefined)
+            return { ...common, kind: 'straight', x: r.straightX };
+        if (r.descentX === undefined) {
+            return { ...common, kind: 'dogleg', exitX: r.exitX, entryX: r.entryX, landingRow: landingRow.get(r) };
+        }
+        return {
+            ...common,
+            kind: 'thread',
+            exitX: r.exitX,
+            entryX: r.entryX,
+            descentX: r.descentX,
+            exitRow: exitRow.get(r),
+            landingRow: landingRow.get(r),
+        };
+    });
+    return { edges, gapRowCount, fallbackCount };
+}
+/**
+ * The polyline one edge draws, once the rows are placed: box bottom border,
+ * down the exit column, along a track row, and into the target's top border.
+ */
+export function edgePolyline(edge, rows) {
+    const from = rows.boxOf.get(edge.from.node.id);
+    const to = rows.boxOf.get(edge.to.node.id);
+    const sy = from.y + from.h - 1; // bottom border row of the source box
+    const ey = to.y; // top border row of the target box
+    if (edge.kind === 'straight') {
+        return [
+            [edge.x, sy],
+            [edge.x, ey],
+        ];
+    }
+    const landingY = rows.gapTrackStartY[edge.toBand - 1] + edge.landingRow;
+    if (edge.kind === 'dogleg') {
+        return [
+            [edge.exitX, sy],
+            [edge.exitX, landingY],
+            [edge.entryX, landingY],
+            [edge.entryX, ey],
+        ];
+    }
+    const exitY = rows.gapTrackStartY[edge.fromBand] + edge.exitRow;
+    return [
+        [edge.exitX, sy],
+        [edge.exitX, exitY],
+        [edge.descentX, exitY],
+        [edge.descentX, landingY],
+        [edge.entryX, landingY],
+        [edge.entryX, ey],
+    ];
+}

package/lib/render/skins.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Layer 4a — the status vocabulary as this medium wears it.
+ *
+ * The GLYPHS are the map's shared alphabet and live in ../semantics; what a
+ * TERMINAL owns is decided here and only here: which border repertoire a
+ * status draws with, and which SGR color it burns. One table, so the pane's
+ * chrome (tab strip, panel header) and the picture's boxes cannot drift
+ * apart — the pane reads statusSgr from this very file.
+ */
+import type { MapNode, MellosMap, NodeStatus } from '../domain/types.js';
+import { type Style } from './canvas.js';
+import type { RenderOptions } from './options.js';
+export interface BoxSkin {
+    readonly h: string;
+    readonly v: string;
+    readonly corners: readonly [string, string, string, string];
+    readonly style: Style;
+}
+/**
+ * What a box paints for its status. `done` has two FACES, because the ledger
+ * has a rule about it ("no evidence, no done") that the picture could not
+ * show: a node built and verified and a node merely declared done were the
+ * same solid green square at every zoom. This is not a fifth status —
+ * evidence is a property of a node, and whether it exists is presentation.
+ */
+export type StatusFace = NodeStatus | 'done-unverified';
+/** The color role a status face wears in a terminal. */
+export declare function styleFor(face: StatusFace): Style;
+/**
+ * SGR parameters of a status' skin, for terminal chrome painted outside the
+ * canvas (a tab strip, a panel header). The pane's chrome and the picture's
+ * boxes therefore wear one palette by construction, not by a second table.
+ */
+export declare function statusSgr(status: NodeStatus): string;
+export declare function skinFor(face: StatusFace, unicode: boolean): BoxSkin;
+/**
+ * The glyph a node shows for its status face. A terminal box CAN animate, so
+ * in-progress spins through the shared frames; every other face is a shared
+ * static glyph.
+ */
+export declare function glyphFor(face: StatusFace, opts: RenderOptions): string;
+/** Plain solid box for documentation diagrams — presence, not progress. */
+export declare function neutralSkin(unicode: boolean): BoxSkin;
+/** The glyph slot of a box on a documentation page: the KIND, or a bullet. */
+export declare function neutralGlyph(node: MapNode, unicode: boolean): string;
+/**
+ * Ids of the boxes whose `done` has nothing behind it.
+ *
+ * Computed against the map as DECLARED, not as drawn: an aggregated group box
+ * carries no evidence field of its own, and reading that absence literally
+ * would paint every grouped far-zoom view as unverified. A group is exactly
+ * as backed as the members it stands for.
+ */
+export declare function unverifiedDoneIds(declared: MellosMap, drawn: MellosMap): Set<string>;