pi-ask-popup 0.1.0

package/src/state/questionnaire-session.ts

@@ -0,0 +1,382 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Editor, OverlayHandle, TUI } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF, formatKeySpecForDisplay } from "../config.js";
+import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/types.js";
+import {
+  COLLAPSED_HINT_TEMPLATE,
+  HINT_PART_CANCEL,
+  KEY_PLACEHOLDER,
+} from "../view/dialog-builder.js";
+import type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
+import { buildQuestionnaire, type QuestionnaireBuilt } from "./build-questionnaire.js";
+import { type QuestionnaireAction, routeKey } from "./key-router.js";
+import type { WrappingSelectItem } from "./row-intent.js";
+import { type ApplyContext, type Effect, reduce } from "./state-reducer.js";
+import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
+
+export interface QuestionnaireSessionConfig {
+  tui: TUI;
+  theme: Theme;
+  params: QuestionParams;
+  itemsByTab: WrappingSelectItem[][];
+  done: (result: QuestionnaireResult) => void;
+  keybindings: QuestionnaireRuntime["keybindings"];
+  /** Opens Pi's configured external editor. Resolves undefined when the launch failed. */
+  editInput: (value: string) => Promise<string | undefined>;
+  /** Resolved collapse key, e.g. `"ctrl+]"`, `"alt+o"` or `"off"`. */
+  collapseKey: string;
+  /**
+   * Whether a raw terminal-input listener is registered, which is the only
+   * thing that can reach a hidden overlay.
+   *
+   * This gates hiding, and it has to. Pi routes no input to a hidden overlay,
+   * so on a host that hands out an `OverlayHandle` but no raw terminal input,
+   * hiding would put the dialog somewhere nothing can bring it back from. That
+   * host gets the visible one-line collapsed row instead, which keeps focus and
+   * keeps receiving keys.
+   */
+  canReopenWhileHidden: boolean;
+}
+
+export interface QuestionnaireSessionComponent {
+  render(width: number): string[];
+  invalidate(): void;
+  handleInput(data: string): void;
+}
+
+function initialState(timeout?: number): QuestionnaireState {
+  if (timeout !== undefined) {
+    const now = Date.now();
+    return {
+      currentTab: 0,
+      optionIndex: 0,
+      inputMode: false,
+      notesVisible: false,
+      answers: new Map(),
+      multiSelectChecked: new Set(),
+      customDraftsByTab: new Map(),
+      notesByTab: new Map(),
+      submitChoiceIndex: 0,
+      notesDraft: "",
+      collapsed: false,
+      timerCancelled: false,
+      deadline: now + timeout,
+      remainingMs: timeout,
+    };
+  }
+  return {
+    currentTab: 0,
+    optionIndex: 0,
+    inputMode: false,
+    notesVisible: false,
+    answers: new Map(),
+    multiSelectChecked: new Set(),
+    customDraftsByTab: new Map(),
+    notesByTab: new Map(),
+    submitChoiceIndex: 0,
+    notesDraft: "",
+    collapsed: false,
+    timerCancelled: false,
+  };
+}
+
+/**
+ * The runtime, and the only impure thing in the design.
+ *
+ * It owns the canonical state cell, the two headless editors, and the effect
+ * runner. Everything that decides what should happen is elsewhere and pure:
+ * `routeKey` turns a keystroke into an action, `reduce` turns an action into a
+ * new state plus a list of effects. This class does what those say, in order,
+ * and then asks the adapter to re-project.
+ */
+export class QuestionnaireSession {
+  private state: QuestionnaireState;
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  private readonly questions: readonly QuestionData[];
+  private readonly isMulti: boolean;
+  private readonly itemsByTab: WrappingSelectItem[][];
+
+  private readonly notesInput: Editor;
+  private readonly inlineInput: Editor;
+  private readonly viewAdapter: QuestionnairePropsAdapter;
+  private readonly keybindings: QuestionnaireRuntime["keybindings"];
+  private readonly editInput: QuestionnaireSessionConfig["editInput"];
+  private readonly collapseKey: string;
+  private readonly canReopenWhileHidden: boolean;
+  private inputEditorOpen = false;
+
+  /**
+   * Arrives from `ctx.ui.custom`'s `onHandle` callback, just after the overlay
+   * exists. Lets the session tell Pi's overlay stack that the dialog is hidden,
+   * so overlay-aware extensions can behave normally while it is collapsed.
+   */
+  private overlayHandle: OverlayHandle | undefined;
+
+  private readonly tui: QuestionnaireSessionConfig["tui"];
+  private readonly done: QuestionnaireSessionConfig["done"];
+  readonly component: QuestionnaireSessionComponent;
+
+  constructor(config: QuestionnaireSessionConfig) {
+    this.state = initialState(config.params.timeout);
+    this.tui = config.tui;
+    // Wrap done so the interval is always cleared, even when the reducer's
+    // expiry path fires `done` directly.
+    const outerDone = config.done;
+    this.done = (result) => {
+      this.clearTimer();
+      outerDone(result);
+    };
+    this.questions = config.params.questions;
+    this.isMulti = this.questions.length > 1;
+    this.itemsByTab = config.itemsByTab;
+    this.keybindings = config.keybindings;
+    this.editInput = config.editInput;
+    this.collapseKey = config.collapseKey;
+    this.canReopenWhileHidden = config.canReopenWhileHidden;
+
+    const built = buildQuestionnaire({
+      tui: this.tui,
+      theme: config.theme,
+      questions: this.questions,
+      itemsByTab: this.itemsByTab,
+      isMulti: this.isMulti,
+      initialState: this.state,
+      getCurrentTab: () => this.state.currentTab,
+      collapseKey: this.collapseKey,
+    });
+
+    this.notesInput = built.notesInput;
+    this.inlineInput = built.inlineInput;
+    this.viewAdapter = built.adapter;
+
+    this.component = this.assembleComponent(built, config.theme);
+    this.viewAdapter.apply(this.state);
+    if (this.state.deadline !== undefined) this.startTimer();
+  }
+
+  private assembleComponent(
+    built: QuestionnaireBuilt,
+    theme: Theme,
+  ): QuestionnaireSessionComponent {
+    const collapsedRender = this.buildCollapsedRender(theme);
+    return {
+      render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
+      invalidate: built.invalidate,
+      handleInput: (data) => this.dispatch(data),
+    };
+  }
+
+  /**
+   * The collapsed rendering: one dim row.
+   *
+   * Pi sizes an overlay to the number of lines it returns, so returning one
+   * line shrinks a full-height bottom-anchored dialog to a single row and makes
+   * the transcript behind it readable. The overlay stays focused and in the
+   * stack, so the collapse key still arrives here to expand it again.
+   *
+   * With the shortcut off the router never toggles this, but
+   * `toggleCollapsedExternal` is a public entry that is not gated, so the line
+   * falls back to cancel-only rather than telling the user to press "Off".
+   */
+  private startTimer(): void {
+    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") {
+      // SAFETY: same guard as above — only called when unref is a function.
+      (this.timer as unknown as { unref: () => void }).unref();
+    }
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== undefined) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private formatRemaining(): string | undefined {
+    if (this.state.timerCancelled) return undefined;
+    const ms = this.state.remainingMs;
+    if (ms === undefined) return undefined;
+    const secs = Math.max(0, Math.ceil(ms / 1000));
+    return `${secs}s`;
+  }
+
+  private buildCollapsedRender(theme: Theme): (width: number) => string[] {
+    const collapseKeyDisplay = formatKeySpecForDisplay(this.collapseKey);
+    const baseHint =
+      this.collapseKey === COLLAPSE_KEY_OFF
+        ? HINT_PART_CANCEL
+        : COLLAPSED_HINT_TEMPLATE.replace(KEY_PLACEHOLDER, collapseKeyDisplay);
+    return (_width: number): string[] => {
+      const rem = this.formatRemaining();
+      const hint = rem ? `${baseHint} \u00b7 ${rem} left` : baseHint;
+      return [theme.fg("dim", ` ${hint} `)];
+    };
+  }
+
+  dispatch(data: string): void {
+    if (this.inputEditorOpen) return;
+    const action = routeKey(data, this.state, this.runtime());
+    if (action.kind === "ignore") {
+      this.handleIgnoreInline(data);
+      return;
+    }
+    this.commit(action);
+  }
+
+  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);
+    this.state = this.mirrorNotesDraft(this.state);
+    this.viewAdapter.apply(this.state);
+  }
+
+  /**
+   * Keep the stored notes draft in step with the editor.
+   *
+   * Read expanded rather than plain: restoring a draft goes through
+   * `Editor.setText`, which clears the editor's paste map, so a draft stored in
+   * its collapsed form would come back with a paste marker pointing at nothing.
+   */
+  private mirrorNotesDraft(s: QuestionnaireState): QuestionnaireState {
+    const draft = this.notesInput.getExpandedText?.() ?? this.notesInput.getText();
+    return s.notesDraft === draft ? s : { ...s, notesDraft: draft };
+  }
+
+  private runEffect(effect: Effect): void {
+    switch (effect.kind) {
+      case "set_input_buffer":
+        this.inlineInput.setText(effect.value);
+        return;
+      case "clear_input_buffer":
+        this.inlineInput.setText("");
+        return;
+      case "open_input_editor":
+        this.openInputEditorAsync(effect.value);
+        return;
+      case "set_notes_value":
+        this.notesInput.setText(effect.value);
+        return;
+      case "set_notes_focused":
+        this.notesInput.focused = effect.focused;
+        return;
+      case "forward_notes_keystroke":
+        this.notesInput.handleInput(effect.data);
+        return;
+      case "set_overlay_hidden":
+        // 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);
+        return;
+      case "clear_timer":
+        this.clearTimer();
+        return;
+      case "done":
+        this.done(effect.result);
+        return;
+    }
+  }
+
+  /**
+   * Hand the draft to the external editor and take back whatever comes out.
+   *
+   * Dispatch is suspended for the duration: the terminal belongs to the editor,
+   * and keystrokes meant for it must not also be routed into the dialog. A
+   * reported launch failure keeps the draft rather than replacing it with
+   * nothing.
+   */
+  private openInputEditorAsync(value: string): void {
+    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 });
+      },
+      () => {
+        this.inputEditorOpen = false;
+      },
+    );
+  }
+
+  /**
+   * The per-keystroke fast path for text the router does not claim.
+   *
+   * Editing is delegated wholesale to Pi's headless editor, which is what gives
+   * the custom-answer row paste, undo, cursor movement and the user's own
+   * newline keybinding for free. The adapter then reads its public text and
+   * cursor, so none of this needs a trip through the reducer.
+   */
+  private handleIgnoreInline(data: string): void {
+    // Any ignored keystroke counts as human-present, so cancel the timer even
+    // when not in inputMode. The normal `reduce` wrapper cannot see this path
+    // because `dispatch` bypasses it for `ignore`.
+    let timerWasCancelled = false;
+    if (this.state.deadline !== undefined && !this.state.timerCancelled) {
+      this.state = { ...this.state, timerCancelled: true, remainingMs: undefined };
+      this.clearTimer();
+      timerWasCancelled = true;
+    }
+    if (!this.state.inputMode) {
+      if (timerWasCancelled) this.viewAdapter.apply(this.state);
+      return;
+    }
+    this.inlineInput.handleInput(data);
+    this.viewAdapter.apply(this.state);
+  }
+
+  private runtime(): QuestionnaireRuntime {
+    const cursor = this.inlineInput.getCursor();
+    const lastLine = this.inlineInput.getLines().length - 1;
+    return {
+      keybindings: this.keybindings,
+      inputBuffer: this.inlineInput.getExpandedText?.() ?? this.inlineInput.getText(),
+      canMoveInputUp: cursor.line > 0,
+      canMoveInputDown: cursor.line < lastLine,
+      questions: this.questions,
+      isMulti: this.isMulti,
+      currentItem: this.currentItem(),
+      items: this.itemsByTab[this.state.currentTab] ?? [],
+      collapseKey: this.collapseKey,
+    };
+  }
+
+  private applyContext(): ApplyContext {
+    return { questions: this.questions, itemsByTab: this.itemsByTab };
+  }
+
+  private currentItem(): WrappingSelectItem | undefined {
+    const items = this.itemsByTab[this.state.currentTab] ?? [];
+    return this.state.optionIndex < items.length ? items[this.state.optionIndex] : undefined;
+  }
+
+  /**
+   * Called by `ctx.ui.custom`'s `onHandle` once the overlay exists. Before this,
+   * hide effects do nothing and the session simply tracks the collapsed flag.
+   */
+  setOverlayHandle(handle: OverlayHandle): void {
+    this.overlayHandle = handle;
+  }
+
+  /**
+   * The way in for the raw terminal listener.
+   *
+   * Pi does not route input to a hidden overlay's `handleInput`, so once the
+   * dialog is hidden the normal dispatch path can never see the key that would
+   * bring it back. The raw listener fires regardless of overlay visibility and
+   * comes in here instead. It still goes through `commit`, so the transition
+   * stays in the reducer and hiding still happens as an effect like everything
+   * else.
+   */
+  toggleCollapsedExternal(): void {
+    if (!this.inputEditorOpen) this.commit({ kind: "toggle_collapsed" });
+  }
+}

