mellos-mapping 0.20.0 → 0.20.2

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>;

package/lib/render/skins.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph } from '../semantics/semantics.js';
+import { SGR } from './canvas.js';
+/** The color role a status face wears in a terminal. */
+export function styleFor(face) {
+    switch (face) {
+        case 'planned':
+            return 'dim';
+        case 'in-progress':
+            return 'amber';
+        case 'done':
+            return 'green';
+        case 'done-unverified':
+            return 'greenDim';
+        case 'regressed':
+            return 'red';
+    }
+}
+/**
+ * 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 function statusSgr(status) {
+    return SGR[styleFor(status)];
+}
+export function skinFor(face, unicode) {
+    const style = styleFor(face);
+    if (!unicode) {
+        return face === 'planned'
+            ? { h: '.', v: ':', corners: ['+', '+', '+', '+'], style }
+            : { h: '-', v: '|', corners: ['+', '+', '+', '+'], style };
+    }
+    switch (face) {
+        case 'planned':
+            return { h: '╌', v: '╎', corners: ['╭', '╮', '╰', '╯'], style };
+        case 'in-progress':
+            return { h: '─', v: '│', corners: ['╭', '╮', '╰', '╯'], style };
+        // an unverified done keeps the heavy border of done — it is the same
+        // claim, told with a hollow glyph and a dimmer green
+        case 'done':
+        case 'done-unverified':
+        case 'regressed':
+            return { h: '━', v: '┃', corners: ['┏', '┓', '┗', '┛'], style };
+    }
+}
+/**
+ * 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 function glyphFor(face, opts) {
+    if (face === 'in-progress')
+        return spinnerGlyph(opts.spinnerFrame, opts.unicode);
+    return face === 'done-unverified' ? unverifiedDoneGlyph(opts.unicode) : statusGlyph(face, opts.unicode);
+}
+/** Plain solid box for documentation diagrams — presence, not progress. */
+export function neutralSkin(unicode) {
+    return unicode
+        ? { h: '─', v: '│', corners: ['╭', '╮', '╰', '╯'], style: 'none' }
+        : { h: '-', v: '|', corners: ['+', '+', '+', '+'], style: 'none' };
+}
+/** The glyph slot of a box on a documentation page: the KIND, or a bullet. */
+export function neutralGlyph(node, unicode) {
+    return ((node.kind !== undefined ? kindGlyph(node.kind, unicode) : undefined) ?? (unicode ? '·' : '.'));
+}
+/**
+ * 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 function unverifiedDoneIds(declared, drawn) {
+    const out = new Set();
+    const declaredById = new Map(declared.nodes.map((n) => [n.id, n]));
+    for (const node of drawn.nodes) {
+        if (node.status !== 'done')
+            continue;
+        const own = declaredById.get(node.id);
+        if (own !== undefined) {
+            if (own.evidence === undefined)
+                out.add(node.id);
+        }
+        else if (declared.nodes.some((m) => m.group === node.id && m.status === 'done' && m.evidence === undefined)) {
+            out.add(node.id); // a group box stands for a member nobody verified
+        }
+    }
+    return out;
+}

package/lib/render/width.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Layer 4a — how many terminal columns a string occupies.
+ *
+ * Everything above this file lays out a grid, and a grid is only as honest as
+ * its widths: a label measured one column short shears every row below its
+ * box, and one column long leaves a gap no border closes. Labels are DATA —
+ * people write Chinese, emoji and accented letters — so this is not a detail
+ * of the drawing code but its foundation.
+ *
+ * The two tables are the Unicode East Asian Width W/F set and the
+ * zero-advance set, kept deliberately narrow: everything the standard calls
+ * AMBIGUOUS (■ ● ✗ ○ and the rest of this map's own glyph alphabet) stays ONE
+ * column, which is what a Western terminal draws.
+ *
+ * Pure functions of a string; no canvas, no options, no I/O.
+ */
+/** Columns one code point occupies: 0 (a mark riding on its base), 1, or 2. */
+export declare function charWidth(cp: number): number;
+/** Terminal column width of a string (CJK chars occupy two columns). */
+export declare function displayWidth(text: string): number;
+/** Truncate to a display width, ANSI-free input, appending … when cut. */
+export declare function fitWidth(s: string, width: number): string;
+/** Hard word-wrap by display width (CJK-aware, splits anywhere). */
+export declare function wrapWidth(s: string, width: number): string[];

package/lib/render/width.js

