@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/tui/host.js

@@ -1,22 +1,27 @@
-// host.ts — the alt-screen loop that hosts a ViewModule.
+// 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; the view paints into the `Draw` it's
-// handed and returns a `ViewAction` per keystroke.
+// 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: !process.stdin.isTTY → view.dump(state) to stdout, exit 0.
+//   • TTY gate: !process.stdin.isTTY → 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 hook (refresh or an async
-//     onKey) in flight; a busy indicator shows in the chrome; keystrokes that
-//     arrive mid-flight are DROPPED (this paces fetches/sends).
+//   • 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 view gets the content Rect.
-//   • loop: parseKeypress → view.onKey → ViewAction → render; refreshMs polling;
+//     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 hook.
+//     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';
 // 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
@@ -43,19 +48,6 @@ const BANNER = {
     action: { glyph: '▸', fg: FG.yellow },
     error: { glyph: '✗', fg: FG.red },
 };
-/** Derive the one state chip from host signals (resume guidance): busy→working,
- *  error banner→blocked, action banner→attention, else ready (once loaded) / idle.
- *  An info banner does not block — the chip stays ready/idle and the cyan banner
- *  carries the notice. */
-function deriveState(c) {
-    if (c.busy)
-        return 'working';
-    if (c.banner?.level === 'error')
-        return 'blocked';
-    if (c.banner?.level === 'action')
-        return 'attention';
-    return c.loaded ? 'ready' : 'idle';
-}
 /** 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). */
@@ -187,37 +179,140 @@ function drawChrome(draw, size, manifest, c, now = Date.now()) {
     return { row: top, col: 0, width: cols, height };
 }
 export { drawChrome };
-/** Host a view in the alt screen until it quits (or Ctrl-C). */
-export async function runView(view, opts = {}) {
+// ── Dual-target core host (runCoreView) ─────────────────────────────────────
+//
+// Hosts a ViewCore + TuiPresenter under the dual-target contract
+// (src/core/view/contract.ts). The model is the immutable-state + intents thunk
+// runtime: the core owns all state + behavior, presenters are pure reads, and a
+// keystroke maps through the keymap to a named intent the host dispatches.
+/** Tokens a keystroke can match a keymap binding's `keys` against. Arrows →
+ *  up/down/left/right, return → return|enter, escape → escape|esc, a printable
+ *  char → the char itself (+ 'space' for ' '), ctrl+x → ctrl+x|c-x. */
+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('');
+}
+/** The first non-capture binding whose key matches and whose `when` (if any)
+ *  passes — returns the intent name + resolved payload. */
+function matchBinding(keymap, input, key, state) {
+    const tokens = keyTokens(input, key);
+    for (const b of keymap) {
+        if ('capture' in b)
+            continue;
+        if (b.when && !b.when(state))
+            continue;
+        if (b.keys.some((k) => tokens.includes(k))) {
+            return { intent: b.intent, payload: b.payload ? b.payload(state) : undefined };
+        }
+    }
+    return null;
+}
+/** 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 chrome = { status: null, banner: null, busy: false, loaded: false, lastRefresh: 0, tick: 0, subtitle: null, mode: null };
-    const host = {
-        options,
-        setStatus(msg) { chrome.status = msg; },
-        setBanner(msg, level) { chrome.banner = msg == null ? null : { msg, level }; },
-        setError(msg) { chrome.banner = msg == null ? null : { msg, level: 'error' }; },
-        setSubtitle(s) { chrome.subtitle = s; },
-        setMode(mode) { chrome.mode = mode; },
-    };
-    // ── Non-TTY / piped path: build state, best-effort load, dump, exit 0. ──
+    const transport = createLocalTransport({ cwd: process.cwd() });
+    // ── Non-TTY / piped path: init, best-effort refresh, dump, exit 0. ──
     if (!process.stdin.isTTY) {
-        const state = await view.init(host);
-        if (view.refresh) {
+        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 view.refresh(state, host);
+                await refresh(dctx, undefined);
             }
             catch { /* dump current state regardless */ }
         }
