@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/inbox/tui/keys.js

@@ -0,0 +1,111 @@
+import { decodeKittyPrintable, matchesKey, parseKey } from '@earendil-works/pi-tui';
+function emptyKey() {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        wordLeft: false,
+        wordRight: false,
+        home: false,
+        end: false,
+        pageUp: false,
+        pageDown: false,
+        del: false,
+        return: false,
+        newline: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        backspace: false,
+    };
+}
+function withFlag(...flags) {
+    const key = emptyKey();
+    for (const flag of flags)
+        key[flag] = true;
+    return key;
+}
+function isPlainText(data) {
+    return data.length > 0 && !data.includes('\x1b') && data.charCodeAt(0) >= 0x20;
+}
+/** pi-tui parses legacy ESC+lowercase as Alt+letter, but does not normalize
+ * the shifted uppercase form. Convert that complete two-byte form to the
+ * equivalent CSI-u key so all semantic matching stays in pi-tui. */
+function normalizeLegacyShiftedMeta(data) {
+    if (data.length !== 2 || data[0] !== '\x1b' || !/[A-Z]/.test(data[1]))
+        return data;
+    return `\x1b[${data.charCodeAt(1)};4u`;
+}
+const BRACKETED_PASTE_START = '\x1b[200~';
+const BRACKETED_PASTE_END = '\x1b[201~';
+function bracketedPaste(data) {
+    if (!data.startsWith(BRACKETED_PASTE_START) || !data.endsWith(BRACKETED_PASTE_END))
+        return undefined;
+    return data.slice(BRACKETED_PASTE_START.length, -BRACKETED_PASTE_END.length);
+}
+export function decodeInboxKey(data) {
+    const pasted = bracketedPaste(data);
+    if (pasted !== undefined)
+        return { input: pasted, key: emptyKey() };
+    const normalized = normalizeLegacyShiftedMeta(data);
+    const parsed = parseKey(normalized);
+    if (matchesKey(normalized, 'up'))
+        return { input: '', key: withFlag('upArrow') };
+    if (matchesKey(normalized, 'down'))
+        return { input: '', key: withFlag('downArrow') };
+    if (matchesKey(normalized, 'left'))
+        return { input: '', key: withFlag('leftArrow') };
+    if (matchesKey(normalized, 'right'))
+        return { input: '', key: withFlag('rightArrow') };
+    if (matchesKey(normalized, 'ctrl+left') || matchesKey(normalized, 'alt+left') || matchesKey(normalized, 'alt+b')) {
+        return { input: '', key: withFlag('wordLeft') };
+    }
+    if (matchesKey(normalized, 'ctrl+right') || matchesKey(normalized, 'alt+right') || matchesKey(normalized, 'alt+f')) {
+        return { input: '', key: withFlag('wordRight') };
+    }
+    if (matchesKey(normalized, 'home'))
+        return { input: '', key: withFlag('home') };
+    if (matchesKey(normalized, 'end'))
+        return { input: '', key: withFlag('end') };
+    if (matchesKey(normalized, 'pageUp'))
+        return { input: '', key: withFlag('pageUp') };
+    if (matchesKey(normalized, 'pageDown'))
+        return { input: '', key: withFlag('pageDown') };
+    if (matchesKey(normalized, 'delete'))
+        return { input: '', key: withFlag('del') };
+    if (matchesKey(normalized, 'alt+enter') || parsed === 'ctrl+alt+j') {
+        return { input: '', key: withFlag('newline') };
+    }
+    // Enter submits; Ctrl-J inserts a newline. Check Ctrl-J first because pi-tui
+    // also recognizes a plain LF as Enter for terminals that do not distinguish it.
+    if (matchesKey(normalized, 'ctrl+j'))
+        return { input: '', key: withFlag('newline') };
+    if (matchesKey(normalized, 'enter'))
+        return { input: '', key: withFlag('return') };
+    // Ctrl-W is the word-erase form of Alt+Backspace on some terminals. Keep it
+    // ahead of the generic Ctrl-letter mapping below.
+    if (matchesKey(normalized, 'alt+backspace') || matchesKey(normalized, 'ctrl+w')) {
+        return { input: '', key: withFlag('meta', 'backspace') };
+    }
+    if (matchesKey(normalized, 'escape'))
+        return { input: '', key: withFlag('escape') };
+    if (matchesKey(normalized, 'tab'))
+        return { input: '', key: withFlag('tab') };
+    if (matchesKey(normalized, 'backspace'))
+        return { input: '', key: withFlag('backspace') };
+    if (matchesKey(normalized, 'alt+shift+r'))
+        return { input: 'R', key: withFlag('meta') };
+    if (parsed?.startsWith('ctrl+') && parsed.length === 'ctrl+'.length + 1) {
+        const letter = parsed.slice('ctrl+'.length);
+        if (/^[a-z]$/.test(letter))
+            return { input: letter, key: withFlag('ctrl') };
+    }
+    const kittyPrintable = decodeKittyPrintable(data);
+    if (kittyPrintable !== undefined)
+        return { input: kittyPrintable, key: emptyKey() };
+    if (isPlainText(data))
+        return { input: data, key: emptyKey() };
+    return { input: data, key: emptyKey() };
+}

