@pellux/goodvibes-tui 1.19.5 → 1.20.0

package/src/input/handler-interactions.ts

@@ -2,7 +2,7 @@ import { buildProviderAccountSnapshot } from '@/runtime/index.ts';
 import { enrichProviderAccountsSnapshot } from '../runtime/onboarding/provider-key-capture.ts';
 import type { OnboardingWizardMode } from './onboarding/onboarding-wizard.ts';
 import { collectOnboardingSnapshot } from '../runtime/onboarding/index.ts';
-import { cleanupMarkerRegistry, expandPrompt, findMarkerAtPos, handleBlockCopy, handleBlockRerun, handleBlockSave, handleBlockToggle, handleBookmark, handleClipboardPaste, handleCopy, handleCtrlC, handleDiffApply, registerPaste } from './handler-content-actions.ts';
+import { cleanupMarkerRegistry, expandPrompt, findMarkerAtPos, handleBlockCopy, handleBlockSave, handleBlockToggle, handleBookmark, handleClipboardPaste, handleCopy, handleCtrlC, handleDiffApply, registerPaste } from './handler-content-actions.ts';
 import { clearModalStack, handleEscape, modalOpened } from './handler-modal-stack.ts';
 import { openOnboardingWizardState, type OpenOnboardingWizardOptions } from './handler-ui-state.ts';
 import type { InputHandlerLike as InputHandler } from './handler-types.ts';
