mixdog 1.2.2 → 1.2.3

package/src/tui/app/slash-dispatch/session-commands.mjs

@@ -1,8 +1,9 @@
 // slash-dispatch/session-commands.mjs
 // Slash commands that act on the session itself: clear/new, compact, goal,
-// resume, inherit, doctor and quit. Busy guards refuse the destructive ones
+// resume, fork (alias inherit), doctor and quit. Busy guards refuse the destructive ones
 // while a turn or session command is running.
 import { presentErrorText } from '../../../runtime/shared/err-text.mjs';
+import { BTW_USAGE_HINT } from '../btw-controller.mjs';
 
 function compactFailureNotice(error) {
   if (error == null || String(error).trim() === '') return 'Compact failed.';
@@ -63,6 +64,18 @@ export const sessionCommands = {
     return true;
   },
 
+  // Side question: allowed mid-turn; never queued, steered, or interrupting.
+  btw(ctx, arg) {
+    const { store, deps } = ctx;
+    const question = String(arg || '').trim();
+    if (!question) {
+      store.pushNotice(BTW_USAGE_HINT, 'warn');
+      return true;
+    }
+    deps.btw.ask(question);
+    return true;
+  },
+
   goal(ctx, arg) {
     const { store } = ctx;
     void Promise.resolve(store.goalControl?.({ command: arg }))
@@ -91,18 +104,18 @@ export const sessionCommands = {
     return true;
   },
 
-  inherit(ctx) {
+  fork(ctx, _arg, rawName) {
     const { state, store } = ctx;
-    if (state.busy) return refuseWhileBusy(store, 'inherit');
+    if (state.busy) return refuseWhileBusy(store, rawName === 'inherit' ? 'inherit' : 'fork');
     void Promise.resolve(store.inheritSession?.())
       .then((result) => {
         if (!result) {
-          store.pushNotice('nothing to inherit', 'warn');
+          store.pushNotice('nothing to fork', 'warn');
           return;
         }
-        store.pushNotice(`inherited ${result.messages} messages into ${result.sessionId}`, 'info');
+        store.pushNotice(`forked ${result.messages} messages into ${result.sessionId}`, 'info');
       })
-      .catch((e) => store.pushNotice(`inherit failed: ${e?.message || e}`, 'error'));
+      .catch((e) => store.pushNotice(`fork failed: ${e?.message || e}`, 'error'));
     return true;
   },
 

package/src/tui/app/use-global-key-input/approval-shortcut.mjs

@@ -0,0 +1,12 @@
+// Global tool-approval shortcuts: Esc/d/n deny, a/y approve. Returns the
+// decision to resolve with, or null. Question approvals (ask_user) are
+// answered only inside QuestionPanel, so typed letters and Esc never reach here.
+export function approvalShortcutDecision(toolApproval, input, key) {
+  if (!toolApproval || toolApproval.kind === 'question') return null;
+  const value = String(input || '')
+    .trim()
+    .toLowerCase();
+  if (key.escape || value === 'd' || value === 'n') return { approved: false, reason: 'denied by user' };
+  if (value === 'a' || value === 'y') return { approved: true, reason: 'approved by user' };
+  return null;
+}

package/src/tui/app/use-global-key-input.mjs

@@ -8,6 +8,7 @@
 import { useInput } from 'ink';
 import { overlayBlocksGlobalTranscriptScroll } from './slash-commands.mjs';
 import { copyActiveSelection } from './use-global-key-input/copy-first.mjs';
+import { approvalShortcutDecision } from './use-global-key-input/approval-shortcut.mjs';
 import { decodeSelectionMoveChord } from './use-global-key-input/shift-arrow.mjs';
 export function useGlobalKeyInput({
   store,
@@ -43,18 +44,10 @@ export function useGlobalKeyInput({
       // settle it through the same path a real release takes, before any branch
       // below reads the selection.
       settleStuckDrag?.();
-      if (toolApproval) {
-        const value = String(input || '')
-          .trim()
-          .toLowerCase();
-        if (key.escape || value === 'd' || value === 'n') {
-          store.resolveToolApproval?.(toolApproval.id, { approved: false, reason: 'denied by user' });
-          return;
-        }
-        if (value === 'a' || value === 'y') {
-          store.resolveToolApproval?.(toolApproval.id, { approved: true, reason: 'approved by user' });
-          return;
-        }
+      const decision = approvalShortcutDecision(toolApproval, input, key);
+      if (decision) {
+        store.resolveToolApproval?.(toolApproval.id, decision);
+        return;
       }
       if (key.ctrl && (input === 'c' || input === 'C')) {
         copyActiveSelection({ promptSelectionRef, dragRef, copySelection, showSelectionCopyHint });

package/src/tui/app/use-prompt-handlers.mjs

@@ -36,6 +36,8 @@ export function usePromptHandlers({
   usagePanel,
   closeUsagePanel,
   contextPanel,
+  btwPanel,
+  closeBtwPanel,
   // paste-attachment helpers (owned by App, threaded in explicitly)
   installPastedImages,
   clearPastedImagesSnapshot,
@@ -72,6 +74,13 @@ export function usePromptHandlers({
         return true;
       }
 
+      // /btw side panel: Esc closes it (cancelling a pending ask) before the
+      // turn interrupt / draft handling sees the key.
+      if (btwPanel) {
+        closeBtwPanel();
+        return true;
+      }
+
       if (meta.phase === 'clear-arm') {
         showPromptHint('Esc again to clear', 'plain', PROMPT_ESCAPE_HINT_TIMEOUT_MS);
         return true;
@@ -107,6 +116,8 @@ export function usePromptHandlers({
     },
     [
       contextPanel,
+      btwPanel,
+      closeBtwPanel,
       surface,
       usagePanel,
       closeUsagePanel,

package/src/tui/components/BtwPanel.jsx

@@ -0,0 +1,53 @@
+/**
+ * components/BtwPanel.jsx — transient `/btw` side-question panel above the prompt.
+ */
+import { useEffect, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { theme } from '../theme.mjs';
+import { Markdown } from './Markdown.jsx';
+import { BTW_CHROME_ROWS, btwContentRows, btwScrollMax, btwScrollOffset } from '../app/btw-controller.mjs';
+
+export function BtwPanel({ panel, columns = 80, panelRows, themeEpoch = 0 }) {
+  const bodyRows = Math.max(1, (panelRows ?? BTW_CHROME_ROWS + 1) - BTW_CHROME_ROWS);
+  const total = btwContentRows(panel, columns);
+  const maxOffset = btwScrollMax(total, bodyRows);
+  const [offset, setOffset] = useState(0);
+  const top = Math.min(offset, maxOffset);
+  const scrollable = maxOffset > 0;
+
+  // A new question or a settled answer starts from the top.
+  useEffect(() => {
+    setOffset(0);
+  }, [panel.question, panel.status]);
+
+  useInput((_input, key) => {
+    if (!scrollable || (!key.pageUp && !key.pageDown)) return;
+    setOffset((current) => btwScrollOffset(key, current, bodyRows, total));
+  });
+
+  let body;
+  if (panel.status === 'pending') body = <Text color={theme.inactive}>answering… (Esc to cancel)</Text>;
+  else if (panel.status === 'error') body = <Text color={theme.error}>{panel.text}</Text>;
+  else
+    body = (
+      <Markdown themeEpoch={themeEpoch} columns={columns}>
+        {panel.text}
+      </Markdown>
+    );
+  return (
+    <Box flexDirection="column" flexShrink={0} width="100%">
+      <Box borderStyle="round" borderColor={theme.promptBorder} paddingX={1} width="100%" flexDirection="column">
+        <Text color={theme.panelTitle} wrap="truncate-end">{`btw · ${panel.question}`}</Text>
+        <Box flexDirection="column" height={bodyRows} overflow="hidden">
+          <Box flexDirection="column" flexShrink={0} marginTop={-top}>
+            {body}
+          </Box>
+        </Box>
+        <Text color={theme.inactive}>
+          {scrollable ? `PgUp/PgDn scroll (${top + 1}-${Math.min(total, top + bodyRows)}/${total}) · ` : ''}
+          Esc to close · not saved to the conversation
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/src/tui/components/QuestionPanel.jsx

@@ -0,0 +1,275 @@
+/**
+ * components/QuestionPanel.jsx — ask_user multiple-choice panel.
+ *
+ * Same round-border chrome as Picker. Digits/↑↓ choose, Space toggles
+ * (multi-select), ←/→ switch questions, Enter confirms the current question
+ * (and sends on the last), Esc dismisses. The last row is an inline text
+ * input; while typing, every key belongs to the input (no slash commands).
+ */
+import { useRef, useState } from 'react';
+import { Box, Text, useInput, usePaste, useStdin } from 'ink';
+import stringWidth from 'string-width';
+import { theme } from '../theme.mjs';
+import { truncatePanelText, padPanelCells } from './panel-cell-text.mjs';
+import { isCsiPrivateReply } from './prompt-input/key-signals.mjs';
+import {
+  CUSTOM_LABEL,
+  appendCapped,
+  answerFor,
+  buildAnswers,
+  initialCursor,
+  optionLayout,
+  planQuestionView,
+  questionHelp,
+} from './question-panel-model.mjs';
+
+const MAX_TAB_CELLS = 10;
+
+function cleanTyped(value) {
+  return String(value ?? '')
+    .replace(/\x1b\[[\d;?<]*[A-Za-z~]/g, '')
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/[\x00-\x1f\x7f]/g, '');
+}
+
+export function QuestionPanel({ questions, columns = 80, rows, onSubmit, onDismiss }) {
+  const { isRawModeSupported } = useStdin();
+  const [state, setState] = useState(() => ({
+    qi: 0,
+    cursors: questions.map(initialCursor),
+    drafts: questions.map(() => ({ selected: [], text: '' })),
+    typing: false,
+    buf: '',
+  }));
+  const ref = useRef(state);
+  ref.current = state;
+  const commit = (next) => {
+    ref.current = next;
+    setState(next);
+  };
+  const last = questions.length - 1;
+
+  const withDraft = (s, qi, patch) => ({
+    ...s,
+    drafts: s.drafts.map((d, i) => (i === qi ? { ...d, ...patch } : d)),
+  });
+
+  // Confirm the current question and advance (or send on the last one).
+  const advance = (s) => {
+    if (s.qi >= last) {
+      onSubmit(buildAnswers(questions, s.drafts));
+      return;
+    }
+    commit({ ...s, qi: s.qi + 1, typing: false, buf: '' });
+  };
+
+  const typeInto = (input) => {
+    const s = ref.current;
+    const text = cleanTyped(input);
+    if (text) commit({ ...s, buf: appendCapped(s.buf, text) });
+  };
+
+  usePaste((text) => {
+    if (ref.current.typing) typeInto(text);
+  }, { isActive: isRawModeSupported });
+
+  useInput(
+    (input, key) => {
+      const s = ref.current;
+      const raw = String(input ?? '');
+      if (/(?:\x1b)?\[<\d+;\d+;\d+[Mm]/.test(raw) || isCsiPrivateReply(raw)) return;
+      const question = questions[s.qi];
+      const n = question.options.length;
+      const multi = question.multi_select === true;
+
+      if (s.typing) {
+        if (key.escape) return commit({ ...s, typing: false, buf: '' });
+        if (key.return) {
+          const text = s.buf.trim();
+          const draft = s.drafts[s.qi];
+          const next = withDraft(s, s.qi, { text, selected: multi ? draft.selected : [] });
+          if (text) return advance({ ...next, typing: false, buf: '' });
+          return commit({ ...next, typing: false, buf: '' });
+        }
+        if (key.backspace || key.delete) return commit({ ...s, buf: Array.from(s.buf).slice(0, -1).join('') });
+        if (key.ctrl || key.meta || key.upArrow || key.downArrow || key.leftArrow || key.rightArrow || key.tab) return;
+        return typeInto(raw);
+      }
+
+      if (key.escape) return onDismiss();
+      const setCursor = (cursor) => commit({ ...s, cursors: s.cursors.map((c, i) => (i === s.qi ? cursor : c)) });
+      const choose = (idx, toggle) => {
+        const draft = s.drafts[s.qi];
+        let selected;
+        if (multi && toggle) {
+          selected = draft.selected.includes(idx) ? draft.selected.filter((i) => i !== idx) : [...draft.selected, idx];
+        } else {
+          selected = multi ? draft.selected : [idx];
+        }
+        const cursors = s.cursors.map((c, i) => (i === s.qi ? idx : c));
+        commit({ ...withDraft(s, s.qi, { selected, text: multi ? draft.text : '' }), cursors });
+      };
+      const cursor = s.cursors[s.qi];
+      if (key.upArrow) return setCursor((cursor - 1 + n + 1) % (n + 1));
+      if (key.downArrow) return setCursor((cursor + 1) % (n + 1));
+      if (key.leftArrow || key.rightArrow) {
+        const qi = Math.max(0, Math.min(last, s.qi + (key.leftArrow ? -1 : 1)));
+        return commit({ ...s, qi });
+      }
+      if (key.return) {
+        if (cursor === n) return commit({ ...s, typing: true, buf: s.drafts[s.qi].text });
+        const draft = s.drafts[s.qi];
+        let next = s;
+        if (!multi) next = withDraft(s, s.qi, { selected: [cursor], text: '' });
+        else if (draft.selected.length === 0 && !draft.text.trim()) next = withDraft(s, s.qi, { selected: [cursor] });
+        return advance(next);
+      }
+      if (raw === ' ' && !key.ctrl && !key.meta) {
+        if (cursor < n) choose(cursor, true);
+        return;
+      }
+      if (/^[1-9]$/.test(raw)) {
+        const idx = Number(raw) - 1;
+        if (idx < n) choose(idx, true);
+        else if (idx === n) setCursor(n);
+      }
+    },
+    { isActive: isRawModeSupported }
+  );
+
+  const question = questions[state.qi];
+  const multi = question.multi_select === true;
+  const layout = optionLayout(question, columns);
+  const n = question.options.length;
+  const cursor = state.cursors[state.qi];
+  const draft = state.drafts[state.qi];
+  const avail = layout.avail;
+
+  const title = questions.length > 1 ? `Question ${state.qi + 1}/${questions.length}` : 'Question';
+  const tabs =
+    questions.length > 1
+      ? questions.map((q, i) => ({
+          text: truncatePanelText(String(q.header || `Q${i + 1}`), MAX_TAB_CELLS),
+          answered: answerFor(q, state.drafts[i]) !== null,
+          current: i === state.qi,
+        }))
+      : [];
+
+  const indexText = (i) => padPanelCells(`${i + 1}.`, layout.indexCells - 1) + ' ';
+  const renderLine = (selected, children, key) => {
+    const text = selected ? { backgroundColor: theme.selectionBackground, color: theme.selectionText } : {};
+    return (
+      <Text key={key} {...text} wrap="truncate">
+        {children}
+      </Text>
+    );
+  };
+
+  const plan = planQuestionView(question, columns, rows ?? Infinity, cursor);
+  const out = [];
+  const optionRow = (i) => {
+    const row = layout.rows[i];
+    const selected = i === cursor;
+    const checked = draft.selected.includes(i);
+    const lead = `${selected ? '› ' : '  '}${indexText(i)}`;
+    const fill = ' '.repeat(Math.max(0, avail - layout.prefixCells - stringWidth(row.label + row.suffix + row.detail)));
+    out.push(
+      renderLine(
+        selected,
+        <>
+          {lead}
+          {multi ? (
+            <Text color={selected ? theme.selectionText : checked ? theme.success : undefined}>
+              {checked ? '[x] ' : '[ ] '}
+            </Text>
+          ) : null}
+          {row.label}
+          {row.suffix ? <Text color={selected ? theme.selectionText : theme.suggestion}>{row.suffix}</Text> : null}
+          {row.detail ? <Text color={selected ? theme.selectionText : theme.subtle}>{row.detail}</Text> : null}
+          {selected ? fill : ''}
+        </>,
+        `o${i}`
+      )
+    );
+  };
+
+  const customSelected = cursor === n;
+  const customLead = `${customSelected ? '› ' : '  '}${indexText(n)}`;
+  const markerPad = multi ? '    ' : '';
+  let customBody;
+  if (state.typing) {
+    const room = Math.max(1, avail - stringWidth(customLead) - stringWidth(markerPad) - 1);
+    let shown = Array.from(state.buf).slice(-room).join('');
+    while (stringWidth(shown) > room) shown = Array.from(shown).slice(1).join('');
+    customBody = `${shown}▌`;
+  } else if (draft.text) {
+    customBody = truncatePanelText(draft.text, Math.max(1, avail - stringWidth(customLead) - stringWidth(markerPad)));
+  } else {
+    customBody = CUSTOM_LABEL;
+  }
+  const customColor = customSelected ? theme.selectionText : draft.text && !state.typing ? theme.text : theme.inactive;
+  const customRow = () =>
+    renderLine(
+      customSelected,
+      <>
+        {customLead}
+        {markerPad}
+        <Text color={state.typing ? undefined : customColor}>{customBody}</Text>
+        {customSelected ? ' '.repeat(Math.max(0, avail - stringWidth(customLead + markerPad + customBody))) : ''}
+      </>,
+      'custom'
+    );
+
+  const moreRow = (key, text) => (
+    <Text key={key} color={theme.subtle} wrap="truncate">
+      {`    ${text}`}
+    </Text>
+  );
+  if (plan.above > 0) out.push(moreRow('above', `↑ ${plan.above} more`));
+  for (const item of plan.items) {
+    if (item.index === n) out.push(customRow());
+    else optionRow(item.index);
+  }
+  if (plan.below > 0) out.push(moreRow('below', `↓ ${plan.below} more`));
+
+  const help = questionHelp({ multi, typing: state.typing, last: state.qi >= last, count: n, questionCount: questions.length });
+
+  return (
+    <Box flexDirection="column" flexShrink={0} width="100%">
+      <Box flexDirection="column" borderStyle="round" borderColor={theme.promptBorder} paddingX={1} width="100%">
+        <Box flexDirection="row" justifyContent="space-between">
+          <Box flexShrink={1}>
+            <Text wrap="truncate">
+              <Text color={theme.panelTitle}>{title}</Text>
+              {tabs.map((tab, i) => (
+                <Text key={i}>
+                  {'  '}
+                  {tab.current ? (
+                    <Text backgroundColor={theme.selectionBackground} color={theme.selectionText}>
+                      {` ${tab.answered ? '✓ ' : ''}${tab.text} `}
+                    </Text>
+                  ) : tab.answered ? (
+                    <Text color={theme.success}>{`✓ ${tab.text}`}</Text>
+                  ) : (
+                    <Text color={theme.subtle}>{tab.text}</Text>
+                  )}
+                </Text>
+              ))}
+            </Text>
+          </Box>
+          <Box flexShrink={0} marginLeft={2}>
+            <Text color={theme.subtle}>{help}</Text>
+          </Box>
+        </Box>
+        <Text> </Text>
+        {plan.qLines.map((line, i) => (
+          <Text key={i} color={theme.text} wrap="truncate">
+            {line}
+          </Text>
+        ))}
+        <Text> </Text>
+        {out}
+      </Box>
+    </Box>
+  );
+}

package/src/tui/components/question-panel-model.mjs

@@ -0,0 +1,156 @@
+/**
+ * components/question-panel-model.mjs — pure model for the ask_user
+ * QuestionPanel: answer building, row layout and reserved panel height.
+ */
+import stringWidth from 'string-width';
+import wrapAnsi from 'wrap-ansi';
+import { truncatePanelText } from './panel-cell-text.mjs';
+
+export const CUSTOM_LABEL = '직접 입력…';
+export const RECOMMENDED_SUFFIX = ' (추천)';
+export const MULTI_HINT = ' (여러 개 선택 가능)';
+// border(2) + title + blank + blank-after-question; question rows added separately.
+const FIXED_ROWS = 5;
+// Panel interior = frame − 2 border − 2 paddingX.
+const CHROME_COLUMNS = 4;
+
+export function questionsOf(toolApproval) {
+  const list = toolApproval?.args?.questions;
+  return Array.isArray(list) ? list : [];
+}
+
+// One question's answer from its draft ({ selected: optionIndex[], text? }).
+export function answerFor(question, draft) {
+  const options = Array.isArray(question?.options) ? question.options : [];
+  const selected = [...new Set(draft?.selected || [])]
+    .filter((i) => Number.isInteger(i) && i >= 0 && i < options.length)
+    .sort((a, b) => a - b)
+    .map((i) => options[i].label);
+  const text = String(draft?.text ?? '').trim();
+  if (selected.length === 0 && !text) return null;
+  return text ? { selected, text } : { selected };
+}
+
+export function buildAnswers(questions, drafts) {
+  return questions.map((question, i) => answerFor(question, drafts?.[i]));
+}
+
+const DETAIL_GAP = '  ';
+const MIN_DETAIL_CELLS = 6;
+
+// Geometry of one question's option rows at `columns` frame width: one line
+// per option (its label, the recommended mark, then its one-sentence
+// tradeoff in the cells left, cut with an ellipsis).
+export function optionLayout(question, columns) {
+  const options = Array.isArray(question?.options) ? question.options : [];
+  const total = options.length + 1;
+  const indexCells = stringWidth(`${total}. `);
+  const markerCells = question?.multi_select ? 4 : 0; // "[x] "
+  const prefixCells = 2 + indexCells + markerCells; // "› " + "1. " + marker
+  const avail = Math.max(10, columns - CHROME_COLUMNS);
+  const labelCap = Math.max(4, avail - prefixCells);
+  const rows = options.map((option, i) => {
+    const suffix = question?.recommended === i ? RECOMMENDED_SUFFIX : '';
+    const label = truncatePanelText(String(option.label ?? ''), Math.max(1, labelCap - stringWidth(suffix)));
+    const left = labelCap - stringWidth(label + suffix) - DETAIL_GAP.length;
+    const text = String(option.description ?? '').trim();
+    const detail = text && left >= MIN_DETAIL_CELLS ? `${DETAIL_GAP}${truncatePanelText(text, left)}` : '';
+    return { label, suffix, detail };
+  });
+  return { rows, prefixCells, avail, indexCells };
+}
+
+export const MAX_ANSWER_CHARS = 4000;
+const MIN_OPTION_ROWS = 3;
+
+// Append `text` to `base`, never exceeding MAX_ANSWER_CHARS UTF-16 units (the
+// unit the runtime checks), and never splitting a character.
+export function appendCapped(base, text) {
+  let out = base;
+  for (const char of text) {
+    if (out.length + char.length > MAX_ANSWER_CHARS) break;
+    out += char;
+  }
+  return out;
+}
+
+export function questionLines(question, columns) {
+  const shown = `${question?.question ?? ''}${question?.multi_select ? MULTI_HINT : ''}`;
+  return wrapAnsi(shown, Math.max(1, columns - CHROME_COLUMNS), { trim: false, hard: true }).split('\n');
+}
+
+function ellipsize(line, width) {
+  return `${truncatePanelText(line, Math.max(1, width - 1)).replace(/…$/, '')}…`;
+}
+
+// Fit the panel into `rows` (Infinity = unbudgeted). Always keeps the question
+// text (capped, leaving MIN_OPTION_ROWS for options) and the highlighted
+// option; the rest scroll with ↑/↓ more indicators.
+export function planQuestionView(question, columns, rows, cursor) {
+  const layout = optionLayout(question, columns);
+  const n = layout.rows.length;
+  let qLines = questionLines(question, columns);
+  const optionBudget = rows - FIXED_ROWS;
+  const qCap = Number.isFinite(rows) ? Math.max(1, optionBudget - MIN_OPTION_ROWS) : Infinity;
+  if (qLines.length > qCap) {
+    qLines = qLines.slice(0, qCap);
+    qLines[qCap - 1] = ellipsize(qLines[qCap - 1], Math.max(1, columns - CHROME_COLUMNS));
+  }
+  const avail = Number.isFinite(rows) ? Math.max(1, rows - FIXED_ROWS - qLines.length) : Infinity;
+  const full = Array(n + 1).fill(1);
+  const total = n + 1;
+  let heights = full;
+  if (full.reduce((a, b) => a + b, 0) > avail) {
+    heights = full.map((h, i) => (i === cursor ? Math.min(h, Math.max(1, avail - 2)) : 1));
+  }
+  let start = Math.min(cursor, total - 1);
+  let end = start + 1;
+  let used = heights[start];
+  const fits = (s, e, sum) => sum + (s > 0 ? 1 : 0) + (e < total ? 1 : 0) <= avail;
+  if (!fits(start, end, used) && avail < Infinity) {
+    // highlighted option alone exceeds budget with indicators: shrink it.
+    heights = heights.map((h, i) => (i === cursor ? 1 : h));
+    used = 1;
+  }
+  for (let grew = true; grew; ) {
+    grew = false;
+    if (end < total && fits(start, end + 1, used + heights[end])) {
+      used += heights[end++];
+      grew = true;
+    }
+    if (start > 0 && fits(start - 1, end, used + heights[start - 1])) {
+      used += heights[--start];
+      grew = true;
+    }
+  }
+  const items = [];
+  for (let i = start; i < end; i++) items.push({ index: i, lines: heights[i] });
+  return { qLines, items, above: start, below: total - end };
+}
+
+function questionRows(question, columns) {
+  const optionRows = Array.isArray(question?.options) ? question.options.length : 0;
+  return FIXED_ROWS + questionLines(question, columns).length + optionRows + 1; // +1 custom-input row
+}
+
+// Reserved floating-panel rows: the tallest question, so switching questions
+// never resizes the panel.
+export function questionPanelRows(questions, columns) {
+  return Math.max(FIXED_ROWS + 3, ...questions.map((q) => questionRows(q, columns)));
+}
+
+export function initialCursor(question) {
+  const n = Array.isArray(question?.options) ? question.options.length : 0;
+  const r = question?.recommended;
+  return Number.isInteger(r) && r >= 0 && r < n ? r : 0;
+}
+
+export function questionHelp({ multi, typing, last, count, questionCount = 1 }) {
+  if (typing) return 'Enter Send · Esc Back to list';
+  // Several questions: the title row also holds the tabs, so keep help short.
+  const parts = questionCount > 1 ? [] : [`1–${count} Choose`, '↑/↓ Move'];
+  if (multi) parts.push('Space Toggle');
+  if (questionCount > 1) parts.push('←/→ Question');
+  parts.push(last ? 'Enter Send' : 'Enter Next', 'Esc Dismiss');
+  return parts.join(' · ');
+}