pi-ask-popup 0.1.0

package/src/state/selectors/projections.ts

@@ -0,0 +1,111 @@
+import {
+  MULTI_SUBMIT_LABEL,
+  type MultiSelectViewProps,
+} from "../../view/components/multi-select-view.js";
+import type { OptionListViewProps } from "../../view/components/option-list-view.js";
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { SubmitPickerProps } from "../../view/components/submit-picker.js";
+import type { TabBarProps } from "../../view/components/tab-bar.js";
+import type { DialogProps } from "../../view/dialog-builder.js";
+import { LABELS_BY_KIND } from "../row-intent.js";
+import { noteForTab } from "../state.js";
+import type { GlobalSelector, PerTabBindingContext, PerTabSelector } from "./contract.js";
+import { selectConfirmedIndicator } from "./derivations.js";
+
+/** Header text for a tab, falling back to a position when the author gave none. */
+function tabLabel(header: string | undefined, index: number): string {
+  return header !== undefined && header.length > 0 ? header : `Q${index + 1}`;
+}
+
+function emptyMultiSelectProps(ctx: PerTabBindingContext): MultiSelectViewProps {
+  return {
+    rows: [],
+    other: {
+      active: false,
+      inputMode: false,
+      inputBuffer: ctx.inputBuffer,
+      inputCursorOffset: ctx.inputCursorOffset,
+    },
+    nextActive: false,
+    nextLabel: LABELS_BY_KIND.next,
+  };
+}
+
+/**
+ * The commit row reads "Next" on every question but the last, where advancing
+ * has nowhere to go and the row submits instead. Both strings come from the
+ * layer that owns them: the row's own metadata, and the multi-select view's
+ * submit label.
+ */
+function nextLabelFor(ctx: PerTabBindingContext): string {
+  const isLastQuestion = ctx.i === ctx.questions.length - 1;
+  return isLastQuestion ? MULTI_SUBMIT_LABEL : LABELS_BY_KIND.next;
+}
+
+export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (state, ctx) => {
+  const question = ctx.questions[ctx.i];
+  if (!question) return emptyMultiSelectProps(ctx);
+  const focused = ctx.activeView === "options";
+  const rows = question.options.map((_option, i) => ({
+    checked: state.multiSelectChecked.has(i),
+    active: focused && i === state.optionIndex,
+  }));
+  return {
+    rows,
+    other: {
+      active: focused && state.optionIndex === question.options.length,
+      inputMode: state.inputMode,
+      inputBuffer: ctx.inputBuffer,
+      inputCursorOffset: ctx.inputCursorOffset,
+    },
+    nextActive: focused && state.optionIndex === question.options.length + 1,
+    nextLabel: nextLabelFor(ctx),
+  };
+};
+
+export const selectOptionListProps: PerTabSelector<OptionListViewProps> = (state, ctx) => {
+  const items = ctx.itemsByTab[ctx.i] ?? [];
+  const confirmed = selectConfirmedIndicator(ctx.questions, state.currentTab, state.answers, items);
+  return {
+    selectedIndex: state.optionIndex,
+    focused: ctx.activeView === "options",
+    inputBuffer: ctx.inputBuffer,
+    inputCursorOffset: ctx.inputCursorOffset,
+    ...(confirmed ? { confirmed } : {}),
+  };
+};
+
+export const selectSubmitPickerProps: GlobalSelector<SubmitPickerProps> = (state, ctx) => {
+  const focused = ctx.activeView === "submit";
+  return {
+    rows: [
+      { active: focused && state.submitChoiceIndex === 0 },
+      { active: focused && state.submitChoiceIndex === 1 },
+    ],
+  };
+};
+
+export const selectPreviewPaneProps: PerTabSelector<PreviewPaneProps> = (state, ctx) => ({
+  notesVisible: state.notesVisible,
+  selectedIndex: state.optionIndex,
+  focused: ctx.activeView === "options",
+  inputMode: state.inputMode,
+});
+
+export const selectTabBarProps: GlobalSelector<TabBarProps> = (state, ctx) => ({
+  tabs: ctx.questions.map((q, i) => ({
+    label: tabLabel(q.header, i),
+    answered: state.answers.has(i),
+    active: i === state.currentTab,
+    noted: noteForTab(state, i).length > 0,
+  })),
+  submit: {
+    active: state.currentTab === ctx.questions.length,
+    allAnswered: state.answers.size === ctx.questions.length && ctx.questions.length > 0,
+  },
+});
+
+export const selectDialogProps: GlobalSelector<DialogProps> = (state, ctx) => ({
+  state,
+  activePreviewPane: ctx.activePreviewPane,
+});

