@north-light/api 0.3.580 → 0.3.587

package/dist/core/inspector/host.js

@@ -0,0 +1,538 @@
+// host.ts — the native Inspector's alt-screen runtime.
+//
+// The host owns the terminal, chrome, subprocess transport, and single-flight
+// intent lane. Inspector state is immutable; keybindings dispatch named intents.
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../tui/terminal.js';
+import { createDraw, detectColorCaps } from '../tui/draw.js';
+import { initialChrome, deriveState } from './chrome.js';
+import { createInspectorTransport } from './transport.js';
+import { formatBinding, matchesTerminalInput, resolveUserKeybindings, } from '../keybindings/index.js';
+// Numeric SGR codes only (a color NAME emits a broken CSI — see draw.ts guard).
+const FG = { cyan: '36', green: '32', yellow: '33', red: '31', grey: '90' };
+/** The persistent state signal. Each hue is paired with a glyph and word. */
+const CHIP = {
+    working: { word: 'working', glyph: '⟳', fg: FG.cyan },
+    blocked: { word: 'blocked', glyph: '⚠', fg: FG.red },
+    attention: { word: 'attention', glyph: '⚠', fg: FG.yellow },
+    ready: { word: 'ready', glyph: '●', fg: FG.green },
+    idle: { word: 'idle', glyph: '◌', fg: FG.grey },
+};
+/** Spinner frames for the working chip (animated only while busy). */
+const SPINNER = ['⟳', '⟲'];
+/** Explicit interaction modes flip the chip to the compose accent (yellow `33`)
+ *  so entering an input mode is unmistakable. Known modes get a tailored glyph;
+ *  any other mode word falls back to `✎`. Color is yellow; the glyph + bold are
+ *  the mono carrier (survive NO_COLOR). */
+const MODE_GLYPH = { compose: '✎', react: '☺' };
+const MODE_GLYPH_FALLBACK = '✎';
+/** Banner glyph + hue by severity (color never carries meaning alone: the glyph
+ *  + bold survive NO_COLOR). */
+const BANNER = {
+    info: { glyph: 'ℹ', fg: FG.cyan },
+    action: { glyph: '▸', fg: FG.yellow },
+    error: { glyph: '✗', fg: FG.red },
+};
+/** Color-code the transient footer status by kind (not dim, so it leads): a
+ *  trailing … or an in-progress verb → cyan; a completed verb → green; else plain.
+ *  The words carry meaning; the hue is decorative (mono-safe). */
+function statusStyle(s) {
+    if (/…$/.test(s) || /^(loading|sending|reacting|opening|working|refreshing)\b/i.test(s))
+        return { fg: FG.cyan };
+    if (/^(sent|reacted|done|saved|caught up)\b/i.test(s) || /\bsent\b/i.test(s))
+        return { fg: FG.green };
+    return {};
+}
+/** Visible width of a span group. */
+function spanWidth(spans) {
+    let n = 0;
+    for (const s of spans)
+        n += Array.from(s.text).length;
+    return n;
+}
+/** Compact relative-time cue for "updated <rel>": now/Ns/Nm/Nh/Nd. */
+function relTime(deltaMs) {
+    const s = Math.max(0, Math.floor(deltaMs / 1000));
+    if (s < 5)
+        return 'just now';
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+}
+/** Build the right-flushed keymap span group, applying the overflow ladder: full
+ *  (key bold + label dim) → keys only → drop trailing hints (keep the last, q quit)
+ *  → the last hint alone. Returns spans ≤ `avail` where possible. */
+function keymapSpans(hints, avail) {
+    if (hints.length === 0 || avail <= 0)
+        return [];
+    const sep = () => ({ text: ' · ', style: { dim: true } });
+    const build = (hs, labels) => {
+        const out = [];
+        hs.forEach((h, i) => {
+            if (i > 0)
+                out.push(sep());
+            out.push({ text: h.keys, style: { bold: true } });
+            if (labels)
+                out.push({ text: ` ${h.label}`, style: { dim: true } });
+        });
+        return out;
+    };
+    let spans = build(hints, true);
+    if (spanWidth(spans) <= avail)
+        return spans;
+    spans = build(hints, false);
+    if (spanWidth(spans) <= avail)
+        return spans;
+    const last = hints[hints.length - 1];
+    for (let keep = hints.length - 1; keep > 0; keep--) {
+        spans = build([...hints.slice(0, keep), last], false);
+        if (spanWidth(spans) <= avail)
+            return spans;
+    }
+    return build([last], false); // may still overflow — spansRight left-clips with …
+}
+/** Draw the host chrome into `draw` and return the content Rect for the view.
+ *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
+ *  a hairline, and a footer (status left, keymap right) with a severity banner
+ *  on the row above it when set. */
+function drawInspectorChrome(draw, size, manifest, c, now = Date.now()) {
+    const { cols, rows } = size;
+    const st = deriveState(c);
+    // Chip selection. An explicit interaction mode (compose/react) WINS the chip
+    // over the derived state — even while busy — so entering input is unmistakable
+    // (precedence: setMode > derived). The mode chip is the yellow compose accent;
+    // only the derived `working` chip animates its spinner.
+    let chipWord;
+    let chipGlyph;
+    let chipFg;
+    let animate = false;
+    if (c.mode) {
+        chipWord = c.mode;
+        chipGlyph = MODE_GLYPH[c.mode] ?? MODE_GLYPH_FALLBACK;
+        chipFg = FG.yellow;
+    }
+    else {
+        const chip = CHIP[st];
+        chipWord = chip.word;
+        chipGlyph = chip.glyph;
+        chipFg = chip.fg;
+        animate = st === 'working';
+    }
+    const chipStyle = { fg: chipFg, bold: true };
+    // ── Title row: right cluster first (measure), then title clipped to fit. ──
+    const glyph = animate ? (SPINNER[c.tick % SPINNER.length] ?? chipGlyph) : chipGlyph;
+    const rightCluster = [{ text: `${glyph} ${chipWord}`, style: chipStyle }];
+    if (c.loaded && c.lastRefresh > 0) {
+        rightCluster.push({ text: ` · updated ${relTime(now - c.lastRefresh)}`, style: { dim: true } });
+    }
+    const rightW = spanWidth(rightCluster);
+    draw.text(0, 0, '▎', chipStyle); // state rail (always drawn; word carries meaning in mono)
+    // Dynamic subtitle overrides the static manifest default; null ⇒ manifest.
+    const subtitle = c.subtitle ?? manifest.subtitle;
+    const titleSpans = [{ text: manifest.title, style: { bold: true } }];
+    if (subtitle)
+        titleSpans.push({ text: ` · ${subtitle}`, style: { dim: true } });
+    draw.spans(0, 2, titleSpans, Math.max(0, cols - 2 - rightW - 1));
+    draw.spansRight(0, cols, rightCluster, rightW);
+    draw.hline(1, 0, cols); // hairline separator (dim)
+    // ── Footer: status left (color-coded, not dim), keymap right. ──
+    const footerRow = rows - 1;
+    const status = c.status ?? '';
+    const statusW = Math.min(spanWidth([{ text: status }]), Math.max(0, Math.floor(cols / 2)));
+    if (status)
+        draw.spans(footerRow, 0, [{ text: status, style: statusStyle(status) }], statusW);
+    const avail = Math.max(0, cols - statusW - 1);
+    draw.spansRight(footerRow, cols, keymapSpans(manifest.keymap ?? [], avail), avail);
+    // ── Banner (bottom-1, only when set): severity-coded, full-width. ──
+    let bottomRows = 1;
+    if (c.banner) {
+        const b = BANNER[c.banner.level];
+        draw.spans(footerRow - 1, 0, [
+            { text: `${b.glyph} `, style: { fg: b.fg, bold: true } },
+            { text: c.banner.msg, style: { bold: true } },
+        ], cols);
+        bottomRows = 2;
+    }
+    const top = 2; // title + separator
+    const height = Math.max(1, rows - top - bottomRows);
+    return { row: top, col: 0, width: cols, height };
+}
+export { drawInspectorChrome };
+/** True when some effective binding claims the `ctrl+h` gesture — used to decide
+ * whether the ambiguous 0x08 byte is a Ctrl-H remap or a plain Backspace. */
+function bindingSetClaimsCtrlH(bindings) {
+    for (const eff of bindings.bindings.values()) {
+        if (eff.gestures.includes('ctrl+h'))
+            return true;
+    }
+    return false;
+}
+/** One-line summary of rejected hand-edited overrides, surfaced once per surface. */
+function summarizeKeybindingDiagnostics(diags) {
+    if (diags.length === 0)
+        return null;
+    const extra = diags.length > 1 ? ` (+${diags.length - 1} more)` : '';
+    return `keybindings: ${diags[0].message}${extra}`;
+}
+/** Decode terminal bytes into the shared keybinding catalog's input shape. */
+export function parseInspectorInput(data, bindings) {
+    const parsed = parseKeypress(data);
+    const raw = { ...parsed.key, input: parsed.input };
+    const sequence = data.toString('utf8');
+    const named = {
+        '\x1b[3~': 'delete', '\x1b[5~': 'pageUp', '\x1b[6~': 'pageDown',
+        '\x1b[H': 'home', '\x1b[F': 'end', '\x1b[1~': 'home', '\x1b[4~': 'end',
+        '\x1bOH': 'home', '\x1bOF': 'end',
+    };
+    const setModifiers = (code) => {
+        const value = Number(code);
+        raw.shift = value === 2 || value === 4 || value === 6 || value === 8;
+        raw.meta = value === 3 || value === 4 || value === 7 || value === 8;
+        raw.ctrl = value === 5 || value === 6 || value === 7 || value === 8;
+    };
+    const namedKey = named[sequence];
+    if (namedKey)
+        raw[namedKey] = true;
+    const arrow = /^\x1b\[(?:1;)?([2-8])?([ABCD])$/.exec(sequence);
+    if (arrow) {
+        setModifiers(arrow[1]);
+        raw[{ A: 'upArrow', B: 'downArrow', C: 'rightArrow', D: 'leftArrow' }[arrow[2]]] = true;
+    }
+    const modifiedNamed = /^\x1b\[(3|5|6|1|4);([2-8])~$/.exec(sequence);
+    if (modifiedNamed) {
+        raw[{ 3: 'delete', 5: 'pageUp', 6: 'pageDown', 1: 'home', 4: 'end' }[modifiedNamed[1]]] = true;
+        setModifiers(modifiedNamed[2]);
+    }
+    const modifiedHomeEnd = /^\x1b\[1;([2-8])([HF])$/.exec(sequence);
+    if (modifiedHomeEnd) {
+        raw[modifiedHomeEnd[2] === 'H' ? 'home' : 'end'] = true;
+        setModifiers(modifiedHomeEnd[1]);
+    }
+    // Alt+<char> gestures arrive as an escape-prefixed byte pair.
+    if (sequence.length === 2 && sequence.startsWith('\x1b') && parsed.input === sequence) {
+        const code = sequence.charCodeAt(1);
+        raw.input = code < 32 ? String.fromCharCode(code + 64).toLowerCase() : sequence[1];
+        raw.meta = true;
+        raw.ctrl = code < 32;
+    }
+    // The 0x08 byte is either Backspace or an explicit Ctrl-H remap.
+    if (raw.backspace) {
+        const ctrlHByte = sequence === '\b' || sequence === '\x1b\b';
+        if (ctrlHByte && bindings && bindingSetClaimsCtrlH(bindings)) {
+            raw.input = 'h';
+            raw.ctrl = true;
+            raw.meta = false;
+            raw.backspace = false;
+        }
+        else {
+            raw.input = '';
+            raw.ctrl = false;
+            raw.meta = false;
+            raw.backspace = true;
+        }
+    }
+    return raw;
+}
+/** Resolve footer hints from the Inspector's current mode and user bindings. */
+export function resolveInspectorKeyHints(keymap, bindings, state) {
+    const hints = [];
+    for (const binding of keymap) {
+        if (!binding.hint || (binding.when && !binding.when(state)))
+            continue;
+        if (bindings.gestures(binding.bindingId).length === 0)
+            continue;
+        hints.push({ keys: formatBinding(bindings, binding.bindingId), label: binding.hint.label });
+    }
+    return hints;
+}
+/** Match the first active Inspector action claimed by the input. */
+export function matchInspectorBinding(keymap, bindings, state, raw) {
+    for (const binding of keymap) {
+        if (binding.when && !binding.when(state))
+            continue;
+        if (matchesTerminalInput(bindings, binding.bindingId, raw)) {
+            return { intent: binding.intent, payload: binding.payload ? binding.payload(state) : undefined };
+        }
+    }
+    return null;
+}
+/** Match the Inspector host's exit action through the catalog snapshot. */
+export function matchesInspectorHostBinding(bindings, raw) {
+    return matchesTerminalInput(bindings, 'crtr.inspector.force-quit', raw);
+}
+/** Run a READ source / WRITE command through a transport → typed Result. */
+async function runRequest(transport, src, args) {
+    const raw = await transport.send(src.request(args));
+    return src.parse(raw);
+}
+/** Host the Inspector until it quits, or emit its static text snapshot. */
+export async function runInspector(core, tui, text, opts = {}) {
+    const options = Object.freeze({ ...(opts.options ?? {}) });
+    const bindings = resolveUserKeybindings();
+    const keybindingNotice = summarizeKeybindingDiagnostics(bindings.diagnostics);
+    const transport = createInspectorTransport({ cwd: process.cwd() });
+    // ── Non-TTY / piped path: init, best-effort refresh, dump, exit 0. ──
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        if (keybindingNotice)
+            process.stderr.write(`${keybindingNotice}\n`);
+        let dstate = core.init(options);
+        const dchrome = initialChrome();
+        const dsignal = {
+            setStatus() { }, setBanner(m, l) { dchrome.banner = { msg: m, level: l }; }, clearBanner() { dchrome.banner = null; },
+            setSubtitle() { }, setMode() { }, quit() { },
+        };
+        const dctx = {
+            get state() { return dstate; },
+            set(next) { dstate = typeof next === 'function' ? next(dstate) : next; },
+            resolve: (s, a) => runRequest(transport, s, a),
+            execute: (c, a) => runRequest(transport, c, a),
+            signal: dsignal,
+            dispatch: async (name, payload) => { const it = core.intents[name]; if (it)
+                await it(dctx, payload); },
+        };
+        const refresh = core.intents['refresh'];
+        if (refresh) {
+            try {
+                await refresh(dctx, undefined);
+            }
+            catch { /* dump current state regardless */ }
+        }
+        let out = text.dump(dstate, { banner: dchrome.banner });
+        if (!out.endsWith('\n'))
+            out += '\n';
+        process.stdout.write(out);
+        return;
+    }
+    const caps = detectColorCaps();
+    let state = core.init(options);
+    const chrome = initialChrome();
+    let tick = 0;
+    // Report rejected hand-edited overrides once, as a chrome notice.
+    if (keybindingNotice)
+        chrome.banner = { msg: keybindingNotice, level: 'action' };
+    // Restore the terminal exactly once, however we leave.
+    let restored = false;
+    const cleanup = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            restoreTerminal();
+        }
+        catch { /* best-effort */ }
+    };
+    process.once('exit', cleanup);
+    const render = () => {
+        const size = getTerminalSize();
+        const { draw, frame } = createDraw(size, caps);
+        const chromeManifest = { ...core.manifest, keymap: resolveInspectorKeyHints(tui.keymap, bindings, state) };
+        const tickChrome = { ...chrome, tick };
+        const content = drawInspectorChrome(draw, size, chromeManifest, tickChrome);
+        try {
+            tui.render(state, draw, content);
+        }
+        catch (e) {
+            chrome.banner = { msg: `render error: ${errText(e)}`, level: 'error' };
+        }
+        process.stdout.write(frame());
+    };
+    // Busy-tick repaint: advance the spinner + repaint while an async intent runs
+    // so live setStatus narration shows. Render-only — never re-enters an intent.
+    let tickTimer;
+    const startBusyTick = () => {
+        if (tickTimer)
+            return;
+        tickTimer = setInterval(() => { tick++; render(); }, 120);
+    };
+    const stopBusyTick = () => {
+        if (tickTimer) {
+            clearInterval(tickTimer);
+            tickTimer = undefined;
+        }
+    };
+    // Loop control hoisted so signal.quit() can finish from inside an intent.
+    let done = false;
+    let resolveLoop = () => { };
+    const loopDone = new Promise((res) => { resolveLoop = res; });
+    let loopTimer;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        if (loopTimer)
+            clearInterval(loopTimer);
+        while (dispatchQueue.length > 0) {
+            dispatchQueue.shift().resolve();
+        }
+        stopBusyTick();
+        cleanup();
+        resolveLoop();
+    };
+    const signal = {
+        setStatus(msg) { chrome.status = msg; },
+        setBanner(msg, level) { chrome.banner = msg == null ? null : { msg, level }; },
+        clearBanner() { chrome.banner = null; },
+        setSubtitle(s) { chrome.subtitle = s; },
+        setMode(mode) { chrome.mode = mode; },
+        quit() { finish(); },
+    };
+    // The single-flight busy lane lives in the external FIFO. Refresh timers skip
+    // while busy; ctx.dispatch from inside an intent runs inline so chained intents
+    // do not deadlock. Keystrokes QUEUE behind an in-flight intent (up to a small
+    // depth) rather than vanishing: Inspector auto-refresh shells out, and silently
+    // swallowing a confirmation or cursor move would make the screen feel deaf.
+    let busy = false;
+    let dispatching = false;
+    const dispatchQueue = [];
+    const markRefreshed = (name) => {
+        if (name === 'refresh') {
+            chrome.loaded = true;
+            chrome.lastRefresh = Date.now();
+        }
+    };
+    function makeCtx() {
+        return {
+            get state() { return state; },
+            set(next) { state = typeof next === 'function' ? next(state) : next; render(); },
+            resolve: (s, a) => runRequest(transport, s, a),
+            execute: (c, a) => runRequest(transport, c, a),
+            signal,
+            dispatch: (name, payload) => runIntentInline(name, payload),
+        };
+    }
+    async function runIntentInline(intentName, payload) {
+        if (done)
+            return;
+        const intent = core.intents[intentName];
+        if (!intent) {
+            chrome.banner = { msg: `unknown intent: ${intentName}`, level: 'error' };
+            render();
+            return;
+        }
+        const ctx = makeCtx();
+        let res;
+        try {
+            res = intent(ctx, payload);
+        }
+        catch (e) {
+            chrome.banner = { msg: errText(e), level: 'error' };
+            markRefreshed(intentName);
+            render();
+            return;
+        }
+        if (res instanceof Promise) {
+            const wasBusy = busy;
+            if (!wasBusy) {
+                busy = true;
+                chrome.busy = true;
+                render();
+                startBusyTick();
+            }
+            try {
+                await res;
+            }
+            catch (e) {
+                chrome.banner = { msg: errText(e), level: 'error' };
+            }
+            finally {
+                if (!wasBusy) {
+                    busy = false;
+                    chrome.busy = false;
+                    stopBusyTick();
+                }
+                markRefreshed(intentName);
+                render();
+            }
+        }
+        else {
+            markRefreshed(intentName);
+            render();
+        }
+    }
+    async function drainDispatchQueue() {
+        if (dispatching)
+            return;
+        dispatching = true;
+        try {
+            while (!done && dispatchQueue.length > 0) {
+                const job = dispatchQueue.shift();
+                try {
+                    await runIntentInline(job.intentName, job.payload);
+                }
+                finally {
+                    job.resolve();
+                }
+            }
+        }
+        finally {
+            dispatching = false;
+            if (!done && dispatchQueue.length > 0)
+                void drainDispatchQueue();
+        }
+    }
+    function enqueueDispatch(intentName, payload) {
+        if (done)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            dispatchQueue.push({ intentName, payload, resolve });
+            void drainDispatchQueue();
+        });
+    }
+    // ── Mount: init → loading frame → first refresh. ──
+    setupTerminal();
+    render();
+    if (core.intents['refresh'])
+        await enqueueDispatch('refresh');
+    // Keystroke-dispatch backlog depth (see onData).
+    const MAX_QUEUED_KEYS = 2;
+    let queuedKeys = 0;
+    if (typeof core.manifest.refreshMs === 'number' && core.manifest.refreshMs > 0) {
+        loopTimer = setInterval(() => { if (!busy)
+            void enqueueDispatch('refresh'); }, core.manifest.refreshMs);
+    }
+    const onData = async (data) => {
+        if (done)
+            return;
+        let raw;
+        try {
+            raw = parseInspectorInput(data, bindings);
+        }
+        catch {
+            return;
+        }
+        // The catalog-backed escape hatch works even mid-flight.
+        if (matchesInspectorHostBinding(bindings, raw)) {
+            finish();
+            return;
+        }
+        // Keep the input backlog shallow so delayed actions never replay against a
+        // substantially newer Inspector frame.
+        if (busy && queuedKeys >= MAX_QUEUED_KEYS)
+            return;
+        const m = matchInspectorBinding(tui.keymap, bindings, state, raw);
+        if (!m)
+            return;
+        queuedKeys += 1;
+        try {
+            await enqueueDispatch(m.intent, m.payload);
+        }
+        finally {
+            queuedKeys -= 1;
+        }
+    };
+    process.stdin.on('data', (d) => { void onData(d); });
+    // Resize → repaint from current state (never re-enter an in-flight intent).
+    process.stdout.on('resize', () => { if (!done)
+        render(); });
+    await loopDone;
+}
+function errText(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}