package/dist/clients/inbox/tui/panel.d.ts

@@ -0,0 +1,2 @@
+import type { MountedPanel, MountedPanelOpts } from './types.js';
+export declare function mountPanel(opts: MountedPanelOpts): MountedPanel;

package/dist/clients/inbox/tui/panel.js

@@ -0,0 +1,217 @@
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { assignShortcuts, handleKeypress } from './input.js';
+import { clampItemReviewScroll, renderFinal, renderItemReview, renderOverview } from './render.js';
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function buildInitialState(deck, editorAvailable = false, wrapWidth = 80) {
+    // Single-question decks skip the overview list — there's nothing to overview,
+    // and overview hides the option hotkeys so users press 'y' and nothing happens.
+    const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
+    const responses = new Map();
+    const preAnsweredIds = new Set();
+    // Seed responses + preAnsweredIds from any `preAnswered` field. The seeded
+    // response counts as answered for navigation/auto-advance, but is rendered
+    // distinctly so the human knows it carried over. `tryResume` runs after and
+    // takes priority — mid-deck progress should not be overwritten by defaults.
+    for (const interaction of deck.interactions) {
+        const pa = interaction.preAnswered;
+        if (pa === undefined)
+            continue;
+        const response = { id: interaction.id };
+        if (pa.selectedOptionId !== undefined)
+            response.selectedOptionId = pa.selectedOptionId;
+        if (pa.selectedOptionIds !== undefined)
+            response.selectedOptionIds = [...pa.selectedOptionIds];
+        if (pa.freetext !== undefined)
+            response.freetext = pa.freetext;
+        responses.set(interaction.id, response);
+        preAnsweredIds.add(interaction.id);
+    }
+    // Start cursor on the first unanswered interaction — humans land where they
+    // need to act. If every interaction is pre-answered, fall back to index 0.
+    const firstUnanswered = deck.interactions.findIndex((i) => !responses.has(i.id));
+    return {
+        phase: initialPhase,
+        currentIndex: firstUnanswered >= 0 ? firstUnanswered : 0,
+        interactions: deck.interactions,
+        responses,
+        preAnsweredIds,
+        inputMode: null,
+        selectedAction: 0,
+        bodyMode: 'question',
+        scrollOffset: 0,
+        bodyScrollOffsets: { question: 0 },
+        hscrollOffset: 0,
+        hscrollMax: 0,
+        wrapWidth,
+        editorAvailable,
+    };
+}
+function collectResponses(state) {
+    const out = [];
+    for (const interaction of state.interactions) {
+        const r = state.responses.get(interaction.id);
+        if (r !== undefined)
+            out.push(r);
+    }
+    return out;
+}
+function tryResume(state, progressPath, interactions) {
+    try {
+        const prior = JSON.parse(readFileSync(progressPath, 'utf8'));
+        if (!Array.isArray(prior.responses))
+            return;
+        const validIds = new Set(interactions.map((i) => i.id));
+        for (const r of prior.responses) {
+            if (validIds.has(r.id))
+                state.responses.set(r.id, r);
+        }
+        const firstUnanswered = interactions.findIndex((i) => !state.responses.has(i.id));
+        state.currentIndex = firstUnanswered >= 0 ? firstUnanswered : 0;
+    }
+    catch {
+        // corrupt or missing progress file — start fresh
+    }
+}
+function atomicWriteProgress(progressPath, responses) {
+    const payload = JSON.stringify({ partial: true, responses, savedAt: new Date().toISOString() }, null, 2);
+    const tmp = `${progressPath}.tmp`;
+    try {
+        writeFileSync(tmp, payload);
+        renameSync(tmp, progressPath);
+    }
+    catch {
+        // best-effort
+    }
+}
+function rebindPersist(internals) {
+    internals.state.persist = () => {
+        const responses = collectResponses(internals.state);
+        if (internals.progressPath !== undefined)
+            atomicWriteProgress(internals.progressPath, responses);
+        internals.callbacks.onProgress?.(responses);
+    };
+}
+export function mountPanel(opts) {
+    const internals = {
+        state: buildInitialState(opts.deck, opts.onEditorRequest !== undefined, opts.cols),
+        cols: opts.cols,
+        rows: opts.rows,
+        mounted: true,
+        progressPath: opts.progressPath,
+        callbacks: {
+            onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit,
+            onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest,
+        },
+    };
+    assignShortcuts(internals.state.interactions);
+    rebindPersist(internals);
+    if (internals.progressPath !== undefined) {
+        tryResume(internals.state, internals.progressPath, opts.deck.interactions);
+    }
+    const renderLines = () => {
+        switch (internals.state.phase) {
+            case 'overview': return renderOverview(internals.state, internals.cols, internals.rows);
+            case 'item-review':
+                // The one pre-render clamp: keeps scrollOffset/hscrollOffset inside the
+                // current body's bounds (so u/d and h/l stay responsive) and publishes
+                // the live horizontal reach the input layer reads. The renderer itself
+                // stays pure; running it here covers mount, resize and every keypress.
+                clampItemReviewScroll(internals.state, internals.cols, internals.rows);
+                return renderItemReview(internals.state, internals.cols, internals.rows);
+            case 'final': return renderFinal(internals.state, internals.cols, internals.rows);
+        }
+    };
+    return {
+        handleKey(input, key) {
+            if (!internals.mounted)
+                return;
+            if (key.ctrl && input === 'o' && internals.state.inputMode !== null && internals.callbacks.onEditorRequest !== undefined) {
+                internals.callbacks.onEditorRequest();
+                return;
+            }
+            const onAutoComplete = () => {
+                const responses = collectResponses(internals.state);
+                if (internals.progressPath !== undefined) {
+                    try {
+                        unlinkSync(internals.progressPath);
+                    }
+                    catch { /* ignore */ }
+                }
+                internals.callbacks.onComplete?.(responses);
+            };
+            handleKeypress(input, key, internals.state, () => { }, () => {
+                const responses = collectResponses(internals.state);
+                if (responses.length >= internals.state.interactions.length) {
+                    onAutoComplete();
+                }
+                else {
+                    internals.callbacks.onExit?.();
+                }
+            });
+        },
+        render() {
+            if (!internals.mounted)
+                return [];
+            return renderLines();
+        },
+        handleResize(cols, rows) {
+            internals.cols = cols;
+            internals.rows = rows;
+            internals.state.wrapWidth = cols;
+            return renderLines();
+        },
+        unmount() {
+            if (!internals.mounted)
+                return;
+            internals.mounted = false;
+            internals.state.persist = undefined;
+        },
+        loadDeck(deck, loadOpts) {
+            if (!internals.mounted)
+                return;
+            const prior = collectResponses(internals.state);
+            internals.state = buildInitialState(deck, internals.callbacks.onEditorRequest !== undefined, internals.cols);
+            if (loadOpts !== undefined && loadOpts.progressPath !== undefined) {
+                internals.progressPath = loadOpts.progressPath;
+            }
+            assignShortcuts(internals.state.interactions);
+            rebindPersist(internals);
+            if (internals.progressPath !== undefined) {
+                tryResume(internals.state, internals.progressPath, deck.interactions);
+            }
+            // A live request replacement is allowed to add/remove questions but not
+            // discard answers the human has already made to surviving ids.
+            const validIds = new Set(deck.interactions.map((interaction) => interaction.id));
+            for (const response of prior) {
+                if (validIds.has(response.id))
+                    internals.state.responses.set(response.id, response);
+            }
+            const currentId = internals.state.interactions[internals.state.currentIndex]?.id;
+            if (currentId === undefined || !validIds.has(currentId)) {
+                const firstUnanswered = internals.state.interactions.findIndex((interaction) => !internals.state.responses.has(interaction.id));
+                internals.state.currentIndex = firstUnanswered >= 0 ? firstUnanswered : 0;
+            }
+        },
+        canAcceptHostKeys() {
+            if (!internals.mounted)
+                return false;
+            return internals.state.inputMode === null;
+        },
+        atDeckTop() {
+            if (!internals.mounted)
+                return true;
+            return internals.state.phase === 'overview' && internals.state.inputMode === null;
+        },
+        getInputBuffer() {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return undefined;
+            return internals.state.inputMode.buffer;
+        },
+        setInputBuffer(text) {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return;
+            internals.state.inputMode.buffer = text;
+            internals.state.inputMode.cursor = [...text].length;
+        },
+    };
+}

