@pellux/goodvibes-tui 2.0.21 → 2.1.1

package/src/input/selection-modal.ts

@@ -29,8 +29,8 @@ export interface SelectionResult {
 export class SelectionModal {
   public active = false;
   public title = '';
-  public query = '';           // fuzzy search query
-  public searchFocused = false;
+  /** The always-live search row's query (fuzzy). Typing edits it directly; there is no search mode. */
+  public query = '';
   public items: SelectionItem[] = [];
   public filteredItems: SelectionItem[] = [];
   public selectedIndex = 0;
@@ -44,6 +44,9 @@ export class SelectionModal {
    * the generic "Select".
    */
   public primaryVerbLabel: string | undefined = undefined;
+  /** Live-preview hook: called when the highlighted row changes (see open()). */
+  private onHighlight: ((item: SelectionItem | null) => void) | undefined = undefined;
+  private lastHighlightedId: string | null | undefined = undefined;
 
   /** Open the modal with items and title */
   open(
@@ -54,13 +57,17 @@ export class SelectionModal {
       allowSearch?: boolean;
       customActions?: Map<string, SelectionAction>;
       primaryVerbLabel?: string;
+      /**
+       * Called with the highlighted row right after open and whenever the
+       * cursor lands on a different row (move, search). Used for live preview.
+       */
+      onHighlight?: (item: SelectionItem | null) => void;
     }
   ): void {
     this.title = title;
     this.items = items;
     this.query = '';
     this.allowSearch = opts?.allowSearch ?? true;
-    this.searchFocused = false;
     this.customActions = opts?.customActions ?? new Map();
     this.primaryVerbLabel = opts?.primaryVerbLabel;
     this.active = true;
@@ -73,13 +80,17 @@ export class SelectionModal {
     } else {
       this.selectedIndex = 0;
     }
+    this.onHighlight = opts?.onHighlight;
+    this.lastHighlightedId = undefined;
+    this.emitHighlight();
   }
 
   close(): void {
+    this.onHighlight = undefined;
+    this.lastHighlightedId = undefined;
     this.active = false;
     this.title = '';
     this.query = '';
-    this.searchFocused = false;
     this.items = [];
     this.filteredItems = [];
     this.selectedIndex = 0;
@@ -93,6 +104,7 @@ export class SelectionModal {
     this.selectedIndex = this.selectedIndex > 0
       ? this.selectedIndex - 1
       : this.filteredItems.length - 1;
+    this.emitHighlight();
   }
 
   moveDown(): void {
@@ -100,6 +112,7 @@ export class SelectionModal {
     this.selectedIndex = this.selectedIndex < this.filteredItems.length - 1
       ? this.selectedIndex + 1
       : 0;
+    this.emitHighlight();
   }
 
   /** Update fuzzy search filter */
@@ -107,18 +120,7 @@ export class SelectionModal {
     this.query = query;
     this.selectedIndex = 0;
     this.filterItems();
-  }
-
-  canFocusSearch(): boolean {
-    return this.allowSearch;
-  }
-
-  focusSearch(): void {
-    if (this.allowSearch) this.searchFocused = true;
-  }
-
-  blurSearch(): void {
-    this.searchFocused = false;
+    this.emitHighlight();
   }
 
   /** Get currently highlighted item */
@@ -127,6 +129,16 @@ export class SelectionModal {
     return this.filteredItems[this.selectedIndex] ?? null;
   }
 
+  /** Notify onHighlight when the highlighted row differs from the last one reported. */
+  private emitHighlight(): void {
+    if (!this.onHighlight) return;
+    const item = this.getSelected();
+    const id = item?.id ?? null;
+    if (id === this.lastHighlightedId) return;
+    this.lastHighlightedId = id;
+    this.onHighlight(item);
+  }
+
   /** Fuzzy match items against query, resets filteredItems */
   private filterItems(): void {
     if (this.query.length === 0) {

package/src/input/session-picker-modal.ts

@@ -82,6 +82,12 @@ export class SessionPickerModal {
   /** Last status message to show in the modal (e.g. error or success). */
   public statusMessage = '';
 
+  /**
+   * The always-live search query. Filters the local sessions by name and
+   * title; selectedIndex and scrollOffset index the filtered list.
+   */
+  public query = '';
+
   public constructor(
     private readonly sessionManager: SessionManager,
     private readonly sessionBroker?: SessionReadFacade,
@@ -122,9 +128,25 @@ export class SessionPickerModal {
     this.scrollOffset = 0;
     this.statusMessage = '';
     this.deleteConfirmationTarget = null;
+    this.query = '';
     this.active = true;
   }
 
+  /** The local sessions matching the query (all of them when it is empty). */
+  visibleSessions(): SessionInfo[] {
+    const q = this.query.trim().toLowerCase();
+    if (q.length === 0) return this.sessions;
+    return this.sessions.filter((s) => s.name.toLowerCase().includes(q) || (s.title ?? '').toLowerCase().includes(q));
+  }
+
+  /** Replace the query; the selection returns to the first match. */
+  setQuery(query: string): void {
+    this.query = query;
+    this.selectedIndex = 0;
+    this.scrollOffset = 0;
+    this.deleteConfirmationTarget = null;
+  }
+
   close(): void {
     this.active = false;
     this.statusMessage = '';
@@ -132,15 +154,17 @@ export class SessionPickerModal {
   }
 
   moveUp(): void {
-    if (this.sessions.length === 0) return;
-    this.selectedIndex = (this.selectedIndex - 1 + this.sessions.length) % this.sessions.length;
+    const count = this.visibleSessions().length;
+    if (count === 0) return;
+    this.selectedIndex = (this.selectedIndex - 1 + count) % count;
     this._clampScroll();
     this.deleteConfirmationTarget = null;
   }
 
   moveDown(): void {
-    if (this.sessions.length === 0) return;
-    this.selectedIndex = (this.selectedIndex + 1) % this.sessions.length;
+    const count = this.visibleSessions().length;
+    if (count === 0) return;
+    this.selectedIndex = (this.selectedIndex + 1) % count;
     this._clampScroll();
     this.deleteConfirmationTarget = null;
   }
@@ -151,7 +175,7 @@ export class SessionPickerModal {
   }
 
   getSelected(): SessionInfo | null {
-    return this.sessions[this.selectedIndex] ?? null;
+    return this.visibleSessions()[this.selectedIndex] ?? null;
   }
 
   /**
@@ -195,8 +219,9 @@ export class SessionPickerModal {
       // Reload list from the global session manager (removes the deleted entry)
       this.sessions = this.sessionManager.list();
       // Adjust selection
-      if (this.selectedIndex >= this.sessions.length) {
-        this.selectedIndex = Math.max(0, this.sessions.length - 1);
+      const remaining = this.visibleSessions().length;
+      if (this.selectedIndex >= remaining) {
+        this.selectedIndex = Math.max(0, remaining - 1);
       }
       this._clampScroll();
       this.deleteConfirmationTarget = null;
@@ -216,7 +241,7 @@ export class SessionPickerModal {
     } else if (this.selectedIndex >= this.scrollOffset + visRows) {
       this.scrollOffset = this.selectedIndex - visRows + 1;
     }
-    const maxOffset = Math.max(0, this.sessions.length - visRows);
+    const maxOffset = Math.max(0, this.visibleSessions().length - visRows);
     this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, maxOffset));
   }
 }

package/src/input/settings-modal-activation.ts

@@ -10,7 +10,7 @@
  * settings-modal-reset.ts and settings-modal-mutations.ts.
  */
 
-import { handleConfirmInput } from '../panels/confirm-state.ts';
+import { handleConfirmInput } from '../views/confirm-state.ts';
 import type { FlagEntry, McpEntry, SettingEntry, SubscriptionEntry } from './settings-modal-types.ts';
 import { buildMcpEntries, buildSubscriptionEntries } from './settings-modal-data.ts';
 import { modelPickerLaunchForKey } from './settings-modal-behavior.ts';
@@ -34,7 +34,7 @@ export interface ActivateSelectedContext {
   setEditBuffer(value: string): void;
   setMcpAllowAllConfirmationTarget(value: string | null): void;
   setSubscriptionLogoutConfirmationTarget(value: string | null): void;
-  setPendingSettingsPickerAction(value: 'tts-provider' | 'tts-voice' | null): void;
+  setPendingSettingsPickerAction(value: 'tts-provider' | 'tts-voice' | 'theme' | null): void;
   setPendingModelPickerTarget(value: ModelPickerTarget | null): void;
   setPendingProviderModelPickerTarget(value: ModelPickerTarget | null): void;
 }
@@ -74,6 +74,11 @@ export function activateSelected(ctx: ActivateSelectedContext): void {
     ctx.setPendingSettingsPickerAction('tts-voice');
     return;
   }
+  // The theme row opens a picker with live preview instead of cycling values.
+  if (setting.key === 'display.theme') {
+    ctx.setPendingSettingsPickerAction('theme');
+    return;
+  }
 
   const pickerLaunch = modelPickerLaunchForKey(setting.key);
   if (pickerLaunch !== null) {

package/src/input/settings-modal-data.ts

@@ -14,7 +14,7 @@ import type { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp';
 import { buildSubscriptionEntries } from './settings-modal-subscriptions.ts';
 import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { ServiceInspectionQuery } from '@/runtime/index.ts';
-import { CODE_INDEX_ENABLED_CONFIG_KEY } from '@pellux/goodvibes-sdk/platform/runtime/operations';
+import { CODE_INDEX_ENABLED_CONFIG_KEY, NOTIFICATIONS_METADATA_ONLY_KEY } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import {
   WORKTREE_SETUP_CARRY_OVER_GLOBS_CONFIG_KEY,
   WORKTREE_SETUP_COMMANDS_CONFIG_KEY,
@@ -167,7 +167,7 @@ export function buildSettingGroups(
 
   // Synthetic behavior.budgetAlertUsd (TUI-local): no schema surface previously,
   // never in /config; /settings-sync show rejects any key not
-  // in CONFIG_KEYS. The Cost panel's 'b' key and /cost budget <usd> remain
+  // in CONFIG_KEYS. The Usage modal's 'b' key and /cost budget <usd> remain
   // the primary way to change it; this entry makes the current effective
   // value (and whether it's still the "no budget configured" default)
   // visible from /config behavior too, same rationale as notifyAfterSeconds.
@@ -190,6 +190,11 @@ export function buildSettingGroups(
         behaviorEntries.push(entry);
       }
     }
+    // behavior.notificationsMetadataOnly is a real SDK schema key (the loop
+    // above already added it); it governs the text of every notification row
+    // above (desktop, in-terminal, webhook), so it is listed right after them.
+    const privacyIndex = behaviorEntries.findIndex((e) => e.setting.key === (NOTIFICATIONS_METADATA_ONLY_KEY as ConfigKey));
+    if (privacyIndex >= 0) behaviorEntries.push(...behaviorEntries.splice(privacyIndex, 1));
   }
 
   // Inject the storage.codeIndexEnabled toggle into the
@@ -331,20 +336,20 @@ export function buildNotifyAfterSecondsSyntheticEntry(configManager: Pick<Config
  *
  * 0 = no budget configured (disabled). Any positive number = the USD
  * threshold. Default matches BUDGET_ALERT_USD_DEFAULT in cost-utils.ts, the
- * single source of truth CostTrackerPanel and budget-breach-notifier.ts share.
+ * single source of truth the Usage modal and budget-breach-notifier.ts share.
  */
 export const BUDGET_ALERT_USD_SYNTHETIC_SETTING: ConfigSetting = {
   key: BUDGET_ALERT_USD_CONFIG_KEY as ConfigKey,
   type: 'number',
   default: BUDGET_ALERT_USD_DEFAULT,
-  description: 'Session cost-budget alert threshold in USD (0 = no budget configured). Set via the Cost panel\'s "b" key or /cost budget <usd>; this entry only displays the current effective value.',
+  description: 'Session cost-budget alert threshold in USD (0 = no budget configured). Set via the Usage modal\'s "b" key or /cost budget <usd>; this entry only displays the current effective value.',
 };
 
 /**
  * Build the synthetic SettingEntry for behavior.budgetAlertUsd.
  *
  * Delegates parsing/fallback to readBudgetAlertUsd (cost-utils.ts) so this
- * display entry can never disagree with what CostTrackerPanel and the
+ * display entry can never disagree with what the Usage modal and the
  * background budget-breach notifier actually read.
  */
 export function buildBudgetAlertUsdSyntheticEntry(configManager: Pick<ConfigManager, 'get'>): SettingEntry {
@@ -370,7 +375,7 @@ export function buildBudgetAlertUsdSyntheticEntry(configManager: Pick<ConfigMana
 const NOTIFY_ALERT_SYNTHETIC_SETTINGS: ReadonlyArray<{ readonly key: string; readonly description: string }> = [
   {
     key: 'behavior.notifyOnBudgetBreach',
-    description: 'Alert when session cost crosses the configured budget (set via the Cost panel\'s "b" key).',
+    description: 'Alert when session cost crosses the configured budget (set via the Usage modal\'s "b" key).',
   },
   {
     key: 'behavior.notifyOnAgentFailure',

package/src/input/settings-modal-types.ts

@@ -93,7 +93,7 @@ export type SettingsCategory =
   | 'google'
   | 'danger';
 
-export type SettingsFocusPane = 'categories' | 'settings';
+export type SettingsFocusRegion = 'categories' | 'settings';
 
 export const SETTINGS_CATEGORY_GROUPS: ReadonlyArray<{
   readonly label: string;

package/src/input/settings-modal.ts

@@ -37,7 +37,7 @@ import {
   type McpEntry,
   type SettingEntry,
   type SettingsCategory,
-  type SettingsFocusPane,
+  type SettingsFocusRegion,
   type SubscriptionEntry,
 } from './settings-modal-types.ts';
 import {
@@ -113,7 +113,7 @@ export {
   type McpEntry,
   type SettingEntry,
   type SettingsCategory,
-  type SettingsFocusPane,
+  type SettingsFocusRegion,
   type SubscriptionEntry,
 } from './settings-modal-types.ts';
 
@@ -130,8 +130,8 @@ export class SettingsModal {
   /** Selected setting index within the current category. */
   public selectedIndex = 0;
 
-  /** Which pane receives up/down navigation and Enter/Space actions. */
-  public focusPane: SettingsFocusPane = 'settings';
+  /** Which region (settings list or documentation) receives up/down navigation and Enter/Space actions. */
+  public focusRegion: SettingsFocusRegion = 'settings';
 
   /** Whether we're in inline edit mode for the selected string/number setting. */
   public editingMode = false;
@@ -139,8 +139,8 @@ export class SettingsModal {
   /** Current value of the inline edit buffer. */
   public editBuffer = '';
   /**
-   * Scroll offset (in wrapped lines) of the documentation pane for the
-   * selected row. The renderer clamps it to the pane's real content height
+   * Scroll offset (in wrapped lines) of the documentation region for the
+   * selected row. The renderer clamps it to the region's real content height
    * and shows honest more-above/below markers, long feature documentation
    * scrolls, it never clips. Reset whenever the selection changes.
    */
@@ -156,7 +156,7 @@ export class SettingsModal {
   /** Set when the highlighted setting should open provider selection before model selection. */
   public pendingProviderModelPickerTarget: ModelPickerTarget | null = null;
   /** Set when a highlighted setting needs an external picker owned by the shell route. */
-  public pendingSettingsPickerAction: 'tts-provider' | 'tts-voice' | null = null;
+  public pendingSettingsPickerAction: 'tts-provider' | 'tts-voice' | 'theme' | null = null;
   /** Provider awaiting explicit logout confirmation, if any. */
   public subscriptionLogoutConfirmationTarget: string | null = null;
 
@@ -251,7 +251,7 @@ export class SettingsModal {
     this.connectionEntries = initialConnectionEntries();
     this.categoryIndex = 0;
     this.selectedIndex = 0;
-    this.focusPane = 'categories';
+    this.focusRegion = 'categories';
     this.editingMode = false;
     this.editBuffer = '';
     this.pendingModelPickerTarget = null;
@@ -268,7 +268,7 @@ export class SettingsModal {
     this.active = true;
   }
 
-  /** Scroll the documentation pane by `delta` wrapped lines (renderer clamps the top end). */
+  /** Scroll the documentation region by `delta` wrapped lines (renderer clamps the top end). */
   scrollContext(delta: number): void {
     this.contextScroll = Math.max(0, this.contextScroll + delta);
   }
@@ -296,7 +296,7 @@ export class SettingsModal {
     this.serviceRegistry = null;
     this.secretsManager = null;
     this.onSettingApplied = null;
-    this.focusPane = 'settings';
+    this.focusRegion = 'settings';
   }
 
   /** Enter search mode (focus the search input bar). */
@@ -355,26 +355,26 @@ export class SettingsModal {
 
   focusCategories(): void {
     if (this.editingMode) return;
-    this.focusPane = 'categories';
+    this.focusRegion = 'categories';
   }
 
   focusSettings(): void {
     if (this.editingMode) return;
-    this.focusPane = 'settings';
+    this.focusRegion = 'settings';
   }
 
-  toggleFocusPane(): void {
+  toggleFocusRegion(): void {
     if (this.editingMode) return;
-    this.focusPane = this.focusPane === 'settings' ? 'categories' : 'settings';
+    this.focusRegion = this.focusRegion === 'settings' ? 'categories' : 'settings';
   }
 
   moveFocusedUp(): void {
-    if (this.focusPane === 'categories') this.prevCategory();
+    if (this.focusRegion === 'categories') this.prevCategory();
     else this.moveUp();
   }
 
   moveFocusedDown(): void {
-    if (this.focusPane === 'categories') this.nextCategory();
+    if (this.focusRegion === 'categories') this.nextCategory();
     else this.moveDown();
   }
 
@@ -476,7 +476,7 @@ export class SettingsModal {
     if (categoryIndex >= 0) {
       this.categoryIndex = categoryIndex;
       this.selectedIndex = 0;
-      this.focusPane = 'settings';
+      this.focusRegion = 'settings';
       return;
     }
 
@@ -487,7 +487,7 @@ export class SettingsModal {
       if (entryIndex >= 0) {
         this.categoryIndex = index;
         this.selectedIndex = entryIndex;
-        this.focusPane = 'settings';
+        this.focusRegion = 'settings';
         return;
       }
     }
@@ -709,7 +709,7 @@ export class SettingsModal {
     // has already applied the change to the gate manager (live flip for
     // runtime-toggleable features, pending-restart marker for startup-gated
     // ones). Re-read the manager for every header bound to this key so the
-    // rows and the context pane show the honest state at the point of change.
+    // rows and the context region show the honest state at the point of change.
     this._syncFeatureHeadersForKey(key);
 
     if (result.restartDomain !== null) {
@@ -721,7 +721,7 @@ export class SettingsModal {
     // No-op (result.changed === false, effectMessage === null): leave lastSettingEffectMessage untouched.
 
     // Selecting 'prompt' for payments.cvvHandling states the tradeoff at the
-    // moment of selection, not just in the documentation pane, see the
+    // moment of selection, not just in the documentation region, see the
     // SDK's own CVV_PROMPT_TRADEOFF_WARNING (platform/payments).
     if (key === PAYMENTS_CVV_HANDLING_CONFIG_KEY && value === 'prompt') {
       this.lastSettingEffectMessage = CVV_PROMPT_TRADEOFF_WARNING;

package/src/input/submission-intent.ts

@@ -5,7 +5,7 @@ export type SubmissionIntentKind =
   | 'orchestration'
   | 'plan'
   | 'review'
-  | 'panel-action'
+  | 'view-action'
   | 'shell'
   | 'memory-pin';
 

package/src/input/submission-router.ts

@@ -3,7 +3,6 @@ import type { SubmissionIntent } from './submission-intent.ts';
 export interface SubmissionRouterInput {
   readonly text: string;
   readonly commandMode?: boolean;
-  readonly panelFocused?: boolean;
   readonly hasAttachments?: boolean;
 }
 
@@ -12,7 +11,7 @@ export interface SubmissionRouterInput {
 // 'plan' composer intent/label. The /plan mode-toggle is a plain slash command.
 const PLAN_COMMANDS = new Set(['project-plan', 'planning']);
 const REVIEW_COMMANDS = new Set(['review']);
-const PANEL_COMMANDS = new Set(['panel']);
+const LEGACY_PANEL_COMMANDS = new Set(['panel']);
 const ORCHESTRATION_COMMANDS = new Set([
   'wrfc',
   'orchestration',
@@ -30,11 +29,7 @@ export function routeSubmissionIntent(input: SubmissionRouterInput): SubmissionI
   const hasAttachments = input.hasAttachments ?? false;
 
   if (!trimmed) {
-    return {
-      kind: input.panelFocused ? 'panel-action' : 'empty',
-      label: input.panelFocused ? 'panel action' : 'prompt',
-      hasAttachments,
-    };
+    return { kind: 'empty', label: 'prompt', hasAttachments };
   }
 
   if (trimmed.startsWith('!#')) {
@@ -53,8 +48,8 @@ export function routeSubmissionIntent(input: SubmissionRouterInput): SubmissionI
     if (REVIEW_COMMANDS.has(commandName)) {
       return { kind: 'review', label: 'review', commandName, hasAttachments };
     }
-    if (PANEL_COMMANDS.has(commandName)) {
-      return { kind: 'panel-action', label: 'panel action', commandName, hasAttachments };
+    if (LEGACY_PANEL_COMMANDS.has(commandName)) {
+      return { kind: 'view-action', label: 'open view', commandName, hasAttachments };
     }
     if (ORCHESTRATION_COMMANDS.has(commandName)) {
       return { kind: 'orchestration', label: 'orchestration', commandName, hasAttachments };

package/src/input/surface-modal-host.ts

@@ -0,0 +1,110 @@
+/**
+ * surface-modal-host.ts, a stack of self-contained kit modals.
+ *
+ * A SurfaceModal owns its keys, its own sub-levels and its rendering (drawn
+ * with the surface kit). The host keeps them in a stack on the InputHandler:
+ *
+ *   - Keys go to the top modal only (focus always belongs to the top modal).
+ *   - Esc pops exactly one level: the top modal's own sub-level first
+ *     (escape() returns true), otherwise the top modal closes. The next Esc
+ *     reaches the modal underneath, then the rest of the Esc chain
+ *     (handler-modal-stack.ts: close modal, clear composer, cancel turn).
+ *   - Every modal in the stack renders, bottom to top; each one dims what is
+ *     underneath it.
+ *
+ * The command palette and the confirm dialog are SurfaceModals; any new modal
+ * can be one without touching the handler plumbing again.
+ */
+
+import type { InputToken } from '@pellux/goodvibes-sdk/platform/core';
+import type { SurfaceLayer } from '../renderer/surface-kit.ts';
+
+export type SurfaceModalCloseReason = 'escape' | 'done' | 'cleared';
+
+export interface SurfaceModal {
+  /** A short identifier (tests, diagnostics). */
+  readonly name: string;
+  /** Handle a key or text token while this modal is on top. */
+  handleToken(token: InputToken, host: SurfaceModalHost): void;
+  /** Esc: pop one of this modal's own sub-levels and return true, or return false to close the modal. */
+  escape?(): boolean;
+  /** Draw the modal for a screen of the given size. */
+  render(screenWidth: number, screenHeight: number): SurfaceLayer;
+  /** Called once when the modal leaves the stack. */
+  onClose?(reason: SurfaceModalCloseReason): void;
+}
+
+export class SurfaceModalHost {
+  private readonly stack: SurfaceModal[] = [];
+
+  /** Called after the stack changes (wired to the render request). */
+  onChange: (() => void) | null = null;
+
+  get active(): boolean {
+    return this.stack.length > 0;
+  }
+
+  get depth(): number {
+    return this.stack.length;
+  }
+
+  top(): SurfaceModal | undefined {
+    return this.stack[this.stack.length - 1];
+  }
+
+  /** The open modals, bottom first. */
+  modals(): readonly SurfaceModal[] {
+    return this.stack;
+  }
+
+  /** Open a modal on top of whatever is open. Opening one already in the stack moves it to the top. */
+  push(modal: SurfaceModal): void {
+    const existing = this.stack.indexOf(modal);
+    if (existing >= 0) this.stack.splice(existing, 1);
+    this.stack.push(modal);
+    this.onChange?.();
+  }
+
+  /** Remove a modal (usually the top one closing itself after acting). */
+  close(modal: SurfaceModal, reason: SurfaceModalCloseReason = 'done'): void {
+    const index = this.stack.indexOf(modal);
+    if (index < 0) return;
+    this.stack.splice(index, 1);
+    modal.onClose?.(reason);
+    this.onChange?.();
+  }
+
+  /** Esc: one level. Returns false when nothing was open. */
+  escape(): boolean {
+    const top = this.top();
+    if (!top) return false;
+    if (top.escape?.() === true) {
+      this.onChange?.();
+      return true;
+    }
+    this.close(top, 'escape');
+    return true;
+  }
+
+  /** Route a token to the top modal. Returns false when nothing was open. */
+  handleToken(token: InputToken): boolean {
+    const top = this.top();
+    if (!top) return false;
+    top.handleToken(token, this);
+    return true;
+  }
+
+  /** Close everything (e.g. when the whole modal stack is cleared). */
+  clear(): void {
+    while (this.stack.length > 0) {
+      const modal = this.stack.pop()!;
+      modal.onClose?.('cleared');
+    }
+    this.onChange?.();
+  }
+
+  /** Layers for the compositor, bottom first. */
+  render(screenWidth: number, screenHeight: number): SurfaceLayer[] {
+    return this.stack.map((modal) => modal.render(screenWidth, screenHeight));
+  }
+}