package/src/state/row-intent.ts

@@ -0,0 +1,156 @@
+import type { QuestionData } from "../tool/types.js";
+
+/**
+ * Row kind discriminator, and the single source of truth for it.
+ *
+ * Upstream derived this from the view layer's `WrappingSelectItem` union. The
+ * direction is inverted here: intent is a property of the protocol, not of the
+ * renderer, so the union lives at the bottom of the dependency graph and the
+ * view builds its item type from it. The compile-time forcing gets stronger
+ * rather than weaker. Adding a kind here breaks `ROW_INTENT_META` (a
+ * `Record<RowKind, ...>`) AND every exhaustive switch in the renderer, so a new
+ * row cannot ship half-wired.
+ */
+export type RowKind = "option" | "other" | "next";
+
+/**
+ * Sentinel kinds: the protocol-driven rows, as opposed to author-defined
+ * `option` rows. The auto-append walker, the reserved-label derivation and
+ * `LABELS_BY_KIND` all iterate this list.
+ */
+export type SentinelKind = Exclude<RowKind, "option">;
+export const SENTINEL_KINDS: readonly SentinelKind[] = ["other", "next"];
+
+/**
+ * One renderable row. Lives here rather than in the view because it is the
+ * protocol shape a row carries, and both the reducer and the key router read it
+ * without knowing anything about rendering. The option renderer re-exports this
+ * name so view-layer code reads unchanged.
+ *
+ * `kind` narrows exactly as a hand-written union would: `item.kind === "other"`
+ * still discriminates, and a `switch` over it is still exhaustiveness-checked.
+ */
+export interface WrappingSelectItem {
+  kind: RowKind;
+  label: string;
+  description?: string;
+}
+
+/**
+ * Per-kind static metadata. Pure data. No closures, no per-kind handlers.
+ * The behavior-bearing code (answer construction in the key router, the Next
+ * row branch in the multi-select view, the inline editor branch in the option
+ * renderer) keeps its own exhaustive switches and READS these flags.
+ *
+ * Adding a sentinel:
+ *   1. Add the variant to `RowKind`.
+ *   2. Add an entry here. Compilation fails until both edits exist.
+ *   3. If user-facing, synthesize the row wherever it belongs, typically in
+ *      the per-question item builder.
+ *
+ * Field semantics:
+ * - `label` — user-facing text. Empty for `option`, whose label is per-instance
+ *   and comes from `QuestionData.options[i].label`. Every sentinel treats its
+ *   entry here as the single source of truth.
+ * - `reserved` — an authored option carrying this label is rejected at
+ *   validation time. `RESERVED_LABEL_SET` derives from this flag.
+ * - `livesInMainList` — the row appears in the tab's item array.
+ * - `numbered` — the row contributes to main-list numbering. The multi-select
+ *   `Next` row is the only listed row that does not.
+ * - `activatesInputMode` — focusing the row flips `state.inputMode`, turning it
+ *   into an inline editor. Read by the reducer's `nav` case.
+ * - `blocksMultiToggle` — in multi-select, Space and Enter-as-toggle are
+ *   suppressed on this row. `Next` only.
+ * - `autoSubmitsInMulti` — in multi-select, Enter on this row commits the
+ *   question. `Next` only.
+ * - `autoAppendOnSingleSelect` / `autoAppendOnMultiSelect` — whether the item
+ *   builder appends this row in that mode.
+ */
+export interface RowIntentMeta {
+  label: string;
+  reserved: boolean;
+  livesInMainList: boolean;
+  numbered: boolean;
+  activatesInputMode: boolean;
+  blocksMultiToggle: boolean;
+  autoSubmitsInMulti: boolean;
+  autoAppendOnSingleSelect: boolean;
+  autoAppendOnMultiSelect: boolean;
+}
+
+export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
+  option: {
+    label: "",
+    reserved: false,
+    livesInMainList: true,
+    numbered: true,
+    activatesInputMode: false,
+    blocksMultiToggle: false,
+    autoSubmitsInMulti: false,
+    autoAppendOnSingleSelect: false,
+    autoAppendOnMultiSelect: false,
+  },
+  other: {
+    label: "Type something.",
+    reserved: true,
+    livesInMainList: true,
+    numbered: true,
+    activatesInputMode: true,
+    blocksMultiToggle: false,
+    autoSubmitsInMulti: false,
+    autoAppendOnSingleSelect: true,
+    autoAppendOnMultiSelect: true,
+  },
+  next: {
+    label: "Next",
+    reserved: true,
+    livesInMainList: true,
+    numbered: false,
+    activatesInputMode: false,
+    blocksMultiToggle: true,
+    autoSubmitsInMulti: true,
+    autoAppendOnSingleSelect: false,
+    autoAppendOnMultiSelect: true,
+  },
+};
+
+/**
+ * Kind-keyed label view. `option` is excluded because its label is
+ * per-instance rather than per-kind.
+ */
+export const LABELS_BY_KIND: { readonly [K in SentinelKind]: string } = {
+  other: ROW_INTENT_META.other.label,
+  next: ROW_INTENT_META.next.label,
+};
+
+/**
+ * Reserved-label set for runtime validation. Every sentinel marked `reserved`,
+ * plus `"Other"`, which has no runtime row kind at all. `"Other"` is reserved
+ * because models are conditioned to author it as an escape-hatch option; the
+ * runtime sentinel must stay the only way to reach free text.
+ */
+export const RESERVED_LABEL_SET: ReadonlySet<string> = new Set<string>([
+  "Other",
+  ...SENTINEL_KINDS.filter((k) => ROW_INTENT_META[k].reserved).map((k) => ROW_INTENT_META[k].label),
+]);
+
+/**
+ * Walk the metadata table to decide which sentinel rows a question gets.
+ * The two append predicates are mutually exclusive in practice (multi-select
+ * versus single-select) but the walker does not enforce that, so adding a third
+ * bucket needs only a new flag.
+ *
+ * Returns kinds in `SENTINEL_KINDS` order. The caller wraps each into a
+ * renderable row.
+ */
+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;
+    const appends =
+      question.multiSelect === true ? meta.autoAppendOnMultiSelect : meta.autoAppendOnSingleSelect;
+    if (appends) out.push(kind);
+  }
+  return out;
+}

