mellos-mapping 0.19.0 → 0.20.2

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;

package/lib/render/zoom-geometry.js

@@ -0,0 +1,56 @@
+/**
+ * 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 { zoomMode } from '../semantics/semantics.js';
+/** Height of a box with nothing unfolded inside it: border, content, border. */
+export const BOX_H = 3;
+/** Columns between two boxes of one band at the roomy default. */
+export const BOX_GAP = 2;
+/** Columns before the leftmost box; the picture never starts at the edge. */
+export const LEFT_MARGIN = 2;
+/** Bar cells kept left of the narrowest band label, so a band still reads as a band. */
+export const BAR_MIN_RUN = 7;
+/** +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 };
+export function zoomGeometry(zoom) {
+    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 };
+    }
+}
+/**
+ * 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 const AGGREGATE_GEO = {
+    mode: 'boxes',
+    scale: 1,
+    pad: 0,
+    boxGap: 1,
+    breathe: 0,
+    titleGap: 0,
+    barGap: 1,
+    bandCounts: false,
+};

package/lib/semantics/semantics.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Layer 1c — medium-neutral VIEW SEMANTICS of a MellosMap.
+ *
+ * Every renderer (the terminal pane, a web panel, a future editor view) must
+ * agree on what a zoom step MEANS, when a map aggregates into its groups,
+ * how sequence time is oriented, and which map kinds render neutrally.
+ * Those rules live here, pure of any medium: no cells, no colors, no DOM,
+ * no I/O. Geometry — how a mode maps onto character cells or pixels — stays
+ * private to each renderer.
+ *
+ * The shared ALPHABET (status glyphs, spinner frames, node-kind glyphs) is
+ * medium-neutral for the same reason and lives beside this file in
+ * ./vocabulary.js, re-exported here so consumers keep one import site.
+ */
+import type { MapGroup, MapNode, MellosMap, NodeStatus } from '../domain/types.js';
+export { NODE_KIND_GLYPHS, SPINNER_FRAMES, STATUS_GLYPHS, UNVERIFIED_DONE_GLYPHS, kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph, } from './vocabulary.js';
+/** One wheel tick on the zoom ladder. */
+export type ZoomStep = -4 | -3 | -2 | -1 | 0 | 1 | 2;
+export declare const ZOOM_MIN: ZoomStep;
+export declare const ZOOM_MAX: ZoomStep;
+export declare const ZOOM_DEFAULT: ZoomStep;
+export declare function clampZoom(n: number): ZoomStep;
+/**
+ * What a zoom step MEANS, before any renderer decides what it looks like:
+ * scaling only compresses, the ends of the ladder switch mode. 'detail'
+ * unfolds evidence and design notes; 'overview' switches to the aggregated
+ * far view (groups become the nodes — see aggregateMap); 'boxes' is every
+ * step in between, where boxes stay boxes and only whitespace and label
+ * budgets change.
+ */
+export declare function zoomMode(zoom: ZoomStep): 'detail' | 'boxes' | 'overview';
+/** What a footer shows: a percentage while scaling, a mode name at the ends. */
+export declare function zoomLabel(zoom: ZoomStep): string;
+/** Documentation kinds render neutrally: no status skins, no progress counts. */
+export declare function isNeutralKind(map: MellosMap): boolean;
+/**
+ * The derived coarse picture the far zoom renders when the map declares
+ * groups: each group becomes ONE labeled node (status derived from members,
+ * label carrying done/total), ungrouped nodes stay themselves, and edges
+ * collapse onto representatives (intra-group wiring disappears into the
+ * box). Derived for rendering only — never persisted. A map without groups
+ * returns undefined and falls back to whatever anonymous overview the
+ * renderer draws.
+ */
+export declare function aggregateMap(map: MellosMap): MellosMap | undefined;
+/** One neighbour across a dependency edge, with what flows along it. */
+export interface NeighborRef {
+    readonly id: string;
+    readonly label: string;
+    readonly status: NodeStatus;
+    readonly edgeLabel?: string;
+}
+/** Everything a detail panel derives for a focused NODE. */
+export interface NodeFocus {
+    readonly kind: 'node';
+    readonly node: MapNode;
+    readonly layerName: string;
+    readonly laneLabel?: string;
+    /** Lower neighbours this node stands on (on sequence pages: the earlier events). */
+    readonly uses: readonly NeighborRef[];
+    /** Upper neighbours standing on this node (on sequence pages: the later events). */
+    readonly usedBy: readonly NeighborRef[];
+}
+/** Everything a detail panel derives for a focused GROUP (the far zoom's boxes). */
+export interface GroupFocus {
+    readonly kind: 'group';
+    readonly group: MapGroup;
+    readonly status: NodeStatus;
+    readonly layerName: string;
+    readonly members: readonly MapNode[];
+    /** Outside-the-group lower neighbours, each shown as its own group when it has one. */
+    readonly uses: readonly NeighborRef[];
+    /** Outside-the-group upper neighbours, each shown as its own group when it has one. */
+    readonly usedBy: readonly NeighborRef[];
+}
+/**
+ * Derive what a detail panel says about one focused id — a node, or a group
+ * when the far zoom's aggregated boxes are what the pointer is over. Pure
+ * data: every renderer picks its own glyphs, colors, and words (a sequence
+ * page reads uses/usedBy as after/before; that is the caller's vocabulary).
+ * Groups are resolved first, which is unambiguous: one id names one box on
+ * the map (I10), so no node can be shadowed by a group of the same name.
+ * @param map - the map the focus lives in.
+ * @param focusId - node or group id.
+ * @returns the focus view, or undefined when the id names neither.
+ *
+ * VIOLATION: no-primitive-obsession - `focusId` is a raw string, not a brand.
+ * It has to be: the caller is a hit test over the picture, and at the far
+ * zoom that picture is the AGGREGATED map, whose boxes are groups. So the id
+ * arriving here is a NodeId or a GroupId and the caller cannot know which —
+ * deciding that is this function's whole job. `NodeId | GroupId` would type
+ * it, but every hit-test path (BoxHit.id, RenderOptions.focus, the pane's
+ * hover/selection state) would then have to carry that union and cast into it
+ * at the same boundary, moving the cast rather than removing it. The value is
+ * validated the only way it can be: an id that names neither answers
+ * undefined.
+ */
+export declare function focusInfo(map: MellosMap, focusId: string): NodeFocus | GroupFocus | undefined;
+/**
+ * Page slugs some node of any map dives into — the raw fact only, WITHOUT
+ * the rule a sibling strip needs on top of it (that is interiorPages).
+ * @param maps - every known page's map (undefined entries are skipped).
+ * @returns the referenced submap slugs.
+ */
+export declare function submapRefs(maps: Iterable<MellosMap | undefined>): Set<string>;
+/**
+ * Which pages are INTERIOR: reached by diving through a node, never by
+ * sitting beside their parent as a sibling tab.
+ *
+ * "Referenced by anyone" is NOT the rule, because a strip computed that way
+ * can erase itself. Two refinements make it total:
+ *   - a page never hides itself. A node whose submap names its own page is a
+ *     loop with no bottom, not a parent link — read as one, it deleted the
+ *     tab of the very page it was drawn on.
+ *   - a page referenced only from pages it can itself reach keeps its tab. A
+ *     link cycle has no outside, so hiding every page in it leaves a strip
+ *     with nothing in it and a client with nowhere left to go.
+ * Everything else is interior: some page OUTSIDE its own loop dives into it,
+ * and that page's node is the way in.
+ *
+ * @param pages - every known page as (slug, map) pairs; the default page has
+ *   no slug a node could name, so it is passed as undefined and is never
+ *   interior. Entries with no map (unreadable, not yet loaded) contribute no
+ *   links.
+ * @returns the slugs to keep out of a sibling strip.
+ */
+export declare function interiorPages(pages: Iterable<readonly [string | undefined, MellosMap | undefined]>): Set<string>;
+/**
+ * Where a sub-map page was dived into from: the entry whose map links the
+ * page, plus the linking node's label. Derived by scan, so a breadcrumb
+ * survives any client restart with an empty dive stack.
+ * @param entries - known pages as (key, map) pairs; keys are caller-owned.
+ * @param pageId - the sub-map page's slug.
+ * @returns the linking entry's key and node label, or undefined for a top-level page.
+ */
+export declare function diveParent<K>(entries: Iterable<readonly [K, MellosMap | undefined]>, pageId: string): {
+    parent: K;
+    label: string;
+} | undefined;
+/**
+ * The page a client shows when nobody asked for one: the most recently
+ * WRITTEN page — the ledger last touched is almost always the effort under
+ * way. Keys without a readable timestamp lose; an empty set answers the
+ * first key (caller-ordered: default page first, then slug order).
+ * @param keys - candidate page keys in the caller's fallback order.
+ * @param mtimeOf - last-written timestamp of a key, undefined when unknown.
+ * @returns the winning key, or undefined for an empty candidate set.
+ *
+ * VIOLATION: prefer-objects - `mtimeOf` is a function parameter, which this
+ * layer otherwise avoids. It is what keeps the rule medium-neutral: the two
+ * callers ask different worlds for the same fact — the pane stats a file, the
+ * browser panel reads an mtime the host already sent over the wire — and
+ * neither timestamp source can be named here without dragging a filesystem or
+ * a transport into a module that must stay free of both. The alternative,
+ * taking `readonly [K, number | undefined][]`, only moves the same lookup to
+ * the caller and makes it allocate a pair per page per tick. The parameter is
+ * a pure query, called once per key, never stored.
+ */
+export declare function mostRecentKey<K>(keys: readonly K[], mtimeOf: (key: K) => number | undefined): K | undefined;
+/**
+ * Sequence pages read like the classic diagram: time flows DOWNWARD, the
+ * earliest step right under the participant headers. The stored map keeps
+ * rank 0 = earliest with edges pointing later -> earlier ("later stands on
+ * earlier"); this derived value inverts the ranks and reverses the edges so
+ * unchanged top-down machinery draws top-down time — each wire now runs
+ * from the sender's moment down into the receiver's. Derived for rendering
+ * only, never persisted (same contract as aggregateMap).
+ */
+export declare function flipForSequence(map: MellosMap): MellosMap;