@north-light/crouter 0.3.192 → 0.3.193

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

@@ -1,130 +1,50 @@
+import { isResponseBearingSlot } from '../../../core/human/page-schema.js';
 import { panItemReview, verticalCursor } from './render.js';
-const RESERVED = new Set(['c', 'r', 'n', 'p', 'q', 'j', 'k', 'u', 'd', ' ']);
-export function assignShortcuts(interactions) {
-    for (const it of interactions) {
-        const used = new Set(it.options.map((o) => o.shortcut).filter((s) => s !== undefined));
-        for (const opt of it.options) {
-            if (opt.shortcut !== undefined)
-                continue;
-            const letters = [...opt.label.toLowerCase()].filter((c) => /[a-z]/.test(c));
-            let chosen;
-            for (const letter of letters) {
-                if (!used.has(letter) && !RESERVED.has(letter)) {
-                    chosen = letter;
-                    break;
-                }
-            }
-            if (chosen === undefined) {
-                for (let d = 1; d <= 9; d++) {
-                    const s = String(d);
-                    if (!used.has(s)) {
-                        chosen = s;
-                        break;
-                    }
-                }
-            }
-            if (chosen !== undefined) {
-                opt.shortcut = chosen;
-                used.add(chosen);
-            }
-        }
-    }
-}
+import { commentIdFor, pageComplete, slotActions, slotAnswered, terminalAnswerable } from './slots.js';
+/** Only a single-mode options/cards pick jumps ahead; a table pick leaves the user on the table. */
+const autoAdvances = (slot, mode) => mode === 'single' && (slot.kind === 'options' || slot.kind === 'cards');
 export function handleKeypress(input, key, state, render, exit) {
     if (key.ctrl && input === 'c') {
-        exit();
+        exit(false);
         return;
     }
-    // Clear any transient hint from the previous keypress. Handlers below may set
-    // a fresh one (e.g. an empty multi-select Enter), so it survives exactly one
-    // render cycle.
     state.hint = undefined;
-    if (state.inputMode) {
+    if (state.inputMode !== null) {
         handleInputMode(input, key, state, render);
-        checkAutoExit(state, exit);
         return;
     }
-    switch (state.phase) {
-        case 'overview':
-            handleOverview(input, key, state, render, exit);
-            break;
-        case 'item-review':
-            handleItemReview(input, key, state, render);
-            checkAutoExit(state, exit);
-            break;
-        case 'final':
-            handleFinal(input, key, state, render, exit);
-            break;
-    }
-}
-function checkAutoExit(state, exit) {
-    if (state.phase !== 'final')
-        return;
-    if (state.responses.size < state.interactions.length)
-        return;
-    // Multi-select commits route THROUGH the Summary/confirm screen instead of
-    // auto-exiting on the first Enter: the commit advances the deck to `final`,
-    // but the human must press Enter again (handleFinal) to actually submit.
-    // The interaction that pushed us into `final` is still at currentIndex — the
-    // advance helpers leave it there when they fall through to `final` — so a
-    // multi-select there means "just confirmed a set, await deliberate submit".
-    // Single-select keeps its submit-on-pick fast path (auto-exit below).
-    const justCommitted = state.interactions[state.currentIndex];
-    if (justCommitted?.multiSelect === true)
-        return;
-    exit();
+    if (state.phase === 'overview')
+        handleOverview(input, key, state, render, exit);
+    else if (state.phase === 'item-review')
+        handleItemReview(input, key, state, render, exit);
+    else
+        handleFinal(input, key, state, render, exit);
 }
-// ── Overview ─────────────────────────────────────────────────────────────────
 function handleOverview(input, key, state, render, exit) {
-    if (input === 'j' || key.downArrow) {
-        state.currentIndex = Math.min(state.currentIndex + 1, state.interactions.length - 1);
-        render();
-        return;
-    }
-    if (input === 'k' || key.upArrow) {
+    if (input === 'j' || key.downArrow)
+        state.currentIndex = Math.min(state.currentIndex + 1, Math.max(0, state.slots.length - 1));
+    else if (input === 'k' || key.upArrow)
         state.currentIndex = Math.max(state.currentIndex - 1, 0);
-        render();
-        return;
-    }
-    if (key.return || input === ' ') {
+    else if ((key.return || input === ' ') && state.slots.length > 0) {
         state.phase = 'item-review';
-        state.selectedAction = 0;
-        state.bodyMode = 'question';
-        state.scrollOffset = state.bodyScrollOffsets.question;
-        render();
-        return;
+        resetItem(state);
     }
-    if (input === 'q') {
-        if (state.responses.size >= state.interactions.length) {
-            exit();
-        }
-        else {
-            state.phase = 'final';
-            render();
-        }
+    else if (input === 'q' || key.escape) {
+        exit(!state.manifest.slots.some(isResponseBearingSlot));
         return;
     }
-    // Quick-answer: option shortcut for the focused interaction. Lets users
-    // answer from the overview list without pressing Enter first.
-    const interaction = state.interactions[state.currentIndex];
-    if (interaction !== undefined) {
-        const matched = interaction.options.find((o) => o.shortcut === input);
-        if (matched !== undefined) {
-            if (interaction.multiSelect) {
-                toggleMulti(state, interaction, matched.id);
-            }
-            else {
-                submitOption(state, interaction, matched.id, undefined);
-            }
-            // Don't auto-advance the cursor — users may want to re-answer the same
-            // question. The response icon flips ✓ and they can j/k away when ready.
-            render();
-        }
-    }
+    else
+        return;
+    render();
 }
-// ── Item Review ──────────────────────────────────────────────────────────────
-function handleItemReview(input, key, state, render) {
-    const interaction = state.interactions[state.currentIndex];
+function handleItemReview(input, key, state, render, exit) {
+    const slot = state.slots[state.currentIndex];
+    if (slot === undefined) {
+        state.phase = 'overview';
+        render();
+        return;
+    }
+    const actions = slotActions(slot);
     if (input === 'n') {
         advanceItem(state, 1);
         render();
@@ -135,519 +55,288 @@ function handleItemReview(input, key, state, render) {
         render();
         return;
     }
-    // q / Esc step back to the deck overview (one level up from a card).
     if (input === 'q' || key.escape) {
-        state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
-        state.phase = 'overview';
-        render();
+        exit(false);
         return;
     }
-    // Space toggles the focused option for multi-select.
-    if (input === ' ' && interaction.multiSelect
-        && state.selectedAction < interaction.options.length) {
-        toggleMulti(state, interaction, interaction.options[state.selectedAction].id);
-        render();
-        return;
-    }
-    // Body scroll: u/d, PageUp/PageDown, or Ctrl+D / Ctrl+U (half-page), Ctrl+E / Ctrl+Y (line).
-    // Plain u/d exists because tmux configs commonly bind C-d/C-u for pane scroll
-    // and intercept them before they reach the app. Render clamps state.scrollOffset,
-    // so over-scroll past the bottom is harmless.
     if (input === 'd' || key.pageDown || (key.ctrl && (input === 'd' || input === 'e'))) {
-        state.scrollOffset = (state.scrollOffset ?? 0) + (input === 'e' ? 1 : 10);
+        state.scrollOffset += input === 'e' ? 1 : 10;
         render();
         return;
     }
     if (input === 'u' || key.pageUp || (key.ctrl && (input === 'u' || input === 'y'))) {
-        state.scrollOffset = Math.max(0, (state.scrollOffset ?? 0) - (input === 'y' ? 1 : 10));
+        state.scrollOffset = Math.max(0, state.scrollOffset - (input === 'y' ? 1 : 10));
         render();
         return;
     }
-    // Body pan: contextual, so h/l only claim the key while the visible body
-    // actually overflows its rectangle (a wide diagram) AND no option owns that
-    // shortcut. Otherwise they fall through to the option/action handling below.
-    if ((input === 'h' || input === 'l' || key.leftArrow || key.rightArrow)
-        && (state.hscrollMax ?? 0) > 0
-        && !interaction.options.some((o) => o.shortcut === input)) {
+    if ((input === 'h' || input === 'l' || key.leftArrow || key.rightArrow) && state.hscrollMax > 0 && !actions.some((a) => a.kind === 'select' && a.shortcut === input)) {
         panItemReview(state, input === 'h' || key.leftArrow ? -1 : 1);
         render();
         return;
     }
     if (input === 'j' || key.downArrow) {
-        const max = actionCount(interaction) - 1;
-        state.selectedAction = Math.min(state.selectedAction + 1, max);
+        state.selectedAction = Math.min(state.selectedAction + 1, Math.max(0, actions.length - 1));
         render();
         return;
     }
     if (input === 'k' || key.upArrow) {
-        state.selectedAction = Math.max(state.selectedAction - 1, 0);
-        render();
-        return;
-    }
-    handleInteractionAction(input, key, state, interaction, render);
-}
-function handleInteractionAction(input, key, state, interaction, render) {
-    const opts = interaction.options;
-    // Match by shortcut. Multi-select toggles (stay put); single-select submits.
-    const matched = opts.find((o) => o.shortcut === input);
-    if (matched !== undefined) {
-        if (interaction.multiSelect) {
-            toggleMulti(state, interaction, matched.id);
-            render();
-            return;
-        }
-        submitOption(state, interaction, matched.id, undefined);
-        advanceToNextUnanswered(state);
+        state.selectedAction = Math.max(0, state.selectedAction - 1);
         render();
         return;
     }
-    // Comment mode: allowFreetext + options exist.
-    //
-    // Single-select: pre-attach the focused option (the comment qualifies that
-    // pick). Multi-select: also pre-attach the focused option — the comment is
-    // saved under `optionComments[id]` (per-option note) and submitting
-    // auto-checks the option. From the [c] freetext row in multi-select,
-    // start with no attachment so the comment becomes the overall freetext.
-    if (input === 'c' && interaction.allowFreetext && opts.length > 0) {
-        const onOption = state.selectedAction < opts.length;
-        if (onOption) {
-            const optId = opts[state.selectedAction].id;
-            let prefill = '';
-            if (interaction.multiSelect) {
-                const existing = state.responses.get(interaction.id);
-                const prior = existing?.optionComments?.[optId];
-                if (typeof prior === 'string')
-                    prefill = prior;
-            }
-            state.inputMode = { kind: 'comment', buffer: prefill, cursor: [...prefill].length, selectedOptionId: optId };
-        }
-        else {
-            // On the [c] row in multi-select: pre-fill from existing overall freetext.
-            let prefill = '';
-            if (interaction.multiSelect) {
-                const existing = state.responses.get(interaction.id);
-                if (existing !== undefined && typeof existing.freetext === 'string') {
-                    prefill = existing.freetext;
-                }
-            }
-            state.inputMode = { kind: 'comment', buffer: prefill, cursor: [...prefill].length };
-        }
+    if (input === 'c' && terminalAnswerable(slot)) {
+        startComment(state, slot, actions);
         render();
         return;
     }
-    // Freetext-only: 'r' or enter opens input mode
-    if (interaction.allowFreetext && opts.length === 0) {
-        if (input === 'r' || key.return) {
-            const existing = state.responses.get(interaction.id);
-            const prefill = existing !== undefined && existing.freetext !== undefined ? existing.freetext : '';
-            state.inputMode = { kind: 'freetext', buffer: prefill, cursor: [...prefill].length };
-            render();
-            return;
-        }
-    }
-    // Enter on selected option row. Multi-select confirms the accumulated set
-    // and advances; single-select picks that one option.
-    if (key.return && state.selectedAction < opts.length) {
-        if (interaction.multiSelect) {
-            const checked = state.responses.get(interaction.id)?.selectedOptionIds ?? [];
-            if (checked.length === 0) {
-                // Accidental Enter with nothing toggled is a no-op: don't finalize or
-                // advance. A deliberate empty finish is still reachable via `q` →
-                // overview → finish (partial); freetext-only via the [c] row.
-                state.hint = 'Select at least one option (space to toggle), or q to skip';
-                render();
-                return;
-            }
-            commitMulti(state, interaction);
-            advanceToNextUnanswered(state);
-            render();
-            return;
-        }
-        const o = opts[state.selectedAction];
-        submitOption(state, interaction, o.id, undefined);
-        advanceToNextUnanswered(state);
+    const shortcut = actions.find((a) => a.kind === 'select' && a.shortcut === input);
+    if (shortcut?.kind === 'select') {
+        commitSelection(state, slot, shortcut, autoAdvances(slot, shortcut.mode));
         render();
+        if (autoAdvances(slot, shortcut.mode) && state.phase === 'final' && pageComplete(state))
+            exit(true);
         return;
     }
-    // Enter on the [c] row (allowFreetext + options exist)
-    if (key.return && state.selectedAction === opts.length
-        && interaction.allowFreetext && opts.length > 0) {
-        state.inputMode = { kind: 'comment', buffer: '', cursor: 0 };
+    if (input === ' ' && actions[state.selectedAction]?.kind === 'select') {
+        const action = actions[state.selectedAction];
+        commitSelection(state, slot, action, autoAdvances(slot, action.mode));
         render();
+        if (autoAdvances(slot, action.mode) && state.phase === 'final' && pageComplete(state))
+            exit(true);
         return;
     }
-}
-// ── Input Mode ───────────────────────────────────────────────────────────────
-function handleInputMode(input, key, state, render) {
-    const mode = state.inputMode;
-    if (key.escape) {
-        state.inputMode = null;
+    if (input === 'r' && actions.some((a) => a.kind === 'freetext')) {
+        const r = responseFor(slot, state.responses.get(slot.id));
+        state.inputMode = { kind: 'freetext', buffer: r.freetext ?? '', cursor: [...(r.freetext ?? '')].length };
         render();
         return;
     }
-    // Tab cycles attached option in comment mode: (none) → opt1 → opt2 → ... → (none)
-    if (key.tab && mode.kind === 'comment') {
-        const interaction = state.interactions[state.currentIndex];
-        const opts = interaction.options;
-        if (opts.length > 0) {
-            const cur = mode.selectedOptionId;
-            const curIdx = cur === undefined ? -1 : opts.findIndex((o) => o.id === cur);
-            const nextIdx = curIdx + 1; // -1 → 0, last → length (which we map to none)
-            if (nextIdx >= opts.length) {
-                delete mode.selectedOptionId;
-            }
-            else {
-                mode.selectedOptionId = opts[nextIdx].id;
-            }
-            render();
-        }
-        return;
-    }
-    if (key.pageDown) {
-        state.scrollOffset = (state.scrollOffset ?? 0) + 10;
+    if (input === 'e' && actions.some((a) => a.kind === 'edit')) {
+        const r = responseFor(slot, state.responses.get(slot.id));
+        state.inputMode = { kind: 'text', buffer: r.text, cursor: [...r.text].length };
         render();
         return;
     }
-    if (key.pageUp) {
-        state.scrollOffset = Math.max(0, (state.scrollOffset ?? 0) - 10);
-        render();
-        return;
-    }
-    if (key.downArrow) {
-        mode.cursor = verticalCursor(mode.buffer, mode.cursor, 1, inputWrapWidth(state));
-        render();
-        return;
-    }
-    if (key.upArrow) {
-        mode.cursor = verticalCursor(mode.buffer, mode.cursor, -1, inputWrapWidth(state));
+    if (input === 'a' && actions.some((a) => a.kind === 'accept')) {
+        setResponse(state, slot, { text: slot.config.initialText, edited: false, comments: commentsFor(state.responses.get(slot.id)) });
+        advanceToNextIncomplete(state);
         render();
         return;
     }
     if (key.return) {
-        const interaction = state.interactions[state.currentIndex];
-        const perOption = interaction.multiSelect === true
-            && mode.kind === 'comment'
-            && mode.selectedOptionId !== undefined;
-        if (perOption) {
-            // Per-option comment: save under optionComments[id], auto-check the
-            // option (idempotent), stay on this interaction so the human can comment
-            // on another option.
-            setOptionComment(state, interaction, mode.selectedOptionId, mode.buffer);
-            state.inputMode = null;
+        const action = actions[state.selectedAction];
+        if (action?.kind === 'freetext') {
+            const r = responseFor(slot, state.responses.get(slot.id));
+            state.inputMode = { kind: 'freetext', buffer: r.freetext ?? '', cursor: [...(r.freetext ?? '')].length };
             render();
             return;
         }
-        if (interaction.multiSelect) {
-            commitMulti(state, interaction, mode.buffer);
+        if (action?.kind === 'edit') {
+            const r = responseFor(slot, state.responses.get(slot.id));
+            state.inputMode = { kind: 'text', buffer: r.text, cursor: [...r.text].length };
+            render();
+            return;
         }
-        else {
-            const attached = mode.kind === 'comment' ? mode.selectedOptionId : undefined;
-            submitOption(state, interaction, attached, mode.buffer);
+        if (action?.kind === 'accept') {
+            setResponse(state, slot, { text: slot.config.initialText, edited: false, comments: commentsFor(state.responses.get(slot.id)) });
+            advanceToNextIncomplete(state);
+            render();
+            return;
         }
-        state.inputMode = null;
-        advanceToNextUnanswered(state);
-        render();
-        return;
-    }
-    // Newline-insert chord (ctrl+j / alt+enter) — distinct from key.return
-    // (submit), handled above.
-    if (key.newline) {
-        insertAtCursor(mode, '\n');
-        render();
-        return;
-    }
-    // ── Cursor motion ──────────────────────────────────────────────────────
-    if (key.leftArrow) {
-        mode.cursor = Math.max(0, mode.cursor - 1);
-        render();
-        return;
-    }
-    if (key.rightArrow) {
-        mode.cursor = Math.min([...mode.buffer].length, mode.cursor + 1);
-        render();
-        return;
-    }
-    if (key.wordLeft) {
-        mode.cursor = wordLeftIndex(mode.buffer, mode.cursor);
-        render();
-        return;
-    }
-    if (key.wordRight) {
-        mode.cursor = wordRightIndex(mode.buffer, mode.cursor);
-        render();
-        return;
-    }
-    if (key.home || (key.ctrl && input === 'a')) {
-        mode.cursor = lineStart(mode.buffer, mode.cursor);
-        render();
-        return;
-    }
-    if (key.end || (key.ctrl && input === 'e')) {
-        mode.cursor = lineEnd(mode.buffer, mode.cursor);
-        render();
-        return;
-    }
-    // ── Edits ───────────────────────────────────────────────────────────────
-    if (key.backspace && key.meta) {
-        deleteWordAtCursor(mode);
+        if (slot.kind === 'table' && terminalAnswerable(slot)) {
+            const r = responseFor(slot, state.responses.get(slot.id));
+            setResponse(state, slot, r);
+            advanceToNextIncomplete(state);
+            render();
+            return;
+        }
+        if (slotAnswered(state, slot)) {
+            advanceToNextIncomplete(state);
+            render();
+            return;
+        }
+        if (isResponseBearingSlot(slot)) {
+            state.hint = terminalAnswerable(slot) ? 'Select at least one option (space to toggle), or q to go back' : 'This must be answered in Northlight';
+            render();
+            return;
+        }
+        advanceItem(state, 1);
         render();
-        return;
     }
-    // Ctrl-U: delete from line start to cursor (readline "unix-line-discard").
-    // iTerm2 maps Cmd+Backspace to a bare 0x15, which arrives here as ctrl+'u'.
-    if (key.ctrl && input === 'u') {
-        deleteToLineStart(mode);
+}
+function handleFinal(input, key, state, render, exit) {
+    if (input === 'q' || key.escape) {
+        state.phase = state.slots.length === 1 ? 'item-review' : 'overview';
+        state.scrollOffset = 0;
         render();
         return;
     }
-    if (key.del) {
-        deleteAtCursor(mode);
-        render();
+    if (key.return && (pageComplete(state) || !state.manifest.slots.some(isResponseBearingSlot)))
+        exit(true);
+}
+function resetItem(state) { state.selectedAction = 0; state.scrollOffset = 0; state.hscrollOffset = 0; state.hscrollMax = 0; }
+function advanceItem(state, delta) {
+    const next = state.currentIndex + delta;
+    if (next < 0) {
+        state.phase = state.slots.length > 1 ? 'overview' : 'item-review';
         return;
     }
-    if (key.backspace) {
-        backspaceAtCursor(mode);
-        render();
+    if (next >= state.slots.length) {
+        state.phase = 'final';
+        state.scrollOffset = 0;
         return;
     }
-    // Typed input / paste. Bracketed-paste markers and other control chars are
-    // stripped, but \n (0x0A) is preserved so pasted newlines land as real
-    // newlines in the buffer instead of vanishing (CRLF is normalized to LF).
-    const cleaned = input
-        .replace(/\x1b\[20[01]~/g, '')
-        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
-        .replace(/\r\n?/g, '\n')
-        .replace(/[\x00-\x09\x0B-\x1F\x7F]/g, '');
-    if (cleaned.length > 0) {
-        insertAtCursor(mode, cleaned);
-        render();
-    }
-}
-function insertAtCursor(mode, text) {
-    const chars = [...mode.buffer];
-    const insert = [...text];
-    chars.splice(mode.cursor, 0, ...insert);
-    mode.buffer = chars.join('');
-    mode.cursor += insert.length;
-}
-function backspaceAtCursor(mode) {
-    if (mode.cursor <= 0)
-        return;
-    const chars = [...mode.buffer];
-    chars.splice(mode.cursor - 1, 1);
-    mode.buffer = chars.join('');
-    mode.cursor -= 1;
-}
-function deleteAtCursor(mode) {
-    const chars = [...mode.buffer];
-    if (mode.cursor >= chars.length)
-        return;
-    chars.splice(mode.cursor, 1);
-    mode.buffer = chars.join('');
-}
-function deleteWordAtCursor(mode) {
-    const start = wordLeftIndex(mode.buffer, mode.cursor);
-    const chars = [...mode.buffer];
-    chars.splice(start, mode.cursor - start);
-    mode.buffer = chars.join('');
-    mode.cursor = start;
+    state.currentIndex = next;
+    resetItem(state);
 }
-function deleteToLineStart(mode) {
-    const start = lineStart(mode.buffer, mode.cursor);
-    const chars = [...mode.buffer];
-    chars.splice(start, mode.cursor - start);
-    mode.buffer = chars.join('');
-    mode.cursor = start;
+function advanceToNextIncomplete(state) {
+    for (let i = state.currentIndex + 1; i < state.slots.length; i++) {
+        const slot = state.slots[i];
+        if (isResponseBearingSlot(slot) && !slotAnswered(state, slot)) {
+            state.currentIndex = i;
+            resetItem(state);
+            return;
+        }
+    }
+    state.phase = 'final';
+    state.scrollOffset = 0;
 }
-/** Skip whitespace backward from `cursor`, then skip the non-whitespace word
- *  before it — lands on the word's start (readline alt-b / ctrl+left). */
-function wordLeftIndex(buffer, cursor) {
-    const chars = [...buffer];
-    let i = Math.min(cursor, chars.length);
-    while (i > 0 && /\s/.test(chars[i - 1]))
-        i--;
-    while (i > 0 && !/\s/.test(chars[i - 1]))
-        i--;
-    return i;
+function responseFor(slot, existing) {
+    if (existing !== undefined)
+        return existing;
+    if (slot.kind === 'options')
+        return { selectedOptionIds: [], comments: [] };
+    if (slot.kind === 'cards')
+        return { selectedCardIds: [], comments: [] };
+    if (slot.kind === 'table')
+        return { selectedRowIds: [], selectedColumnIds: [], comments: [] };
+    if (slot.kind === 'text')
+        return { text: slot.config.initialText, edited: false, comments: [] };
+    return {};
 }
-/** Skip whitespace forward from `cursor`, then skip the non-whitespace word
- *  after it — lands just past the word's end (readline alt-f / ctrl+right). */
-function wordRightIndex(buffer, cursor) {
-    const chars = [...buffer];
-    let i = Math.min(cursor, chars.length);
-    while (i < chars.length && /\s/.test(chars[i]))
-        i++;
-    while (i < chars.length && !/\s/.test(chars[i]))
-        i++;
-    return i;
+function commentsFor(response) { return [...((response?.comments) ?? [])]; }
+function setResponse(state, slot, response) { if (slot.id === undefined)
+    return; state.responses.set(slot.id, response); state.persist?.(); }
+function commitSelection(state, slot, action, advance) {
+    const response = responseFor(slot, state.responses.get(slot.id));
+    if (slot.kind === 'options') {
+        const r = response;
+        const ids = toggleIds(r.selectedOptionIds, action.id, action.mode);
+        setResponse(state, slot, { ...r, selectedOptionIds: ids });
+    }
+    else if (slot.kind === 'cards') {
+        const r = response;
+        setResponse(state, slot, { ...r, selectedCardIds: toggleIds(r.selectedCardIds, action.id, action.mode) });
+    }
+    else if (slot.kind === 'table') {
+        const r = response;
+        if (action.group === 'row')
+            setResponse(state, slot, { ...r, selectedRowIds: toggleIds(r.selectedRowIds, action.id, action.mode) });
+        else
+            setResponse(state, slot, { ...r, selectedColumnIds: toggleIds(r.selectedColumnIds, action.id, action.mode) });
+    }
+    if (advance)
+        advanceToNextIncomplete(state);
 }
-/** Index just after the previous `\n` (or 0), i.e. the start of the current
- *  visual line — the multiline analog of ctrl+a/home. */
-function lineStart(buffer, cursor) {
-    const chars = [...buffer];
-    let i = Math.min(cursor, chars.length);
-    while (i > 0 && chars[i - 1] !== '\n')
-        i--;
-    return i;
+function toggleIds(ids, id, mode) { if (mode === 'single')
+    return [id]; return ids.includes(id) ? ids.filter((x) => x !== id) : [...ids, id]; }
+function anchorFor(action) {
+    if (action?.kind !== 'select')
+        return { kind: 'whole' };
+    if (action.group === 'option')
+        return { kind: 'option', optionId: action.id };
+    if (action.group === 'card')
+        return { kind: 'card', cardId: action.id };
+    if (action.group === 'row')
+        return { kind: 'row', rowId: action.id };
+    return { kind: 'column', columnId: action.id };
 }
-/** Index at the next `\n` (or end of buffer) — the multiline analog of
- *  ctrl+e/end. */
-function lineEnd(buffer, cursor) {
-    const chars = [...buffer];
-    let i = Math.min(cursor, chars.length);
-    while (i < chars.length && chars[i] !== '\n')
-        i++;
-    return i;
+function startComment(state, slot, actions) {
+    const anchor = anchorFor(actions[state.selectedAction]);
+    const comments = commentsFor(slot.id === undefined ? undefined : state.responses.get(slot.id));
+    const prior = comments.find((c) => c.id === commentIdFor(anchor))?.text ?? '';
+    state.inputMode = { kind: 'comment', buffer: prior, cursor: [...prior].length, anchor };
 }
-/** Width the input buffer is wrapped to on screen — kept in step with the
- *  `renderInputBuffer(..., maxW - 1)` call in the item-review layout, so up/down
- *  step by the rows the human sees rather than by logical lines. */
-function inputWrapWidth(state) {
-    return Math.max(10, Math.min(state.wrapWidth - 4, 120) - 1);
+function cycleCommentAnchor(state) {
+    if (state.inputMode?.kind !== 'comment')
+        return;
+    const slot = state.slots[state.currentIndex];
+    const anchors = [{ kind: 'whole' }, ...slotActions(slot).filter((a) => a.kind === 'select').map(anchorFor)];
+    const current = commentIdFor(state.inputMode.anchor ?? { kind: 'whole' });
+    const index = anchors.findIndex((a) => commentIdFor(a) === current);
+    const anchor = anchors[(index + 1) % anchors.length];
+    const prior = commentsFor(slot.id === undefined ? undefined : state.responses.get(slot.id)).find((c) => c.id === commentIdFor(anchor))?.text ?? '';
+    state.inputMode = { kind: 'comment', anchor, buffer: prior, cursor: [...prior].length };
 }
-// ── Final ────────────────────────────────────────────────────────────────────
-function handleFinal(input, key, state, render, exit) {
-    if (key.return) {
-        exit();
-    }
-    else if (key.escape) {
-        state.phase = 'overview';
+function handleInputMode(input, key, state, render) {
+    const mode = state.inputMode;
+    if (key.escape) {
+        state.inputMode = null;
         render();
+        return;
     }
-    else if (input === 'p') {
-        state.phase = 'item-review';
-        state.currentIndex = state.interactions.length - 1;
+    if (key.tab && mode.kind === 'comment') {
+        cycleCommentAnchor(state);
         render();
-    }
-}
-// ── Helpers ──────────────────────────────────────────────────────────────────
-function advanceItem(state, direction) {
-    const next = state.currentIndex + direction;
-    if (next < 0)
         return;
-    if (next >= state.interactions.length) {
-        state.phase = 'final';
+    }
+    if (key.return) {
+        commitInput(state);
+        render();
         return;
     }
-    state.currentIndex = next;
-    state.selectedAction = 0;
-    state.bodyMode = 'question';
-    state.scrollOffset = 0;
-    state.bodyScrollOffsets = { question: 0 };
-    state.hscrollOffset = 0;
-}
-/**
- * Move to the next interaction WITHOUT a response, falling through to the
- * final phase if every following interaction is already answered (whether
- * user-answered or `preAnswered`-seeded). Used by all post-submit advance
- * sites so the human flies through pre-approved items by hitting Enter; raw
- * `n`/`p` still step one at a time via `advanceItem`.
- */
-function advanceToNextUnanswered(state) {
-    let next = state.currentIndex + 1;
-    while (next < state.interactions.length && state.responses.has(state.interactions[next].id)) {
-        next++;
-    }
-    if (next >= state.interactions.length) {
-        state.phase = 'final';
+    if (key.newline) {
+        insert(mode, '\n');
+        render();
         return;
     }
-    state.currentIndex = next;
-    state.selectedAction = 0;
-    state.bodyMode = 'question';
-    state.scrollOffset = 0;
-    state.bodyScrollOffsets = { question: 0 };
-    state.hscrollOffset = 0;
-}
-function actionCount(interaction) {
-    return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);
-}
-function submitOption(state, interaction, selectedOptionId, freetext) {
-    const response = { id: interaction.id };
-    if (selectedOptionId !== undefined)
-        response.selectedOptionId = selectedOptionId;
-    if (freetext !== undefined)
-        response.freetext = freetext;
-    state.responses.set(interaction.id, response);
-    // Explicit user submission overrides any preAnswered seed — flip the icon
-    // from "previously answered" to user-answered.
-    state.preAnsweredIds.delete(interaction.id);
-    state.persist?.();
-}
-// ── Multi-select ─────────────────────────────────────────────────────────────
-// Toggle/commit write progressively into state.responses (mirrors single-select
-// submitOption immediacy); Enter just confirms the accumulated set + advances.
-function toggleMulti(state, interaction, optionId) {
-    const existing = state.responses.get(interaction.id);
-    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
-        ? existing.selectedOptionIds
-        : [];
-    const set = new Set(priorIds);
-    if (set.has(optionId))
-        set.delete(optionId);
-    else
-        set.add(optionId);
-    const response = { id: interaction.id, selectedOptionIds: [...set] };
-    if (existing !== undefined && existing.freetext !== undefined)
-        response.freetext = existing.freetext;
-    if (existing !== undefined && existing.optionComments !== undefined) {
-        response.optionComments = { ...existing.optionComments };
-    }
-    state.responses.set(interaction.id, response);
-    // User edited the checked set — no longer a passive carry-over.
-    state.preAnsweredIds.delete(interaction.id);
-    state.persist?.();
-}
-/** Ensure a (possibly empty) response exists so the interaction counts as
- *  answered, optionally setting/replacing freetext. */
-function commitMulti(state, interaction, freetext) {
-    const existing = state.responses.get(interaction.id);
-    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
-        ? existing.selectedOptionIds
-        : [];
-    const response = {
-        id: interaction.id,
-        selectedOptionIds: [...priorIds],
-    };
-    let ft;
-    if (freetext !== undefined)
-        ft = freetext;
-    else if (existing !== undefined)
-        ft = existing.freetext;
-    if (ft !== undefined)
-        response.freetext = ft;
-    if (existing !== undefined && existing.optionComments !== undefined) {
-        response.optionComments = { ...existing.optionComments };
-    }
-    state.responses.set(interaction.id, response);
-    // Explicit confirm overrides any preAnswered seed.
-    state.preAnsweredIds.delete(interaction.id);
-    state.persist?.();
+    if (key.leftArrow)
+        mode.cursor = Math.max(0, mode.cursor - 1);
+    else if (key.rightArrow)
+        mode.cursor = Math.min([...mode.buffer].length, mode.cursor + 1);
+    else if (key.upArrow)
+        mode.cursor = verticalCursor(mode.buffer, mode.cursor, -1, inputWrapWidth(state));
+    else if (key.downArrow)
+        mode.cursor = verticalCursor(mode.buffer, mode.cursor, 1, inputWrapWidth(state));
+    else if (key.home || (key.ctrl && input === 'a'))
+        mode.cursor = lineStart(mode.buffer, mode.cursor);
+    else if (key.end || (key.ctrl && input === 'e'))
+        mode.cursor = lineEnd(mode.buffer, mode.cursor);
+    else if (key.backspace || input === '\x7f')
+        backspace(mode);
+    else if (key.del || (key.ctrl && input === 'd'))
+        del(mode);
+    else if (input.length > 0 && !key.ctrl && !key.meta)
+        insert(mode, input);
+    render();
 }
-/**
- * Multi-select per-option comment: write `comment` to optionComments[optionId]
- * and auto-check the option. Empty comment still records the entry (the user
- * committed deliberately via Enter; Esc cancels without write).
- */
-function setOptionComment(state, interaction, optionId, comment) {
-    const existing = state.responses.get(interaction.id);
-    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
-        ? existing.selectedOptionIds
-        : [];
-    const set = new Set(priorIds);
-    set.add(optionId);
-    const priorComments = existing !== undefined && existing.optionComments !== undefined
-        ? existing.optionComments
-        : {};
-    const nextComments = { ...priorComments, [optionId]: comment };
-    const response = {
-        id: interaction.id,
-        selectedOptionIds: [...set],
-        optionComments: nextComments,
-    };
-    if (existing !== undefined && existing.freetext !== undefined)
-        response.freetext = existing.freetext;
-    state.responses.set(interaction.id, response);
-    state.preAnsweredIds.delete(interaction.id);
-    state.persist?.();
+function commitInput(state) {
+    const mode = state.inputMode;
+    const slot = state.slots[state.currentIndex];
+    const response = responseFor(slot, slot.id === undefined ? undefined : state.responses.get(slot.id));
+    if (mode.kind === 'comment') {
+        const anchor = mode.anchor ?? { kind: 'whole' };
+        const id = commentIdFor(anchor);
+        const comments = commentsFor(response).filter((c) => c.id !== id);
+        if (mode.buffer.trim() !== '')
+            comments.push({ id, anchor, text: mode.buffer });
+        setResponse(state, slot, { ...response, comments });
+    }
+    else if (mode.kind === 'freetext') {
+        setResponse(state, slot, { ...response, freetext: mode.buffer });
+        advanceToNextIncomplete(state);
+    }
+    else {
+        setResponse(state, slot, { text: mode.buffer, edited: mode.buffer !== slot.config.initialText, comments: commentsFor(response) });
+        advanceToNextIncomplete(state);
+    }
+    state.inputMode = null;
 }
+function insert(mode, text) { const chars = [...mode.buffer]; chars.splice(mode.cursor, 0, ...text); mode.buffer = chars.join(''); mode.cursor += [...text].length; }
+function backspace(mode) { if (mode.cursor === 0)
+    return; const chars = [...mode.buffer]; chars.splice(mode.cursor - 1, 1); mode.buffer = chars.join(''); mode.cursor--; }
+function del(mode) { const chars = [...mode.buffer]; if (mode.cursor >= chars.length)
+    return; chars.splice(mode.cursor, 1); mode.buffer = chars.join(''); }
+function lineStart(buffer, cursor) { const before = [...buffer].slice(0, cursor).join(''); const i = before.lastIndexOf('\n'); return i < 0 ? 0 : [...before.slice(0, i + 1)].length; }
+function lineEnd(buffer, cursor) { const chars = [...buffer]; const i = chars.slice(cursor).indexOf('\n'); return i < 0 ? chars.length : cursor + i; }
+function inputWrapWidth(state) { return Math.max(10, Math.min(state.wrapWidth - 8, 116)); }