pi-ask-popup 0.1.0 → 0.2.0

package/src/state/questionnaire-session.ts

@@ -1,5 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Editor, OverlayHandle, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import { COLLAPSE_KEY_OFF, formatKeySpecForDisplay } from "../config.js";
 import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/types.js";
 import {
@@ -38,6 +39,32 @@ export interface QuestionnaireSessionConfig {
   canReopenWhileHidden: boolean;
 }
 
+/** Header of the screen shown when the overlay could not be painted. */
+export const RENDER_FAILED_TEXT = "Questionnaire failed to render — press Esc to cancel";
+
+/** Never throws, whatever was thrown: this runs inside the boundary. */
+function describeThrown(thrown: unknown): string {
+  try {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+  } catch {
+    return "unknown error";
+  }
+}
+
+/**
+ * The screen the boundary paints in place of the overlay.
+ *
+ * Deliberately themeless and unstyled: a theme call is one of the things that
+ * can have thrown, and a fallback that needs the failing machinery to work is
+ * not a fallback. Two plain rows, clipped to the width.
+ */
+function renderFailureScreen(width: number, thrown: unknown): string[] {
+  return [
+    truncateToWidth(` ${RENDER_FAILED_TEXT} `, width, ""),
+    truncateToWidth(` ${describeThrown(thrown)} `, width, "…"),
+  ];
+}
+
 export interface QuestionnaireSessionComponent {
   render(width: number): string[];
   invalidate(): void;
@@ -152,7 +179,9 @@ export class QuestionnaireSession {
 
     this.component = this.assembleComponent(built, config.theme);
     this.viewAdapter.apply(this.state);
-    if (this.state.deadline !== undefined) this.startTimer();
+    if (this.state.deadline !== undefined) {
+      this.startTimer();
+    }
   }
 
   private assembleComponent(
@@ -161,7 +190,18 @@ export class QuestionnaireSession {
   ): QuestionnaireSessionComponent {
     const collapsedRender = this.buildCollapsedRender(theme);
     return {
-      render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
+      // The boundary. Everything below it — markdown from the model, border
+      // arithmetic, width math — runs inside pi-tui's render loop, where a
+      // throw takes the overlay down and leaves the user with no way to answer
+      // or dismiss it. Input still routes through `handleInput`, so Esc works
+      // on the fallback screen.
+      render: (width) => {
+        try {
+          return this.state.collapsed ? collapsedRender(width) : built.render(width);
+        } catch (thrown) {
+          return renderFailureScreen(width, thrown);
+        }
+      },
       invalidate: built.invalidate,
       handleInput: (data) => this.dispatch(data),
     };
@@ -180,15 +220,17 @@ export class QuestionnaireSession {
    * falls back to cancel-only rather than telling the user to press "Off".
    */
   private startTimer(): void {
-    if (this.timer !== undefined) return;
+    if (this.timer !== undefined) {
+      return;
+    }
     this.timer = setInterval(() => {
       this.commit({ kind: "tick", now: Date.now() });
     }, 1000);
     // Don't keep the process alive after Pi exits.
     // SAFETY: Node's Timeout has unref, DOM/Bun number does not; guard ensures we only call when present.
-    if (typeof (this.timer as unknown as { unref?: () => void }).unref === "function") {
+    if (typeof (this.timer as { unref?: () => void }).unref === "function") {
       // SAFETY: same guard as above — only called when unref is a function.
-      (this.timer as unknown as { unref: () => void }).unref();
+      (this.timer as { unref: () => void }).unref();
     }
   }
 
@@ -200,9 +242,13 @@ export class QuestionnaireSession {
   }
 
   private formatRemaining(): string | undefined {
-    if (this.state.timerCancelled) return undefined;
+    if (this.state.timerCancelled) {
+      return undefined;
+    }
     const ms = this.state.remainingMs;
-    if (ms === undefined) return undefined;
+    if (ms === undefined) {
+      return undefined;
+    }
     const secs = Math.max(0, Math.ceil(ms / 1000));
     return `${secs}s`;
   }
@@ -221,7 +267,9 @@ export class QuestionnaireSession {
   }
 
   dispatch(data: string): void {
-    if (this.inputEditorOpen) return;
+    if (this.inputEditorOpen) {
+      return;
+    }
     const action = routeKey(data, this.state, this.runtime());
     if (action.kind === "ignore") {
       this.handleIgnoreInline(data);
@@ -233,7 +281,9 @@ export class QuestionnaireSession {
   private commit(action: QuestionnaireAction): void {
     const result = reduce(this.state, action, this.applyContext());
     this.state = result.state;
-    for (const effect of result.effects) this.runEffect(effect);
+    for (const effect of result.effects) {
+      this.runEffect(effect);
+    }
     this.state = this.mirrorNotesDraft(this.state);
     this.viewAdapter.apply(this.state);
   }
@@ -274,7 +324,9 @@ export class QuestionnaireSession {
         // A no-op until the handle arrives, and suppressed entirely without a
         // raw terminal listener: see `canReopenWhileHidden`. The state still
         // says collapsed either way, so the view renders the one-line row.
-        if (this.canReopenWhileHidden) this.overlayHandle?.setHidden(effect.hidden);
+        if (this.canReopenWhileHidden) {
+          this.overlayHandle?.setHidden(effect.hidden);
+        }
         return;
       case "clear_timer":
         this.clearTimer();
@@ -294,12 +346,16 @@ export class QuestionnaireSession {
    * nothing.
    */
   private openInputEditorAsync(value: string): void {
-    if (this.inputEditorOpen) return;
+    if (this.inputEditorOpen) {
+      return;
+    }
     this.inputEditorOpen = true;
     void this.editInput(value).then(
       (edited) => {
         this.inputEditorOpen = false;
-        if (edited !== undefined) this.commit({ kind: "input_replace", value: edited });
+        if (edited !== undefined) {
+          this.commit({ kind: "input_replace", value: edited });
+        }
       },
       () => {
         this.inputEditorOpen = false;
@@ -326,9 +382,16 @@ export class QuestionnaireSession {
       timerWasCancelled = true;
     }
     if (!this.state.inputMode) {
-      if (timerWasCancelled) this.viewAdapter.apply(this.state);
+      if (timerWasCancelled) {
+        this.viewAdapter.apply(this.state);
+      }
       return;
     }
+    // One apply, and the editor adds none of its own: pi-tui's `Editor`
+    // requests a render from its setters and its autocomplete callbacks, never
+    // from `handleInput`, and this editor has no autocomplete provider. So a
+    // keystroke here asks for exactly one render — which the session's tests
+    // pin, since a second would mean two owners of one tick.
     this.inlineInput.handleInput(data);
     this.viewAdapter.apply(this.state);
   }
@@ -377,6 +440,8 @@ export class QuestionnaireSession {
    * else.
    */
   toggleCollapsedExternal(): void {
-    if (!this.inputEditorOpen) this.commit({ kind: "toggle_collapsed" });
+    if (!this.inputEditorOpen) {
+      this.commit({ kind: "toggle_collapsed" });
+    }
   }
 }

package/src/state/row-intent.ts

@@ -147,10 +147,14 @@ export function sentinelsToAppend(question: QuestionData): SentinelKind[] {
   const out: SentinelKind[] = [];
   for (const kind of SENTINEL_KINDS) {
     const meta = ROW_INTENT_META[kind];
-    if (!meta.livesInMainList) continue;
+    if (!meta.livesInMainList) {
+      continue;
+    }
     const appends =
       question.multiSelect === true ? meta.autoAppendOnMultiSelect : meta.autoAppendOnSingleSelect;
-    if (appends) out.push(kind);
+    if (appends) {
+      out.push(kind);
+    }
   }
   return out;
 }

package/src/state/selectors/derivations.ts

@@ -15,17 +15,27 @@ export function selectConfirmedIndicator(
   items: readonly WrappingSelectItem[],
 ): { index: number; labelOverride?: string } | undefined {
   const q = questions[currentTab];
-  if (!q || q.multiSelect === true) return undefined;
+  if (!q || q.multiSelect === true) {
+    return undefined;
+  }
   const prior = answers.get(currentTab);
-  if (!prior) return undefined;
+  if (!prior) {
+    return undefined;
+  }
   if (prior.kind === "custom") {
     const otherIndex = items.findIndex((it) => it.kind === "other");
-    if (otherIndex < 0) return undefined;
+    if (otherIndex < 0) {
+      return undefined;
+    }
     return { index: otherIndex, labelOverride: prior.answer ?? "" };
   }
-  if (prior.kind !== "option" || typeof prior.answer !== "string") return undefined;
+  if (prior.kind !== "option" || typeof prior.answer !== "string") {
+    return undefined;
+  }
   const index = items.findIndex((it) => it.kind === "option" && it.label === prior.answer);
-  if (index < 0) return undefined;
+  if (index < 0) {
+    return undefined;
+  }
   return { index };
 }
 
@@ -35,6 +45,8 @@ export function selectConfirmedIndicator(
  * machinery picks the right body component independently. Defensive against `totalQuestions === 0`.
  */
 export function selectActivePreviewPaneIndex(currentTab: number, totalQuestions: number): number {
-  if (totalQuestions <= 0) return 0;
+  if (totalQuestions <= 0) {
+    return 0;
+  }
   return Math.min(currentTab, totalQuestions - 1);
 }

package/src/state/selectors/focus.ts

@@ -11,7 +11,11 @@ export function selectActiveView(
   state: { notesVisible: boolean; currentTab: number },
   totalQuestions: number,
 ): ActiveView {
-  if (state.notesVisible) return "notes";
-  if (state.currentTab === totalQuestions) return "submit";
+  if (state.notesVisible) {
+    return "notes";
+  }
+  if (state.currentTab === totalQuestions) {
+    return "submit";
+  }
   return "options";
 }

package/src/state/selectors/projections.ts

@@ -22,6 +22,7 @@ function emptyMultiSelectProps(ctx: PerTabBindingContext): MultiSelectViewProps
     rows: [],
     other: {
       active: false,
+      checked: false,
       inputMode: false,
       inputBuffer: ctx.inputBuffer,
       inputCursorOffset: ctx.inputCursorOffset,
@@ -44,7 +45,9 @@ function nextLabelFor(ctx: PerTabBindingContext): string {
 
 export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (state, ctx) => {
   const question = ctx.questions[ctx.i];
-  if (!question) return emptyMultiSelectProps(ctx);
+  if (!question) {
+    return emptyMultiSelectProps(ctx);
+  }
   const focused = ctx.activeView === "options";
   const rows = question.options.map((_option, i) => ({
     checked: state.multiSelectChecked.has(i),
@@ -54,6 +57,11 @@ export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (sta
     rows,
     other: {
       active: focused && state.optionIndex === question.options.length,
+      // Text in the row is the tick: it appears on the first character typed and
+      // goes on the first delete that empties the row, without a keystroke of
+      // its own. Read from the live editor text, because typing never reaches
+      // the reducer — `handleIgnoreInline` feeds the editor directly.
+      checked: ctx.inputBuffer.trim().length > 0,
       inputMode: state.inputMode,
       inputBuffer: ctx.inputBuffer,
       inputCursorOffset: ctx.inputCursorOffset,

package/src/state/state-reducer.ts

@@ -8,6 +8,17 @@ 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";
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+function isString(value: JsonValue | undefined): value is string {
+  return typeof value === "string";
+}
 
 /** Session-lifetime constants. No live-component reads — peripheral values live on canonical state. */
 export interface ApplyContext {
@@ -51,7 +62,9 @@ function orderedAnswers(
   const out: QuestionAnswer[] = [];
   for (let i = 0; i < questions.length; i++) {
     const a = state.answers.get(i);
-    if (a) out.push(a);
+    if (a) {
+      out.push(a);
+    }
   }
   return out;
 }
@@ -73,10 +86,14 @@ function unansweredNotesFor(
 ): UnansweredNote[] {
   const out: UnansweredNote[] = [];
   for (let i = 0; i < questions.length; i++) {
-    if (state.answers.has(i)) continue;
+    if (state.answers.has(i)) {
+      continue;
+    }
     const question = questions[i];
     const note = state.notesByTab.get(i);
-    if (!question || note === undefined || note.length === 0) continue;
+    if (!question || note === undefined || note.length === 0) {
+      continue;
+    }
     out.push({ questionIndex: i, question: question.question, note });
   }
   return out;
@@ -88,13 +105,19 @@ function syncMultiSelectFromAnswers(
   tab: number,
 ): ReadonlySet<number> {
   const q = questions[tab];
-  if (!q?.multiSelect) return new Set();
+  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);
+    if (labels.includes(q.options[i]!.label)) {
+      indices.add(i);
+    }
   }
+  // The typed row needs nothing here. Its tick is its text, and the text comes
+  // back with the tab's draft.
   return indices;
 }
 
@@ -103,10 +126,20 @@ function persistMultiSelectAnswer(
   ctx: ApplyContext,
 ): ReadonlyMap<number, QuestionAnswer> {
   const q = ctx.questions[state.currentTab];
-  if (!q?.multiSelect) return state.answers;
+  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);
+    if (state.multiSelectChecked.has(i)) {
+      selected.push(q.options[i]!.label);
+    }
+  }
+  // Text in the typed row is itself the tick, so a non-blank draft joins the
+  // selection. A draft that repeats an option label is not listed twice.
+  const typed = customDraftValueFor(state, state.currentTab).trim();
+  if (typed.length > 0 && !selected.includes(typed)) {
+    selected.push(typed);
   }
   const out = new Map(state.answers);
   if (selected.length === 0) {
@@ -114,22 +147,28 @@ function persistMultiSelectAnswer(
     return out;
   }
   const pendingNotes = state.notesByTab.get(state.currentTab);
-  out.set(state.currentTab, {
+  const entry: QuestionAnswer = {
     questionIndex: state.currentTab,
     question: q.question,
     kind: "multi",
     answer: null,
     selected,
-    ...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
-  });
+  };
+  if (pendingNotes && pendingNotes.length > 0) {
+    // SAFETY: notes is an optional string per QuestionAnswer contract; adding when present preserves the shape.
+    (entry as QuestionAnswer & { notes: string }).notes = pendingNotes;
+  }
+  out.set(state.currentTab, entry);
   return out;
 }
 
 function customDraftValueFor(state: QuestionnaireState, tab: number): string {
   const draft = state.customDraftsByTab.get(tab);
-  if (draft !== undefined) return draft;
+  if (draft !== undefined) {
+    return draft;
+  }
   const answer = state.answers.get(tab);
-  return answer?.kind === "custom" && typeof answer.answer === "string" ? answer.answer : "";
+  return answer?.kind === "custom" && isString(answer.answer) ? answer.answer : "";
 }
 
 function setCustomDraft(
@@ -143,7 +182,9 @@ function setCustomDraft(
 }
 
 function withoutCustomDraft(state: QuestionnaireState, tab: number): ReadonlyMap<number, string> {
-  if (!state.customDraftsByTab.has(tab)) return state.customDraftsByTab;
+  if (!state.customDraftsByTab.has(tab)) {
+    return state.customDraftsByTab;
+  }
   const drafts = new Map(state.customDraftsByTab);
   drafts.delete(tab);
   return drafts;
@@ -189,9 +230,16 @@ function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolea
   const result: QuestionnaireResult = {
     answers: orderedAnswers(state, ctx.questions),
     cancelled,
-    ...(globalNote && globalNote.length > 0 ? { globalNote } : {}),
-    ...(unansweredNotes.length > 0 ? { unansweredNotes } : {}),
   };
+  if (globalNote && globalNote.length > 0) {
+    // SAFETY: globalNote is optional per QuestionnaireResult; present only when non-empty.
+    (result as QuestionnaireResult & { globalNote: string }).globalNote = globalNote;
+  }
+  if (unansweredNotes.length > 0) {
+    // SAFETY: unansweredNotes is optional per QuestionnaireResult; present only when non-empty.
+    (result as QuestionnaireResult & { unansweredNotes: UnansweredNote[] }).unansweredNotes =
+      unansweredNotes;
+  }
   return { state, effects: [{ kind: "done", result }] };
 }
 
@@ -218,7 +266,15 @@ const navHandler: Handler<"nav"> = (state, action, ctx) => {
     inputMode,
     customDraftsByTab,
   };
-  if (!inputMode) return { state: next, effects: [] };
+  // Leaving the typed row: keystrokes never reached the reducer, so this is the
+  // first moment it sees the finished text. Re-state the answer here or the
+  // Submit review quotes a draft that is several characters out of date.
+  if (state.inputMode) {
+    next.answers = persistMultiSelectAnswer(next, ctx);
+  }
+  if (!inputMode) {
+    return { state: next, effects: [] };
+  }
   return {
     state: next,
     effects: [{ kind: "set_input_buffer", value: customDraftValueFor(next, state.currentTab) }],
@@ -256,11 +312,6 @@ const confirmHandler: Handler<"confirm"> = (state, action, ctx) => {
   }
   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)
@@ -269,16 +320,20 @@ const confirmHandler: Handler<"confirm"> = (state, action, ctx) => {
     ...state,
     answers,
     customDraftsByTab,
-    ...(isCustomMulti ? { multiSelectChecked: new Set<number>() } : {}),
   };
-  if (action.autoAdvanceTab !== undefined) return switchTabResult(next, action.autoAdvanceTab, ctx);
+  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);
+  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: [] };
@@ -286,24 +341,31 @@ const toggleHandler: Handler<"toggle"> = (state, action, ctx) => {
 
 const multiConfirmHandler: Handler<"multi_confirm"> = (state, action, ctx) => {
   const q = ctx.questions[state.currentTab];
-  if (!q) return { state, effects: [] };
+  if (!q) {
+    return { state, effects: [] };
+  }
   const pendingNotes = state.notesByTab.get(state.currentTab);
   const answers = new Map(state.answers);
-  answers.set(state.currentTab, {
+  const multiAnswer: QuestionAnswer = {
     questionIndex: state.currentTab,
     question: q.question,
     kind: "multi",
     answer: null,
     selected: action.selected,
-    ...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
-  });
+  };
+  if (pendingNotes && pendingNotes.length > 0) {
+    // SAFETY: notes is optional per QuestionAnswer; adding when present preserves the shape.
+    (multiAnswer as QuestionAnswer & { notes: string }).notes = pendingNotes;
+  }
+  answers.set(state.currentTab, multiAnswer);
   const synced: QuestionnaireState = {
     ...state,
     answers,
     multiSelectChecked: syncMultiSelectFromAnswers(answers, ctx.questions, state.currentTab),
   };
-  if (action.autoAdvanceTab !== undefined)
+  if (action.autoAdvanceTab !== undefined) {
     return switchTabResult(synced, action.autoAdvanceTab, ctx);
+  }
   return doneFor(synced, ctx, false);
 };
 
@@ -327,13 +389,16 @@ const notesExitHandler: Handler<"notes_exit"> = (state, _action, _ctx) => {
     const prev = answers.get(state.currentTab);
     if (prev?.notes) {
       const stripped = { ...prev };
-      delete (stripped as { notes?: string }).notes;
-      answers.set(state.currentTab, stripped);
+      const { notes: _removed, ...withoutNotes } = stripped;
+      // SAFETY: withoutNotes preserves all required QuestionAnswer fields; notes is optional and removed intentionally.
+      answers.set(state.currentTab, withoutNotes as QuestionAnswer);
     }
   } else {
     notes.set(state.currentTab, trimmed);
     const prev = answers.get(state.currentTab);
-    if (prev) answers.set(state.currentTab, { ...prev, notes: trimmed });
+    if (prev) {
+      answers.set(state.currentTab, { ...prev, notes: trimmed });
+    }
   }
   return {
     state: { ...state, notesByTab: notes, answers, notesVisible: false },
@@ -356,7 +421,9 @@ const toggleCollapsedHandler: Handler<"toggle_collapsed"> = (s, _a, _c) => ({
   effects: [{ kind: "set_overlay_hidden", hidden: !s.collapsed }],
 });
 const tickHandler: Handler<"tick"> = (state, action, ctx) => {
-  if (state.timerCancelled || state.deadline === undefined) return { state, effects: [] };
+  if (state.timerCancelled || state.deadline === undefined) {
+    return { state, effects: [] };
+  }
   const remaining = state.deadline - action.now;
   if (remaining > 0) {
     return { state: { ...state, remainingMs: remaining }, effects: [] };
@@ -366,8 +433,11 @@ const tickHandler: Handler<"tick"> = (state, action, ctx) => {
     answers: orderedAnswers(state, ctx.questions),
     cancelled: true,
     error: "timed_out",
-    ...(globalNote && globalNote.length > 0 ? { globalNote } : {}),
   };
+  if (globalNote && globalNote.length > 0) {
+    // SAFETY: globalNote is optional per QuestionnaireResult; present only when non-empty.
+    (result as QuestionnaireResult & { globalNote: string }).globalNote = globalNote;
+  }
   return { state, effects: [{ kind: "done", result }] };
 };
 const ignoreHandler: Handler<"ignore"> = (s, _a, _c) => ({ state: s, effects: [] });
@@ -378,7 +448,7 @@ const ignoreHandler: Handler<"ignore"> = (s, _a, _c) => ({ state: s, effects: []
  * 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> } = {
+const HANDLERS = {
   nav: navHandler,
   input_clear: inputClearHandler,
   input_edit: inputEditHandler,
@@ -396,10 +466,10 @@ const HANDLERS: { [K in QuestionnaireAction["kind"]]: Handler<K> } = {
   toggle_collapsed: toggleCollapsedHandler,
   tick: tickHandler,
   ignore: ignoreHandler,
-};
+} satisfies { [K in QuestionnaireAction["kind"]]: Handler<K> };
 
 /**
- * Pure reducer: (state, action, ctx) → (state, Effect[]). Mirrors `rpiv-todo`'s `applyTaskMutation`.
+ * Pure reducer: (state, action, ctx) → (state, Effect[]).
  * 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.
  */
@@ -408,7 +478,9 @@ export function reduce(
   action: QuestionnaireAction,
   ctx: ApplyContext,
 ): ApplyResult {
+  // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
   const handler = HANDLERS[action.kind] as Handler<typeof action.kind>;
+  // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
   const result = handler(state, action as never, ctx);
   const isHumanKeystroke = action.kind !== "tick" && action.kind !== "toggle_collapsed";
   if (isHumanKeystroke && state.deadline !== undefined && !state.timerCancelled) {