package/src/state/selectors/contract.ts

@@ -0,0 +1,40 @@
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { StatefulView } from "../../view/stateful-view.js";
+import type { TabComponents } from "../../view/tab-components.js";
+import type { QuestionData } from "../../tool/types.js";
+import type { WrappingSelectItem } from "../row-intent.js";
+import type { ActiveView, QuestionnaireState } from "../state.js";
+
+/**
+ * Everything a selector may read besides canonical state. Per-tick and
+ * read-only: the adapter builds one of these per `apply()` and hands the same
+ * object to every binding.
+ *
+ * `activeView` and `WrappingSelectItem` come from the state layer, not from the
+ * view. Which surface owns the keyboard, and what a row means, are canonical
+ * facts; the components only render the answer.
+ */
+export interface BindingContext {
+  readonly questions: readonly QuestionData[];
+  readonly itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+  readonly totalQuestions: number;
+  readonly activeView: ActiveView;
+  readonly inputBuffer: string;
+  /**
+   * Caret position in `inputBuffer`, always known: the adapter computes it from
+   * the editor every tick. The two row views that consume it disagree on
+   * whether their own prop is optional, so pinning it down here is what keeps
+   * one selector from having to satisfy both shapes.
+   */
+  readonly inputCursorOffset: number;
+  readonly activePreviewPane: StatefulView<PreviewPaneProps>;
+}
+
+/** `BindingContext` plus the tab a per-tab binding is currently visiting. */
+export interface PerTabBindingContext extends BindingContext {
+  readonly tab: TabComponents;
+  readonly i: number;
+}
+
+export type GlobalSelector<P> = (state: QuestionnaireState, ctx: BindingContext) => P;
+export type PerTabSelector<P> = (state: QuestionnaireState, ctx: PerTabBindingContext) => P;