-        // Thread the host's current banner so a view can surface guidance without
-        // mirroring it into state (older views ignore the arg).
-        let text = view.dump(state, { banner: chrome.banner });
-        if (!text.endsWith('\n'))
-            text += '\n';
-        process.stdout.write(text);
+        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();
-    const state = await view.init(host);
+    let state = core.init(options);
+    const chrome = initialChrome();
+    let tick = 0;
+    // Footer hints come from the keymap bindings' `hint` field (single source of
+    // truth) — projected into the (ChromeManifest, Chrome) shape drawChrome reads.
+    const hints = [];
+    for (const b of tui.keymap) {
+        if (b.hint)
+            hints.push(b.hint);
+    }
     // Restore the terminal exactly once, however we leave.
     let restored = false;
     const cleanup = () => {
@@ -233,23 +328,24 @@ export async function runView(view, opts = {}) {
     const render = () => {
         const size = getTerminalSize();
         const { draw, frame } = createDraw(size, caps);
-        const content = drawChrome(draw, size, view.manifest, chrome);
+        const chromeManifest = { ...core.manifest, keymap: hints };
+        const tickChrome = { ...chrome, tick };
+        const content = drawChrome(draw, size, chromeManifest, tickChrome);
         try {
-            view.render(state, draw, content);
+            tui.render(state, draw, content);
         }
         catch (e) {
             chrome.banner = { msg: `render error: ${errText(e)}`, level: 'error' };
         }
         process.stdout.write(frame());
     };
-    // Busy-tick repaint: while an async op is in flight, a ~120ms timer advances
-    // the spinner + re-renders so live setStatus narration shows. Render-only — it
-    // NEVER re-enters a hook, and Ctrl-C still escapes (handled before the drop).
+    // 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(() => { chrome.tick++; render(); }, 120);
+        tickTimer = setInterval(() => { tick++; render(); }, 120);
     };
     const stopBusyTick = () => {
         if (tickTimer) {
@@ -257,120 +353,155 @@ export async function runView(view, opts = {}) {
             tickTimer = undefined;
         }
     };
-    // The single-flight lane. Returns true if the op ran (false if one was already
-    // in flight). Always repaints around the op so the busy indicator shows.
+    // 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);
+        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 dispatch. The INPUT layer drops
+    // keystrokes while busy (paces fetches); a chained ctx.dispatch from inside an
+    // intent runs inline without re-toggling the lane.
     let busy = false;
-    const runRefresh = async () => {
-        if (!view.refresh || busy)
+    const markRefreshed = (name) => {
+        if (name === 'refresh') {
+            chrome.loaded = true;
+            chrome.lastRefresh = Date.now();
+        }
+    };
+    const makeCtx = () => ({
+        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) => dispatch(name, payload),
+    });
+    const dispatch = async (intentName, payload) => {
+        if (done)
             return;
-        busy = true;
-        chrome.busy = true;
-        render();
-        startBusyTick();
+        const intent = core.intents[intentName];
+        if (!intent) {
+            chrome.banner = { msg: `unknown intent: ${intentName}`, level: 'error' };
+            render();
+            return;
+        }
+        const ctx = makeCtx();
+        let res;
         try {
-            await view.refresh(state, host);
+            res = intent(ctx, payload);
         }
         catch (e) {
             chrome.banner = { msg: errText(e), level: 'error' };
-        }
-        finally {
-            busy = false;
-            chrome.busy = false;
-            chrome.loaded = true;
-            chrome.lastRefresh = Date.now();
-            stopBusyTick();
+            markRefreshed(intentName);
             render();
+            return;
         }
-    };
-    setupTerminal();
-    render(); // initial loading paint (before any fetch)
-    await runRefresh(); // first data load
-    await new Promise((resolveLoop) => {
-        let done = false;
-        let timer;
-        const finish = () => {
-            if (done)
-                return;
-            done = true;
-            if (timer)
-                clearInterval(timer);
-            stopBusyTick();
-            cleanup();
-            resolveLoop();
-        };
-        if (typeof view.manifest.refreshMs === 'number' && view.manifest.refreshMs > 0) {
-            timer = setInterval(() => { void runRefresh(); }, view.manifest.refreshMs);
-        }
-        const apply = async (action) => {
-            switch (action.type) {
-                case 'render':
-                    render();
-                    break;
-                case 'refresh':
-                    await runRefresh();
-                    break;
-                case 'quit':
-                    finish();
-                    break;
-                case 'none': break;
+        if (res instanceof Promise) {
+            const wasBusy = busy;
+            if (!wasBusy) {
+                busy = true;
+                chrome.busy = true;
+                render();
+                startBusyTick();
             }
-        };
-        const onData = async (data) => {
-            if (done)
-                return;
-            let parsed;
             try {
-                parsed = parseKeypress(data);
+                await res;
             }
-            catch {
-                return;
+            catch (e) {
+                chrome.banner = { msg: errText(e), level: 'error' };
             }
-            const { input, key } = parsed;
-            // Ctrl-C is the universal escape hatch — works even mid-flight.
-            if (key.ctrl && input === 'c') {
-                finish();
-                return;
+            finally {
+                if (!wasBusy) {
+                    busy = false;
+                    chrome.busy = false;
+                    stopBusyTick();
+                }
+                markRefreshed(intentName);
+                render();
             }
-            // Drop keystrokes while an async op is in flight (paces fetch/send).
-            if (busy)
-                return;
-            if (!view.onKey) {
-                if (input === 'q')
-                    finish(); // minimal default so a no-onKey view escapes
+        }
+        else {
+            markRefreshed(intentName);
+            render();
+        }
+    };
+    // ── Mount: init → loading frame → first refresh (if the view has one). ──
+    setupTerminal();
+    render();
+    if (core.intents['refresh'])
+        await dispatch('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 dispatch('refresh'); }, core.manifest.refreshMs);
+    }
+    const onData = async (data) => {
+        if (done)
+            return;
+        let parsed;
+        try {
+            parsed = parseKeypress(data);
+        }
+        catch {
+            return;
+        }
+        const { input, key } = parsed;
+        // Ctrl-C is the universal escape hatch — works even mid-flight.
+        if (key.ctrl && input === 'c') {
+            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 (isPrintable(input, key)) {
+                captureBuf += sanitizePrintable(input);
+                await dispatch(cap.capture, captureBuf);
                 return;
             }
-            try {
-                const r = view.onKey({ input, key }, state, host);
-                let action;
-                if (r instanceof Promise) {
-                    busy = true;
-                    chrome.busy = true;
-                    render();
-                    startBusyTick();
-                    try {
-                        action = await r;
-                    }
-                    finally {
-                        busy = false;
-                        chrome.busy = false;
-                        stopBusyTick();
-                    }
-                }
-                else {
-                    action = r;
-                }
-                await apply(action);
-            }
-            catch (e) {
-                chrome.banner = { msg: errText(e), level: 'error' };
-                render();
+            if (key.backspace) {
+                captureBuf = captureBuf.slice(0, -1);
+                await dispatch(cap.capture, captureBuf);
+                return;
             }
-        };
-        process.stdin.on('data', (d) => { void onData(d); });
-        // Resize → repaint from current state (never re-enter the in-flight hook).
-        process.stdout.on('resize', () => { if (!done)
-            render(); });
-    });
+        }
+        else {
+            captureBuf = '';
+        }
+        const m = matchBinding(tui.keymap, input, key, state);
+        if (m)
+            await dispatch(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)

package/dist/core/view/bridge.d.ts

@@ -0,0 +1,10 @@
+import type { Transport } from './transport.js';
+export interface BridgeResult {
+    status: number;
+    body: string;
+}
+/** Decode a POST body as a SourceRequest and run it through `transport`,
+ *  returning the HTTP status + JSON-encoded RawResponse the bridge should send
+ *  back. Never throws — a malformed body or a transport failure both come back
+ *  as a RawResponse with ok:false. */
+export declare function runSourceRequest(transport: Transport, rawBody: string): Promise<BridgeResult>;

package/dist/core/view/bridge.js

@@ -0,0 +1,31 @@
+// bridge.ts — the server side of the local web transport (Node only).
+//
+// `crtr view serve` runs the portable core CLIENT-SIDE in the browser; its
+// sources resolve over an HTTP Transport that POSTs each SourceRequest here.
+// This helper decodes that POST body and runs it through any Transport (the
+// local exec/file/http one today) — the single endpoint a cloud deploy
+// replaces. Kept transport-agnostic + framework-free so it is trivially
+// testable and tear-out-able.
+function bad(stderr) {
+    const raw = { ok: false, stdout: '', stderr };
+    return { status: 400, body: JSON.stringify(raw) };
+}
+/** Decode a POST body as a SourceRequest and run it through `transport`,
+ *  returning the HTTP status + JSON-encoded RawResponse the bridge should send
+ *  back. Never throws — a malformed body or a transport failure both come back
+ *  as a RawResponse with ok:false. */
+export async function runSourceRequest(transport, rawBody) {
+    let req;
+    try {
+        req = JSON.parse(rawBody);
+    }
+    catch {
+        return bad('bridge: request body is not valid JSON');
+    }
+    const kind = req.kind;
+    if (!req || typeof req !== 'object' || (kind !== 'exec' && kind !== 'file' && kind !== 'http')) {
+        return bad(`bridge: request body is not a SourceRequest (kind must be exec|file|http, got ${JSON.stringify(kind)})`);
+    }
+    const raw = await transport.send(req);
+    return { status: 200, body: JSON.stringify(raw) };
+}

package/dist/core/view/chrome.d.ts

@@ -0,0 +1,9 @@
+import type { ChromeState } from './contract.js';
+export type ChipState = 'working' | 'blocked' | 'attention' | 'ready' | 'idle';
+/** Derive the state chip from host signals: busy→working, error banner→blocked,
+ *  action banner→attention, else ready (once loaded) / idle. An info banner does
+ *  not block. An explicit interaction mode (setMode) overrides the chip — that
+ *  precedence is applied by each target's chrome renderer, not here. */
+export declare function deriveState(c: ChromeState): ChipState;
+/** A fresh chrome record (the shape both hosts start from). */
+export declare function initialChrome(): ChromeState;

package/dist/core/view/chrome.js

@@ -0,0 +1,22 @@
+// chrome.ts — portable chrome-state derivation shared by both targets.
+//
+// The TUI's drawChrome and the web's <ViewChrome> both derive the one state
+// chip from the same host signals via deriveState, so the two targets never
+// drift on what "blocked" / "working" / "ready" mean.
+/** Derive the state chip from host signals: busy→working, error banner→blocked,
+ *  action banner→attention, else ready (once loaded) / idle. An info banner does
+ *  not block. An explicit interaction mode (setMode) overrides the chip — that
+ *  precedence is applied by each target's chrome renderer, not here. */
+export function deriveState(c) {
+    if (c.busy)
+        return 'working';
+    if (c.banner?.level === 'error')
+        return 'blocked';
+    if (c.banner?.level === 'action')
+        return 'attention';
+    return c.loaded ? 'ready' : 'idle';
+}
+/** A fresh chrome record (the shape both hosts start from). */
+export function initialChrome() {
+    return { status: null, banner: null, subtitle: null, mode: null, busy: false, loaded: false, lastRefresh: 0 };
+}