@@ -0,0 +1,139 @@
+/**
+ * Layer 4a — how many terminal columns a string occupies.
+ *
+ * Everything above this file lays out a grid, and a grid is only as honest as
+ * its widths: a label measured one column short shears every row below its
+ * box, and one column long leaves a gap no border closes. Labels are DATA —
+ * people write Chinese, emoji and accented letters — so this is not a detail
+ * of the drawing code but its foundation.
+ *
+ * The two tables are the Unicode East Asian Width W/F set and the
+ * zero-advance set, kept deliberately narrow: everything the standard calls
+ * AMBIGUOUS (■ ● ✗ ○ and the rest of this map's own glyph alphabet) stays ONE
+ * column, which is what a Western terminal draws.
+ *
+ * Pure functions of a string; no canvas, no options, no I/O.
+ */
+const WIDE_RANGES = [
+    [0x1100, 0x115f], // Hangul Jamo
+    // Wide symbols scattered through the BMP — mostly emoji that predate the
+    // emoji planes (⌚ ⏰ ⚡ ✅ ✨ ❌ ❓ ⭐ ⬛ …).
+    [0x231a, 0x231b],
+    [0x2329, 0x232a],
+    [0x23e9, 0x23ec],
+    [0x23f0, 0x23f0],
+    [0x23f3, 0x23f3],
+    [0x25fd, 0x25fe],
+    [0x2614, 0x2615],
+    [0x2648, 0x2653],
+    [0x267f, 0x267f],
+    [0x2693, 0x2693],
+    [0x26a1, 0x26a1],
+    [0x26aa, 0x26ab],
+    [0x26bd, 0x26be],
+    [0x26c4, 0x26c5],
+    [0x26ce, 0x26ce],
+    [0x26d4, 0x26d4],
+    [0x26ea, 0x26ea],
+    [0x26f2, 0x26f3],
+    [0x26f5, 0x26f5],
+    [0x26fa, 0x26fa],
+    [0x26fd, 0x26fd],
+    [0x2705, 0x2705],
+    [0x270a, 0x270b],
+    [0x2728, 0x2728],
+    [0x274c, 0x274c],
+    [0x274e, 0x274e],
+    [0x2753, 0x2755],
+    [0x2757, 0x2757],
+    [0x2795, 0x2797],
+    [0x27b0, 0x27b0],
+    [0x27bf, 0x27bf],
+    [0x2b1b, 0x2b1c],
+    [0x2b50, 0x2b50],
+    [0x2b55, 0x2b55],
+    [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],
+    [0x1f300, 0x1f64f], // pictographs, transport, emoticons (🚀 🎯 😀 …)
+    [0x1f680, 0x1f6ff],
+    [0x1f900, 0x1f9ff], // supplemental symbols (🤖 🧱 …)
+    [0x1fa70, 0x1faff], // symbols extended-A
+    [0x20000, 0x3fffd], // CJK extension planes
+];
+/** Code points that advance the cursor by nothing at all. */
+const ZERO_WIDTH_RANGES = [
+    [0x0300, 0x036f], // combining diacritical marks (decomposed 'e' + ´)
+    [0x1ab0, 0x1aff],
+    [0x1dc0, 0x1dff],
+    [0x200b, 0x200f], // zero-width space .. RLM, zero-width joiner among them
+    [0x20d0, 0x20f0], // combining marks for symbols
+    [0xfe00, 0xfe0f], // variation selectors, VS16 (emoji presentation) included
+    [0xfe20, 0xfe2f], // combining half marks
+    [0x1f3fb, 0x1f3ff], // emoji skin tone modifiers — always applied to a base
+];
+function inRanges(cp, ranges) {
+    for (const [lo, hi] of ranges) {
+        if (cp >= lo && cp <= hi)
+            return true;
+    }
+    return false;
+}
+/** Columns one code point occupies: 0 (a mark riding on its base), 1, or 2. */
+export function charWidth(cp) {
+    if (inRanges(cp, ZERO_WIDTH_RANGES))
+        return 0;
+    return inRanges(cp, WIDE_RANGES) ? 2 : 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;
+}

package/lib/render/zoom-geometry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Layer 4a — what one rung of the zoom ladder buys, in terminal cells.
+ *
+ * Terminals cannot scale glyphs, so zooming out COMPRESSES geometry instead:
+ * gaps, breathing rows and padding shrink, labels truncate toward a
+ * scale-proportional budget, and only when a further step would leave labels
+ * too short to mean anything does the picture switch mode. WHICH steps switch
+ * mode is semantics (zoomMode over in ../semantics); this module owns only
+ * the whitespace and label budgets each step spends.
+ */
+import { type ZoomStep } from '../semantics/semantics.js';
+/** Height of a box with nothing unfolded inside it: border, content, border. */
+export declare const BOX_H = 3;
+/** Columns between two boxes of one band at the roomy default. */
+export declare const BOX_GAP = 2;
+/** Columns before the leftmost box; the picture never starts at the edge. */
+export declare const LEFT_MARGIN = 2;
+/** Bar cells kept left of the narrowest band label, so a band still reads as a band. */
+export declare const BAR_MIN_RUN = 7;
+/** Box content budget for a detail step; present exactly when mode is 'detail'. */
+export interface DetailBudget {
+    /** Clamp range for the box's inner width. */
+    readonly innerMin: number;
+    readonly innerMax: number;
+    /** Design-note rows shown before the … cut. */
+    readonly noteRows: number;
+}
+/** How one zoom step translates into whitespace geometry; see the module header. */
+export interface ZoomGeometry {
+    readonly mode: 'constellation' | 'boxes' | 'detail';
+    /** Label width multiplier while scaling down (boxes mode). */
+    readonly scale: number;
+    /** Inner padding around "glyph label" (1 = the roomy standard look). */
+    readonly pad: 0 | 1;
+    readonly boxGap: number;
+    /** Breathing rows around wire track rows in a band gap. */
+    readonly breathe: 0 | 1;
+    /** Blank row after the title. */
+    readonly titleGap: 0 | 1;
+    /** Blank row between a band bar and its boxes. */
+    readonly barGap: 0 | 1;
+    /** Band bars carry done/total counts once boxes are too small to speak. */
+    readonly bandCounts: boolean;
+    /** Content budget of the detail steps; set exactly when mode is 'detail'. */
+    readonly detail?: DetailBudget;
+}
+export declare function zoomGeometry(zoom: ZoomStep): ZoomGeometry;
+/**
+ * Geometry for the aggregated far zoom: tight chrome, but FULL labels — the
+ * point of collapsing a map into its groups is reading their names.
+ */
+export declare const AGGREGATE_GEO: ZoomGeometry;