package/dist/clients/inbox/tui/render.d.ts

@@ -0,0 +1,37 @@
+import type { TuiState } from './types.js';
+import type { Interaction, InteractionResponse } from '../../../core/human/types.js';
+export declare function renderOverview(state: TuiState, cols: number, rows: number): string[];
+/**
+ * Render a (possibly multiline) input buffer with a visible cursor at
+ * `cursor` (a code-point index). A private-use sentinel is inserted at the
+ * cursor position, the result is hard-wrapped (so `\n` and width-wrapping
+ * behave exactly as they would without a cursor), then the sentinel is
+ * swapped for a reverse-video block on whichever wrapped line it landed on.
+ * `stringWidth('\uE000') === 1`, so it occupies exactly one column and never
+ * throws off the wrap math.
+ */
+export declare function renderInputBuffer(buffer: string, cursor: number, maxWidth: number): string[];
+/** Code-point bounds of every visual row `renderInputBuffer` paints, mirroring
+ *  `hardWrap` (character-based, lossless) so a cursor index maps to the row the
+ *  human actually sees. `end` is exclusive of the row's trailing '\n', if any. */
+export declare function wrappedRowBounds(buffer: string, width: number): {
+    start: number;
+    end: number;
+}[];
+/** Vertical motion by *visual* row — what up/down mean in a wrapped input box,
+ *  where one long soft-wrapped paragraph spans many rows. Returns the new
+ *  code-point cursor, unchanged when there is no row in that direction. */
+export declare function verticalCursor(buffer: string, cursor: number, delta: number, width: number): number;
+/**
+ * Clamp state.scrollOffset to the current body's scroll bounds. The host runs
+ * this as a pre-render step (from the input path) so `renderItemReview` stays a
+ * pure function of state — the clamp keeps u/d scrolling responsive without the
+ * renderer mutating state mid-frame.
+ */
+export declare function clampItemReviewScroll(state: TuiState, cols: number, rows: number): void;
+/** Pan the card body horizontally. Clamping happens in the pre-render clamp
+ *  the host already runs, exactly like vertical over-scroll. */
+export declare function panItemReview(state: TuiState, direction: -1 | 1): void;
+export declare function renderItemReview(state: TuiState, cols: number, rows: number): string[];
+export declare function renderFinal(state: TuiState, cols: number, rows: number): string[];
+export declare function responseSummary(r: InteractionResponse, interaction: Interaction): string;