@north-light/crouter 0.3.154

package/dist/core/tui/host.js

@@ -0,0 +1,689 @@
+// host.ts — the alt-screen loop that hosts a dual-target ViewCore + TuiPresenter
+// (src/core/view/contract.ts).
+//
+// Models browse/app.ts's loop, generalized: the host owns the screen, input,
+// chrome, and the single-flight async lane. State is immutable (the core's
+// intents update it via `ctx.set`); presenters are pure reads. A keystroke maps
+// through the TuiPresenter's keymap to a named intent the host dispatches.
+//
+//   • TTY gate: non-interactive stdin OR stdout → text.dump(state) (or a synthesized
+//     one-line dump) to stdout, exit 0.
+//   • setup/restore terminal (alt-screen, raw); restore exactly once, however we
+//     leave (quit / Ctrl-C / crash / process exit).
+//   • single-flight async lane: at most ONE async intent in flight; a busy
+//     indicator shows in the chrome; keystrokes that arrive mid-flight are
+//     DROPPED (this paces fetches/sends).
+//   • chrome: title row + separator on top; an error banner + a footer (status
+//     left, keymap hints right) on the bottom; the presenter gets the content Rect.
+//   • loop: parseKeypress → keymap → dispatch(intent) → render; refreshMs polling;
+//     resize → render (NOT refresh) so a resize mid-fetch repaints from current
+//     state without re-entering the in-flight intent.
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from './terminal.js';
+import { createDraw, detectColorCaps } from './draw.js';
+import { initialChrome, deriveState } from '../view/chrome.js';
+import { createLocalTransport } from '../view/transport-local.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: word + glyph + hue, derived from host signals so
+ *  every view gets it for free. Each pairs hue with a glyph/word — mono-safe. */
+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 drawChrome(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 { drawChrome };
+/** 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}`;
+}
+/** Extend the shared legacy parser with the terminal gestures the catalog can
+ * express. The raw shape goes only to the catalog matcher; custom literals keep
+ * their established Key-based matching. When `bindings` is supplied the ambiguous
+ * 0x08 byte resolves to Ctrl-H only if an effective binding claims it. */
+export function parseViewKeypress(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 (ESC-prefixed printables/control letters) that the
+    // legacy parser leaves as a raw two-byte `input`. Only the raw catalog shape
+    // gains the alt modifier; `parsed` keeps its Key-based shape so custom literals
+    // still match exactly as before (Alt+<letter> must NOT match a bare literal).
+    // Special keys the legacy parser already decoded (Alt+Backspace, arrows, …)
+    // return `input: ''`, so `parsed.input === sequence` skips them here.
+    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;
+    }
+    // Backspace family. \x7f, \b, and their Alt-prefixed forms all mean "delete one
+    // char" and canonicalize to plain backspace (there is no alt+backspace catalog
+    // action, so Alt+Backspace deletes exactly like Backspace, as before). The 0x08
+    // byte is ALSO Ctrl-H: honor a Ctrl-H remap only when an effective binding
+    // actually claims `ctrl+h`, otherwise it stays backspace so default deletion
+    // keeps working on ^H-erase terminals.
+    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 { ...parsed, raw };
+}
+function keyTokens(input, key) {
+    const t = [];
+    if (key.upArrow)
+        t.push('up');
+    if (key.downArrow)
+        t.push('down');
+    if (key.leftArrow)
+        t.push('left');
+    if (key.rightArrow)
+        t.push('right');
+    if (key.return)
+        t.push('return', 'enter');
+    if (key.escape)
+        t.push('escape', 'esc');
+    if (key.tab)
+        t.push('tab');
+    if (key.shiftTab)
+        t.push('shifttab');
+    if (key.backspace)
+        t.push('backspace');
+    if (key.ctrl && input)
+        t.push(`ctrl+${input}`, `c-${input}`);
+    if (!key.ctrl && !key.escape && input.length === 1)
+        t.push(input);
+    if (input === ' ')
+        t.push('space');
+    return t;
+}
+/** A printable text edit (for the capture line-editor): a non-empty input with
+ *  no special-key flag set. */
+function isPrintable(input, key) {
+    if (key.ctrl || key.meta || key.escape || key.return || key.tab || key.backspace
+        || key.upArrow || key.downArrow || key.leftArrow || key.rightArrow || key.shiftTab)
+        return false;
+    return input.length >= 1;
+}
+/** Strip control chars so a paste can't smuggle ANSI into the draft buffer. */
+function sanitizePrintable(s) {
+    return Array.from(s).filter((ch) => ch.charCodeAt(0) >= 32).join('');
+}
+/** Resolve footer hints for the CURRENT state: only bindings whose `when(state)`
+ * passes contribute, so mode-gated affordances (compose/react send/cancel/pick)
+ * appear exactly while active. Catalog bindings render the effective key label
+ * (omitted entirely when disabled); custom-view literal hints stay verbatim. */
+export function resolveViewKeyHints(keymap, bindings, state) {
+    const hints = [];
+    for (const binding of keymap) {
+        if (!binding.hint)
+            continue;
+        if (binding.when && !binding.when(state))
+            continue;
+        if ('bindingId' in binding) {
+            if (bindings.gestures(binding.bindingId).length === 0)
+                continue; // disabled: no hint
+            hints.push({ keys: formatBinding(bindings, binding.bindingId), label: binding.hint.label });
+        }
+        else if ('capture' in binding) {
+            hints.push('keys' in binding.hint ? binding.hint : { keys: 'type', label: binding.hint.label });
+        }
+        else {
+            hints.push(binding.hint);
+        }
+    }
+    return hints;
+}
+/** The first non-capture binding whose key matches and whose `when` (if any)
+ * passes — catalog IDs use the terminal matcher; custom literals retain their
+ * presenter-authored matching. */
+export function matchViewBinding(keymap, bindings, input, key, state, raw = { ...key, input }) {
+    const tokens = keyTokens(input, key);
+    for (const binding of keymap) {
+        if ('capture' in binding)
+            continue;
+        if (binding.when && !binding.when(state))
+            continue;
+        const matches = 'bindingId' in binding
+            ? matchesTerminalInput(bindings, binding.bindingId, raw)
+            : binding.keys.some((literal) => tokens.includes(literal));
+        if (matches)
+            return { intent: binding.intent, payload: binding.payload ? binding.payload(state) : undefined };
+    }
+    return null;
+}
+/** Match a host-owned generic-view action through the same catalog snapshot. */
+export function matchesViewHostBinding(bindings, id, raw) {
+    return matchesTerminalInput(bindings, id, raw);
+}
+/** The active text-capture binding for this state, if any (compose-mode entry). */
+function activeCapture(keymap, state) {
+    for (const b of keymap) {
+        if ('capture' in b && b.when(state))
+            return b;
+    }
+    return null;
+}
+/** Synthesize a one-line dump for a view that ships no text.mjs: `<title>` plus
+ *  ` — <n> items` if state has an obvious top-level list. */
+function synthDump(title, state) {
+    if (state && typeof state === 'object') {
+        for (const v of Object.values(state)) {
+            if (Array.isArray(v))
+                return `${title} — ${v.length} items`;
+        }
+    }
+    return title;
+}
+/** 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 a dual-target ViewCore + TuiPresenter in the alt screen until it quits
+ *  (or Ctrl-C). `text` is the optional text presenter for the piped path. */
+export async function runCoreView(core, tui, text, opts = {}) {
+    const options = Object.freeze({ ...(opts.options ?? {}) });
+    const bindings = resolveUserKeybindings();
+    const keybindingNotice = summarizeKeybindingDiagnostics(bindings.diagnostics);
+    const transport = createLocalTransport({ 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,
+            connect() { throw new Error('stream sources require an interactive view host'); },
+            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 ? text.dump(dstate, { banner: dchrome.banner }) : synthDump(core.manifest.title, dstate);
+        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);
+        // Footer hints are re-derived per draw so they track the active mode
+        // (compose/react affordances appear only while their `when(state)` holds).
+        const chromeManifest = { ...core.manifest, keymap: resolveViewKeyHints(tui.keymap, bindings, state) };
+        const tickChrome = { ...chrome, tick };
+        const content = drawChrome(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();
+        }
+        for (const channel of streams) {
+            try {
+                channel.close();
+            }
+            catch { /* best-effort */ }
+        }
+        streams.clear();
+        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. Key input still
+    // drops while busy; refresh timers still skip while busy; ctx.dispatch from
+    // inside an intent runs inline so chained intents do not deadlock.
+    const streams = new Set();
+    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),
+            connect(source, args) {
+                let channel;
+                channel = transport.open(source.request(args), {
+                    onFrame(frame) {
+                        void enqueueDispatch(source.onFrame, frame);
+                    },
+                    onClose(reason) {
+                        streams.delete(channel);
+                        if (source.onClose)
+                            void enqueueDispatch(source.onClose, { reason, channelId: channel.id });
+                    },
+                    onError(err) {
+                        signal.setBanner(err.display.headline, err.display.level);
+                    },
+                });
+                streams.add(channel);
+                if (source.onOpen)
+                    void enqueueDispatch(source.onOpen, channel);
+                return channel;
+            },
+            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 (if the view has one). ──
+    setupTerminal();
+    render();
+    if (core.intents['refresh'])
+        await enqueueDispatch('refresh');
+    // Capture-mode buffer: the host's line-editor draft while a `capture` binding's
+    // when(state) is true; reset to '' whenever no capture binding is active.
+    let captureBuf = '';
+    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 parsed;
+        try {
+            parsed = parseViewKeypress(data, bindings);
+        }
+        catch {
+            return;
+        }
+        const { input, key, raw } = parsed;
+        // The catalog-backed escape hatch works even mid-flight.
+        if (matchesViewHostBinding(bindings, 'crtr.view.host.force-quit', raw)) {
+            finish();
+            return;
+        }
+        // Drop keystrokes while an async intent is in flight (paces fetch/send).
+        if (busy)
+            return;
+        // Text-capture: while a capture binding is active, printable/backspace edit
+        // the host buffer and dispatch capture(nextDraft); other keys (return/escape)
+        // fall through to the keymap so submit/cancel can be bound.
+        const cap = activeCapture(tui.keymap, state);
+        if (cap) {
+            if (matchesViewHostBinding(bindings, 'crtr.view.host.editor.backspace', raw)) {
+                captureBuf = captureBuf.slice(0, -1);
+                await enqueueDispatch(cap.capture, captureBuf);
+                return;
+            }
+            if (isPrintable(input, key)) {
+                captureBuf += sanitizePrintable(input);
+                await enqueueDispatch(cap.capture, captureBuf);
+                return;
+            }
+        }
+        else {
+            captureBuf = '';
+        }
+        const m = matchViewBinding(tui.keymap, bindings, input, key, state, raw);
+        if (m)
+            await enqueueDispatch(m.intent, m.payload);
+    };
+    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);
+}