package/src/state/state-reducer.ts

@@ -0,0 +1,421 @@
+import type {
+  QuestionAnswer,
+  QuestionData,
+  QuestionnaireResult,
+  UnansweredNote,
+} from "../tool/types.js";
+import type { WrappingSelectItem } from "./row-intent.js";
+import type { QuestionnaireAction } from "./key-router.js";
+import { ROW_INTENT_META } from "./row-intent.js";
+import { noteForTab, type QuestionnaireState } from "./state.js";
+
+/** Session-lifetime constants. No live-component reads — peripheral values live on canonical state. */
+export interface ApplyContext {
+  questions: readonly QuestionData[];
+  itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+}
+
+/**
+ * Declarative side-effects emitted by `reduce`. The runtime executes them after
+ * committing the new state, then asks the props-adapter to re-project. Closed set —
+ * adding an effect requires updating both the union AND the runtime's `runEffect` switch
+ * (compiler-enforced exhaustive). No string-keyed escape hatch.
+ */
+export type Effect =
+  | { kind: "set_input_buffer"; value: string }
+  | { kind: "clear_input_buffer" }
+  | { kind: "open_input_editor"; value: string }
+  | { kind: "set_notes_value"; value: string }
+  | { kind: "set_notes_focused"; focused: boolean }
+  | { kind: "forward_notes_keystroke"; data: string }
+  /**
+   * Tell the session to hide or show its underlying overlay. Emitted by the
+   * `toggle_collapsed` action so the runtime can call `OverlayHandle.setHidden(...)`,
+   * which lets other overlay-aware consumers (e.g. `pi-station`) see the questionnaire
+   * as truly hidden and resume normal chat scroll while the user reads the transcript
+   * behind the modal.
+   */
+  | { kind: "set_overlay_hidden"; hidden: boolean }
+  | { kind: "clear_timer" }
+  | { kind: "done"; result: QuestionnaireResult };
+
+export interface ApplyResult {
+  state: QuestionnaireState;
+  effects: readonly Effect[];
+}
+
+function orderedAnswers(
+  state: QuestionnaireState,
+  questions: readonly QuestionData[],
+): QuestionAnswer[] {
+  const out: QuestionAnswer[] = [];
+  for (let i = 0; i < questions.length; i++) {
+    const a = state.answers.get(i);
+    if (a) out.push(a);
+  }
+  return out;
+}
+
+/**
+ * Notes on questions with no answer behind them.
+ *
+ * Walks the questions rather than the map, which gives ask order for free and
+ * keeps the global note out: it lives at the `questions.length` pseudo-index in
+ * `notesByTab`, and this loop never reaches that far.
+ *
+ * Reads `state.notesByTab` directly rather than `noteForTab`, because the
+ * answer-mirror half of that lookup is unreachable here by construction — an
+ * index with no entry in `answers` has no mirror to read.
+ */
+function unansweredNotesFor(
+  state: QuestionnaireState,
+  questions: readonly QuestionData[],
+): UnansweredNote[] {
+  const out: UnansweredNote[] = [];
+  for (let i = 0; i < questions.length; i++) {
+    if (state.answers.has(i)) continue;
+    const question = questions[i];
+    const note = state.notesByTab.get(i);
+    if (!question || note === undefined || note.length === 0) continue;
+    out.push({ questionIndex: i, question: question.question, note });
+  }
+  return out;
+}
+
+function syncMultiSelectFromAnswers(
+  answers: ReadonlyMap<number, QuestionAnswer>,
+  questions: readonly QuestionData[],
+  tab: number,
+): ReadonlySet<number> {
+  const q = questions[tab];
+  if (!q?.multiSelect) return new Set();
+  const saved = answers.get(tab);
+  const labels = saved?.selected ?? [];
+  const indices = new Set<number>();
+  for (let i = 0; i < q.options.length; i++) {
+    if (labels.includes(q.options[i]!.label)) indices.add(i);
+  }
+  return indices;
+}
+
+function persistMultiSelectAnswer(
+  state: QuestionnaireState,
+  ctx: ApplyContext,
+): ReadonlyMap<number, QuestionAnswer> {
+  const q = ctx.questions[state.currentTab];
+  if (!q?.multiSelect) return state.answers;
+  const selected: string[] = [];
+  for (let i = 0; i < q.options.length; i++) {
+    if (state.multiSelectChecked.has(i)) selected.push(q.options[i]!.label);
+  }
+  const out = new Map(state.answers);
+  if (selected.length === 0) {
+    out.delete(state.currentTab);
+    return out;
+  }
+  const pendingNotes = state.notesByTab.get(state.currentTab);
+  out.set(state.currentTab, {
+    questionIndex: state.currentTab,
+    question: q.question,
+    kind: "multi",
+    answer: null,
+    selected,
+    ...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
+  });
+  return out;
+}
+
+function customDraftValueFor(state: QuestionnaireState, tab: number): string {
+  const draft = state.customDraftsByTab.get(tab);
+  if (draft !== undefined) return draft;
+  const answer = state.answers.get(tab);
+  return answer?.kind === "custom" && typeof answer.answer === "string" ? answer.answer : "";
+}
+
+function setCustomDraft(
+  state: QuestionnaireState,
+  tab: number,
+  value: string,
+): ReadonlyMap<number, string> {
+  const drafts = new Map(state.customDraftsByTab);
+  drafts.set(tab, value);
+  return drafts;
+}
+
+function withoutCustomDraft(state: QuestionnaireState, tab: number): ReadonlyMap<number, string> {
+  if (!state.customDraftsByTab.has(tab)) return state.customDraftsByTab;
+  const drafts = new Map(state.customDraftsByTab);
+  drafts.delete(tab);
+  return drafts;
+}
+
+function switchTabResult(
+  state: QuestionnaireState,
+  nextTab: number,
+  ctx: ApplyContext,
+): ApplyResult {
+  const notesValue = noteForTab(state, nextTab);
+  const transitioned: QuestionnaireState = {
+    ...state,
+    currentTab: nextTab,
+    optionIndex: 0,
+    inputMode: false,
+    notesVisible: false,
+    submitChoiceIndex: 0,
+    multiSelectChecked: syncMultiSelectFromAnswers(state.answers, ctx.questions, nextTab),
+    notesDraft: notesValue,
+  };
+  return {
+    state: transitioned,
+    effects: [
+      { kind: "set_notes_focused", focused: false },
+      { kind: "set_notes_value", value: notesValue },
+      { kind: "set_input_buffer", value: customDraftValueFor(state, nextTab) },
+    ],
+  };
+}
+
+function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolean): ApplyResult {
+  // Global note lift: the Submit-tab note lives at the `questions.length` pseudo-index
+  // in `notesByTab` — question tabs only occupy 0..questions.length-1, so this can never
+  // cross-contaminate a per-question note. Attached regardless of `cancelled` (the
+  // reducer is truth; the envelope owns decline presentation), with cancel/submit/confirm
+  // sharing this single lift. Conditional spread keeps note-free results byte-identical.
+  const globalNote = state.notesByTab.get(ctx.questions.length);
+  // Notes on unanswered questions are lifted the same way and for the same
+  // reason: they belong to the person who wrote them, not to the answer they
+  // never gave, so cancelling must not eat them either.
+  const unansweredNotes = unansweredNotesFor(state, ctx.questions);
+  const result: QuestionnaireResult = {
+    answers: orderedAnswers(state, ctx.questions),
+    cancelled,
+    ...(globalNote && globalNote.length > 0 ? { globalNote } : {}),
+    ...(unansweredNotes.length > 0 ? { unansweredNotes } : {}),
+  };
+  return { state, effects: [{ kind: "done", result }] };
+}
+
+/**
+ * Per-kind handler signature: action payload narrows to the matching union member
+ * via `Extract`, so handlers consume fully-typed actions without `as` casts.
+ */
+type Handler<K extends QuestionnaireAction["kind"]> = (
+  state: QuestionnaireState,
+  action: Extract<QuestionnaireAction, { kind: K }>,
+  ctx: ApplyContext,
+) => ApplyResult;
+
+const navHandler: Handler<"nav"> = (state, action, ctx) => {
+  const items = ctx.itemsByTab[state.currentTab] ?? [];
+  const item = items[action.nextIndex];
+  const inputMode = item ? ROW_INTENT_META[item.kind].activatesInputMode : false;
+  const customDraftsByTab = state.inputMode
+    ? setCustomDraft(state, state.currentTab, action.inputValue)
+    : state.customDraftsByTab;
+  const next: QuestionnaireState = {
+    ...state,
+    optionIndex: action.nextIndex,
+    inputMode,
+    customDraftsByTab,
+  };
+  if (!inputMode) return { state: next, effects: [] };
+  return {
+    state: next,
+    effects: [{ kind: "set_input_buffer", value: customDraftValueFor(next, state.currentTab) }],
+  };
+};
+
+const inputClearHandler: Handler<"input_clear"> = (state, _action, _ctx) => ({
+  state: { ...state, customDraftsByTab: setCustomDraft(state, state.currentTab, "") },
+  effects: [{ kind: "clear_input_buffer" }],
+});
+const inputEditHandler: Handler<"input_edit"> = (state, action, _ctx) => ({
+  state,
+  effects: [{ kind: "open_input_editor", value: action.value }],
+});
+const inputReplaceHandler: Handler<"input_replace"> = (state, action, _ctx) => ({
+  state: { ...state, customDraftsByTab: setCustomDraft(state, state.currentTab, action.value) },
+  effects: [{ kind: "set_input_buffer", value: action.value }],
+});
+
+const tabSwitchHandler: Handler<"tab_switch"> = (state, action, ctx) =>
+  switchTabResult(state, action.nextTab, ctx);
+
+const confirmHandler: Handler<"confirm"> = (state, action, ctx) => {
+  let answer = action.answer;
+  if (answer.kind === "option" && answer.answer) {
+    const q = ctx.questions[answer.questionIndex];
+    const matched = q?.options.find((o) => o.label === answer.answer);
+    if (matched?.preview && matched.preview.length > 0) {
+      answer = { ...answer, preview: matched.preview };
+    }
+  }
+  const pendingNotes = state.notesByTab.get(answer.questionIndex);
+  if (pendingNotes && pendingNotes.length > 0) {
+    answer = { ...answer, notes: pendingNotes };
+  }
+  const answers = new Map(state.answers);
+  answers.set(answer.questionIndex, answer);
+  // Custom free-text on a multi-select tab is mutually exclusive with checkbox selections:
+  // clear the checked set immediately so [✔] glyphs vanish on Enter. (A custom answer
+  // carries no `selected` array, so syncMultiSelectFromAnswers keeps it empty on tab-back.)
+  const isCustomMulti =
+    answer.kind === "custom" && ctx.questions[answer.questionIndex]?.multiSelect === true;
+  const customDraftsByTab =
+    answer.kind === "custom"
+      ? withoutCustomDraft(state, answer.questionIndex)
+      : state.customDraftsByTab;
+  const next: QuestionnaireState = {
+    ...state,
+    answers,
+    customDraftsByTab,
+    ...(isCustomMulti ? { multiSelectChecked: new Set<number>() } : {}),
+  };
+  if (action.autoAdvanceTab !== undefined) return switchTabResult(next, action.autoAdvanceTab, ctx);
+  return doneFor(next, ctx, false);
+};
+
+const toggleHandler: Handler<"toggle"> = (state, action, ctx) => {
+  const checked = new Set(state.multiSelectChecked);
+  if (checked.has(action.index)) checked.delete(action.index);
+  else checked.add(action.index);
+  const intermediate: QuestionnaireState = { ...state, multiSelectChecked: checked };
+  const answers = persistMultiSelectAnswer(intermediate, ctx);
+  return { state: { ...intermediate, answers }, effects: [] };
+};
+
+const multiConfirmHandler: Handler<"multi_confirm"> = (state, action, ctx) => {
+  const q = ctx.questions[state.currentTab];
+  if (!q) return { state, effects: [] };
+  const pendingNotes = state.notesByTab.get(state.currentTab);
+  const answers = new Map(state.answers);
+  answers.set(state.currentTab, {
+    questionIndex: state.currentTab,
+    question: q.question,
+    kind: "multi",
+    answer: null,
+    selected: action.selected,
+    ...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
+  });
+  const synced: QuestionnaireState = {
+    ...state,
+    answers,
+    multiSelectChecked: syncMultiSelectFromAnswers(answers, ctx.questions, state.currentTab),
+  };
+  if (action.autoAdvanceTab !== undefined)
+    return switchTabResult(synced, action.autoAdvanceTab, ctx);
+  return doneFor(synced, ctx, false);
+};
+
+const notesEnterHandler: Handler<"notes_enter"> = (state, _action, _ctx) => {
+  const value = noteForTab(state, state.currentTab);
+  return {
+    state: { ...state, notesVisible: true, notesDraft: value },
+    effects: [
+      { kind: "set_notes_value", value },
+      { kind: "set_notes_focused", focused: true },
+    ],
+  };
+};
+
+const notesExitHandler: Handler<"notes_exit"> = (state, _action, _ctx) => {
+  const trimmed = state.notesDraft.trim();
+  const notes = new Map(state.notesByTab);
+  const answers = new Map(state.answers);
+  if (trimmed.length === 0) {
+    notes.delete(state.currentTab);
+    const prev = answers.get(state.currentTab);
+    if (prev?.notes) {
+      const stripped = { ...prev };
+      delete (stripped as { notes?: string }).notes;
+      answers.set(state.currentTab, stripped);
+    }
+  } else {
+    notes.set(state.currentTab, trimmed);
+    const prev = answers.get(state.currentTab);
+    if (prev) answers.set(state.currentTab, { ...prev, notes: trimmed });
+  }
+  return {
+    state: { ...state, notesByTab: notes, answers, notesVisible: false },
+    effects: [{ kind: "set_notes_focused", focused: false }],
+  };
+};
+
+const cancelHandler: Handler<"cancel"> = (s, _a, c) => doneFor(s, c, true);
+const submitHandler: Handler<"submit"> = (s, _a, c) => doneFor(s, c, false);
+const submitNavHandler: Handler<"submit_nav"> = (s, a, _c) => ({
+  state: { ...s, submitChoiceIndex: a.nextIndex },
+  effects: [],
+});
+const notesForwardHandler: Handler<"notes_forward"> = (s, a, _c) => ({
+  state: s,
+  effects: [{ kind: "forward_notes_keystroke", data: a.data }],
+});
+const toggleCollapsedHandler: Handler<"toggle_collapsed"> = (s, _a, _c) => ({
+  state: { ...s, collapsed: !s.collapsed },
+  effects: [{ kind: "set_overlay_hidden", hidden: !s.collapsed }],
+});
+const tickHandler: Handler<"tick"> = (state, action, ctx) => {
+  if (state.timerCancelled || state.deadline === undefined) return { state, effects: [] };
+  const remaining = state.deadline - action.now;
+  if (remaining > 0) {
+    return { state: { ...state, remainingMs: remaining }, effects: [] };
+  }
+  const globalNote = state.notesByTab.get(ctx.questions.length);
+  const result: QuestionnaireResult = {
+    answers: orderedAnswers(state, ctx.questions),
+    cancelled: true,
+    error: "timed_out",
+    ...(globalNote && globalNote.length > 0 ? { globalNote } : {}),
+  };
+  return { state, effects: [{ kind: "done", result }] };
+};
+const ignoreHandler: Handler<"ignore"> = (s, _a, _c) => ({ state: s, effects: [] });
+
+/**
+ * Compile-time-exhaustive dispatch table. `{ [K in Kind]: Handler<K> }` requires
+ * an entry per union member — adding a new `QuestionnaireAction` variant fails to
+ * compile here until a handler is registered, mirroring the `Record<RowKind, …>`
+ * pattern used by `ROW_INTENT_META`.
+ */
+const HANDLERS: { [K in QuestionnaireAction["kind"]]: Handler<K> } = {
+  nav: navHandler,
+  input_clear: inputClearHandler,
+  input_edit: inputEditHandler,
+  input_replace: inputReplaceHandler,
+  tab_switch: tabSwitchHandler,
+  confirm: confirmHandler,
+  toggle: toggleHandler,
+  multi_confirm: multiConfirmHandler,
+  cancel: cancelHandler,
+  notes_enter: notesEnterHandler,
+  notes_exit: notesExitHandler,
+  notes_forward: notesForwardHandler,
+  submit: submitHandler,
+  submit_nav: submitNavHandler,
+  toggle_collapsed: toggleCollapsedHandler,
+  tick: tickHandler,
+  ignore: ignoreHandler,
+};
+
+/**
+ * Pure reducer: (state, action, ctx) → (state, Effect[]). Mirrors `rpiv-todo`'s `applyTaskMutation`.
+ * Delegates to `HANDLERS` — per-kind handlers above are pure, named, and individually testable.
+ * `ignore` is also handled outside the reducer by `handleIgnoreInline` in the runtime fast path.
+ */
+export function reduce(
+  state: QuestionnaireState,
+  action: QuestionnaireAction,
+  ctx: ApplyContext,
+): ApplyResult {
+  const handler = HANDLERS[action.kind] as Handler<typeof action.kind>;
+  const result = handler(state, action as never, ctx);
+  const isHumanKeystroke = action.kind !== "tick" && action.kind !== "toggle_collapsed";
+  if (isHumanKeystroke && state.deadline !== undefined && !state.timerCancelled) {
+    return {
+      state: { ...result.state, timerCancelled: true, remainingMs: undefined },
+      effects: [...result.effects, { kind: "clear_timer" }],
+    };
+  }
+  return result;
+}

