@pellux/goodvibes-tui 2.0.20 → 2.1.0

package/src/input/handler-modal-stack.ts

@@ -8,8 +8,7 @@ import type { SelectionResult } from './selection-modal.ts';
 
 export type ModalStackState = ActiveModalState & {
   modalStack: string[];
-  modalReturnFocus?: 'prompt' | 'panel' | 'indicator';
-  panelFocused: boolean;
+  modalReturnFocus?: 'prompt' | 'indicator';
   indicatorFocused: boolean;
 };
 
@@ -20,7 +19,7 @@ export function modalOpened(state: ModalStackState, name: string): void {
   if (state.modalStack[state.modalStack.length - 1] === name) return;
   if (state.modalStack.includes(name)) return;
   if (state.modalStack.length === 0) {
-    state.modalReturnFocus = state.indicatorFocused ? 'indicator' : state.panelFocused ? 'panel' : 'prompt';
+    state.modalReturnFocus = state.indicatorFocused ? 'indicator' : 'prompt';
   }
   state.modalStack.push(name);
 }
@@ -49,10 +48,34 @@ export type EscapeState = ModalStackState & {
   selectionModal: ModalStackState['selectionModal'];
   autocompleteReset: () => void;
   autocompleteUpdate?: (query: string) => void;
+  /**
+   * An agent or process view (core/session-focus.ts). With no modal open and
+   * the composer empty, Esc there goes back up one level (closing the
+   * process view's search first) and never reaches cancelGeneration: leaving
+   * a view never stops the agent, the process or main.
+   */
+  sessionView?: { readonly active: boolean; escape(): void };
+  /**
+   * The main transcript's scroll. While it is scrolled away from the live
+   * bottom (and no modal, composer text or view took the Esc first), Esc
+   * returns to the bottom and re-locks there; it never reaches
+   * cancelGeneration then. At the bottom the next Esc interrupts as before.
+   */
+  transcriptScroll?: TranscriptScrollControls;
+  /** Kit modals: the top one (or its own sub-level) is the first thing Esc pops. */
+  surfaceModals?: { readonly active: boolean; escape(): boolean };
   clearOnboardingModelPickerCancelState?: () => void;
   restoreOnboardingModelPickerCancelState?: () => void;
 };
 
+/** What handleEscape needs of the main transcript's scroll. */
+export interface TranscriptScrollControls {
+  /** The main transcript is scrolled away from its live bottom. */
+  scrolledBack(): boolean;
+  /** Return to the live bottom and follow it again. */
+  toBottom(): void;
+}
+
 export function handleEscape(state: EscapeState): {
   prompt: string;
   cursorPos: number;
@@ -62,7 +85,6 @@ export function handleEscape(state: EscapeState): {
   shortcutsOverlayActive: boolean;
   shortcutsScrollOffset: number;
   selectionCallback: ((result: SelectionResult | null) => void) | null;
-  panelFocused: boolean;
   indicatorFocused: boolean;
   modalReturnFocus: NonNullable<ModalStackState['modalReturnFocus']>;
 } {
@@ -74,7 +96,6 @@ export function handleEscape(state: EscapeState): {
   let shortcutsOverlayActive = state.shortcutsOverlayActive;
   let shortcutsScrollOffset = state.shortcutsScrollOffset;
   let selectionCallback = state.selectionCallback;
-  let panelFocused = state.panelFocused;
   let indicatorFocused = state.indicatorFocused;
   let modalReturnFocus: NonNullable<ModalStackState['modalReturnFocus']> = state.modalReturnFocus ?? 'prompt';
 
@@ -85,12 +106,29 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       commandMode,
     }) !== null) return;
-    panelFocused = modalReturnFocus === 'panel';
     indicatorFocused = modalReturnFocus === 'indicator';
     modalReturnFocus = 'prompt';
     state.modalReturnFocus = 'prompt';
   };
 