package/src/state/selectors/derivations.ts

@@ -0,0 +1,40 @@
+import type { QuestionAnswer, QuestionData } from "../../tool/types.js";
+import type { WrappingSelectItem } from "../row-intent.js";
+
+/**
+ * Which row in the active tab should be marked as "previously confirmed"? Drives the
+ * `WrappingSelect` confirmed-row indicator (label + ` ✔`) when the user navigates back
+ * to a question they already answered. Returns `undefined` when no marker should be drawn —
+ * multi-select handles its own `[✔]` boxes via `multiSelectChecked`, and a missing/non-matching
+ * answer (defensive) silently skips the marker.
+ */
+export function selectConfirmedIndicator(
+  questions: readonly QuestionData[],
+  currentTab: number,
+  answers: ReadonlyMap<number, QuestionAnswer>,
+  items: readonly WrappingSelectItem[],
+): { index: number; labelOverride?: string } | undefined {
+  const q = questions[currentTab];
+  if (!q || q.multiSelect === true) return undefined;
+  const prior = answers.get(currentTab);
+  if (!prior) return undefined;
+  if (prior.kind === "custom") {
+    const otherIndex = items.findIndex((it) => it.kind === "other");
+    if (otherIndex < 0) return undefined;
+    return { index: otherIndex, labelOverride: prior.answer ?? "" };
+  }
+  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;
+  return { index };
+}
+
+/**
+ * Index of the preview pane to display for the current tab. The Submit tab (currentTab ===
+ * questions.length) reuses the last question's pane purely for layout — the strategy
+ * machinery picks the right body component independently. Defensive against `totalQuestions === 0`.
+ */
+export function selectActivePreviewPaneIndex(currentTab: number, totalQuestions: number): number {
+  if (totalQuestions <= 0) return 0;
+  return Math.min(currentTab, totalQuestions - 1);
+}

package/src/state/selectors/focus.ts

@@ -0,0 +1,17 @@
+import type { ActiveView } from "../state.js";
+
+/**
+ * Discriminated focus selector — single source of truth for "which view owns
+ * focus this tick?" Priority order matches the dispatcher cascade
+ * (`key-router.ts`) and the reducer's defensive clears (`state-reducer.ts`).
+ *
+ * Priority: notes > submit > options.
+ */
+export function selectActiveView(
+  state: { notesVisible: boolean; currentTab: number },
+  totalQuestions: number,
+): ActiveView {
+  if (state.notesVisible) return "notes";
+  if (state.currentTab === totalQuestions) return "submit";
+  return "options";
+}