@pellux/goodvibes-tui 0.19.24 → 0.19.26

package/src/input/commands.ts

@@ -53,6 +53,7 @@ import { registerLocalAuthRuntimeCommands } from './commands/local-auth-runtime.
 import { registerIntelligenceRuntimeCommands } from './commands/intelligence-runtime.ts';
 import { registerConversationRuntimeCommands } from './commands/conversation-runtime.ts';
 import { registerQrcodeRuntimeCommands } from './commands/qrcode-runtime.ts';
+import { registerOnboardingRuntimeCommands } from './commands/onboarding-runtime.ts';
 
 /**
  * registerBuiltinCommands - Register all built-in slash commands into the registry.
@@ -100,6 +101,7 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registerIntelligenceRuntimeCommands(registry);
   registerConversationRuntimeCommands(registry);
   registerQrcodeRuntimeCommands(registry);
+  registerOnboardingRuntimeCommands(registry);
   registerLocalRuntimeCommands(registry);
   registerSessionWorkflowCommands(registry);
   registerDiscoveryRuntimeCommands(registry);

package/src/input/feed-context-factory.ts

@@ -31,10 +31,12 @@ import type { BookmarkModal } from './bookmark-modal.ts';
 import type { SettingsModal } from './settings-modal.ts';
 import type { SessionPickerModal } from './session-picker-modal.ts';
 import type { ProfilePickerModal } from './profile-picker-modal.ts';
+import type { OnboardingWizardController } from './onboarding/onboarding-wizard.ts';
 import type { WrappedPromptInfo } from './handler-prompt-buffer.ts';
 import type { Panel } from '../panels/types.ts';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { KeybindingsManager } from './keybindings.ts';
+import type { ModelPickerTarget } from './model-picker.ts';
 
 /**
  * Initial mutable scalar values for InputFeedContext.
@@ -77,7 +79,7 @@ export interface FeedContextMutableInit {
  *     `profilePickerModal` — modal objects constructed once
  *   - `filePicker`, `modelPicker`, `processModal`, `liveTailModal`,
  *     `agentDetailModal`, `contextInspectorModal`, `blockActionsMenu`,
- *     `searchManager`, `historySearch` — service objects constructed once
+ *     `searchManager`, `historySearch`, `onboardingWizard` — service objects constructed once
  *   - `panelManager`, `keybindingsManager` — from uiServices, stable
  *   - `modalStack` — reference to the handler's shared array
  *   - `getHistory`, `getViewportHeight`, `getScrollTop`, `scroll`, `exitApp` — callbacks
@@ -104,6 +106,7 @@ export interface FeedContextStableRefs {
   autocomplete: AutocompleteEngine | null;
   filePicker: FilePickerModal;
   modelPicker: ModelPickerModal;
+  onboardingWizard: OnboardingWizardController;
   processModal: ProcessModal;
   liveTailModal: LiveTailModal;
   agentDetailModal: AgentDetailModal;
@@ -148,6 +151,9 @@ export interface FeedContextClosures {
   findMarkerAtPos: (pos: number) => { start: number; end: number } | null;
   cleanupMarkerRegistry: (text: string) => void;
   expandPrompt: (text: string) => string | import('@pellux/goodvibes-sdk/platform/providers/interface').ContentPart[];
+  openModelPickerWithTarget: (target: ModelPickerTarget, source?: 'settings' | 'onboarding') => boolean;
+  onModelPickerCommit: () => boolean;
+  onOnboardingAction: (action: import('./onboarding/onboarding-wizard.ts').OnboardingWizardAction) => void;
 }
 
 /**
@@ -233,4 +239,5 @@ export function syncFeedContextMutableFields(
   ctx.nextImageId = fields.nextImageId;
   ctx.mouseDownRow = fields.mouseDownRow;
   ctx.mouseDownCol = fields.mouseDownCol;
+  ctx.contentWidth = fields.contentWidth;
 }

package/src/input/handler-feed.ts

@@ -18,6 +18,8 @@ import { BookmarkModal } from './bookmark-modal.ts';
 import { SettingsModal } from './settings-modal.ts';
 import { SessionPickerModal } from './session-picker-modal.ts';
 import { ProfilePickerModal } from './profile-picker-modal.ts';
+import type { OnboardingWizardController } from './onboarding/onboarding-wizard.ts';
+import type { OnboardingWizardAction } from './onboarding/onboarding-wizard.ts';
 import {
   IMAGE_EXTENSIONS,
   formatFileSize,
@@ -39,6 +41,7 @@ import { handlePanelIntegrationAction } from './panel-integration-actions.ts';
 import { SelectionManager } from './selection.ts';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { KeybindingsManager } from './keybindings.ts';
+import type { ModelPickerTarget } from './model-picker.ts';
 
 /**
  * InputFeedContext — The single long-lived context object passed to feedInputTokens
@@ -66,8 +69,8 @@ import type { KeybindingsManager } from './keybindings.ts';
  *   - `pasteRegistry`, `imageRegistry` — owned Maps, never replaced
  *   - `selectionModal`, `bookmarkModal`, `settingsModal`, `sessionPickerModal`,
  *     `profilePickerModal` — modal objects constructed once in InputHandler constructor
- *   - `filePicker`, `modelPicker`, `processModal`, `liveTailModal`, `agentDetailModal`,
- *     `contextInspectorModal`, `blockActionsMenu`, `searchManager`, `historySearch` —
+ *   - `filePicker`, `modelPicker`, `onboardingWizard`, `processModal`, `liveTailModal`,
+ *     `agentDetailModal`, `contextInspectorModal`, `blockActionsMenu`, `searchManager`, `historySearch` —
  *     service objects constructed once
  *   - `panelManager`, `keybindingsManager` — from uiServices, stable for app lifetime
  *   - `modalStack` — reference to the handler's shared array (mutated in place)
@@ -108,6 +111,7 @@ export interface InputFeedContext {
   autocomplete: AutocompleteEngine | null;
   readonly filePicker: FilePickerModal;
   readonly modelPicker: ModelPickerModal;
+  readonly onboardingWizard: OnboardingWizardController;
   readonly processModal: ProcessModal;
   readonly liveTailModal: LiveTailModal;
   readonly agentDetailModal: AgentDetailModal;
@@ -148,6 +152,9 @@ export interface InputFeedContext {
   readonly findMarkerAtPos: (pos: number) => { start: number; end: number } | null;
   readonly cleanupMarkerRegistry: (text: string) => void;
   readonly expandPrompt: (text: string) => string | import('@pellux/goodvibes-sdk/platform/providers/interface').ContentPart[];
+  readonly openModelPickerWithTarget: (target: ModelPickerTarget, source?: 'settings' | 'onboarding') => boolean;
+  readonly onModelPickerCommit: () => boolean;
+  readonly onOnboardingAction: (action: OnboardingWizardAction) => void;
   readonly exitApp: () => void;
 }
 
@@ -173,6 +180,7 @@ export function feedInputTokens(context: InputFeedContext, tokens: readonly Inpu
       settingsModal: context.settingsModal,
       sessionPickerModal: context.sessionPickerModal,
       profilePickerModal: context.profilePickerModal,
+      onboardingWizard: context.onboardingWizard,
       helpOverlayActive: context.helpOverlayActive,
       helpScrollOffset: context.helpScrollOffset,
       shortcutsOverlayActive: context.shortcutsOverlayActive,
@@ -204,12 +212,9 @@ export function feedInputTokens(context: InputFeedContext, tokens: readonly Inpu
       searchManager: context.searchManager,
       scroll: context.scroll,
       getScrollTop: context.getScrollTop,
-      openModelPickerWithTarget: context.commandContext?.openModelPicker
-        ? (target: import('./model-picker.ts').ModelPickerTarget) => {
-            context.modelPicker.target = target;
-            context.commandContext!.openModelPicker!();
-          }
-        : undefined,
+      openModelPickerWithTarget: context.openModelPickerWithTarget,
+      onModelPickerCommit: context.onModelPickerCommit,
+      onOnboardingAction: context.onOnboardingAction,
     }, token);
     context.selectionCallback = modalRoute.selectionCallback;
     context.helpOverlayActive = modalRoute.helpOverlayActive;

package/src/input/handler-interactions.ts

@@ -0,0 +1,266 @@
+import { buildProviderAccountSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/provider-accounts/registry';
+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 { clearModalStack, handleEscape, modalOpened } from './handler-modal-stack.ts';
+import { openOnboardingWizardState, type OpenOnboardingWizardOptions } from './handler-ui-state.ts';
+import type { InputHandler } from './handler.ts';
+
+export function openOnboardingWizardForHandler(
+  handler: InputHandler,
+    modeOrOptions: OnboardingWizardMode | OpenOnboardingWizardOptions = 'new',
+  ): void {
+    const options = typeof modeOrOptions === 'string' ? { mode: modeOrOptions } : modeOrOptions;
+    if (!handler.modalStack.includes('onboarding')) handler.modalOpened('onboarding');
+    handler.clearOnboardingModelPickerCancelState();
+    openOnboardingWizardState(handler.onboardingWizard, options);
+    const hydrationSerial = ++handler.onboardingHydrationSerial;
+    if (options.preload === undefined) {
+      handler.onboardingWizard.beginRuntimeHydration();
+      void handler.hydrateOnboardingWizardFromRuntime(hydrationSerial);
+    }
+    handler.requestRender();
+  }
+
+export async function hydrateOnboardingWizardFromRuntimeForHandler(handler: InputHandler, hydrationSerial: number): Promise<void> {
+    try {
+      const snapshot = await collectOnboardingSnapshot({
+        config: handler.uiServices.platform.configManager,
+        shellPaths: handler.uiServices.environment.shellPaths,
+        acknowledgementScope: 'project',
+        subscriptions: handler.uiServices.platform.subscriptionManager,
+        secrets: handler.uiServices.platform.secretsManager,
+        auth: handler.uiServices.platform.localUserAuthManager,
+        services: handler.uiServices.platform.serviceRegistry,
+        surfaces: {
+          list: () => handler.uiServices.platform.surfaceRegistry.syncConfiguredSurfaces(),
+        },
+        providerAccounts: {
+          loadSnapshot: () => buildProviderAccountSnapshot({
+            providerRegistry: handler.uiServices.providers.providerRegistry,
+            serviceRegistry: handler.uiServices.platform.serviceRegistry,
+            subscriptionManager: handler.uiServices.platform.subscriptionManager,
+            secretsManager: handler.uiServices.platform.secretsManager,
+          }),
+        },
+      });
+      if (!handler.onboardingWizard.active || hydrationSerial !== handler.onboardingHydrationSerial) return;
+      handler.onboardingWizard.hydrateRuntimeState({ snapshot }, { resetValues: true });
+      handler.requestRender();
+    } catch (error) {
+      if (!handler.onboardingWizard.active || hydrationSerial !== handler.onboardingHydrationSerial) return;
+      const message = error instanceof Error ? error.message : String(error);
+      handler.onboardingWizard.failRuntimeHydration(message);
+      handler.commandContext?.print?.(`Onboarding runtime snapshot failed: ${message}`);
+      handler.requestRender();
+    }
+  }
+
+export function registerPasteForHandler(handler: InputHandler, content: string): string {
+    const result = registerPaste({
+      pasteRegistry: handler.pasteRegistry,
+      nextPasteId: handler.nextPasteId,
+      imageRegistry: handler.imageRegistry,
+      nextImageId: handler.nextImageId,
+    }, content, handler.uiServices.environment.shellPaths.workingDirectory);
+    handler.nextPasteId = result.nextPasteId;
+    handler.nextImageId = result.nextImageId;
+    return result.marker;
+  }
+
+  /**
+   * expandPrompt - Replaces paste markers with actual content.
+   * If image markers are present, returns ContentPart[] for multimodal delivery.
+   * Otherwise returns a plain string.
+   */
+export function expandPromptForHandler(handler: InputHandler, text: string) {
+    return expandPrompt(handler.pasteRegistry, handler.imageRegistry, text, handler.uiServices.environment.shellPaths.workingDirectory);
+  }
+
+  /**
+   * getImageAttachments - Returns a copy of the current image registry.
+   * Callers can use this to attach images when building LLM messages.
+   */
+export function getImageAttachmentsForHandler(handler: InputHandler): Map<string, { data: string; mediaType: string }> {
+    return new Map(handler.imageRegistry);
+  }
+
+  /**
+   * findMarkerAtPos - Returns the start/end of an atomic marker if pos is inside one.
+   * Used to make backspace/delete/arrow treat markers as single units.
+   */
+  /**
+   * cleanupMarkerRegistry - If the given marker text is an IMAGE marker,
+   * parses its ID and removes it from imageRegistry.
+   */
+export function cleanupMarkerRegistryForHandler(handler: InputHandler, markerText: string): void {
+    cleanupMarkerRegistry(handler.imageRegistry, markerText);
+  }
+
+export function findMarkerAtPosForHandler(handler: InputHandler, pos: number): { start: number; end: number } | null {
+    return findMarkerAtPos(handler.prompt, pos);
+  }
+
+export function handleCopyForHandler(handler: InputHandler): void {
+    handleCopy(handler.selection, handler.getHistory, handler.requestRender, () => {
+      handler.lastCopyTime = Date.now();
+    });
+  }
+
+  /**
+   * handleBlockCopy - Ctrl+Y: Copy the content of the nearest code/tool block.
+   */
+export function handleBlockCopyForHandler(handler: InputHandler): void {
+    handleBlockCopy(handler.conversationManager, handler.getScrollTop, handler.requestRender, () => {
+      handler.lastBlockCopyTime = Date.now();
+    });
+  }
+
+  /**
+   * handleBookmark - Ctrl+B: Toggle bookmark on the nearest block.
+   */
+export function handleBookmarkForHandler(handler: InputHandler): void {
+    handleBookmark(handler.conversationManager, handler.getScrollTop, handler.requestRender, handler.uiServices.shell.bookmarkManager);
+  }
+
+  /**
+   * handleBlockSave - Ctrl+S: Save nearest block content to a file.
+   */
+export function handleBlockSaveForHandler(handler: InputHandler): void {
+    handleBlockSave(handler.conversationManager, handler.getScrollTop, 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.
+   */
+export function executeBlockActionForHandler(handler: InputHandler, actionId: string): void {
+    switch (actionId) {
+      case 'copy':     handler.handleBlockCopy(); break;
+      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.
+   */
+export function handleBlockToggleForHandler(handler: InputHandler): void {
+    handleBlockToggle(handler.conversationManager, handler.getScrollTop, 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).
+   */
+export function handleDiffApplyForHandler(handler: InputHandler): boolean {
+    return handleDiffApply(
+      handler.conversationManager,
+      handler.getScrollTop,
+      handler.commandContext,
+      handler.requestRender,
+      () => `diff-apply-${Date.now()}`,
+      'write',
+    );
+  }
+
+  /**
+   * Handle Ctrl+C:
+   * - If prompt has text: clear it
+   * - If prompt is empty and LLM is thinking: cancel generation
+   * - If prompt is empty and idle: show exit notice (double = exit)
+   */
+export function handleCtrlCForHandler(handler: InputHandler): void {
+    handleCtrlC(
+      handler.prompt,
+      () => handler.saveUndoState(),
+      (value) => { handler.prompt = value; },
+      (value) => { handler.cursorPos = value; },
+      handler.commandContext?.cancelGeneration,
+      handler.exitApp,
+      handler.requestRender,
+      handler.lastCtrlCTime,
+      (value) => { handler.lastCtrlCTime = value; },
+      (value) => { handler.showExitNotice = value; },
+    );
+  }
+
+  /**
+   * Handle Escape:
+   * - If prompt has text: clear it
+   * - If prompt is empty: cancel generation (double-tap not needed)
+   */
+  /**
+   * Record that a modal has been opened and push it onto the navigation stack.
+   * Call this EVERY time a modal opens (except inside openModal()).
+   *
+   * @param name - The modal identifier (e.g. 'settings', 'help', 'process').
+   */
+export function modalOpenedForHandler(handler: InputHandler, name: string): void {
+    modalOpened(handler, name);
+  }
+
+  /**
+   * Clear the modal navigation stack on non-modal user input (e.g. submit).
+   */
+export function clearModalStackForHandler(handler: InputHandler): void {
+    clearModalStack(handler.modalStack);
+  }
+
+export function handleEscapeForHandler(handler: InputHandler): void {
+    const result = handleEscape({
+      helpOverlayActive: handler.helpOverlayActive,
+      shortcutsOverlayActive: handler.shortcutsOverlayActive,
+      bookmarkModal: handler.bookmarkModal,
+      agentDetailModal: handler.agentDetailModal,
+      liveTailModal: handler.liveTailModal,
+      settingsModal: handler.settingsModal,
+      sessionPickerModal: handler.sessionPickerModal,
+      profilePickerModal: handler.profilePickerModal,
+      contextInspectorModal: handler.contextInspectorModal,
+      processModal: handler.processModal,
+      modelPicker: handler.modelPicker,
+      filePicker: handler.filePicker,
+      blockActionsMenu: handler.blockActionsMenu,
+      selectionModal: handler.selectionModal,
+      onboardingWizard: handler.onboardingWizard,
+      commandMode: handler.commandMode,
+      modalStack: handler.modalStack,
+      modalReturnFocus: handler.modalReturnFocus,
+      panelFocused: handler.panelFocused,
+      indicatorFocused: handler.indicatorFocused,
+      prompt: handler.prompt,
+      cursorPos: handler.cursorPos,
+      requestRender: handler.requestRender,
+      saveUndoState: () => handler.saveUndoState(),
+      cancelGeneration: handler.commandContext?.cancelGeneration,
+      selectionCallback: handler.selectionCallback,
+      autocompleteReset: () => handler.autocomplete?.reset(),
+      autocompleteUpdate: (query: string) => handler.autocomplete?.update(query),
+      helpScrollOffset: handler.helpScrollOffset,
+      shortcutsScrollOffset: handler.shortcutsScrollOffset,
+      clearOnboardingModelPickerCancelState: () => handler.clearOnboardingModelPickerCancelState(),
+      restoreOnboardingModelPickerCancelState: () => handler.restoreOnboardingModelPickerCancelState(),
+    });
+    handler.prompt = result.prompt;
+    handler.cursorPos = result.cursorPos;
+    handler.commandMode = result.commandMode;
+    handler.helpOverlayActive = result.helpOverlayActive;
+    handler.helpScrollOffset = result.helpScrollOffset;
+    handler.shortcutsOverlayActive = result.shortcutsOverlayActive;
+    handler.shortcutsScrollOffset = result.shortcutsScrollOffset;
+    handler.selectionCallback = result.selectionCallback;
+    handler.panelFocused = result.panelFocused;
+    handler.indicatorFocused = result.indicatorFocused;
+    handler.modalReturnFocus = result.modalReturnFocus;
+}

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

@@ -17,6 +17,8 @@ export function modalOpened(state: ModalStackState, name: string): void {
   if (getActiveModalName(state) === null && state.modalStack.length > 0) {
     state.modalStack.length = 0;
   }
+  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';
   }
@@ -46,6 +48,8 @@ export type EscapeState = ModalStackState & {
   selectionModal: ModalStackState['selectionModal'];
   autocompleteReset: () => void;
   autocompleteUpdate?: (query: string) => void;
+  clearOnboardingModelPickerCancelState?: () => void;
+  restoreOnboardingModelPickerCancelState?: () => void;
 };
 
 export function handleEscape(state: EscapeState): {
@@ -59,6 +63,7 @@ export function handleEscape(state: EscapeState): {
   selectionCallback: ((result: SelectionResult | null) => void) | null;
   panelFocused: boolean;
   indicatorFocused: boolean;
+  modalReturnFocus: NonNullable<ModalStackState['modalReturnFocus']>;
 } {
   let prompt = state.prompt;
   let cursorPos = state.cursorPos;
@@ -70,6 +75,7 @@ export function handleEscape(state: EscapeState): {
   let selectionCallback = state.selectionCallback;
   let panelFocused = state.panelFocused;
   let indicatorFocused = state.indicatorFocused;
+  let modalReturnFocus: NonNullable<ModalStackState['modalReturnFocus']> = state.modalReturnFocus ?? 'prompt';
 
   const restoreFocus = (): void => {
     if (state.modalStack.length > 0 || getActiveModalName({
@@ -78,8 +84,9 @@ export function handleEscape(state: EscapeState): {
       shortcutsOverlayActive,
       commandMode,
     }) !== null) return;
-    panelFocused = state.modalReturnFocus === 'panel';
-    indicatorFocused = state.modalReturnFocus === 'indicator';
+    panelFocused = modalReturnFocus === 'panel';
+    indicatorFocused = modalReturnFocus === 'indicator';
+    modalReturnFocus = 'prompt';
     state.modalReturnFocus = 'prompt';
   };
 
@@ -97,6 +104,7 @@ export function handleEscape(state: EscapeState): {
       selectionCallback,
       panelFocused,
       indicatorFocused,
+      modalReturnFocus,
     };
   }
 
@@ -118,7 +126,10 @@ export function handleEscape(state: EscapeState): {
       closeProfilePicker: () => state.profilePickerModal.close(),
       closeContextInspector: () => state.contextInspectorModal.close(),
       closeProcess: () => state.processModal.close(),
-      closeModelPicker: () => state.modelPicker.close(),
+      closeModelPicker: () => {
+        state.modelPicker.close();
+        state.restoreOnboardingModelPickerCancelState?.();
+      },
       closeFilePicker: () => state.filePicker.close(),
       closeBlockActions: () => state.blockActionsMenu.close(),
       closeSelection: () => {
@@ -127,6 +138,10 @@ export function handleEscape(state: EscapeState): {
         state.selectionModal.close();
         cb?.(null);
       },
+      closeOnboarding: () => {
+        state.onboardingWizard?.close();
+        state.clearOnboardingModelPickerCancelState?.();
+      },
       closeCommandMode: () => {
         commandMode = false;
         for (let i = state.modalStack.length - 1; i >= 0; i--) {
@@ -146,6 +161,7 @@ export function handleEscape(state: EscapeState): {
       openBookmark: () => state.bookmarkModal.open(),
       openProcess: () => state.processModal.open(),
       openContextInspector: () => state.contextInspectorModal.open(),
+      openOnboarding: () => state.onboardingWizard?.reopen(),
       openCommandMode: () => {
         commandMode = true;
         prompt = '/';
@@ -176,6 +192,7 @@ export function handleEscape(state: EscapeState): {
       selectionCallback,
       panelFocused,
       indicatorFocused,
+      modalReturnFocus,
     };
   }
 
@@ -200,6 +217,7 @@ export function handleEscape(state: EscapeState): {
       selectionCallback,
       panelFocused,
       indicatorFocused,
+      modalReturnFocus,
     };
   }
 
@@ -218,6 +236,7 @@ export function handleEscape(state: EscapeState): {
       selectionCallback,
       panelFocused,
       indicatorFocused,
+      modalReturnFocus,
     };
   }
 
@@ -233,5 +252,6 @@ export function handleEscape(state: EscapeState): {
     selectionCallback,
     panelFocused,
     indicatorFocused,
+    modalReturnFocus,
   };
 }

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

@@ -15,7 +15,9 @@ import type { ContextInspectorModal } from '../renderer/context-inspector.ts';
 import type { FilePickerModal } from './file-picker.ts';
 import type { BlockActionsMenu, BlockActionId } from '../renderer/block-actions.ts';
 import type { SearchManager } from './search.ts';
+import type { OnboardingWizardAction, OnboardingWizardController } from './onboarding/onboarding-wizard.ts';
 import { handleHistorySearchToken, handleOverlayToken, handleSearchModeToken } from './handler-ui-state.ts';
+import { handleOnboardingWizardToken } from './onboarding/handler-onboarding-routes.ts';
 import {
   handleBookmarkModalToken,
   handleProfilePickerToken,
@@ -41,6 +43,7 @@ export type ModalTokenRouteState = {
   settingsModal: SettingsModal;
   sessionPickerModal: SessionPickerModal;
   profilePickerModal: ProfilePickerModal;
+  onboardingWizard: OnboardingWizardController;
   helpOverlayActive: boolean;
   helpScrollOffset: number;
   shortcutsOverlayActive: boolean;
@@ -73,7 +76,14 @@ export type ModalTokenRouteState = {
   scroll: (delta: number) => void;
   getScrollTop: () => number;
   /** Callback to open the model picker with a specific target (helper or tool). Optional — only wired when available. */
-  openModelPickerWithTarget?: (target: import('./model-picker.ts').ModelPickerTarget) => void;
+  openModelPickerWithTarget?: (
+    target: import('./model-picker.ts').ModelPickerTarget,
+    source?: 'settings' | 'onboarding',
+  ) => boolean;
+  clearOnboardingModelPickerCancelState?: () => void;
+  restoreOnboardingModelPickerCancelState?: () => void;
+  onModelPickerCommit?: () => boolean;
+  onOnboardingAction?: (action: OnboardingWizardAction) => void;
 };
 
 export function handleModalTokenRoutes(state: ModalTokenRouteState, token: InputToken): {
@@ -173,6 +183,18 @@ export function handleModalTokenRoutes(state: ModalTokenRouteState, token: Input
     getViewportHeight: state.getViewportHeight,
     requestRender: state.requestRender,
     handleEscape: state.handleEscape,
+    onModelPickerCommit: state.onModelPickerCommit,
+  }, token)) {
+    return withState(state, true);
+  }
+
+  if (handleOnboardingWizardToken({
+    onboardingWizard: state.onboardingWizard,
+    getViewportHeight: state.getViewportHeight,
+    requestRender: state.requestRender,
+    handleEscape: state.handleEscape,
+    openModelPickerWithTarget: state.openModelPickerWithTarget,
+    onAction: state.onOnboardingAction,
   }, token)) {
     return withState(state, true);
   }