+  // Kit modals are always on top: one Esc pops one of their levels and stops.
+  if (state.surfaceModals?.active) {
+    state.surfaceModals.escape();
+    state.requestRender();
+    return {
+      prompt,
+      cursorPos,
+      commandMode,
+      helpOverlayActive,
+      helpScrollOffset,
+      shortcutsOverlayActive,
+      shortcutsScrollOffset,
+      selectionCallback,
+      indicatorFocused,
+      modalReturnFocus,
+    };
+  }
+
   if (state.settingsModal.active && state.settingsModal.editingMode) {
     state.settingsModal.cancelEdit();
     state.requestRender();
@@ -103,7 +141,6 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       shortcutsScrollOffset,
       selectionCallback,
-      panelFocused,
       indicatorFocused,
       modalReturnFocus,
     };
@@ -200,7 +237,6 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       shortcutsScrollOffset,
       selectionCallback,
-      panelFocused,
       indicatorFocused,
       modalReturnFocus,
     };
@@ -225,7 +261,6 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       shortcutsScrollOffset,
       selectionCallback,
-      panelFocused,
       indicatorFocused,
       modalReturnFocus,
     };
@@ -244,7 +279,43 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       shortcutsScrollOffset,
       selectionCallback,
-      panelFocused,
+      indicatorFocused,
+      modalReturnFocus,
+    };
+  }
+
+  // Inside an agent or process view Esc goes up one level and stops here:
+  // interrupting belongs to main alone.
+  if (state.sessionView?.active) {
+    state.sessionView.escape();
+    state.requestRender();
+    return {
+      prompt,
+      cursorPos,
+      commandMode,
+      helpOverlayActive,
+      helpScrollOffset,
+      shortcutsOverlayActive,
+      shortcutsScrollOffset,
+      selectionCallback,
+      indicatorFocused,
+      modalReturnFocus,
+    };
+  }
+
+  // Scrolled back: Esc returns to the live output and never interrupts the turn.
+  if (state.transcriptScroll?.scrolledBack()) {
+    state.transcriptScroll.toBottom();
+    state.requestRender();
+    return {
+      prompt,
+      cursorPos,
+      commandMode,
+      helpOverlayActive,
+      helpScrollOffset,
+      shortcutsOverlayActive,
+      shortcutsScrollOffset,
+      selectionCallback,
       indicatorFocused,
       modalReturnFocus,
     };
@@ -260,7 +331,6 @@ export function handleEscape(state: EscapeState): {
     shortcutsOverlayActive,
     shortcutsScrollOffset,
     selectionCallback,
-    panelFocused,
     indicatorFocused,
     modalReturnFocus,
   };

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

@@ -12,6 +12,7 @@ import type { ModelPickerModal } from './model-picker.ts';
 import { handleMcpWorkspaceToken, type McpWorkspace } from './mcp-workspace.ts';
 import type { CommandContext } from './command-registry.ts';
 import type { ContextInspectorModal } from '../renderer/context-inspector.ts';
+import type { OverlayFilters } from './overlay-filter.ts';
 import type { FilePickerModal } from './file-picker.ts';
 import type { BlockActionsMenu, BlockActionId } from '../renderer/block-actions.ts';
 import type { SearchManager } from './search.ts';
@@ -64,6 +65,7 @@ export type ModalTokenRouteState = {
   requestRender: () => void;
   handleEscape: () => void;
   contextInspectorModal: ContextInspectorModal;
+  overlayFilters?: OverlayFilters;
   modalOpened: (name: string) => void;
   filePicker: FilePickerModal;
   imageRegistry: Map<string, { data: string; mediaType: string }>;
@@ -191,6 +193,7 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
     helpScrollOffset: state.helpScrollOffset,
     shortcutsOverlayActive: state.shortcutsOverlayActive,
     shortcutsScrollOffset: state.shortcutsScrollOffset,
+    overlayFilters: state.overlayFilters,
     requestRender: state.requestRender,
     handleEscape: state.handleEscape,
   };
@@ -241,6 +244,7 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
     active: state.contextInspectorModal.active,
     requestRender: state.requestRender,
     handleEscape: state.handleEscape,
+    scroll: (delta) => state.contextInspectorModal.scrollBy(delta),
   }, token)) {
     return withState(state, true);
   }

package/src/input/handler-onboarding.ts