package/src/state/state.ts

@@ -0,0 +1,110 @@
+import type { QuestionAnswer, QuestionData } from "../tool/types.js";
+import type { WrappingSelectItem } from "./row-intent.js";
+
+/**
+ * The note attached to a tab, or `""` when it has none.
+ *
+ * `notesByTab` is authoritative: before an option is confirmed the note lives
+ * only there, and `answers[tab].notes` is the mirror written at confirm time.
+ * One lookup shared by the reducer, the tab-bar marker and the resting row, so
+ * the three cannot disagree about whether a note exists.
+ *
+ * Question indices only. The global note sits at the `questions.length`
+ * pseudo-index, and no caller should reach it through here.
+ */
+export function noteForTab(state: QuestionnaireState, tab: number): string {
+  return state.notesByTab.get(tab) ?? state.answers.get(tab)?.notes ?? "";
+}
+
+/**
+ * Canonical state for the questionnaire dialog. Single source of truth — both the
+ * dispatcher (`routeKey`) and the view layer read this same shape.
+ */
+export interface QuestionnaireState {
+  currentTab: number;
+  optionIndex: number;
+  inputMode: boolean;
+  notesVisible: boolean;
+  answers: ReadonlyMap<number, QuestionAnswer>;
+  multiSelectChecked: ReadonlySet<number>;
+  /** In-flight custom answers keyed by tab. A present empty string overrides an older answer. */
+  customDraftsByTab: ReadonlyMap<number, string>;
+  /**
+   * Pre-answer notes side-band, keyed by tab index. Decoupled from `answers` so adding
+   * notes does NOT mark a question answered (the Submit-tab missing-check would falsely
+   * pass otherwise). Merged into the answer at confirm time.
+   */
+  notesByTab: ReadonlyMap<number, string>;
+  /** Focused row in the Submit-tab picker (0 = Submit, 1 = Cancel). Reset on tab switch. */
+  submitChoiceIndex: number;
+  /** Canonical mirror of the in-flight notes editor; runtime mirrors after `forward_notes_keystroke`. */
+  notesDraft: string;
+  /**
+   * Absolute deadline in epoch milliseconds when the questionnaire should auto-dismiss.
+   * Set once at initialization when `timeout` is provided; never reset. Undefined when
+   * no timeout is configured.
+   */
+  deadline?: number | undefined;
+  /**
+   * Milliseconds remaining until `deadline`. Updated on every `tick`; undefined when
+   * no timeout is active or after the timer is cancelled by human input.
+   */
+  remainingMs?: number | undefined;
+  /**
+   * Whether the countdown has been cancelled by the first human keystroke.
+   * Cancelled outright, not reset — once true it stays true.
+   */
+  timerCancelled: boolean;
+  /**
+   * Collapsed mode: the questionnaire gets out of the way so the agent transcript behind
+   * the bottom-anchored overlay becomes readable. Toggled by the configured collapse key
+   * from any state; while true, every keystroke except cancel is swallowed (see
+   * `routeKey`). Two renderings, chosen by host capability:
+   *
+   * - Hosts with an `OverlayHandle` AND a raw `onTerminalInput` listener (real pi-tui):
+   *   the `set_overlay_hidden` effect fully hides the overlay; the raw listener registered
+   *   in `execute()` reopens it, because pi-tui routes no input to a hidden overlay.
+   * - Hosts without the raw listener (or without a handle): the overlay stays visible and
+   *   shrinks to a single hint row. The row keeps focus and input routing, so the same key
+   *   expands it and Esc cancels, and the expand key never falls through to an underlying
+   *   overlay (e.g. `/btw`). The session gates `set_overlay_hidden` on the listener's
+   *   existence (`canReopenWhileHidden`) so a handle-bearing host without raw input can
+   *   never hide the overlay into a state nothing can reopen.
+   */
+  collapsed: boolean;
+}
+
+/**
+ * Per-tick context the dispatcher needs alongside canonical state. Held separately
+ * because `keybindings` / `inputBuffer` must never reach view setProps consumers.
+ */
+export interface QuestionnaireRuntime {
+  keybindings: { matches(data: string, name: string): boolean };
+  inputBuffer: string;
+  canMoveInputUp: boolean;
+  canMoveInputDown: boolean;
+  questions: readonly QuestionData[];
+  isMulti: boolean;
+  currentItem: WrappingSelectItem | undefined;
+  items: readonly WrappingSelectItem[];
+  /**
+   * Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. Resolved
+   * from `AskUserQuestionConfig.collapseKey` (or the package default). When `"off"`,
+   * the collapse shortcut is disabled.
+   */
+  collapseKey: string;
+}
+
+/**
+ * Which of the three focusable surfaces owns the keyboard this tick.
+ *
+ * Declared here rather than in the view layer because focus is a property of
+ * canonical state, not of any renderer: the key router's cascade and the
+ * reducer's defensive clears are what enforce mutual exclusion, and components
+ * only read the result. Per-component `focused: boolean` flags derive from one
+ * equality check against this discriminant instead of parallel boolean reads.
+ *
+ * Priority order is notes > submit > options, matching the router cascade
+ * exactly.
+ */
+export type ActiveView = "notes" | "options" | "submit";

