@flyingrobots/bijou-tui 7.0.0 → 7.2.0

package/dist/app-frame.js

@@ -4,7 +4,7 @@
  * Provides tabs, pane focus/scroll isolation, shell key handling, help,
  * panel-scoped overlay context, and optional frame-level command palette.
  */
-import { cloneContextWithResolvedTheme, createResolved, createSurface, perfOverlaySurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
+import { cloneContextWithResolvedTheme, createSurface, perfOverlaySurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
 import { createKeyMap, formatKeyCombo } from './keybindings.js';
 import { isKeyMsg, isMouseMsg, isResizeMsg } from './types.js';
 import { quit } from './commands.js';
@@ -16,15 +16,19 @@ import { restoreLayoutState } from './layout-preset.js';
 import { createNotificationState, dismissNotification, hitTestNotificationStack, notificationsNeedTick, pushNotification, renderNotificationStack, tickNotifications, trimNotificationsToViewport, } from './notification.js';
 import { isFrameScopedMsg, isPageScopedMsg, wrapCmdForPage, emitMsg, emitMsgForPage, wrapFrameMsg, } from './app-frame-types.js';
 import { createFrameKeyMap, frameBodyRect, mergeBindingSources, resolveFramePageText, } from './app-frame-utils.js';
-import { renderHelpOverlay, isHelpScrollAction, resolveCurrentShellTheme, resolveNextShellTheme, resolveShellThemeForContext, resolveFrameSettings, resolveFrameNotificationCenter, resolveSettingsLayout, resolveNotificationCenterLayout, resolveInputAreas, findInputAreaByPaneId, moveSettingsFocus, scrollSettingsBy, clampSettingsScroll, scrollNotificationCenterBy, cycleNotificationCenterFilter, clampSettingsFocus, renderSettingsDrawer, renderNotificationCenterDrawer, resolveNotificationFooterCue, } from './app-frame-overlays.js';
+import { renderHelpOverlay, isHelpScrollAction, resolveFrameShellThemeChoices, resolveCurrentShellTheme, resolveNextShellTheme, resolveShellThemeModeToggle, resolveShellThemeForContext, resolveFrameSettings, resolveFrameNotificationCenter, resolveSettingsLayout, resolveNotificationCenterLayout, resolveInputAreas, findInputAreaByPaneId, moveSettingsFocus, scrollSettingsBy, clampSettingsScroll, scrollNotificationCenterBy, cycleNotificationCenterFilter, clampSettingsFocus, renderSettingsDrawer, renderNotificationCenterDrawer, resolveNotificationFooterCue, } from './app-frame-overlays.js';
 import { activeFrameLayer, describeFrameRuntimeViewStack, projectFrameControls, } from './app-frame-layers.js';
 import { applyRuntimeCommandBuffer, bufferRuntimeRouteResult, createRuntimeBuffers, createRuntimeRetainedLayouts, retainRuntimeLayout, routeRuntimeInput, } from './runtime-engine.js';
 import { frameMessage, frameNotificationFilterLabel, } from './app-frame-i18n.js';
 import { resolveHeaderLine, renderHelpLine, renderPageContent, renderPageContentInto, renderMaximizedPane, renderMaximizedPaneInto, renderTransition, createFramePaneScratchPool, } from './app-frame-render.js';
 import { applyFrameAction, scrollFocusedPane, switchTab, syncPageFrameState, } from './app-frame-actions.js';
 import { handlePaletteKey, openCommandPalette, openSearchPalette, } from './app-frame-palette.js';
-import { createInputActionMap, createInputGestureRecognizer, } from './input-map.js';
-export { emitFrameAction, notify, } from './app-frame-types.js';
+/** Stable values for shell theme mode siblings. */
+export const FRAME_SHELL_THEME_MODE_SUPPORT = Object.freeze({
+    single: 'single',
+    paired: 'paired',
+});
+export { FRAME_MSG_TOKEN, PAGE_MSG_TOKEN, emitMsg, emitFrameAction, emitMsgForPage, isFrameScopedMsg, isPageScopedMsg, notify, wrapCmdForPage, wrapFrameMsg, wrapPageMsg, } from './app-frame-types.js';
 export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, projectFrameControls, underlyingFrameLayer, } from './app-frame-layers.js';
 // ---------------------------------------------------------------------------
 // Frame Notification Helpers
@@ -32,7 +36,6 @@ export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStac
 const FRAME_NOTIFICATION_TICK_MS = 40;
 const DEFAULT_FRAME_NOTIFICATION_DURATION_MS = 6_000;
 const SETTINGS_FEEDBACK_TOAST_WIDTH = 40;
-const FRAME_FOOTER_DOUBLE_TAB_MS = 300;
 const EMPTY_RUNTIME_LAYOUTS = createRuntimeRetainedLayouts();
 function createQuitHelpKeys(i18n) {
     const t = (id, fallback) => frameMessage(i18n, id, fallback);
@@ -148,7 +151,7 @@ function cloneShellThemeContext(ctx, resolvedTheme) {
 function readStageDuration(timings, stage) {
     return timings.find((timing) => timing.stage === stage)?.durationMs ?? 0;
 }
-function summarizeFrameTimings(timings, frameBudgetMs) {
+export function summarizeFrameTimings(timings, frameBudgetMs) {
     const frameTimeMs = timings.reduce((total, timing) => total + timing.durationMs, 0);
     return {
         frameTimeMs,
@@ -158,6 +161,36 @@ function summarizeFrameTimings(timings, frameBudgetMs) {
         frameOverBudget: frameBudgetMs != null && frameTimeMs > frameBudgetMs,
     };
 }
+export function renderFramePerfHudOverlay(telemetry, options = {}) {
+    const refreshRate = telemetry.refreshRate ?? options.ctx?.runtime.refreshRate ?? 60;
+    const fps = telemetry.frameTimeMs > 0
+        ? Math.min(refreshRate, 1000 / telemetry.frameTimeMs)
+        : refreshRate;
+    const width = Math.max(12, Math.min(40, telemetry.columns - 2));
+    const surface = perfOverlaySurface({
+        fps,
+        frameTimeMs: telemetry.frameTimeMs,
+        width: telemetry.columns,
+        height: telemetry.rows,
+        extras: [
+            { label: 'view', value: `${telemetry.viewTimeMs.toFixed(2)} ms` },
+            { label: 'diff', value: `${telemetry.diffTimeMs.toFixed(2)} ms` },
+        ],
+    }, {
+        title: frameMessage(options.i18n, 'perfHud.title', 'Perf HUD'),
+        width,
+        showChart: false,
+        borderToken: options.ctx?.border('primary'),
+        bgToken: options.ctx?.surface('elevated'),
+        ctx: options.ctx,
+    });
+    return {
+        content: '',
+        surface,
+        row: 1,
+        col: Math.max(0, telemetry.columns - surface.width - 1),
+    };
+}
 function applyFrameTimingSnapshot(model, snapshot) {
     if (model.frameTimeMs === snapshot.frameTimeMs
         && model.viewTimeMs === snapshot.viewTimeMs
@@ -201,14 +234,15 @@ export function createFramedApp(options) {
         pagesById.set(page.id, page);
     }
     const pageOrder = options.pages.map((p) => p.id);
-    const defaultPageId = options.defaultPageId ?? pageOrder[0];
-    if (!pagesById.has(defaultPageId)) {
-        throw new Error(`createFramedApp: defaultPageId "${defaultPageId}" not found in pages`);
+    const defaultPageId = options.defaultPageId ?? pageOrder.at(0);
+    if (defaultPageId === undefined || !pagesById.has(defaultPageId)) {
+        throw new Error(`createFramedApp: defaultPageId "${String(defaultPageId)}" not found in pages`);
     }
     const shellThemeSpecs = options.shellThemes ?? [];
     let defaultFrameCtx = options.ctx ?? resolveSafeCtx();
     let resolvedShellThemes = [];
-    const enableShellThemeSettings = shellThemeSpecs.length > 1;
+    const enableShellThemeSettings = shellThemeSpecs.length > 1
+        || shellThemeSpecs.some((theme) => (theme.modes?.length ?? 0) > 1);
     const usesAmbientDefaultContext = options.ctx == null && defaultFrameCtx != null;
     let frameCtx = options.ctx;
     let frameCtxShellThemeId;
@@ -221,13 +255,7 @@ export function createFramedApp(options) {
             throw new Error('createFramedApp: shellThemes requires options.ctx, app.run({ ctx }), or a default Bijou context');
         }
         defaultFrameCtx ??= baseCtx;
-        resolvedShellThemes = shellThemeSpecs.map((theme) => ({
-            id: theme.id,
-            label: theme.label,
-            description: theme.description,
-            shellTheme: theme,
-            resolvedTheme: createResolved(theme.theme, defaultFrameCtx.theme.noColor, defaultFrameCtx.theme.colorScheme),
-        }));
+        resolvedShellThemes = resolveFrameShellThemeChoices(shellThemeSpecs, defaultFrameCtx);
     }
     if (frameCtx != null) {
         ensureResolvedShellThemes(frameCtx);
@@ -263,22 +291,21 @@ export function createFramedApp(options) {
         }
         options.onShellThemeChange?.({
             shellTheme: nextTheme.shellTheme,
+            shellThemeSpec: nextTheme.shellThemeSpec,
+            shellThemeId: nextTheme.shellThemeId,
+            shellThemeLabel: nextTheme.shellThemeLabel,
+            modeId: nextTheme.modeId,
+            modeLabel: nextTheme.modeLabel,
             ctx: frameCtx,
         });
         return frameCtx;
     }
     const frameKeys = createFrameKeyMap({
         enableSettings: options.settings != null || enableShellThemeSettings,
+        enableShellThemeModeToggle: shellThemeSpecs.some((theme) => (theme.modes?.length ?? 0) > 1),
         enableNotifications: options.notificationCenter != null || options.runtimeNotifications !== false,
         i18n: options.i18n,
     });
-    const frameInputRecognizer = createInputGestureRecognizer({
-        doubleTapMs: FRAME_FOOTER_DOUBLE_TAB_MS,
-    });
-    const frameInputActions = createInputActionMap()
-        .bind('frame.footer.doubleTab', 'Toggle footer', [
-        { deviceId: 'keyboard', featureId: 'key.tab', type: 'double-tap' },
-    ], { type: 'toggle-footer' });
     const quitHelpKeys = createQuitHelpKeys(options.i18n);
     const helpLayerHelpKeys = createHelpLayerHelpKeys(options.i18n);
     const settingsHelpKeys = createSettingsHelpKeys(options.i18n);
@@ -300,10 +327,10 @@ export function createFramedApp(options) {
     });
     function bindingComboKey(binding) {
         const combo = binding.combo;
-        return `${combo.key}|${combo.ctrl ? 1 : 0}|${combo.alt ? 1 : 0}|${combo.shift ? 1 : 0}`;
+        return [combo.key, combo.ctrl ? '1' : '0', combo.alt ? '1' : '0', combo.shift ? '1' : '0'].join('|');
     }
     function findBindingForMessage(bindings, msg) {
-        const comboKey = `${msg.key}|${msg.ctrl ? 1 : 0}|${msg.alt ? 1 : 0}|${msg.shift ? 1 : 0}`;
+        const comboKey = [msg.key, msg.ctrl ? '1' : '0', msg.alt ? '1' : '0', msg.shift ? '1' : '0'].join('|');
         return bindings.find((binding) => binding.enabled && bindingComboKey(binding) === comboKey);
     }
     function queueFrameKeyCollisionWarning(model, msg, teaCmds) {
@@ -320,7 +347,7 @@ export function createFramedApp(options) {
         const frameBinding = findBindingForMessage(frameKeys.bindings(), msg);
         if (pageBinding == null || frameBinding == null)
             return model;
-        const warningCmd = async () => wrapFrameMsg({
+        const warningCmd = () => wrapFrameMsg({
             type: 'runtime-issue',
             issue: {
                 level: 'warning',
@@ -342,43 +369,12 @@ export function createFramedApp(options) {
         };
     }
     function getComposedFrameScratch(width, height) {
-        if (composedFrameScratch == null
-            || composedFrameScratch.width !== width
+        if (composedFrameScratch?.width !== width
             || composedFrameScratch.height !== height) {
             composedFrameScratch = createSurface(width, height);
         }
         return composedFrameScratch;
     }
-    function renderFramePerfHudOverlay(model, ctx) {
-        const refreshRate = ctx?.runtime.refreshRate ?? 60;
-        const fps = model.frameTimeMs > 0
-            ? Math.min(refreshRate, 1000 / model.frameTimeMs)
-            : refreshRate;
-        const width = Math.max(12, Math.min(40, model.columns - 2));
-        const surface = perfOverlaySurface({
-            fps,
-            frameTimeMs: model.frameTimeMs,
-            width: model.columns,
-            height: model.rows,
-            extras: [
-                { label: 'view', value: `${model.viewTimeMs.toFixed(2)} ms` },
-                { label: 'diff', value: `${model.diffTimeMs.toFixed(2)} ms` },
-            ],
-        }, {
-            title: frameMessage(options.i18n, 'perfHud.title', 'Perf HUD'),
-            width,
-            showChart: false,
-            borderToken: ctx?.border('primary'),
-            bgToken: ctx?.surface('elevated'),
-            ctx,
-        });
-        return {
-            content: '',
-            surface,
-            row: 1,
-            col: Math.max(0, model.columns - surface.width - 1),
-        };
-    }
     function closeCommandPalette(model) {
         return {
             ...model,
@@ -388,189 +384,171 @@ export function createFramedApp(options) {
             commandPaletteKind: undefined,
         };
     }
-    const shellCommandHandlers = {
-        // --- overlay lifecycle ---
-        'close-help': (model) => ({ ...model, helpOpen: false, helpScrollY: 0 }),
-        'close-settings': (model) => ({ ...model, settingsOpen: false }),
-        'close-notification-center': (model) => ({ ...model, notificationCenterOpen: false, notificationCenterScrollY: 0 }),
-        'close-palette': (model) => closeCommandPalette(model),
-        'close-quit-confirm': (model) => ({ ...model, quitConfirmOpen: false }),
-        'open-help': (model) => ({ ...model, helpOpen: true }),
-        'open-quit-confirm': (model) => {
-            if (!shouldUseShellQuitConfirm())
-                return model;
-            if (model.quitConfirmOpen)
-                return model;
-            return {
-                ...model,
-                quitConfirmOpen: true,
-                helpOpen: false,
-                helpScrollY: 0,
-                settingsOpen: false,
-                notificationCenterOpen: false,
-                commandPalette: undefined,
-                commandPaletteEntries: undefined,
-                commandPaletteTitle: undefined,
-                commandPaletteKind: undefined,
-            };
-        },
-        'open-search-palette': (model) => openSearchPalette(model, frameKeys, options, pagesById),
-        'open-command-palette': (model) => openCommandPalette(model, frameKeys, options, pagesById),
-        // --- settings ---
-        'settings-focus-move': (model, cmd) => {
-            const c = cmd;
-            const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
-            return layout != null ? moveSettingsFocus(model, layout, c.delta) : model;
-        },
-        'settings-scroll': (model, cmd) => {
-            const c = cmd;
-            const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
-            return layout != null ? scrollSettingsBy(model, layout, c.delta) : model;
-        },
-        'settings-scroll-to': (model, cmd) => {
-            const c = cmd;
-            const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
-            if (layout == null)
-                return model;
-            return { ...model, settingsScrollY: c.position === 'top' ? 0 : layout.maxScrollY };
-        },
-        'activate-settings-row': (model, cmd, teaCmds) => {
-            const c = cmd;
-            const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
-            if (layout == null)
-                return model;
-            const hitRow = layout.rows.find((r) => r.index === c.rowIndex);
-            if (hitRow == null)
-                return model;
-            const focusedModel = { ...model, settingsFocusIndex: hitRow.index };
-            if (hitRow.behavior === 'cycle-shell-theme') {
-                const [nextModel, cmds] = cycleShellThemeSetting(focusedModel, hitRow.row);
+    function applyShellCommand(model, cmd, teaCmds) {
+        switch (cmd.type) {
+            case 'close-help':
+                return { ...model, helpOpen: false, helpScrollY: 0 };
+            case 'close-settings':
+                return { ...model, settingsOpen: false };
+            case 'close-notification-center':
+                return { ...model, notificationCenterOpen: false, notificationCenterScrollY: 0 };
+            case 'close-palette':
+                return closeCommandPalette(model);
+            case 'close-quit-confirm':
+                return { ...model, quitConfirmOpen: false };
+            case 'open-help':
+                return { ...model, helpOpen: true };
+            case 'open-quit-confirm': {
+                if (!shouldUseShellQuitConfirm() || model.quitConfirmOpen)
+                    return model;
+                return {
+                    ...model,
+                    quitConfirmOpen: true,
+                    helpOpen: false,
+                    helpScrollY: 0,
+                    settingsOpen: false,
+                    notificationCenterOpen: false,
+                    commandPalette: undefined,
+                    commandPaletteEntries: undefined,
+                    commandPaletteTitle: undefined,
+                    commandPaletteKind: undefined,
+                };
+            }
+            case 'open-search-palette':
+                return openSearchPalette(model, frameKeys, options, pagesById);
+            case 'open-command-palette':
+                return openCommandPalette(model, frameKeys, options, pagesById);
+            case 'settings-focus-move': {
+                const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
+                return layout != null ? moveSettingsFocus(model, layout, cmd.delta) : model;
+            }
+            case 'settings-scroll': {
+                const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
+                return layout != null ? scrollSettingsBy(model, layout, cmd.delta) : model;
+            }
+            case 'settings-scroll-to': {
+                const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
+                if (layout == null)
+                    return model;
+                return { ...model, settingsScrollY: cmd.position === 'top' ? 0 : layout.maxScrollY };
+            }
+            case 'activate-settings-row': {
+                const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
+                if (layout == null)
+                    return model;
+                const hitRow = layout.rows.find((row) => row.index === cmd.rowIndex);
+                if (hitRow == null)
+                    return model;
+                const focusedModel = { ...model, settingsFocusIndex: hitRow.index };
+                if (hitRow.behavior === 'cycle-shell-theme') {
+                    const [nextModel, cmds] = cycleShellThemeSetting(focusedModel, hitRow.row);
+                    teaCmds.push(...cmds);
+                    return nextModel;
+                }
+                if (hitRow.row.action === undefined || hitRow.row.enabled === false || hitRow.row.kind === 'info') {
+                    return focusedModel;
+                }
+                const [nextModel, cmds] = activateSettingsRow(focusedModel, hitRow.row);
                 teaCmds.push(...cmds);
                 return nextModel;
             }
-            if (hitRow.row.action === undefined || hitRow.row.enabled === false || hitRow.row.kind === 'info') {
-                return focusedModel;
+            case 'toggle-shell-theme-mode': {
+                const [nextModel, cmds] = toggleShellThemeMode(model);
+                teaCmds.push(...cmds);
+                return nextModel;
             }
-            const [nextModel, cmds] = activateSettingsRow(focusedModel, hitRow.row);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        // --- notification center ---
-        'notification-center-scroll': (model, cmd) => {
-            const c = cmd;
-            const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
-            return layout != null ? scrollNotificationCenterBy(model, layout, c.delta) : model;
-        },
-        'notification-center-scroll-to': (model, cmd) => {
-            const c = cmd;
-            const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
-            if (layout == null)
+            case 'notification-center-scroll': {
+                const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
+                return layout != null ? scrollNotificationCenterBy(model, layout, cmd.delta) : model;
+            }
+            case 'notification-center-scroll-to': {
+                const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
+                if (layout == null)
+                    return model;
+                return { ...model, notificationCenterScrollY: cmd.position === 'top' ? 0 : layout.maxScrollY };
+            }
+            case 'cycle-notification-filter': {
+                const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
+                if (layout == null)
+                    return model;
+                const [nextModel, cmds] = cycleNotificationCenterFilter(model, layout);
+                teaCmds.push(...cmds);
+                return nextModel;
+            }
+            case 'warn-frame-key-collision':
+                return queueFrameKeyCollisionWarning(model, cmd.msg, teaCmds);
+            case 'help-scroll': {
+                const helpSource = resolvePresentedLayerContext(model).controlProjection.helpSource;
+                if (helpSource == null)
+                    return model;
+                const overlay = renderHelpOverlay(model, helpSource, options.i18n);
+                const viewportHeight = Math.max(1, overlay.body.height - 1);
+                const delta = cmd.action === 'down' ? 3
+                    : cmd.action === 'up' ? -3
+                        : cmd.action === 'page-down' ? viewportHeight
+                            : cmd.action === 'page-up' ? -viewportHeight
+                                : cmd.action === 'bottom' ? Infinity
+                                    : -Infinity;
+                return { ...model, helpScrollY: Math.max(0, Math.min(overlay.maxScrollY, overlay.scrollY + delta)) };
+            }
+            case 'focus-pane':
+                return focusPane(model, cmd.paneId);
+            case 'scroll-focused-pane':
+                return scrollFocusedPane(model, { type: cmd.direction === 'down' ? 'scroll-down' : 'scroll-up' }, pagesById, options);
+            case 'switch-tab': {
+                const [nextModel, cmds] = switchTab(model, cmd.delta, pagesById, options);
+                teaCmds.push(...cmds);
+                return nextModel;
+            }
+            case 'apply-frame-action': {
+                const [nextModel, cmds] = applyFrameAction(cmd.action, model, options, pagesById);
+                teaCmds.push(...cmds);
+                return nextModel;
+            }
+            case 'palette-key': {
+                const [nextModel, cmds] = handlePaletteKey(cmd.msg, model, paletteKeys, options, pagesById, (action, closedModel) => action.type === 'toggle-shell-theme-mode'
+                    ? toggleShellThemeMode(closedModel)
+                    : undefined);
+                teaCmds.push(...cmds);
+                return nextModel;
+            }
+            case 'emit-page-msg':
+                teaCmds.push(emitMsgForPage(cmd.pageId, cmd.msg));
                 return model;
-            return { ...model, notificationCenterScrollY: c.position === 'top' ? 0 : layout.maxScrollY };
-        },
-        'cycle-notification-filter': (model, _cmd, teaCmds) => {
-            const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
-            if (layout == null)
+            case 'emit-global-msg':
+                teaCmds.push(emitMsg(cmd.msg));
                 return model;
-            const [nextModel, cmds] = cycleNotificationCenterFilter(model, layout);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        'warn-frame-key-collision': (model, cmd, teaCmds) => {
-            const c = cmd;
-            return queueFrameKeyCollisionWarning(model, c.msg, teaCmds);
-        },
-        // --- help ---
-        'help-scroll': (model, cmd) => {
-            const c = cmd;
-            const helpSource = resolvePresentedLayerContext(model).controlProjection.helpSource;
-            if (helpSource == null) {
+            case 'quit':
+                teaCmds.push(quit());
                 return model;
+            case 'dismiss-notification': {
+                if (!frameNotificationOptions.enabled)
+                    return model;
+                const nowMs = resolveClock(resolveFrameCtx()).now();
+                const [nextModel, cmds] = applyFrameNotificationState(model, dismissNotification(model.runtimeNotifications, cmd.notificationId, nowMs), nowMs);
+                teaCmds.push(...cmds);
+                return nextModel;
             }
-            const overlay = renderHelpOverlay(model, helpSource, options.i18n);
-            const viewportHeight = Math.max(1, overlay.body.height - 1);
-            const delta = c.action === 'down' ? 3
-                : c.action === 'up' ? -3
-                    : c.action === 'page-down' ? viewportHeight
-                        : c.action === 'page-up' ? -viewportHeight
-                            : c.action === 'bottom' ? Infinity
-                                : /* top */ -Infinity;
-            return {
-                ...model,
-                helpScrollY: Math.max(0, Math.min(overlay.maxScrollY, overlay.scrollY + delta)),
-            };
-        },
-        // --- workspace ---
-        'focus-pane': (model, cmd) => {
-            const c = cmd;
-            return focusPane(model, c.paneId);
-        },
-        'scroll-focused-pane': (model, cmd) => {
-            const c = cmd;
-            return scrollFocusedPane(model, { type: c.direction === 'down' ? 'scroll-down' : 'scroll-up' }, pagesById, options);
-        },
-        'switch-tab': (model, cmd, teaCmds) => {
-            const c = cmd;
-            const [nextModel, cmds] = switchTab(model, c.delta, pagesById, options);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        // --- delegation ---
-        'apply-frame-action': (model, cmd, teaCmds) => {
-            const c = cmd;
-            const [nextModel, cmds] = applyFrameAction(c.action, model, options, pagesById);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        'palette-key': (model, cmd, teaCmds) => {
-            const c = cmd;
-            const [nextModel, cmds] = handlePaletteKey(c.msg, model, paletteKeys, options, pagesById);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        // --- TEA command emissions ---
-        'emit-page-msg': (model, cmd, teaCmds) => {
-            const c = cmd;
-            teaCmds.push(emitMsgForPage(c.pageId, c.msg));
-            return model;
-        },
-        'emit-global-msg': (model, cmd, teaCmds) => {
-            const c = cmd;
-            teaCmds.push(emitMsg(c.msg));
-            return model;
-        },
-        'quit': (_model, _cmd, teaCmds) => {
-            teaCmds.push(quit());
-            return _model;
-        },
-        'dismiss-notification': (model, cmd, teaCmds) => {
-            const c = cmd;
-            if (!frameNotificationOptions.enabled)
+            case 'observed-key': {
+                const observed = options.observeKey?.(cmd.msg, cmd.route);
+                if (observed !== undefined)
+                    teaCmds.push(emitMsgForPage(model.activePageId, observed));
                 return model;
-            const nowMs = resolveClock(resolveFrameCtx()).now();
-            const [nextModel, cmds] = applyFrameNotificationState(model, dismissNotification(model.runtimeNotifications, c.notificationId, nowMs), nowMs);
-            teaCmds.push(...cmds);
-            return nextModel;
-        },
-        // --- observation ---
-        'observed-key': (model, cmd, teaCmds) => {
-            const c = cmd;
-            const observed = options.observeKey?.(c.msg, c.route);
-            if (observed !== undefined) {
-                teaCmds.push(emitMsgForPage(model.activePageId, observed));
             }
-            return model;
-        },
-    };
+        }
+    }
     function drainShellCommandBuffer(model, routeResult) {
         const buffers = bufferRuntimeRouteResult(createRuntimeBuffers(), routeResult);
         const teaCmds = [];
-        const { state } = applyRuntimeCommandBuffer(model, buffers.commands, (s, cmd) => shellCommandHandlers[cmd.type](s, cmd, teaCmds));
+        const { state } = applyRuntimeCommandBuffer(model, buffers.commands, (s, cmd) => applyShellCommand(s, cmd, teaCmds));
         return [state, teaCmds];
     }
     function resolveLayerContext(model) {
         const activePage = pagesById.get(model.activePageId);
         const activePageModel = model.pageModels[model.activePageId];
+        if (activePage == null || activePageModel === undefined) {
+            throw new Error(`createFramedApp: active page "${model.activePageId}" is missing`);
+        }
         const inputAreas = resolveInputAreas(activePage, activePageModel);
         const activeInputArea = findInputAreaByPaneId(inputAreas, model.focusedPaneByPage[model.activePageId]);
         const modalKeyMap = activePage.modalKeyMap?.(activePageModel);
@@ -592,23 +570,6 @@ export function createFramedApp(options) {
         }
         return [{ type: 'observed-key', msg, route }, { type: 'open-quit-confirm' }];
     }
-    function resolveFrameInputActionCommands(msg, route) {
-        const inputEvent = frameInputRecognizer.observeKey(msg, resolveClock(resolveFrameCtx()).now());
-        const inputAction = frameInputActions.handle(inputEvent);
-        if (inputAction == null || msg.ctrl || msg.alt || msg.shift) {
-            return undefined;
-        }
-        return [{ type: 'observed-key', msg, route }, { type: 'apply-frame-action', action: inputAction }];
-    }
-    function routeForFrameInputAction(layerKind) {
-        if (layerKind === 'search' || layerKind === 'command-palette')
-            return 'palette';
-        if (layerKind === 'help')
-            return 'help';
-        if (layerKind === 'page-modal')
-            return 'page';
-        return 'frame';
-    }
     function resolveFrameActionCommands(msg, action, route) {
         if (action.type === 'open-search' && options.enableCommandPalette) {
             return [{ type: 'observed-key', msg, route }, { type: 'open-search-palette' }];
@@ -616,6 +577,9 @@ export function createFramedApp(options) {
         if (action.type === 'open-palette' && options.enableCommandPalette) {
             return [{ type: 'observed-key', msg, route }, { type: 'open-command-palette' }];
         }
+        if (action.type === 'toggle-shell-theme-mode') {
+            return [{ type: 'observed-key', msg, route }, { type: 'toggle-shell-theme-mode' }];
+        }
         return [{ type: 'observed-key', msg, route }, { type: 'apply-frame-action', action }];
     }
     function handlePaletteLayerKeyCommands(msg, routedLayerKind) {
@@ -637,6 +601,9 @@ export function createFramedApp(options) {
                 ? [obs, { type: 'close-palette' }]
                 : [obs, { type: 'open-command-palette' }];
         }
+        if (frameAction?.type === 'toggle-shell-theme-mode') {
+            return [obs, { type: 'toggle-shell-theme-mode' }];
+        }
         if (frameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'close-palette' }, { type: 'apply-frame-action', action: frameAction }];
         }
@@ -654,6 +621,9 @@ export function createFramedApp(options) {
             return quitRequestCommands(msg, 'help');
         }
         const helpAction = frameKeys.handle(msg);
+        if (helpAction?.type === 'toggle-shell-theme-mode') {
+            return [obs, { type: 'toggle-shell-theme-mode' }];
+        }
         if (helpAction?.type === 'toggle-perf-hud') {
             return [obs, { type: 'apply-frame-action', action: helpAction }];
         }
@@ -692,6 +662,9 @@ export function createFramedApp(options) {
             return [obs, { type: 'open-command-palette' }];
         }
         const settingsFrameAction = frameKeys.handle(msg);
+        if (settingsFrameAction?.type === 'toggle-shell-theme-mode') {
+            return [obs, { type: 'toggle-shell-theme-mode' }];
+        }
         if (settingsFrameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'apply-frame-action', action: settingsFrameAction }];
         }
@@ -747,6 +720,9 @@ export function createFramedApp(options) {
             return quitRequestCommands(msg, 'frame');
         }
         const centerFrameAction = frameKeys.handle(msg);
+        if (centerFrameAction?.type === 'toggle-shell-theme-mode') {
+            return [obs, { type: 'toggle-shell-theme-mode' }];
+        }
         if (centerFrameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'apply-frame-action', action: centerFrameAction }];
         }
@@ -840,10 +816,6 @@ export function createFramedApp(options) {
             const frameLayer = layer.model;
             if (frameLayer == null)
                 return undefined;
-            const inputActionCommands = resolveFrameInputActionCommands(msg, routeForFrameInputAction(frameLayer.kind));
-            if (inputActionCommands != null) {
-                return { handled: true, commands: inputActionCommands };
-            }
             if (frameLayer.kind === 'search' || frameLayer.kind === 'command-palette') {
                 return { handled: true, commands: handlePaletteLayerKeyCommands(msg, frameLayer.kind) };
             }
@@ -923,9 +895,13 @@ export function createFramedApp(options) {
     }
     function rememberWorkspaceLayout(model, paneRects, tabTargets) {
         const activePageId = model.activePageId;
+        const activePageModel = model.pageModels[activePageId];
+        if (activePageModel === undefined) {
+            throw new Error(`createFramedApp: active page model "${activePageId}" is missing`);
+        }
         const next = {
             activePageId,
-            activePageModel: model.pageModels[activePageId],
+            activePageModel,
             columns: model.columns,
             rows: model.rows,
             visibilityState: model.minimizedByPage[activePageId],
@@ -953,7 +929,9 @@ export function createFramedApp(options) {
     }
     function resolveWorkspaceLayout(model) {
         if (matchesWorkspaceLayoutCache(model)) {
-            return workspaceLayoutCache;
+            const cached = workspaceLayoutCache;
+            if (cached !== undefined)
+                return cached;
         }
         const bodyRect = resolveBodyRect(model, options);
         const maxState = model.maximizedPaneByPage[model.activePageId];
@@ -981,7 +959,7 @@ export function createFramedApp(options) {
             const clippedBottom = Math.min(viewportBottom, screenRow + flatRow.height);
             if (clippedTop >= clippedBottom)
                 continue;
-            children.push(createShellRetainedLayoutNode(`settings-row:${flatRow.index}`, {
+            children.push(createShellRetainedLayoutNode(`settings-row:${String(flatRow.index)}`, {
                 row: clippedTop,
                 col: layout.startCol,
                 width: layout.drawerWidth,
@@ -990,6 +968,10 @@ export function createFramedApp(options) {
         }
         return children;
     }
+    function nodeIdSuffix(node, prefix) {
+        const id = node.id;
+        return id?.startsWith(prefix) === true ? id.slice(prefix.length) : undefined;
+    }
     function resolveFrameMouseRuntimeLayouts(model) {
         let layouts = EMPTY_RUNTIME_LAYOUTS;
         const settingsLayout = model.settingsOpen
@@ -1063,8 +1045,9 @@ export function createFramedApp(options) {
                 if (msg.action === 'press' && msg.button === 'left') {
                     const rowNode = hit.path.find((n) => n.id?.startsWith('settings-row:'));
                     if (rowNode != null) {
-                        const rowIndex = parseInt(rowNode.id.slice('settings-row:'.length), 10);
-                        cmds.push({ type: 'activate-settings-row', rowIndex });
+                        const rowId = nodeIdSuffix(rowNode, 'settings-row:');
+                        if (rowId !== undefined)
+                            cmds.push({ type: 'activate-settings-row', rowIndex: Number.parseInt(rowId, 10) });
                     }
                     return { handled: true, commands: cmds };
                 }
@@ -1100,8 +1083,8 @@ export function createFramedApp(options) {
                 }
                 // tab click
                 const tabNode = hit?.path.find((n) => n.id?.startsWith('tab:'));
-                if (tabNode != null) {
-                    const pageId = tabNode.id.slice('tab:'.length);
+                const pageId = tabNode == null ? undefined : nodeIdSuffix(tabNode, 'tab:');
+                if (pageId !== undefined) {
                     const currentIndex = model.pageOrder.indexOf(model.activePageId);
                     const nextIndex = model.pageOrder.indexOf(pageId);
                     if (currentIndex >= 0 && nextIndex >= 0 && nextIndex !== currentIndex) {
@@ -1114,18 +1097,21 @@ export function createFramedApp(options) {
                 }
                 // pane click
                 const clickedPaneNode = hit?.path.find((n) => n.id?.startsWith('pane:'));
-                if (clickedPaneNode != null) {
-                    const paneId = clickedPaneNode.id.slice('pane:'.length);
+                const clickedPaneId = clickedPaneNode == null ? undefined : nodeIdSuffix(clickedPaneNode, 'pane:');
+                if (clickedPaneId !== undefined) {
                     const paneRects = resolveWorkspacePaneRects(model);
-                    const paneRect = paneRects.get(paneId);
+                    const paneRect = paneRects.get(clickedPaneId);
                     if (paneRect != null) {
-                        cmds.push({ type: 'focus-pane', paneId });
-                        const inputArea = findInputAreaByPaneId(inputAreas, paneId);
+                        cmds.push({ type: 'focus-pane', paneId: clickedPaneId });
+                        const inputArea = findInputAreaByPaneId(inputAreas, clickedPaneId);
                         const areaMsg = inputArea?.mouse?.({ msg, model: activePageModel, rect: paneRect });
+                        let routedMsg = msg;
+                        if (areaMsg !== undefined)
+                            routedMsg = areaMsg;
                         cmds.push({
                             type: 'emit-page-msg',
                             pageId: model.activePageId,
-                            msg: areaMsg !== undefined ? areaMsg : msg,
+                            msg: routedMsg,
                         });
                         return { handled: true, commands: cmds };
                     }
@@ -1133,13 +1119,13 @@ export function createFramedApp(options) {
             }
             if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
                 const scrollPaneNode = hit?.path.find((n) => n.id?.startsWith('pane:'));
-                if (scrollPaneNode != null) {
-                    const paneId = scrollPaneNode.id.slice('pane:'.length);
+                const scrollPaneId = scrollPaneNode == null ? undefined : nodeIdSuffix(scrollPaneNode, 'pane:');
+                if (scrollPaneId !== undefined) {
                     const paneRects = resolveWorkspacePaneRects(model);
-                    const paneRect = paneRects.get(paneId);
+                    const paneRect = paneRects.get(scrollPaneId);
                     if (paneRect != null) {
-                        cmds.push({ type: 'focus-pane', paneId });
-                        const inputArea = findInputAreaByPaneId(inputAreas, paneId);
+                        cmds.push({ type: 'focus-pane', paneId: scrollPaneId });
+                        const inputArea = findInputAreaByPaneId(inputAreas, scrollPaneId);
                         const areaMsg = inputArea?.mouse?.({ msg, model: activePageModel, rect: paneRect });
                         if (areaMsg !== undefined) {
                             cmds.push({ type: 'emit-page-msg', pageId: model.activePageId, msg: areaMsg });
@@ -1151,7 +1137,7 @@ export function createFramedApp(options) {
                     }
                 }
             }
-            return { handled: true };
+            return { handled: false };
         });
     }
     function resolveWorkspaceHelpSource(activePage, activeInputArea) {
@@ -1178,7 +1164,7 @@ export function createFramedApp(options) {
         const helpHint = frameMessage(options.i18n, 'help.hint', 'j/k scroll • d/u page • g/G top/bottom • mouse wheel • ?/Esc close');
         const settingsHint = frameMessage(options.i18n, 'settings.footer', 'F2/Esc close • ↑/↓ rows • Enter toggle • / search • q quit');
         const notificationsHint = frameMessage(options.i18n, 'notifications.footer', 'Shift+N close • f filter • j/k scroll • q quit');
-        const quitHint = frameMessage(options.i18n, 'quit.footer', 'Y quit • N stay');
+        const quitHint = frameMessage(options.i18n, 'quit.footer', 'Y Quit • N Stay');
         const paletteTitle = model.commandPaletteTitle
             ?? frameMessage(options.i18n, 'palette.title', 'Command Palette');
         const activePageTitle = resolveFramePageText(activePage.title, activePageModel) ?? '';
@@ -1262,8 +1248,10 @@ export function createFramedApp(options) {
         if (targetPage == null)
             return [model, []];
         const pageModel = model.pageModels[targetPageId];
+        if (pageModel === undefined)
+            return [model, []];
         const updateResult = targetPage.update(targetMsg, pageModel);
-        const [nextPageModel, cmds = []] = updateResult;
+        const [nextPageModel, cmds] = updateResult;
         const nextModels = { ...model.pageModels, [targetPageId]: nextPageModel };
         const synced = syncPageFrameState({ ...model, pageModels: nextModels }, targetPageId, pagesById);
         const wrappedCmds = cmds.map((cmd) => wrapCmdForPage(targetPageId, cmd));
@@ -1328,6 +1316,53 @@ export function createFramedApp(options) {
         }, row);
         return [nextModel, notificationCmds];
     }
+    function pushShellThemeModeFeedback(model, nextTheme) {
+        if (!frameNotificationOptions.enabled) {
+            return [model, []];
+        }
+        const nowMs = resolveClock(resolveFrameCtx()).now();
+        const notifications = pushNotification(model.runtimeNotifications, {
+            title: frameMessage(options.i18n, 'settings.title', 'Settings'),
+            message: frameMessage(options.i18n, 'settings.shellTheme.feedback', 'Shell theme set to {theme}.', { theme: nextTheme.label }),
+            variant: 'TOAST',
+            tone: 'INFO',
+            width: SETTINGS_FEEDBACK_TOAST_WIDTH,
+            placement: frameNotificationOptions.placement,
+            durationMs: 2_500,
+            overflow: frameNotificationOptions.overflow,
+        }, nowMs);
+        return applyFrameNotificationState(model, notifications, nowMs);
+    }
+    function pushShellThemeModeUnsupportedFeedback(model, currentTheme) {
+        if (!frameNotificationOptions.enabled || currentTheme == null) {
+            return [model, []];
+        }
+        const nowMs = resolveClock(resolveFrameCtx()).now();
+        const notifications = pushNotification(model.runtimeNotifications, {
+            title: frameMessage(options.i18n, 'settings.title', 'Settings'),
+            message: frameMessage(options.i18n, 'settings.shellTheme.modeUnsupported', 'Shell theme {theme} has no alternate mode.', { theme: currentTheme.label }),
+            variant: 'TOAST',
+            tone: 'INFO',
+            width: SETTINGS_FEEDBACK_TOAST_WIDTH,
+            placement: frameNotificationOptions.placement,
+            durationMs: 2_500,
+            overflow: frameNotificationOptions.overflow,
+        }, nowMs);
+        return applyFrameNotificationState(model, notifications, nowMs);
+    }
+    function toggleShellThemeMode(model) {
+        ensureResolvedShellThemes(resolveFrameCtx());
+        const currentTheme = resolveCurrentShellTheme(resolvedShellThemes, model.activeShellThemeId);
+        const nextTheme = resolveShellThemeModeToggle(resolvedShellThemes, model.activeShellThemeId);
+        if (nextTheme == null) {
+            return pushShellThemeModeUnsupportedFeedback(model, currentTheme);
+        }
+        publishShellThemeContext(nextTheme);
+        return pushShellThemeModeFeedback({
+            ...model,
+            activeShellThemeId: nextTheme.id,
+        }, nextTheme);
+    }
     const app = {
         init() {
             const pageModels = {};
@@ -1439,6 +1474,9 @@ export function createFramedApp(options) {
                     const notifications = tickNotifications(model.runtimeNotifications, action.atMs);
                     return applyFrameNotificationState(model, notifications, action.atMs, true);
                 }
+                if (action.type === 'toggle-shell-theme-mode') {
+                    return toggleShellThemeMode(model);
+                }
                 if (action.type === 'transition') {
                     // Ignore stale transition ticks from a previous generation
                     if (action.generation !== model.transitionGeneration)
@@ -1561,9 +1599,13 @@ export function createFramedApp(options) {
             rememberWorkspaceLayout(model, activeResult.paneRects, headerResult.tabTargets);
             const overlays = [];
             if (options.overlayFactory != null) {
+                const activePageModel = model.pageModels[model.activePageId];
+                if (activePageModel === undefined) {
+                    throw new Error(`createFramedApp: active page model "${model.activePageId}" is missing`);
+                }
                 overlays.push(...options.overlayFactory({
                     activePageId: model.activePageId,
-                    pageModel: model.pageModels[model.activePageId],
+                    pageModel: activePageModel,
                     paneRects: activeResult.paneRects,
                     screenRect: { row: 0, col: 0, width: model.columns, height: model.rows },
                 }));
@@ -1643,7 +1685,17 @@ export function createFramedApp(options) {
             }
             const dimBackground = overlays.length > 0;
             if (model.perfHudOpen) {
-                overlays.push(renderFramePerfHudOverlay(model, themedFrameCtx));
+                overlays.push(renderFramePerfHudOverlay({
+                    columns: model.columns,
+                    rows: model.rows,
+                    frameTimeMs: model.frameTimeMs,
+                    viewTimeMs: model.viewTimeMs,
+                    diffTimeMs: model.diffTimeMs,
+                    refreshRate: themedFrameCtx?.runtime.refreshRate,
+                }, {
+                    i18n: options.i18n,
+                    ctx: themedFrameCtx,
+                }));
             }
             if (bodySurface != null && bodyRect.width > 0 && bodyRect.height > 0) {
                 frameSurface.blit(bodySurface, bodyRect.col, bodyRect.row);
@@ -1656,9 +1708,31 @@ export function createFramedApp(options) {
             return wrapFrameMsg({ type: 'runtime-issue', issue });
         },
     };
-    const framedApp = app;
+    function isInternalFrameModel(model) {
+        return 'helpScrollY' in model && 'warnedFrameKeyCollisionPages' in model;
+    }
+    function requireInternalFrameModel(model) {
+        if (isInternalFrameModel(model))
+            return model;
+        throw new Error('createFramedApp: framed runtime received a non-frame model');
+    }
     let hostedRunActive = false;
-    framedApp.run = async (runOptions) => {
+    const framedApp = {
+        init() {
+            return app.init();
+        },
+        update(msg, model) {
+            return app.update(msg, requireInternalFrameModel(model));
+        },
+        view(model) {
+            return app.view(requireInternalFrameModel(model));
+        },
+        routeRuntimeIssue(issue) {
+            return app.routeRuntimeIssue?.(issue);
+        },
+        run: runHostedFramedApp,
+    };
+    async function runHostedFramedApp(runOptions) {
         if (hostedRunActive) {
             throw new Error('createFramedApp: concurrent app.run() calls on the same framed app are not supported');
         }
@@ -1687,7 +1761,7 @@ export function createFramedApp(options) {
                 beforeRender(model) {
                     if (pendingTimingSnapshot == null)
                         return model;
-                    return applyFrameTimingSnapshot(model, pendingTimingSnapshot);
+                    return applyFrameTimingSnapshot(requireInternalFrameModel(model), pendingTimingSnapshot);
                 },
                 afterRender({ timings }) {
                     pendingTimingSnapshot = summarizeFrameTimings(timings, frameBudgetMs);
@@ -1706,7 +1780,7 @@ export function createFramedApp(options) {
             defaultFrameCtx = previousDefaultFrameCtx;
             resolvedShellThemes = previousResolvedShellThemes;
         }
-    };
+    }
     return framedApp;
 }
 /**