@@ -348,7 +348,6 @@ export async function handleOnboardingActionForHandler(handler: InputHandler, ac
     }
     if (handler.modalStack.length === 0) {
       const returnFocus = handler.modalReturnFocus;
-      handler.panelFocused = returnFocus === 'panel';
       handler.indicatorFocused = returnFocus === 'indicator';
       handler.modalReturnFocus = 'prompt';
     }

package/src/input/handler-picker-routes.ts

@@ -4,6 +4,7 @@ import type { CommandContext } from './command-registry.ts';
 import type { CapabilityFilter, CategoryFilter, ModelPickerModal } from './model-picker.ts';
 import { MODEL_PICKER_CHROME_LINES } from '../renderer/model-picker-overlay.ts';
 import { ensureProviderKeyThenSelect } from './provider-key-intake.ts';
+import { isTextBackspace } from './delete-key-policy.ts';
 import { resolveAndValidatePath } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import type { BlockActionId } from '../renderer/block-actions.ts';
@@ -49,17 +50,10 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
 
   if (token.type === 'key') {
     if (token.logicalName === 'escape') {
-      // Search now starts focused by default (see
-      // ModelPickerModal.openAllModels() doc comment). Escape with an empty
-      // query used to only blurSearch() here, leaving the picker open and
-      // requiring a SECOND Escape to actually close it, confusing on a
-      // freshly-opened, untouched picker where there is nothing to "clear".
-      // Clearing a non-empty query is still a distinct first Escape (whether
-      // or not search is focused); an empty query falls through to the same
-      // effort/contextCap/previousMode/close cascade as before.
-      if (state.modelPicker.mode !== 'contextCap' && state.modelPicker.query.length > 0) {
-        state.modelPicker.clearQuery();
-      } else if (state.modelPicker.mode === 'effort') {
+      // Esc pops exactly one level: the effort and context-cap steps and a
+      // provider-first model list are sub-levels of the picker; otherwise the
+      // picker closes. A typed query is not a level, it goes with the picker.
+      if (state.modelPicker.mode === 'effort') {
         state.modelPicker.mode = 'model';
         state.modelPicker.selectedIndex = 0;
       } else if (state.modelPicker.mode === 'contextCap') {
@@ -73,11 +67,11 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
         state.handleEscape();
         return true;
       }
-    } else if (token.logicalName === 'backspace') {
+    } else if (isTextBackspace(token.logicalName ?? '')) {
       if (state.modelPicker.mode === 'contextCap') state.modelPicker.deleteContextCapChar();
-      else if (state.modelPicker.searchFocused && (state.modelPicker.mode === 'model' || state.modelPicker.mode === 'provider')) state.modelPicker.deleteChar();
+      else if (state.modelPicker.canFocusSearch()) state.modelPicker.deleteChar();
     } else if (token.logicalName === 'enter') {
-      if (state.modelPicker.focusPane === 'targets') {
+      if (state.modelPicker.focusRegion === 'targets') {
         state.modelPicker.focusItems();
         state.requestRender();
         return true;
@@ -174,84 +168,45 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
           if (state.modalStack[state.modalStack.length - 1] === 'modelPicker') state.modalStack.pop();
         }
       }
-    } else if (token.logicalName === 'up') {
-      if (state.modelPicker.focusPane === 'targets') {
-        state.modelPicker.moveTarget(-1);
-        state.requestRender();
-        return true;
-      }
-      if (state.modelPicker.canFocusSearch() && !state.modelPicker.searchFocused && state.modelPicker.selectedIndex === 0) {
-        state.modelPicker.focusSearch();
-      } else if (state.modelPicker.searchFocused) {
-        // Symmetric with 'down' (below): search now starts focused by default
-        // so 'up' must have a way out of it too, or it would be a
-        // silent no-op the very first time a user reaches for the list.
-        state.modelPicker.blurSearch();
-      } else {
-        const maxVis = Math.max(5, state.getViewportHeight() - MODEL_PICKER_CHROME_LINES - 4);
-        state.modelPicker.moveUp(maxVis);
-      }
-    } else if (token.logicalName === 'down') {
-      if (state.modelPicker.focusPane === 'targets') {
-        state.modelPicker.moveTarget(1);
-        state.requestRender();
-        return true;
-      }
-      if (state.modelPicker.searchFocused) {
-        state.modelPicker.blurSearch();
-      } else {
-        const maxVis = Math.max(5, state.getViewportHeight() - MODEL_PICKER_CHROME_LINES - 4);
-        state.modelPicker.moveDown(maxVis);
-      }
-    } else if (token.logicalName === 'left' && !state.modelPicker.searchFocused && state.modelPicker.mode !== 'contextCap') {
-      state.modelPicker.focusTargets();
-    } else if (token.logicalName === 'right' && !state.modelPicker.searchFocused && state.modelPicker.mode !== 'contextCap') {
+    } else if (token.logicalName === 'up' || token.logicalName === 'down') {
+      // The search row is always live, so arrows always walk the list.
+      const maxVis = Math.max(5, state.getViewportHeight() - MODEL_PICKER_CHROME_LINES - 4);
       state.modelPicker.focusItems();
-    } else if (token.logicalName === 'tab' && state.modelPicker.mode === 'model') {
-      if (state.modelPicker.focusPane === 'targets') {
-        state.modelPicker.focusItems();
-      } else {
+      if (token.logicalName === 'up') state.modelPicker.moveUp(maxVis);
+      else state.modelPicker.moveDown(maxVis);
+    } else if ((token.logicalName === 'tab' || token.logicalName === 'right' || token.logicalName === 'left') && state.modelPicker.mode !== 'contextCap' && state.modelPicker.mode !== 'effort') {
+      // The five model targets are tabs: tab / → next, shift+tab / ← previous.
+      const back = token.logicalName === 'left' || (token.logicalName === 'tab' && token.shift);
+      state.modelPicker.moveTarget(back ? -1 : 1);
+    } else if (token.ctrl && state.modelPicker.mode === 'model') {
+      const picker = state.modelPicker;
+      if (token.logicalName === 't') {
         const cycle: CategoryFilter[] = ['all', 'free', 'paid', 'subscription'];
-        const cur = cycle.indexOf(state.modelPicker.categoryFilter);
-        state.modelPicker.setCategoryFilter(cycle[(cur + 1) % cycle.length]!);
+        picker.setCategoryFilter(cycle[(cycle.indexOf(picker.categoryFilter) + 1) % cycle.length]!);
+      } else if (token.logicalName === 'k') cycleCapabilityFilter(picker);
+      else if (token.logicalName === 'a') picker.toggleAvailableOnly();
+      else if (token.logicalName === 'b') picker.cycleBenchmarkSort();
+      else if (token.logicalName === 'g') picker.cycleGroupBy();
+      else if (token.logicalName === 'f') togglePin(state);
+      else if (token.logicalName === 'r') {
+        void state.commandContext?.executeCommand?.('refresh-models', []);
       }
-    } else if (!state.modelPicker.searchFocused && token.logicalName === 'g' && state.modelPicker.mode === 'model') {
-      state.modelPicker.cycleGroupBy();
-    } else if (!state.modelPicker.searchFocused && token.logicalName === 'c' && state.modelPicker.mode === 'model') {
-      cycleCapabilityFilter(state.modelPicker);
-    } else if (!state.modelPicker.searchFocused && token.logicalName === 'a' && state.modelPicker.mode === 'model') {
-      state.modelPicker.toggleAvailableOnly();
-    } else if (!state.modelPicker.searchFocused && token.logicalName === 'b' && state.modelPicker.mode === 'model') {
-      state.modelPicker.cycleBenchmarkSort();
-    } else if (!state.modelPicker.searchFocused && token.logicalName === '/' && state.modelPicker.canFocusSearch()) {
-      state.modelPicker.focusItems();
-      state.modelPicker.focusSearch();
     }
   } else if (token.type === 'text') {
-    if (state.modelPicker.mode === 'contextCap') {
-      if (token.value.length === 1) state.modelPicker.appendContextCapChar(token.value);
-    } else if ((state.modelPicker.mode === 'model' || state.modelPicker.mode === 'provider') && state.modelPicker.searchFocused) {
-      // When search is focused every printable char, including space, goes to the query.
-      // The space=context-cap shortcut remains active only in the non-search branch below.
-      const ch = token.value;
-      if (ch.length === 1 && ch >= ' ') state.modelPicker.appendChar(ch);
-    } else if (token.value === ' ' && state.modelPicker.mode === 'model') {
-      const selected = state.modelPicker.getSelected();
-      if (selected && state.modelPicker.isLocalModel(selected)) state.modelPicker.enterContextCapMode(selected);
+    const picker = state.modelPicker;
+    if (picker.mode === 'contextCap') {
+      if (token.value.length === 1) picker.appendContextCapChar(token.value);
+    } else if (token.value === ' ' && picker.mode === 'model' && picker.query.length === 0) {
+      // Space on an untouched search sets a context cap for a local model.
+      const selected = picker.getSelected();
+      if (selected && picker.isLocalModel(selected)) picker.enterContextCapMode(selected);
     } else if (token.value === '\t') {
-      if (state.modelPicker.focusPane === 'targets') state.modelPicker.focusItems();
-      else state.modelPicker.focusTargets();
-    } else if (token.value === 'g' && state.modelPicker.mode === 'model') {
-      state.modelPicker.cycleGroupBy();
-    } else if (token.value === 'c' && state.modelPicker.mode === 'model') {
-      cycleCapabilityFilter(state.modelPicker);
-    } else if (token.value === 'a' && state.modelPicker.mode === 'model') {
-      state.modelPicker.toggleAvailableOnly();
-    } else if (token.value === 'b' && state.modelPicker.mode === 'model') {
-      state.modelPicker.cycleBenchmarkSort();
-    } else if (token.value === '/' && state.modelPicker.canFocusSearch()) {
-      state.modelPicker.focusItems();
-      state.modelPicker.focusSearch();
+      picker.moveTarget(1);
+    } else if (picker.canFocusSearch() && !(token.value === '/' && picker.query.length === 0)) {
+      // Every printable character goes to the always-live search.
+      picker.focusItems();
+      picker.focusSearch();
+      for (const ch of token.value) if (ch >= ' ') picker.appendChar(ch);
     }
   }
 
@@ -259,6 +214,14 @@ export function handleModelPickerToken(state: ModelPickerRouteState, token: Inpu
   return true;
 }
 
+/** Pin or unpin the selected model: flipped locally at once, persisted through /pin or /unpin. */
+function togglePin(state: ModelPickerRouteState): void {
+  const model = state.modelPicker.getSelected();
+  if (!model) return;
+  const pinned = state.modelPicker.togglePinnedLocal(model);
+  void state.commandContext?.executeCommand?.(pinned ? 'pin' : 'unpin', [model.registryKey]);
+}
+
 function cycleCapabilityFilter(modelPicker: ModelPickerModal): void {
   const cycle: CapabilityFilter[] = ['none', 'reasoning', 'toolUse', 'multimodal'];
   const cur = cycle.indexOf(modelPicker.capabilityFilter);
@@ -274,6 +237,8 @@ type EscapeOnlyModalRouteState = {
   active: boolean;
   requestRender: () => void;
   handleEscape: () => void;
+  /** Optional scrolling for read-only modals: ↑ passes +1 (back), ↓ passes -1. */
+  scroll?: (delta: number) => void;
 };
 
 export function handleEscapeOnlyModalToken(state: EscapeOnlyModalRouteState, token: InputToken): boolean {
@@ -282,6 +247,12 @@ export function handleEscapeOnlyModalToken(state: EscapeOnlyModalRouteState, tok
     state.handleEscape();
     return true;
   }
+  if (token.type === 'key' && state.scroll) {
+    if (token.logicalName === 'up') state.scroll(1);
+    else if (token.logicalName === 'down') state.scroll(-1);
+    else if (token.logicalName === 'pageup') state.scroll(10);
+    else if (token.logicalName === 'pagedown') state.scroll(-10);
+  }
   state.requestRender();
   return true;
 }
@@ -319,21 +290,16 @@ type FilePickerRouteState = {
 export function handleFilePickerToken(state: FilePickerRouteState, token: InputToken): boolean {
   if (!state.filePicker.active) return false;
 
+  // The query is always live: typing filters, arrows move, Esc closes.
   if (token.type === 'text') {
-    if (!state.filePicker.searchFocused && token.value === '/') {
-      state.filePicker.focusSearch();
-    } else if (state.filePicker.searchFocused && token.value === ' ' && state.filePicker.query === '') {
+    if (token.value === ' ' && state.filePicker.query === '') {
       state.filePicker.close();
-    } else if (state.filePicker.searchFocused) {
+    } else {
+      state.filePicker.focusSearch();
       state.filePicker.setQuery(state.filePicker.query + token.value);
     }
   } else if (token.type === 'key') {
     if (token.logicalName === 'escape') {
-      if (state.filePicker.searchFocused && state.filePicker.query.length > 0) {
-        state.filePicker.setQuery('');
-        state.requestRender();
-        return true;
-      }
       state.handleEscape();
       return true;
     } else if (token.logicalName === 'enter') {
@@ -379,21 +345,13 @@ export function handleFilePickerToken(state: FilePickerRouteState, token: InputT
       }
       state.filePicker.close();
     } else if (token.logicalName === 'up') {
-      if (!state.filePicker.searchFocused && state.filePicker.selectedIndex === 0) {
-        state.filePicker.focusSearch();
-      } else if (!state.filePicker.searchFocused) {
-        state.filePicker.moveUp();
-      }
+      state.filePicker.moveUp();
     } else if (token.logicalName === 'down') {
-      if (state.filePicker.searchFocused) {
-        state.filePicker.blurSearch();
-      } else {
-        state.filePicker.moveDown();
-      }
+      state.filePicker.moveDown();
     } else if (token.logicalName === 'backspace') {
-      if (state.filePicker.searchFocused && state.filePicker.query.length > 0) {
+      if (state.filePicker.query.length > 0) {
         state.filePicker.setQuery(state.filePicker.query.slice(0, -1));
-      } else if (state.filePicker.searchFocused) {
+      } else {
         const removeCount = state.filePicker.injectMode ? 2 : 1;
         if (state.cursorPos >= removeCount) {
           state.prompt = state.prompt.slice(0, state.cursorPos - removeCount) + state.prompt.slice(state.cursorPos);

package/src/input/handler-session-view-route.ts

@@ -0,0 +1,149 @@
+/**
+ * handler-session-view-route.ts, the keyboard while an agent or process is
+ * open full screen, and the session chips' Tab cycling everywhere.
+ *
+ * Runs after the modals (a modal open takes every key first) and before the
+ * work tree and the composer.
+ *
+ *   Tab / Shift+Tab   next / previous session chip, only while the composer
+ *                     is empty and not completing a command (otherwise Tab
+ *                     keeps its completion meaning and Shift+Tab its mode
+ *                     cycling), and only when the chips row shows
+ *   ctrl+x            stop the agent or process: the first press asks, the
+ *                     second (within 3 s) stops
+ *   PageUp/PageDown   scroll the view
+ *
+ * Agent view: Enter sends the composer's text to the agent as a steer (main
+ * keeps running); everything else types into the composer as usual.
+ *
+ * Process view: the composer takes no text (the process's stdin is not
+ * reachable), so letters are the view's keys: / search, n next match, y copy
+ * the output, r restart (when supported); ↑ ↓ scroll a row, End follows the
+ * output again.
+ *
+ * Esc is not handled here: it goes through the shared chain
+ * (handler-modal-stack.ts), whose view step goes back up one level and never
+ * cancels anything.
+ */
+
+import type { InputToken } from '@pellux/goodvibes-sdk/platform/core';
+import { isTextBackspace } from './delete-key-policy.ts';
+
+/** What the route can do to the session views (shell/session-views.ts). */
+export interface SessionViewControls {
+  /** 'main' when no view is open. */
+  readonly kind: 'main' | 'agent' | 'process';
+  readonly active: boolean;
+  /** The chips row is showing (more than one session to switch to). */
+  chipsVisible(): boolean;
+  cycle(delta: 1 | -1): void;
+  /** ctrl+x: ask on the first press, stop on the second. */
+  pressStop(): void;
+  scroll(rows: number): void;
+  /** Rows a page scroll moves. */
+  pageRows(): number;
+  /** Follow the newest output again (End). */
+  follow(): void;
+  /** Agent view: send text to the agent as a steer. True when it was accepted. */
+  steer(text: string): boolean;
+  /** Process view keys. */
+  readonly searchEditing: boolean;
+  startSearch(): void;
+  searchType(text: string): void;
+  searchBackspace(): void;
+  searchNext(): void;
+  copyOutput(): void;
+  restart(): void;
+  /** A key the process view does not take (the composer is off there). */
+  refuseText(): void;
+  /** Esc in a view: close the search, else go back up one level. */
+  escape(): void;
+}
+
+export interface SessionViewRouteState {
+  readonly controls: SessionViewControls | null;
+  prompt: string;
+  cursorPos: number;
+  readonly commandMode: boolean;
+  readonly saveUndoState: () => void;
+  readonly requestRender: () => void;
+}
+
+function isBackTab(token: InputToken): boolean {
+  return token.type === 'key' && (token.logicalName === '\x1b[Z' || (token.logicalName === 'tab' && token.shift === true));
+}
+
+/** Returns true when the token was handled here. */
+export function handleSessionViewToken(state: SessionViewRouteState, token: InputToken): boolean {
+  const c = state.controls;
+  if (!c) return false;
+  const composerIdle = state.prompt.length === 0 && !state.commandMode;
+
+  if (token.type === 'key' && composerIdle && !token.ctrl && !token.meta && (token.logicalName === 'tab' || isBackTab(token)) && c.chipsVisible()) {
+    c.cycle(isBackTab(token) ? -1 : 1);
+    state.requestRender();
+    return true;
+  }
+  if (!c.active) return false;
+
+  if (token.type === 'key') {
+    const name = token.logicalName ?? '';
+    if (token.ctrl && !token.meta && name === 'x') {
+      c.pressStop();
+      state.requestRender();
+      return true;
+    }
+    if (!token.ctrl && !token.meta && (name === 'pageup' || name === 'pagedown')) {
+      c.scroll(name === 'pageup' ? c.pageRows() : -c.pageRows());
+      state.requestRender();
+      return true;
+    }
+    if (c.kind === 'agent' && name === 'enter' && !token.shift && !token.ctrl && !token.meta && !state.commandMode) {
+      const text = state.prompt.trim();
+      if (!text) return true; // an empty Enter in an agent view sends nothing (and never opens main's block actions)
+      if (c.steer(text)) {
+        state.saveUndoState();
+        state.prompt = '';
+        state.cursorPos = 0;
+      }
+      state.requestRender();
+      return true;
+    }
+    if (c.kind === 'process') return handleProcessKey(state, c, token, name);
+    return false;
+  }
+
+  if (token.type === 'text' && c.kind === 'process') {
+    if (c.searchEditing) {
+      c.searchType(token.value.replace(/[\r\n]+/g, ' ').replace(/[\x00-\x1f\x7f]/g, ''));
+    } else if (token.value === '/') c.startSearch();
+    else if (token.value === 'n') c.searchNext();
+    else if (token.value === 'y') c.copyOutput();
+    else if (token.value === 'r') c.restart();
+    else if (token.value === 'G') c.follow();
+    else c.refuseText();
+    state.requestRender();
+    return true;
+  }
+  return false;
+}
+
+function handleProcessKey(state: SessionViewRouteState, c: SessionViewControls, token: InputToken & { type: 'key' }, name: string): boolean {
+  if (token.ctrl || token.meta) return false;
+  if (c.searchEditing) {
+    if (name === 'enter') c.searchNext();
+    else if (isTextBackspace(name)) c.searchBackspace();
+    else return false;
+    state.requestRender();
+    return true;
+  }
+  switch (name) {
+    case 'up': c.scroll(1); break;
+    case 'down': c.scroll(-1); break;
+    case 'end': c.follow(); break;
+    case 'enter': break; // no stdin to send a line to
+    default: return false;
+  }
+  state.requestRender();
+  return true;
+}