@@ -110,31 +110,34 @@ export function handleCopyForHandler(handler: InputHandler): void {
   }
 
   /**
-   * handleBlockCopy - Ctrl+Y: Copy the content of the nearest code/tool block.
+   * handleBlockCopy - Ctrl+Y: Copy the content of the block the user is
+   * looking at (the viewport's bottom-most visible block — see
+   * InputHandler.getBlockAnchorLine).
    */
 export function handleBlockCopyForHandler(handler: InputHandler): void {
-    handleBlockCopy(handler.conversationManager, handler.getScrollTop, handler.requestRender, () => {
+    handleBlockCopy(handler.conversationManager, () => handler.getBlockAnchorLine(), handler.requestRender, () => {
       handler.lastBlockCopyTime = Date.now();
     });
   }
 
   /**
-   * handleBookmark - Ctrl+B: Toggle bookmark on the nearest block.
+   * handleBookmark - Ctrl+B: Toggle bookmark on the block the user is looking at.
    */
 export function handleBookmarkForHandler(handler: InputHandler): void {
-    handleBookmark(handler.conversationManager, handler.getScrollTop, handler.requestRender, handler.uiServices.shell.bookmarkManager);
+    handleBookmark(handler.conversationManager, () => handler.getBlockAnchorLine(), handler.requestRender, handler.uiServices.shell.bookmarkManager);
   }
 
   /**
-   * handleBlockSave - Ctrl+S: Save nearest block content to a file.
+   * handleBlockSave - Ctrl+S: Save the block the user is looking at to a file.
    */
 export function handleBlockSaveForHandler(handler: InputHandler): void {
-    handleBlockSave(handler.conversationManager, handler.getScrollTop, handler.requestRender, handler.uiServices.shell.bookmarkManager);
+    handleBlockSave(handler.conversationManager, () => handler.getBlockAnchorLine(), handler.requestRender, handler.uiServices.shell.bookmarkManager);
   }
 
   /**
-   * executeBlockAction - Execute a block action ID on the nearest block.
-   * Called when the user selects an action from the BlockActionsMenu.
+   * executeBlockAction - Execute a block action ID on the block the
+   * BlockActionsMenu was opened for. Called when the user selects an action
+   * from the menu.
    */
 export function executeBlockActionForHandler(handler: InputHandler, actionId: string): void {
     switch (actionId) {
@@ -142,33 +145,26 @@ export function executeBlockActionForHandler(handler: InputHandler, actionId: st
       case 'bookmark': handler.handleBookmark(); break;
       case 'toggle':   handler.handleBlockToggle(); break;
       case 'apply':    handler.handleDiffApply(); break;
-      case 'rerun':    handler.handleBlockRerun(); break;
     }
   }
 
   /**
-   * handleBlockRerun - Re-run the tool call for the nearest tool block.
-   * Emits a tool-rerun event for the orchestrator to handle.
-   */
-export function handleBlockRerunForHandler(handler: InputHandler): void {
-    handleBlockRerun(handler.conversationManager, handler.getScrollTop, handler.requestRender);
-  }
-
-  /**
-   * handleBlockToggle - Tab (non-command mode): Toggle collapse of nearest block.
+   * handleBlockToggle - Tab (non-command mode): Toggle collapse of the block
+   * the user is looking at.
    */
 export function handleBlockToggleForHandler(handler: InputHandler): void {
-    handleBlockToggle(handler.conversationManager, handler.getScrollTop, handler.requestRender);
+    handleBlockToggle(handler.conversationManager, () => handler.getBlockAnchorLine(), handler.requestRender);
   }
 
   /**
-   * handleDiffApply - Ctrl+A when a diff block is nearest: request approval and apply the diff.
-   * Returns true if a diff was found and applied (so caller can skip default Ctrl+A).
+   * handleDiffApply - Ctrl+A when a diff block is the one the user is
+   * looking at: request approval and apply the diff. Returns true if a diff
+   * was found and applied (so caller can skip default Ctrl+A).
    */
 export function handleDiffApplyForHandler(handler: InputHandler): boolean {
     return handleDiffApply(
       handler.conversationManager,
-      handler.getScrollTop,
+      () => handler.getBlockAnchorLine(),
       handler.commandContext,
       handler.requestRender,
       () => `diff-apply-${Date.now()}`,

package/src/input/handler-modal-token-routes.ts

@@ -1,5 +1,6 @@
 import type { InputToken } from '@pellux/goodvibes-sdk/platform/core';
 import type { InfiniteBuffer } from '../core/history.ts';
+import type { ConversationManager } from '../core/conversation';
 import type { SelectionResult, SelectionModal } from './selection-modal.ts';
 import type { BookmarkModal } from './bookmark-modal.ts';
 import type { SettingsModal } from './settings-modal.ts';
@@ -34,6 +35,9 @@ import {
 
 export type ModalTokenRouteState = {
   history: InfiniteBuffer;
+  /** Threaded into SearchManager.search() so a matching but currently-
+   *  collapsed block gets auto-expanded before the buffer is scanned. */
+  conversationManager?: ConversationManager | null;
   searchShortcutMatch: boolean;
   selectionModal: SelectionModal;
   selectionCallback: ((result: SelectionResult | null) => void) | null;
@@ -108,6 +112,7 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
     scroll: state.scroll,
     getScrollTop: state.getScrollTop,
     getViewportHeight: state.getViewportHeight,
+    conversationManager: state.conversationManager,
   }, token, state.history, state.searchShortcutMatch)) {
     return withState(state, true);
   }

package/src/input/handler-types.ts

@@ -130,7 +130,10 @@ export interface InputHandlerLike {
   handleBookmark(): void;
   handleBlockToggle(): void;
   handleDiffApply(): boolean;
-  handleBlockRerun(): void;
+  /** The absolute history line of the bottom-most visible block — the block
+   *  the user is actually looking at — used to anchor every one of the
+   *  actions above instead of the (possibly off-screen-above) raw scrollTop. */
+  getBlockAnchorLine(): number;
 
   // ── Methods: onboarding ───────────────────────────────────────────────────
   hydrateOnboardingWizardFromRuntime(hydrationSerial: number): Promise<void>;

package/src/input/handler-ui-state.ts

@@ -2,6 +2,7 @@ import type { InputToken } from '@pellux/goodvibes-sdk/platform/core';
 import type { InfiniteBuffer } from '../core/history.ts';
 import type { SearchManager } from './search.ts';
 import type { HistorySearch } from './input-history.ts';
+import type { ConversationManager } from '../core/conversation';
 import type {
   OnboardingWizardController,
   OnboardingWizardMode,
@@ -202,6 +203,9 @@ type SearchRouteState = {
   scroll: (delta: number) => void;
   getScrollTop: () => number;
   getViewportHeight: () => number;
+  /** Optional — when present, search() also expands collapsed blocks whose
+   *  raw content matches (see SearchManager.search's doc). */
+  conversationManager?: ConversationManager | null;
 };
 
 export function handleSearchModeToken(
@@ -216,7 +220,7 @@ export function handleSearchModeToken(
   if (!searchManager.locked) {
     if (token.type === 'text') {
       const newQuery = searchManager.query + token.value;
-      searchManager.search(newQuery, history);
+      searchManager.search(newQuery, history, state.conversationManager);
     } else if (token.type === 'key') {
       if (token.logicalName === 'escape') {
         searchManager.close();
@@ -230,7 +234,7 @@ export function handleSearchModeToken(
         }
       } else if (token.logicalName === 'backspace') {
         const newQuery = searchManager.query.slice(0, -1);
-        searchManager.search(newQuery, history);
+        searchManager.search(newQuery, history, state.conversationManager);
       } else if (matchesSearchShortcut) {
         searchManager.close();
       }

package/src/input/handler.ts

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { dirname } from 'node:path';
 import { InputTokenizer } from '@pellux/goodvibes-sdk/platform/core';
 import { createOAuthLocalListener } from '@pellux/goodvibes-sdk/platform/config';
-import { clearModalStackForHandler, cleanupMarkerRegistryForHandler, executeBlockActionForHandler, expandPromptForHandler, findMarkerAtPosForHandler, getImageAttachmentsForHandler, handleBlockCopyForHandler, handleBlockRerunForHandler, handleBlockSaveForHandler, handleBlockToggleForHandler, handleBookmarkForHandler, handleCopyForHandler, handleCtrlCForHandler, handleDiffApplyForHandler, handleEscapeForHandler, hydrateOnboardingWizardFromRuntimeForHandler, modalOpenedForHandler, openOnboardingWizardForHandler, registerPasteForHandler } from './handler-interactions.ts';
+import { clearModalStackForHandler, cleanupMarkerRegistryForHandler, executeBlockActionForHandler, expandPromptForHandler, findMarkerAtPosForHandler, getImageAttachmentsForHandler, handleBlockCopyForHandler, handleBlockSaveForHandler, handleBlockToggleForHandler, handleBookmarkForHandler, handleCopyForHandler, handleCtrlCForHandler, handleDiffApplyForHandler, handleEscapeForHandler, hydrateOnboardingWizardFromRuntimeForHandler, modalOpenedForHandler, openOnboardingWizardForHandler, registerPasteForHandler } from './handler-interactions.ts';
+import { getViewportBottomLine } from '../renderer/conversation-layout.ts';
 import { clearOnboardingModelPickerCancelStateForHandler, clearOnboardingPendingModelPickerTargetForHandler, completeOpenAiSubscriptionFromListenerForHandler, getOnboardingConfigValueForHandler, getOnboardingRuntimePostureForHandler, handleModelPickerCommitForHandler, handleOnboardingActionForHandler, handleOpenAiSubscriptionFinishForHandler, handleOpenAiSubscriptionStartForHandler, openModelPickerWithTargetForHandler, openProviderModelPickerWithTargetForHandler, refreshOnboardingHydrationForHandler, restartOnboardingExternalServicesIfNeededForHandler, restoreOnboardingModelPickerCancelStateForHandler, saveWizardProgressForHandler, syncRuntimeFromOnboardingRequestForHandler, verifyOnboardingRuntimePostureForHandler, } from './handler-onboarding.ts';
 import type { OnboardingRuntimePosture } from './handler-types.ts';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
@@ -48,7 +49,6 @@ import {
   findMarkerAtPos,
   formatFileSize,
   handleBlockCopy,
-  handleBlockRerun,
   handleBlockSave,
   handleBlockToggle,
   handleBookmark,
@@ -83,6 +83,7 @@ import {
 import { KillRing } from './kill-ring.ts';
 import { maskConcealedText, beginConcealedInputFor, submitConcealedInputFor, cancelConcealedInputFor, type ConcealedInputRequest } from './concealed-input.ts';
 import { clearModalStack, handleEscape, modalOpened } from './handler-modal-stack.ts';
+import { SelectionModalQueue, attachSelectionModalQueue } from './selection-modal-queue.ts';
 import { handleModalTokenRoutes } from './handler-modal-token-routes.ts';
 import {
   captureOnboardingWizardSnapshot,
@@ -222,6 +223,8 @@ export class InputHandler implements InputHandlerLike {
   public conversationManager: ConversationManager | null = null;
   public selectionCallback: SelectionModalCallback | null = null;
   public syncFeedSelectionCallback: ((callback: SelectionModalCallback | null) => void) | null = null;
+  /** FIFO queue for overlapping openSelection() calls — see selection-modal-queue.ts. */
+  private selectionQueue!: SelectionModalQueue;
   /** Time of last [COPIED] block feedback, for brief display. */
   public lastBlockCopyTime = 0;
   public mouseDownRow = -1;
@@ -282,6 +285,7 @@ export class InputHandler implements InputHandlerLike {
     this.bookmarkModal = new BookmarkModal(uiServices.shell.bookmarkManager);
     this.sessionPickerModal = new SessionPickerModal(uiServices.sessions.sessionManager, uiServices.sessions.sessionBroker);
     this.profilePickerModal = new ProfilePickerModal(uiServices.shell.profileManager);
+    this.selectionQueue = attachSelectionModalQueue(this); // wires exitApp teardown too — see selection-modal-queue.ts
     this.initFeedContext();
   }
 
@@ -404,6 +408,8 @@ export class InputHandler implements InputHandlerLike {
   /**
    * openSelection - Open the generic selection modal with a callback.
    * The callback receives SelectionResult on selection, or null on cancel/escape.
+   * A second call while one is already showing queues FIFO instead of
+   * overwriting it — see selection-modal-queue.ts.
    */
   public openSelection(
     title: string,
@@ -416,14 +422,9 @@ export class InputHandler implements InputHandlerLike {
     } | undefined,
     callback: SelectionModalCallback,
   ): void {
-    this.modalOpened('selection');
-    this.selectionModal.open(title, items, opts);
-    this.selectionCallback = callback;
-    this.syncFeedSelectionCallback?.(callback);
-    this.requestRender();
+    this.selectionQueue.request({ title, items, opts, callback });
   }
 
-
   public openOnboardingWizard(
     modeOrOptions: OnboardingWizardMode | OpenOnboardingWizardOptions = 'new',
   ): void { openOnboardingWizardForHandler(this, modeOrOptions); }
@@ -439,7 +440,16 @@ export class InputHandler implements InputHandlerLike {
   public handleBookmark(): void { handleBookmarkForHandler(this); }
   public handleBlockSave(): void { handleBlockSaveForHandler(this); }
   public executeBlockAction(actionId: string): void { executeBlockActionForHandler(this, actionId); }
-  public handleBlockRerun(): void { handleBlockRerunForHandler(this); }
+  /** The block the user is actually looking at: the viewport's bottom-most
+   *  visible line (see getViewportBottomLine's doc) — not the raw scrollTop,
+   *  which is off-screen-above once the transcript exceeds one page. Every
+   *  anchor-based block action (Ctrl+Y/B/S/A, Tab, the block-actions menu)
+   *  resolves its target through this, so they all agree on what "nearest
+   *  block" means. */
+  public getBlockAnchorLine(): number {
+    const lineCount = this.conversationManager?.history.getLineCount() ?? 0;
+    return getViewportBottomLine(this.getScrollTop(), this.getViewportHeight(), lineCount);
+  }
   public handleBlockToggle(): void { handleBlockToggleForHandler(this); }
   public handleDiffApply(): boolean { return handleDiffApplyForHandler(this); }
   public handleCtrlC(): void { handleCtrlCForHandler(this); }

package/src/input/search.ts

@@ -1,4 +1,5 @@
 import type { InfiniteBuffer } from '../core/history.ts';
+import type { ConversationManager } from '../core/conversation';
 
 export interface SearchMatch {
   line: number;
@@ -50,8 +51,37 @@ export class SearchManager {
     this.locked = false;
   }
 
-  /** Update query and find matches in the history buffer. */
-  search(query: string, history: InfiniteBuffer): void {
+  /**
+   * Update query and find matches in the history buffer.
+   *
+   * A collapsed block (or folded tool-result group) renders 1-2 summary
+   * lines, so scanning only the rendered buffer misses text the user watched
+   * stream by before it folded. When `conversationManager` is provided, any
+   * currently-collapsed block whose searchable corpus contains the query is
+   * expanded first (never re-collapsed — a false "No matches" is a lie, an
+   * extra expand is not), so the match becomes a real, navigable line in the
+   * rendered buffer scanned below.
+   *
+   * That corpus is the block's own RAW content, plus — for a folded
+   * tool-result group — the raw content of every one of its member messages.
+   * A group's own rawContent is only its summary header line ("2 tool results
+   * folded (read exec, 18 lines total)") and its members push no BlockMeta of
+   * their own while folded (see conversation-tool-groups.ts), so without the
+   * member corpus a needle living inside a member matches nothing at all and
+   * the user gets "No matches" for text they watched stream by. Member text is
+   * read off the message snapshot, and is the same string the renderer stores
+   * as that member's own block rawContent once the group is expanded.
+   *
+   * A hit anywhere in that corpus expands the group's own collapseKey AND
+   * every member's `msg_<idx>` key — expanding the header alone would leave
+   * the member holding the hit invisible, and expanding all members keeps the
+   * behavior identical whether the hit came from the header or a member.
+   *
+   * `getDisplayBlocks()` is flushed before the buffer is scanned, and the
+   * overlay's match count is always derived from that same rendered scan, so
+   * it never claims more than it can actually navigate to.
+   */
+  search(query: string, history: InfiniteBuffer, conversationManager?: ConversationManager | null): void {
     this.query = query;
     this.matches = [];
     this.currentMatch = 0;
@@ -60,6 +90,68 @@ export class SearchManager {
     if (query.length === 0) return;
 
     const lowerQuery = query.toLowerCase();
+
+    if (conversationManager) {
+      const registry = conversationManager.getBlockRegistry();
+
+      // A folded tool-result group's members render nothing and register no
+      // BlockMeta while collapsed (see conversation-tool-groups.ts), so the
+      // group's searchable corpus is its own header rawContent PLUS each
+      // member's raw content — which only the message snapshot can supply,
+      // since there is no member block to read it from.
+      const memberIndexes: number[] = [];
+      for (const block of registry) {
+        if (block.type !== 'tool_group' || !block.groupMemberIndexes) continue;
+        if (!conversationManager.isCollapsed(block.blockIndex)) continue;
+        memberIndexes.push(...block.groupMemberIndexes);
+      }
+
+      // Read in ONE snapshot pass: getMessageSnapshot() clones the whole
+      // message array (~0.8ms on a 900-message conversation) and search() runs
+      // on every keystroke, so a per-member read would stall typing outright.
+      // Skipped entirely when nothing is folded.
+      const memberContent = new Map<number, string>();
+      if (memberIndexes.length > 0) {
+        const snapshot = conversationManager.getMessageSnapshot();
+        for (const memberIdx of memberIndexes) {
+          // This is the exact string the renderer stores as a member's own
+          // block rawContent (renderConversationToolMessage in
+          // conversation-rendering.ts) — the corpus is what expanding really
+          // reveals, not a second notion of "content". A member index that
+          // outlived its message (undo() splices the messages tail while a
+          // stale registry still names it) reads back undefined and is simply
+          // skipped rather than throwing.
+          const content = snapshot[memberIdx]?.content;
+          if (typeof content === 'string') memberContent.set(memberIdx, content.toLowerCase());
+        }
+      }
+
+      let expandedAny = false;
+      for (const block of registry) {
+        if (!conversationManager.isCollapsed(block.blockIndex)) continue;
+        const members = block.type === 'tool_group' ? (block.groupMemberIndexes ?? []) : [];
+        const hit = block.rawContent.toLowerCase().includes(lowerQuery)
+          || members.some((memberIdx) => (memberContent.get(memberIdx) ?? '').includes(lowerQuery));
+        if (!hit) continue;
+        conversationManager.setCollapsed(block.collapseKey, false);
+        // Expanding just the group header would still hide each member's own
+        // content — including the member the query actually matched — so open
+        // every member's own collapse key in the same pass. Already-expanded
+        // keys are unaffected; setting false over false is a no-op.
+        for (const memberIdx of members) {
+          conversationManager.setCollapsed(`msg_${memberIdx}`, false);
+        }
+        expandedAny = true;
+      }
+      if (expandedAny) {
+        // Flush the pending re-render so `history` (the same buffer
+        // instance) reflects the newly-expanded content before it's scanned
+        // below — mirrors the existing getDisplayBlocks()-before-read idiom
+        // used by jumpToBookmark/scrollToLine.
+        conversationManager.getDisplayBlocks();
+      }
+    }
+
     const lines = history.getAllLines();
 
     for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {

package/src/input/selection-modal-queue.ts

@@ -0,0 +1,176 @@
+/**
+ * selection-modal-queue.ts — Serializes overlapping InputHandler.openSelection() calls.
+ *
+ * openSelection (handler.ts) writes into a singleton SelectionModal plus a
+ * single callback slot. A second openSelection call while one is already
+ * showing used to silently overwrite both — the pre-empted caller's callback
+ * was never invoked, not even with null, so any caller that awaits it (see
+ * the `ask()` helper in runtime/recovery-prompt.ts, which wraps the callback
+ * in a Promise) hung forever. This is reachable in production: the
+ * `--continue` liveness-confirm modal (session-resume-liveness-confirm.ts)
+ * races the startup recovery offer, which is scheduled on a 0ms macrotask
+ * (scheduleRecoveryOffer in runtime/recovery-prompt.ts).
+ *
+ * Fix: queue overlapping requests FIFO and open each automatically once the
+ * previous one resolves, through the SAME callback the caller already
+ * supplied — openSelection's public signature never changes.
+ *
+ * Why the drain is deferred to a microtask instead of running inline inside
+ * the resolving callback: both resolution paths — the select/enter path in
+ * handler-modal-routes.ts's dispatchSelectionAction, and the Escape path in
+ * handler-modal-stack.ts's handleEscape/closeSelection — take a snapshot of
+ * the current selectionCallback before dispatch and write some form of that
+ * snapshot back into handler/context state AFTER invoking the callback (the
+ * select path re-reads via getSelectionCallback; the Escape path threads a
+ * local variable back out through handleEscapeForHandler in
+ * handler-interactions.ts). If this module opened the next queued request
+ * synchronously inside the resolving callback, those post-callback
+ * write-backs would immediately clobber the freshly-set callback for the
+ * newly-opened modal. Deferring past the end of the synchronous resolution
+ * (queueMicrotask) lets all of that settle first, then opens the next
+ * request cleanly — the same shape as the production race this fixes, which
+ * itself resolves via a deferred (macrotask) call.
+ */
+import type { SelectionItem, SelectionAction, SelectionResult, SelectionModal } from './selection-modal.ts';
+
+export type SelectionModalCallback = (result: SelectionResult | null) => void;
+
+export interface SelectionOpenOpts {
+  preSelectId?: string;
+  allowSearch?: boolean;
+  customActions?: Map<string, SelectionAction>;
+  primaryVerbLabel?: string;
+}
+
+export interface PendingSelectionRequest {
+  readonly title: string;
+  readonly items: SelectionItem[];
+  readonly opts: SelectionOpenOpts | undefined;
+  readonly callback: SelectionModalCallback;
+}
+
+/**
+ * Maximum number of openSelection() calls held while one is already showing.
+ * In practice at most two calls ever race in production (the liveness-confirm
+ * modal vs. the recovery offer's 0ms macrotask), so 8 is generous headroom
+ * for any future chained-picker sequence without letting a misbehaving
+ * caller queue without bound. Once full, the overflowing call is resolved
+ * with `null` immediately — a bounded queue must still give every caller a
+ * definite answer, never silently drop one.
+ */
+export const MAX_QUEUED_SELECTIONS = 8;
+
+/** Dependencies the queue needs from InputHandler, kept minimal and explicit. */
+export interface SelectionQueueHost {
+  readonly selectionModal: Pick<SelectionModal, 'active' | 'open'>;
+  /** Assigns InputHandler.selectionCallback (the live resolution slot). */
+  setSelectionCallback(callback: SelectionModalCallback | null): void;
+  /** Mirrors the callback into the in-flight feed context, when a feed() call is in progress (no-op otherwise). */
+  syncFeedSelectionCallback(callback: SelectionModalCallback | null): void;
+  modalOpened(name: string): void;
+  requestRender(): void;
+}
+
+/** Owns the FIFO of pending openSelection() requests for one InputHandler instance. */
+export class SelectionModalQueue {
+  private readonly pending: PendingSelectionRequest[] = [];
+
+  constructor(private readonly host: SelectionQueueHost) {}
+
+  /** Number of requests currently queued (excludes whichever modal is actively showing, if any). */
+  public get size(): number {
+    return this.pending.length;
+  }
+
+  /**
+   * Open `request` immediately if no selection modal is currently showing;
+   * otherwise queue it FIFO. If the queue is already at MAX_QUEUED_SELECTIONS,
+   * the request is resolved with `null` right away instead of being queued.
+   */
+  public request(request: PendingSelectionRequest): void {
+    if (this.host.selectionModal.active) {
+      if (this.pending.length >= MAX_QUEUED_SELECTIONS) {
+        request.callback(null);
+        return;
+      }
+      this.pending.push(request);
+      return;
+    }
+    this.openNow(request);
+  }
+
+  /**
+   * Resolve every still-queued request with `null`. Called when the handler
+   * is torn down (see the exitApp wrap in handler.ts's constructor) so no
+   * queued caller is ever left permanently pending.
+   */
+  public clear(): void {
+    while (this.pending.length > 0) {
+      const next = this.pending.shift();
+      next?.callback(null);
+    }
+  }
+
+  private openNow(request: PendingSelectionRequest): void {
+    const wrapped: SelectionModalCallback = (result) => {
+      request.callback(result);
+      // Only a terminal resolution (select/cancel/escape) actually closes
+      // the modal — dispatchSelectionAction's toggle/increment/decrement
+      // branch invokes the callback but leaves the modal open for further
+      // interaction, so only drain the queue once the modal has gone
+      // inactive, never on every callback invocation.
+      if (!this.host.selectionModal.active) {
+        queueMicrotask(() => this.drain());
+      }
+    };
+    this.host.modalOpened('selection');
+    this.host.selectionModal.open(request.title, request.items, request.opts);
+    this.host.setSelectionCallback(wrapped);
+    this.host.syncFeedSelectionCallback(wrapped);
+    this.host.requestRender();
+  }
+
+  private drain(): void {
+    // Something else already opened a modal in the meantime (e.g. a
+    // synchronously chained openSelection call from inside the resolving
+    // callback) — leave the queue alone; that modal's own resolution will
+    // drain it in turn.
+    if (this.host.selectionModal.active) return;
+    const next = this.pending.shift();
+    if (!next) return;
+    this.openNow(next);
+  }
+}
+
+/** InputHandler's actual field/method shape — satisfies this structurally, no import needed. */
+export interface SelectionQueueOwner {
+  readonly selectionModal: Pick<SelectionModal, 'active' | 'open'>;
+  selectionCallback: SelectionModalCallback | null;
+  syncFeedSelectionCallback: ((callback: SelectionModalCallback | null) => void) | null;
+  modalOpened(name: string): void;
+  requestRender(): void;
+  exitApp: () => void;
+}
+
+/**
+ * Builds the queue for one InputHandler and wires teardown: wraps
+ * `owner.exitApp` (the one path guaranteed to run when the handler is torn
+ * down) so every still-queued selection request resolves with `null`
+ * instead of being left pending. Keeps this bookkeeping out of handler.ts,
+ * which only needs `this.selectionQueue = attachSelectionModalQueue(this);`.
+ */
+export function attachSelectionModalQueue(owner: SelectionQueueOwner): SelectionModalQueue {
+  const queue = new SelectionModalQueue({
+    selectionModal: owner.selectionModal,
+    setSelectionCallback: (callback) => { owner.selectionCallback = callback; },
+    syncFeedSelectionCallback: (callback) => { owner.syncFeedSelectionCallback?.(callback); },
+    modalOpened: (name) => owner.modalOpened(name),
+    requestRender: () => owner.requestRender(),
+  });
+  const suppliedExitApp = owner.exitApp;
+  owner.exitApp = () => {
+    queue.clear();
+    suppliedExitApp();
+  };
+  return queue;
+}