package/dist/core/inspector/model.d.ts

@@ -0,0 +1,88 @@
+import type { CronDTO } from '../../api/dto/crons.js';
+export type InspectorSection = 'overview' | 'schedule' | 'jobs' | 'raw';
+/** One live background bash job, as `crtr --json node bash list` reports it. */
+export interface BashJobRow {
+    job_id: string;
+    command: string;
+    /** Human-readable label supplied with the bash call, or null when absent. */
+    purpose: string | null;
+    started_at: string;
+    elapsed_ms: number;
+    log_path: string;
+    /** Supervisor process group — null for a job started before crtr persisted
+     *  one, which is exactly the set of jobs the Inspector cannot stop. */
+    pgid: number | null;
+    log_tail: string[];
+}
+export interface ScheduledItem {
+    cron: CronDTO;
+    nextAt: string;
+    cadence: string;
+    target: string;
+}
+export declare const ICON: {
+    readonly identity: string;
+    readonly state: string;
+    readonly place: string;
+    readonly graph: string;
+    readonly artifacts: string;
+    readonly paths: string;
+    readonly cron: string;
+    readonly job: string;
+    readonly log: string;
+    readonly section: string;
+    readonly raw: string;
+    readonly empty: string;
+};
+/** Semantic tone for a value. Hue is always paired with a word or glyph so the
+ *  meaning survives NO_COLOR / a mono terminal. */
+export type Tone = 'plain' | 'dim' | 'good' | 'warn' | 'bad' | 'accent';
+export interface Field {
+    label: string;
+    value: string;
+    tone?: Tone;
+    /** Glyph drawn immediately before the value, in the value's tone. */
+    glyph?: string;
+}
+export interface Group {
+    icon: string;
+    title: string;
+    fields: Field[];
+}
+export declare function statusVisual(status: string): {
+    glyph: string;
+    tone: Tone;
+};
+export declare function scheduledItems(crons: readonly CronDTO[]): ScheduledItem[];
+/** Elapsed duration in the shape every bash-handoff surface uses: `12s`,
+ *  `3m 40s`, `1h 04m`. Duplicated from core/bash-jobs.ts on purpose — a view
+ *  module stays a pure read and never pulls the node:fs job scanner in. */
+export declare function elapsed(ms: number): string;
+/** How a running job's age reads at a glance: an ordered ramp, not decoration.
+ *  Fresh work is green, a job past 15m is amber, past an hour is red — the same
+ *  good/warn/bad progression the node status glyphs use. */
+export declare function jobTone(elapsedMs: number): Tone;
+/** Milliseconds a job has been running, live from `started_at`. */
+export declare function jobElapsedMs(job: BashJobRow, now?: number): number;
+/** Live elapsed time for a job row — recomputed from `started_at` so the number
+ *  keeps ticking between the view's 5s refreshes; `elapsed_ms` is the fallback. */
+export declare function jobElapsed(job: BashJobRow, now?: number): string;
+/** First line of a command, whitespace-collapsed and capped for a one-row cell. */
+export declare function commandCell(command: string, cap?: number): string;
+/** A person-readable purpose leads when present; legacy jobs retain their
+ * command label. */
+export declare function jobLabel(job: BashJobRow, cap?: number): string;
+export declare function relativeTime(iso: string | null, now?: number): string;
+/** How long ago an ISO timestamp was, e.g. `3d ago`. `—` when absent. */
+export declare function ago(iso: unknown, now?: number): string;
+/** `$HOME/x` → `~/x`; everything else verbatim. Paths are long and the tail is
+ *  the informative end, so the draw layer clips them, not this. */
+export declare function shortPath(input: unknown, home?: string): string;
+/** 97526 → `97.5k`. Token counts are read at a glance, not audited. */
+export declare function compactCount(input: unknown): string;
+/** The overview, grouped into the cards the presenters draw. Ordering is the
+ *  reading order: who → what it is doing → where → its graph → what it produced
+ *  → where that lives on disk. */
+export declare function overviewGroups(dossier: Record<string, unknown> | null): Group[];
+export declare function record(value: unknown): Record<string, unknown>;
+export declare function value(value: unknown): string;