package/src/tool/format-answer.ts

@@ -0,0 +1,28 @@
+import type { QuestionAnswer } from "./types.js";
+
+/** Stand-in for an answer with no text. One placeholder for every variant. */
+export const NO_INPUT_PLACEHOLDER = "(no input)";
+
+export type FormatAnswerVariant = "summary" | "envelope";
+
+/**
+ * Reduce an answer to its scalar string form.
+ *
+ * `variant` currently changes nothing: the branch that once distinguished the
+ * review summary from the model-facing envelope is gone. It stays on the
+ * signature because both call sites read better naming which surface they are
+ * rendering, and because the distinction is likely to come back.
+ *
+ * The switch is exhaustive by way of a non-void return: adding a `kind` fails
+ * to compile here.
+ */
+export function formatAnswerScalar(a: QuestionAnswer, _variant: FormatAnswerVariant): string {
+  switch (a.kind) {
+    case "multi":
+      return a.selected && a.selected.length > 0 ? a.selected.join(", ") : NO_INPUT_PLACEHOLDER;
+    case "custom":
+      return a.answer && a.answer.length > 0 ? a.answer : NO_INPUT_PLACEHOLDER;
+    case "option":
+      return a.answer ?? NO_INPUT_PLACEHOLDER;
+  }
+}