@flyingrobots/bijou-tui 4.1.0 → 4.4.0

package/dist/app-frame.js

@@ -12,25 +12,27 @@ import { quit } from './commands.js';
 import { compositeSurfaceInto, drawer, modal } from './overlay.js';
 import { isShellQuitConfirmAccept, isShellQuitConfirmDismiss, isShellQuitRequest, renderShellQuitOverlay, shouldUseShellQuitConfirm, } from './shell-quit.js';
 import { commandPalette, commandPaletteKeyMap, } from './command-palette.js';
-import { createPagerStateForSurface, pagerPageDown, pagerPageUp, pagerScrollBy, pagerScrollToBottom, pagerScrollToTop, pagerSurface, } from './pager.js';
+import { createPagerStateForSurface, pagerSurface, } from './pager.js';
 import { restoreLayoutState } from './layout-preset.js';
 import { countNotificationHistory, createNotificationState, dismissNotification, hitTestNotificationStack, notificationsNeedTick, pushNotification, renderNotificationHistorySurface, renderNotificationReviewEntrySurface, renderNotificationStack, tickNotifications, trimNotificationsToViewport, } from './notification.js';
 import { insetLineSurface } from './collection-surface.js';
 import { vstackSurface } from './surface-layout.js';
 import { isFrameScopedMsg, isPageScopedMsg, wrapCmdForPage, emitMsg, emitMsgForPage, wrapFrameMsg, } from './app-frame-types.js';
 import { createFrameKeyMap, frameBodyRect, mergeBindingSources, } from './app-frame-utils.js';
-import { activeFrameLayer, describeFrameLayerStack, } from './app-frame-layers.js';
+import { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, } from './app-frame-layers.js';
+import { applyRuntimeCommandBuffer, bufferRuntimeRouteResult, createRuntimeBuffers, createRuntimeRetainedLayouts, retainRuntimeLayout, routeRuntimeInput, } from './runtime-engine.js';
 import { frameEndAnchor, frameMessage, frameNotificationCue, frameNotificationFilterLabel, frameStartAnchor, } from './app-frame-i18n.js';
-import { resolveHeaderLine, renderHelpLine, renderPageContent, renderPageContentInto, renderMaximizedPane, renderMaximizedPaneInto, renderTransition, } from './app-frame-render.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';
-export { activeFrameLayer, describeFrameLayerStack, underlyingFrameLayer, } from './app-frame-layers.js';
+export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, underlyingFrameLayer, } from './app-frame-layers.js';
 // ---------------------------------------------------------------------------
 // Frame Notification Helpers
 // ---------------------------------------------------------------------------
 const FRAME_NOTIFICATION_TICK_MS = 40;
 const DEFAULT_FRAME_NOTIFICATION_DURATION_MS = 6_000;
 const SETTINGS_FEEDBACK_TOAST_WIDTH = 40;
+const EMPTY_RUNTIME_LAYOUTS = createRuntimeRetainedLayouts();
 const DEFAULT_NOTIFICATION_CENTER_FILTERS = [
     'ALL',
     'ACTIONABLE',
@@ -160,6 +162,9 @@ export function createFramedApp(options) {
     });
     const frameNotificationOptions = resolveFrameNotificationOptions(options);
     let composedFrameScratch = null;
+    let headerScratch;
+    let helpLineScratch;
+    const paneScratchPool = createFramePaneScratchPool();
     const paletteKeys = commandPaletteKeyMap({
         focusNext: { type: 'cp-next' },
         focusPrev: { type: 'cp-prev' },
@@ -176,20 +181,29 @@ export function createFramedApp(options) {
         }
         return composedFrameScratch;
     }
-    function withObservedKey(model, cmds, msg, route) {
-        const observed = options.observeKey?.(msg, route);
-        if (observed === undefined)
-            return [...cmds];
-        return [emitMsgForPage(model.activePageId, observed), ...cmds];
+    function closeCommandPalette(model) {
+        return {
+            ...model,
+            commandPalette: undefined,
+            commandPaletteEntries: undefined,
+            commandPaletteTitle: undefined,
+            commandPaletteKind: undefined,
+        };
     }
-    function applyQuitRequest(model, msg) {
-        if (!shouldUseShellQuitConfirm()) {
-            return [model, withObservedKey(model, [quit()], msg, 'frame')];
-        }
-        if (model.quitConfirmOpen) {
-            return [model, withObservedKey(model, [], msg, 'frame')];
-        }
-        return [{
+    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,
@@ -200,16 +214,149 @@ export function createFramedApp(options) {
                 commandPaletteEntries: undefined,
                 commandPaletteTitle: undefined,
                 commandPaletteKind: undefined,
-            }, withObservedKey(model, [], msg, 'frame')];
-    }
-    function closeCommandPalette(model) {
-        return {
-            ...model,
-            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);
+            return layout != null ? moveSettingsFocus(model, layout, c.delta) : model;
+        },
+        'settings-scroll': (model, cmd) => {
+            const c = cmd;
+            const layout = resolveSettingsLayout(model, options, pagesById);
+            return layout != null ? scrollSettingsBy(model, layout, c.delta) : model;
+        },
+        'settings-scroll-to': (model, cmd) => {
+            const c = cmd;
+            const layout = resolveSettingsLayout(model, options, pagesById);
+            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);
+            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.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;
+        },
+        // --- notification center ---
+        'notification-center-scroll': (model, cmd) => {
+            const c = cmd;
+            const layout = resolveNotificationCenterLayout(model, options, pagesById);
+            return layout != null ? scrollNotificationCenterBy(model, layout, c.delta) : model;
+        },
+        'notification-center-scroll-to': (model, cmd) => {
+            const c = cmd;
+            const layout = resolveNotificationCenterLayout(model, options, pagesById);
+            if (layout == null)
+                return model;
+            return { ...model, notificationCenterScrollY: c.position === 'top' ? 0 : layout.maxScrollY };
+        },
+        'cycle-notification-filter': (model, _cmd, teaCmds) => {
+            const layout = resolveNotificationCenterLayout(model, options, pagesById);
+            if (layout == null)
+                return model;
+            const [nextModel, cmds] = cycleNotificationCenterFilter(model, layout);
+            teaCmds.push(...cmds);
+            return nextModel;
+        },
+        // --- help ---
+        'help-scroll': (model, cmd) => {
+            const c = cmd;
+            const activePage = pagesById.get(model.activePageId);
+            const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
+            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)
+                return model;
+            const nowMs = resolveClock(resolveSafeCtx()).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));
+        return [state, teaCmds];
     }
     function resolveLayerContext(model) {
         const activePage = pagesById.get(model.activePageId);
@@ -229,6 +376,486 @@ export function createFramedApp(options) {
             activeLayer,
         };
     }
+    function quitRequestCommands(msg, route) {
+        if (!shouldUseShellQuitConfirm()) {
+            return [{ type: 'observed-key', msg, route }, { type: 'quit' }];
+        }
+        return [{ type: 'observed-key', msg, route }, { type: 'open-quit-confirm' }];
+    }
+    function resolveFrameActionCommands(msg, action, route) {
+        if (action.type === 'open-search' && options.enableCommandPalette) {
+            return [{ type: 'observed-key', msg, route }, { type: 'open-search-palette' }];
+        }
+        if (action.type === 'open-palette' && options.enableCommandPalette) {
+            return [{ type: 'observed-key', msg, route }, { type: 'open-command-palette' }];
+        }
+        return [{ type: 'observed-key', msg, route }, { type: 'apply-frame-action', action }];
+    }
+    function handlePaletteLayerKeyCommands(msg, routedLayerKind) {
+        const obs = { type: 'observed-key', msg, route: 'palette' };
+        if (msg.ctrl && !msg.alt && msg.key === 'c') {
+            return quitRequestCommands(msg, 'palette');
+        }
+        if (!msg.ctrl && !msg.alt && !msg.shift && msg.key === 'escape') {
+            return [obs, { type: 'close-palette' }];
+        }
+        const frameAction = frameKeys.handle(msg);
+        if (frameAction?.type === 'open-search') {
+            return routedLayerKind === 'search'
+                ? [obs, { type: 'close-palette' }]
+                : [obs, { type: 'open-search-palette' }];
+        }
+        if (frameAction?.type === 'open-palette') {
+            return routedLayerKind === 'command-palette'
+                ? [obs, { type: 'close-palette' }]
+                : [obs, { type: 'open-command-palette' }];
+        }
+        if (frameAction?.type === 'toggle-notifications') {
+            return [obs, { type: 'close-palette' }, { type: 'apply-frame-action', action: frameAction }];
+        }
+        return [obs, { type: 'palette-key', msg }];
+    }
+    function handleHelpLayerKeyCommands(msg) {
+        const obs = { type: 'observed-key', msg, route: 'help' };
+        if (!msg.ctrl && !msg.alt && (msg.key === '?' || msg.key === 'escape')) {
+            return [obs, { type: 'close-help' }];
+        }
+        if (isShellQuitRequest(msg)) {
+            return quitRequestCommands(msg, 'help');
+        }
+        const helpAction = frameKeys.handle(msg);
+        if (helpAction && isHelpScrollAction(helpAction)) {
+            const action = helpAction.type === 'scroll-down' ? 'down'
+                : helpAction.type === 'scroll-up' ? 'up'
+                    : helpAction.type === 'page-down' ? 'page-down'
+                        : helpAction.type === 'page-up' ? 'page-up'
+                            : helpAction.type === 'bottom' ? 'bottom'
+                                : 'top';
+            return [obs, { type: 'help-scroll', action }];
+        }
+        return [obs];
+    }
+    function handleSettingsLayerKeyCommands(msg, model) {
+        const layout = resolveSettingsLayout(model, options, pagesById);
+        if (layout == null)
+            return undefined;
+        const obs = { type: 'observed-key', msg, route: 'frame' };
+        if (!msg.ctrl && !msg.alt && (msg.key === 'escape' || msg.key === 'f2')) {
+            return [obs, { type: 'close-settings' }];
+        }
+        if (msg.ctrl && !msg.alt && msg.key === ',') {
+            return [obs, { type: 'close-settings' }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === '?') {
+            return [obs, { type: 'open-help' }];
+        }
+        if (isShellQuitRequest(msg)) {
+            return quitRequestCommands(msg, 'frame');
+        }
+        if (options.enableCommandPalette && !msg.ctrl && !msg.alt && msg.key === '/') {
+            return [obs, { type: 'open-search-palette' }];
+        }
+        if (options.enableCommandPalette && ((msg.ctrl && !msg.alt && msg.key === 'p') || (!msg.ctrl && !msg.alt && msg.key === ':'))) {
+            return [obs, { type: 'open-command-palette' }];
+        }
+        const settingsFrameAction = frameKeys.handle(msg);
+        if (settingsFrameAction?.type === 'toggle-notifications') {
+            return [obs, { type: 'apply-frame-action', action: settingsFrameAction }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'up') {
+            return [obs, { type: 'settings-focus-move', delta: -1 }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'down') {
+            return [obs, { type: 'settings-focus-move', delta: 1 }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'j') {
+            return [obs, { type: 'settings-scroll', delta: 1 }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'k') {
+            return [obs, { type: 'settings-scroll', delta: -1 }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'd') {
+            return [obs, { type: 'settings-scroll', delta: Math.max(1, layout.contentHeight - 1) }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'u') {
+            return [obs, { type: 'settings-scroll', delta: -Math.max(1, layout.contentHeight - 1) }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'g') {
+            return [obs, { type: 'settings-scroll-to', position: 'top' }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'G') {
+            return [obs, { type: 'settings-scroll-to', position: 'bottom' }];
+        }
+        if (!msg.ctrl && !msg.alt && (msg.key === 'enter' || msg.key === 'space')) {
+            const rowIndex = clampSettingsFocus(model, layout);
+            const row = layout.rows[rowIndex];
+            if (row?.row.action !== undefined && row.row.enabled !== false && row.row.kind !== 'info') {
+                return [obs, { type: 'activate-settings-row', rowIndex: row.index }];
+            }
+            return [obs];
+        }
+        return [obs];
+    }
+    function handleNotificationCenterLayerKeyCommands(msg, model) {
+        const layout = resolveNotificationCenterLayout(model, options, pagesById);
+        if (layout == null)
+            return undefined;
+        const obs = { type: 'observed-key', msg, route: 'frame' };
+        if (!msg.ctrl && !msg.alt && msg.key === 'escape') {
+            return [obs, { type: 'close-notification-center' }];
+        }
+        if (isShellQuitRequest(msg)) {
+            return quitRequestCommands(msg, 'frame');
+        }
+        const centerFrameAction = frameKeys.handle(msg);
+        if (centerFrameAction?.type === 'toggle-notifications') {
+            return [obs, { type: 'apply-frame-action', action: centerFrameAction }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'f2') {
+            return [obs, { type: 'close-notification-center' }, { type: 'apply-frame-action', action: { type: 'toggle-settings' } }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === '?') {
+            return [obs, { type: 'close-notification-center' }, { type: 'open-help' }];
+        }
+        if (options.enableCommandPalette && !msg.ctrl && !msg.alt && msg.key === '/') {
+            return [obs, { type: 'close-notification-center' }, { type: 'open-search-palette' }];
+        }
+        if (options.enableCommandPalette && ((msg.ctrl && !msg.alt && msg.key === 'p') || (!msg.ctrl && !msg.alt && msg.key === ':'))) {
+            return [obs, { type: 'close-notification-center' }, { type: 'open-command-palette' }];
+        }
+        if (!msg.ctrl && !msg.alt && (msg.key === 'up' || msg.key === 'k')) {
+            return [obs, { type: 'notification-center-scroll', delta: -1 }];
+        }
+        if (!msg.ctrl && !msg.alt && (msg.key === 'down' || msg.key === 'j')) {
+            return [obs, { type: 'notification-center-scroll', delta: 1 }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'd') {
+            return [obs, { type: 'notification-center-scroll', delta: Math.max(1, layout.contentHeight - 2) }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'u') {
+            return [obs, { type: 'notification-center-scroll', delta: -Math.max(1, layout.contentHeight - 2) }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'g') {
+            return [obs, { type: 'notification-center-scroll-to', position: 'top' }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'G') {
+            return [obs, { type: 'notification-center-scroll-to', position: 'bottom' }];
+        }
+        if (!msg.ctrl && !msg.alt && msg.key === 'f') {
+            return [obs, { type: 'cycle-notification-filter' }];
+        }
+        return [obs];
+    }
+    function handleWorkspaceLayerKeyCommands(msg, model) {
+        if (isShellQuitRequest(msg)) {
+            return quitRequestCommands(msg, 'frame');
+        }
+        const context = resolveLayerContext(model);
+        const { activePage, activeInputArea } = context;
+        const paneAction = activeInputArea?.keyMap?.handle(msg);
+        const pageAction = activePage.keyMap?.handle(msg);
+        const globalAction = options.globalKeys?.handle(msg);
+        const frameAction = frameKeys.handle(msg);
+        const keyPriority = options.keyPriority ?? 'frame-first';
+        if (keyPriority === 'page-first') {
+            if (paneAction !== undefined) {
+                return [{ type: 'observed-key', msg, route: 'page' }, { type: 'emit-page-msg', pageId: model.activePageId, msg: paneAction }];
+            }
+            if (pageAction !== undefined) {
+                return [{ type: 'observed-key', msg, route: 'page' }, { type: 'emit-page-msg', pageId: model.activePageId, msg: pageAction }];
+            }
+            if (globalAction !== undefined) {
+                return [{ type: 'observed-key', msg, route: 'global' }, { type: 'emit-global-msg', msg: globalAction }];
+            }
+            if (frameAction !== undefined) {
+                return resolveFrameActionCommands(msg, frameAction, 'frame');
+            }
+            return [{ type: 'observed-key', msg, route: 'unhandled' }];
+        }
+        // frame-first (default)
+        if (frameAction !== undefined) {
+            return resolveFrameActionCommands(msg, frameAction, 'frame');
+        }
+        if (paneAction !== undefined) {
+            return [{ type: 'observed-key', msg, route: 'page' }, { type: 'emit-page-msg', pageId: model.activePageId, msg: paneAction }];
+        }
+        if (globalAction !== undefined) {
+            return [{ type: 'observed-key', msg, route: 'global' }, { type: 'emit-global-msg', msg: globalAction }];
+        }
+        if (pageAction !== undefined) {
+            return [{ type: 'observed-key', msg, route: 'page' }, { type: 'emit-page-msg', pageId: model.activePageId, msg: pageAction }];
+        }
+        return [{ type: 'observed-key', msg, route: 'unhandled' }];
+    }
+    function resolveRoutedKeyLayer(msg, model) {
+        const context = resolveLayerContext(model);
+        const runtimeStack = describeFrameRuntimeViewStack(model, {
+            pageModalOpen: context.pageModalOpen,
+        });
+        return routeRuntimeInput(runtimeStack, EMPTY_RUNTIME_LAYOUTS, { kind: 'key', key: msg.key }, ({ layer }) => {
+            const frameLayer = layer.model;
+            if (frameLayer == null)
+                return undefined;
+            if (frameLayer.kind === 'search' || frameLayer.kind === 'command-palette') {
+                return { handled: true, commands: handlePaletteLayerKeyCommands(msg, frameLayer.kind) };
+            }
+            if (frameLayer.kind === 'help') {
+                return { handled: true, commands: handleHelpLayerKeyCommands(msg) };
+            }
+            if (frameLayer.kind === 'settings') {
+                const cmds = handleSettingsLayerKeyCommands(msg, model);
+                return cmds != null ? { handled: true, commands: cmds } : { bubble: true };
+            }
+            if (frameLayer.kind === 'notification-center') {
+                const cmds = handleNotificationCenterLayerKeyCommands(msg, model);
+                return cmds != null ? { handled: true, commands: cmds } : { bubble: true };
+            }
+            if (frameLayer.kind === 'quit-confirm') {
+                const obs = { type: 'observed-key', msg, route: 'frame' };
+                if (isShellQuitConfirmAccept(msg)) {
+                    return { handled: true, commands: [obs, { type: 'close-quit-confirm' }, { type: 'quit' }] };
+                }
+                if (isShellQuitConfirmDismiss(msg)) {
+                    return { handled: true, commands: [obs, { type: 'close-quit-confirm' }] };
+                }
+                return { handled: true, commands: [obs] };
+            }
+            if (frameLayer.kind === 'page-modal') {
+                const { modalKeyMap } = context;
+                const obs = { type: 'observed-key', msg, route: 'page' };
+                if (modalKeyMap != null) {
+                    const modalAction = modalKeyMap.handle(msg);
+                    if (modalAction !== undefined) {
+                        return { handled: true, commands: [obs, { type: 'emit-page-msg', pageId: model.activePageId, msg: modalAction }] };
+                    }
+                }
+                return { handled: true, commands: [obs] };
+            }
+            // workspace (root layer)
+            return { handled: true, commands: handleWorkspaceLayerKeyCommands(msg, model) };
+        });
+    }
+    function createShellRetainedLayoutNode(id, rect, children) {
+        return {
+            id,
+            rect: {
+                x: rect.col,
+                y: rect.row,
+                width: rect.width,
+                height: rect.height,
+            },
+            children: children ?? [],
+        };
+    }
+    function resolveWorkspacePaneRects(model) {
+        const bodyRect = resolveBodyRect(model, options);
+        const maxState = model.maximizedPaneByPage[model.activePageId];
+        const maximizedPaneId = maxState?.maximizedPaneId;
+        const renderResult = maximizedPaneId
+            ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, paneScratchPool)
+            : renderPageContent(model.activePageId, model, bodyRect, pagesById);
+        return renderResult.paneRects;
+    }
+    function buildWorkspaceLayoutTree(model) {
+        const header = resolveHeaderLine(model, options, pagesById, headerScratch);
+        headerScratch = header.surface;
+        const tabChildren = header.tabTargets.map((target) => createShellRetainedLayoutNode(`tab:${target.pageId}`, {
+            row: 0,
+            col: target.startCol,
+            width: target.endCol - target.startCol + 1,
+            height: 1,
+        }));
+        const bodyRect = resolveBodyRect(model, options);
+        const paneRects = resolveWorkspacePaneRects(model);
+        const paneChildren = [];
+        for (const [paneId, rect] of paneRects.entries()) {
+            paneChildren.push(createShellRetainedLayoutNode(`pane:${paneId}`, rect));
+        }
+        return createShellRetainedLayoutNode('workspace', { row: 0, col: 0, width: model.columns, height: model.rows }, [
+            createShellRetainedLayoutNode('header-bar', { row: 0, col: 0, width: model.columns, height: 1 }, tabChildren),
+            createShellRetainedLayoutNode('workspace-body', bodyRect, paneChildren),
+        ]);
+    }
+    function buildSettingsRowChildren(model, layout) {
+        const scrollY = clampSettingsScroll(model, layout);
+        const viewportTop = 1;
+        const viewportBottom = model.rows - 1;
+        const children = [];
+        for (const flatRow of layout.rows) {
+            const screenRow = flatRow.line - scrollY + viewportTop;
+            const clippedTop = Math.max(viewportTop, screenRow);
+            const clippedBottom = Math.min(viewportBottom, screenRow + flatRow.height);
+            if (clippedTop >= clippedBottom)
+                continue;
+            children.push(createShellRetainedLayoutNode(`settings-row:${flatRow.index}`, {
+                row: clippedTop,
+                col: layout.startCol,
+                width: layout.drawerWidth,
+                height: clippedBottom - clippedTop,
+            }));
+        }
+        return children;
+    }
+    function resolveFrameMouseRuntimeLayouts(model) {
+        let layouts = EMPTY_RUNTIME_LAYOUTS;
+        const settingsLayout = model.settingsOpen ? resolveSettingsLayout(model, options, pagesById) : undefined;
+        if (settingsLayout != null) {
+            layouts = retainRuntimeLayout(layouts, {
+                viewId: 'settings',
+                tree: createShellRetainedLayoutNode('settings-drawer', {
+                    row: 0,
+                    col: settingsLayout.startCol,
+                    width: settingsLayout.drawerWidth,
+                    height: model.rows,
+                }, buildSettingsRowChildren(model, settingsLayout)),
+            });
+        }
+        const notificationCenterLayout = model.notificationCenterOpen ? resolveNotificationCenterLayout(model, options, pagesById) : undefined;
+        if (notificationCenterLayout != null) {
+            layouts = retainRuntimeLayout(layouts, {
+                viewId: 'notification-center',
+                tree: createShellRetainedLayoutNode('notification-center-drawer', {
+                    row: 0,
+                    col: notificationCenterLayout.startCol,
+                    width: notificationCenterLayout.drawerWidth,
+                    height: model.rows,
+                }),
+            });
+        }
+        layouts = retainRuntimeLayout(layouts, {
+            viewId: 'workspace',
+            tree: buildWorkspaceLayoutTree(model),
+        });
+        return layouts;
+    }
+    function resolveRoutedMouseLayer(msg, model) {
+        const context = resolveLayerContext(model);
+        const { activePageModel, inputAreas } = context;
+        const runtimeStack = describeFrameRuntimeViewStack(model, {
+            pageModalOpen: context.pageModalOpen,
+        });
+        return routeRuntimeInput(runtimeStack, resolveFrameMouseRuntimeLayouts(model), {
+            kind: 'pointer',
+            action: msg.action,
+            x: msg.col,
+            y: msg.row,
+            button: msg.button === 'none' ? undefined : msg.button,
+        }, ({ layer, hit }) => {
+            const frameLayer = layer.model;
+            if (frameLayer == null)
+                return undefined;
+            const cmds = [];
+            if (frameLayer.kind === 'help') {
+                if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
+                    cmds.push({ type: 'help-scroll', action: msg.action === 'scroll-down' ? 'down' : 'up' });
+                }
+                return { handled: true, commands: cmds };
+            }
+            if (frameLayer.kind === 'search' || frameLayer.kind === 'command-palette'
+                || frameLayer.kind === 'quit-confirm' || frameLayer.kind === 'page-modal') {
+                return { handled: true };
+            }
+            if (frameLayer.kind === 'settings') {
+                if (hit == null)
+                    return { handled: true };
+                if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
+                    cmds.push({ type: 'settings-scroll', delta: msg.action === 'scroll-down' ? 3 : -3 });
+                    return { handled: true, commands: cmds };
+                }
+                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 });
+                    }
+                    return { handled: true, commands: cmds };
+                }
+                return { handled: true };
+            }
+            if (frameLayer.kind === 'notification-center') {
+                if (hit == null)
+                    return { handled: true };
+                if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
+                    cmds.push({ type: 'notification-center-scroll', delta: msg.action === 'scroll-down' ? 3 : -3 });
+                    return { handled: true, commands: cmds };
+                }
+                return { handled: true };
+            }
+            // workspace layer
+            if (msg.action === 'press' && msg.button === 'left') {
+                // notification toast hit-testing (outside retained layouts)
+                if (frameNotificationOptions.enabled) {
+                    const notificationTarget = hitTestNotificationStack(model.runtimeNotifications, {
+                        screenWidth: model.columns,
+                        screenHeight: model.rows,
+                        margin: frameNotificationOptions.margin,
+                        gap: frameNotificationOptions.gap,
+                        ctx: resolveSafeCtx() ?? undefined,
+                    }, msg.col, msg.row);
+                    if (notificationTarget?.kind === 'dismiss') {
+                        cmds.push({ type: 'dismiss-notification', notificationId: notificationTarget.item.id });
+                        return { handled: true, commands: cmds };
+                    }
+                    if (notificationTarget != null) {
+                        return { handled: true };
+                    }
+                }
+                // tab click
+                const tabNode = hit?.path.find((n) => n.id?.startsWith('tab:'));
+                if (tabNode != null) {
+                    const pageId = tabNode.id.slice('tab:'.length);
+                    const currentIndex = model.pageOrder.indexOf(model.activePageId);
+                    const nextIndex = model.pageOrder.indexOf(pageId);
+                    if (currentIndex >= 0 && nextIndex >= 0 && nextIndex !== currentIndex) {
+                        cmds.push({ type: 'switch-tab', delta: nextIndex - currentIndex });
+                    }
+                    return { handled: true, commands: cmds };
+                }
+                if (msg.row === 0) {
+                    return { handled: true };
+                }
+                // pane click
+                const clickedPaneNode = hit?.path.find((n) => n.id?.startsWith('pane:'));
+                if (clickedPaneNode != null) {
+                    const paneId = clickedPaneNode.id.slice('pane:'.length);
+                    const paneRects = resolveWorkspacePaneRects(model);
+                    const paneRect = paneRects.get(paneId);
+                    if (paneRect != null) {
+                        cmds.push({ type: 'focus-pane', paneId });
+                        const inputArea = findInputAreaByPaneId(inputAreas, paneId);
+                        const areaMsg = inputArea?.mouse?.({ msg, model: activePageModel, rect: paneRect });
+                        cmds.push({
+                            type: 'emit-page-msg',
+                            pageId: model.activePageId,
+                            msg: areaMsg !== undefined ? areaMsg : msg,
+                        });
+                        return { handled: true, commands: cmds };
+                    }
+                }
+            }
+            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 paneRects = resolveWorkspacePaneRects(model);
+                    const paneRect = paneRects.get(paneId);
+                    if (paneRect != null) {
+                        cmds.push({ type: 'focus-pane', paneId });
+                        const inputArea = findInputAreaByPaneId(inputAreas, paneId);
+                        const areaMsg = inputArea?.mouse?.({ msg, model: activePageModel, rect: paneRect });
+                        if (areaMsg !== undefined) {
+                            cmds.push({ type: 'emit-page-msg', pageId: model.activePageId, msg: areaMsg });
+                        }
+                        else {
+                            cmds.push({ type: 'scroll-focused-pane', direction: msg.action === 'scroll-down' ? 'down' : 'up' });
+                        }
+                        return { handled: true, commands: cmds };
+                    }
+                }
+            }
+            return { handled: true };
+        });
+    }
     function resolveWorkspaceHelpSource(activePage, activeInputArea) {
         return mergeBindingSources(frameKeys, quitHelpKeys, options.globalKeys, activeInputArea?.helpSource ?? activeInputArea?.keyMap, activePage.helpSource ?? activePage.keyMap);
     }
@@ -337,132 +964,6 @@ export function createFramedApp(options) {
         const wrappedCmds = cmds.map((cmd) => wrapCmdForPage(targetPageId, cmd));
         return [synced, wrappedCmds];
     }
-    function handleFrameMouse(msg, model) {
-        const { activePage, activePageModel, inputAreas, activeLayer, } = resolveLayerContext(model);
-        if (activeLayer.kind === 'help') {
-            if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
-                return [applyHelpScroll(model, activePage, msg.action === 'scroll-down' ? 3 : -3, frameKeys, paletteKeys, options, pagesById), []];
-            }
-            return [model, []];
-        }
-        if (activeLayer.kind === 'search' || activeLayer.kind === 'command-palette') {
-            return [model, []];
-        }
-        if (activeLayer.kind === 'quit-confirm' || activeLayer.kind === 'page-modal') {
-            return [model, []];
-        }
-        if (activeLayer.kind === 'settings') {
-            const layout = resolveSettingsLayout(model, options, pagesById);
-            if (layout != null) {
-                if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
-                    if (isInsideSettingsDrawer(msg.col, msg.row, layout, model)) {
-                        return [
-                            scrollSettingsBy(model, layout, msg.action === 'scroll-down' ? 3 : -3),
-                            [],
-                        ];
-                    }
-                    return [model, []];
-                }
-                if (msg.action === 'press' && msg.button === 'left') {
-                    if (!isInsideSettingsDrawer(msg.col, msg.row, layout, model)) {
-                        return [model, []];
-                    }
-                    const hit = settingsRowAtPosition(msg.col, msg.row, model, layout);
-                    if (hit == null)
-                        return [model, []];
-                    const focusedModel = { ...model, settingsFocusIndex: hit.index };
-                    if (hit.row.action === undefined || hit.row.enabled === false || hit.row.kind === 'info') {
-                        return [focusedModel, []];
-                    }
-                    return activateSettingsRow(focusedModel, hit.row);
-                }
-                return [model, []];
-            }
-        }
-        if (activeLayer.kind === 'notification-center') {
-            const layout = resolveNotificationCenterLayout(model, options, pagesById);
-            if (layout != null) {
-                if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
-                    if (isInsideNotificationCenterDrawer(msg.col, msg.row, layout, model)) {
-                        return [
-                            scrollNotificationCenterBy(model, layout, msg.action === 'scroll-down' ? 3 : -3),
-                            [],
-                        ];
-                    }
-                    return [model, []];
-                }
-                if (msg.action === 'press' && msg.button === 'left') {
-                    return [model, []];
-                }
-                return [model, []];
-            }
-        }
-        if (msg.action === 'press' && msg.button === 'left') {
-            if (frameNotificationOptions.enabled) {
-                const nowMs = resolveClock(resolveSafeCtx()).now();
-                const notificationTarget = hitTestNotificationStack(model.runtimeNotifications, {
-                    screenWidth: model.columns,
-                    screenHeight: model.rows,
-                    margin: frameNotificationOptions.margin,
-                    gap: frameNotificationOptions.gap,
-                    ctx: resolveSafeCtx() ?? undefined,
-                }, msg.col, msg.row);
-                if (notificationTarget?.kind === 'dismiss') {
-                    return applyFrameNotificationState(model, dismissNotification(model.runtimeNotifications, notificationTarget.item.id, nowMs), nowMs);
-                }
-                if (notificationTarget != null) {
-                    return [model, []];
-                }
-            }
-            if (msg.row === 0) {
-                const header = resolveHeaderLine(model, options, pagesById);
-                const tab = header.tabTargets.find((target) => msg.col >= target.startCol && msg.col <= target.endCol);
-                if (tab != null) {
-                    const currentIndex = model.pageOrder.indexOf(model.activePageId);
-                    const nextIndex = model.pageOrder.indexOf(tab.pageId);
-                    if (currentIndex >= 0 && nextIndex >= 0 && nextIndex !== currentIndex) {
-                        return switchTab(model, nextIndex - currentIndex, pagesById, options);
-                    }
-                    return [model, []];
-                }
-                return [model, []];
-            }
-            const clickedPane = paneHitAtPosition(model, msg.col, msg.row, pagesById, options);
-            if (clickedPane != null) {
-                const focusedModel = focusPane(model, clickedPane.paneId);
-                const inputArea = findInputAreaByPaneId(inputAreas, clickedPane.paneId);
-                const areaMsg = inputArea?.mouse?.({
-                    msg,
-                    model: activePageModel,
-                    rect: clickedPane.rect,
-                });
-                if (areaMsg !== undefined) {
-                    return [focusedModel, [emitMsgForPage(model.activePageId, areaMsg)]];
-                }
-                return [focusedModel, [emitMsgForPage(model.activePageId, msg)]];
-            }
-        }
-        if (msg.action === 'scroll-up' || msg.action === 'scroll-down') {
-            const hoveredPane = paneHitAtPosition(model, msg.col, msg.row, pagesById, options);
-            if (hoveredPane != null) {
-                const focusedModel = focusPane(model, hoveredPane.paneId);
-                const inputArea = findInputAreaByPaneId(inputAreas, hoveredPane.paneId);
-                const areaMsg = inputArea?.mouse?.({
-                    msg,
-                    model: activePageModel,
-                    rect: hoveredPane.rect,
-                });
-                if (areaMsg !== undefined) {
-                    return [focusedModel, [emitMsgForPage(model.activePageId, areaMsg)]];
-                }
-                const action = msg.action === 'scroll-down'
-                    ? { type: 'scroll-down' }
-                    : { type: 'scroll-up' };
-                return [scrollFocusedPane(focusedModel, action, pagesById, options), []];
-            }
-        }
-        return undefined;
-    }
     function applyFrameNotificationState(model, notifications, nowMs, forceTick = false) {
         const trimmed = trimNotificationsToViewport(notifications, {
             screenWidth: model.columns,
@@ -642,270 +1143,13 @@ export function createFramedApp(options) {
                     }, []];
             }
             if (isKeyMsg(msg)) {
-                const { activePage, activeInputArea, modalKeyMap, activeLayer, } = resolveLayerContext(model);
-                if (activeLayer.kind === 'search' || activeLayer.kind === 'command-palette') {
-                    if (msg.ctrl && !msg.alt && msg.key === 'c') {
-                        return applyQuitRequest(model, msg);
-                    }
-                    if (!msg.ctrl && !msg.alt && !msg.shift && msg.key === 'escape') {
-                        return [closeCommandPalette(model), withObservedKey(model, [], msg, 'palette')];
-                    }
-                    const frameAction = frameKeys.handle(msg);
-                    if (frameAction?.type === 'open-search') {
-                        if (activeLayer.kind === 'search') {
-                            return [closeCommandPalette(model), withObservedKey(model, [], msg, 'palette')];
-                        }
-                        return [openSearchPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'palette')];
-                    }
-                    if (frameAction?.type === 'open-palette') {
-                        if (activeLayer.kind === 'command-palette') {
-                            return [closeCommandPalette(model), withObservedKey(model, [], msg, 'palette')];
-                        }
-                        return [openCommandPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'palette')];
-                    }
-                    if (frameAction?.type === 'toggle-notifications') {
-                        const [nextModel, cmds] = applyFrameAction(frameAction, closeCommandPalette(model), options, pagesById);
-                        return [nextModel, withObservedKey(model, cmds, msg, 'palette')];
-                    }
-                    const [nextModel, cmds] = handlePaletteKey(msg, model, paletteKeys, options, pagesById);
-                    return [nextModel, withObservedKey(model, cmds, msg, 'palette')];
-                }
-                if (activeLayer.kind === 'help') {
-                    if (!msg.ctrl && !msg.alt && (msg.key === '?' || msg.key === 'escape')) {
-                        return [{ ...model, helpOpen: false, helpScrollY: 0 }, withObservedKey(model, [], msg, 'help')];
-                    }
-                    if (isShellQuitRequest(msg)) {
-                        return applyQuitRequest(model, msg);
-                    }
-                    const helpAction = frameKeys.handle(msg);
-                    if (helpAction && isHelpScrollAction(helpAction)) {
-                        return [
-                            applyHelpScrollAction(model, activePage, helpAction, frameKeys, paletteKeys, options, pagesById),
-                            withObservedKey(model, [], msg, 'help'),
-                        ];
-                    }
-                    return [model, withObservedKey(model, [], msg, 'help')];
-                }
-                if (activeLayer.kind === 'settings') {
-                    const layout = resolveSettingsLayout(model, options, pagesById);
-                    if (layout != null) {
-                        const settingsFrameAction = frameKeys.handle(msg);
-                        if (!msg.ctrl && !msg.alt && msg.key === 'escape') {
-                            return [{
-                                    ...model,
-                                    settingsOpen: false,
-                                }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (msg.ctrl && !msg.alt && msg.key === ',') {
-                            return [{
-                                    ...model,
-                                    settingsOpen: false,
-                                }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'f2') {
-                            return [{
-                                    ...model,
-                                    settingsOpen: false,
-                                }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === '?') {
-                            return [{ ...model, helpOpen: true }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (isShellQuitRequest(msg)) {
-                            return applyQuitRequest(model, msg);
-                        }
-                        if (options.enableCommandPalette && !msg.ctrl && !msg.alt && msg.key === '/') {
-                            return [openSearchPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (options.enableCommandPalette && ((msg.ctrl && !msg.alt && msg.key === 'p') || (!msg.ctrl && !msg.alt && msg.key === ':'))) {
-                            return [openCommandPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (settingsFrameAction?.type === 'toggle-notifications') {
-                            const [nextModel, cmds] = applyFrameAction(settingsFrameAction, model, options, pagesById);
-                            return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'up') {
-                            return [moveSettingsFocus(model, layout, -1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'down') {
-                            return [moveSettingsFocus(model, layout, 1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'j') {
-                            return [scrollSettingsBy(model, layout, 1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'k') {
-                            return [scrollSettingsBy(model, layout, -1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'd') {
-                            return [scrollSettingsBy(model, layout, Math.max(1, layout.contentHeight - 1)), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'u') {
-                            return [scrollSettingsBy(model, layout, -Math.max(1, layout.contentHeight - 1)), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'g') {
-                            return [{ ...model, settingsScrollY: 0 }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'G') {
-                            return [{ ...model, settingsScrollY: layout.maxScrollY }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && (msg.key === 'enter' || msg.key === 'space')) {
-                            const row = layout.rows[clampSettingsFocus(model, layout)]?.row;
-                            if (row?.action !== undefined && row.enabled !== false && row.kind !== 'info') {
-                                const [nextModel, cmds] = activateSettingsRow(model, row);
-                                return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                            }
-                            return [model, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        return [model, withObservedKey(model, [], msg, 'frame')];
-                    }
-                }
-                if (activeLayer.kind === 'notification-center') {
-                    const layout = resolveNotificationCenterLayout(model, options, pagesById);
-                    if (layout != null) {
-                        const centerFrameAction = frameKeys.handle(msg);
-                        if (!msg.ctrl && !msg.alt && msg.key === 'escape') {
-                            return [{
-                                    ...model,
-                                    notificationCenterOpen: false,
-                                    notificationCenterScrollY: 0,
-                                }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (isShellQuitRequest(msg)) {
-                            return applyQuitRequest(model, msg);
-                        }
-                        if (centerFrameAction?.type === 'toggle-notifications') {
-                            const [nextModel, cmds] = applyFrameAction(centerFrameAction, model, options, pagesById);
-                            return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'f2') {
-                            const [nextModel, cmds] = applyFrameAction({ type: 'toggle-settings' }, model, options, pagesById);
-                            return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === '?') {
-                            return [{
-                                    ...model,
-                                    helpOpen: true,
-                                    notificationCenterOpen: false,
-                                    notificationCenterScrollY: 0,
-                                }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (options.enableCommandPalette && !msg.ctrl && !msg.alt && msg.key === '/') {
-                            return [openSearchPalette({
-                                    ...model,
-                                    notificationCenterOpen: false,
-                                    notificationCenterScrollY: 0,
-                                }, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (options.enableCommandPalette && ((msg.ctrl && !msg.alt && msg.key === 'p') || (!msg.ctrl && !msg.alt && msg.key === ':'))) {
-                            return [openCommandPalette({
-                                    ...model,
-                                    notificationCenterOpen: false,
-                                    notificationCenterScrollY: 0,
-                                }, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && (msg.key === 'up' || msg.key === 'k')) {
-                            return [scrollNotificationCenterBy(model, layout, -1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && (msg.key === 'down' || msg.key === 'j')) {
-                            return [scrollNotificationCenterBy(model, layout, 1), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'd') {
-                            return [scrollNotificationCenterBy(model, layout, Math.max(1, layout.contentHeight - 2)), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'u') {
-                            return [scrollNotificationCenterBy(model, layout, -Math.max(1, layout.contentHeight - 2)), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'g') {
-                            return [{ ...model, notificationCenterScrollY: 0 }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'G') {
-                            return [{ ...model, notificationCenterScrollY: layout.maxScrollY }, withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (!msg.ctrl && !msg.alt && msg.key === 'f') {
-                            const [nextModel, cmds] = cycleNotificationCenterFilter(model, layout);
-                            return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                        }
-                        return [model, withObservedKey(model, [], msg, 'frame')];
-                    }
-                }
-                if (activeLayer.kind === 'quit-confirm') {
-                    if (isShellQuitConfirmAccept(msg)) {
-                        return [{
-                                ...model,
-                                quitConfirmOpen: false,
-                            }, withObservedKey(model, [quit()], msg, 'frame')];
-                    }
-                    if (isShellQuitConfirmDismiss(msg)) {
-                        return [{
-                                ...model,
-                                quitConfirmOpen: false,
-                            }, withObservedKey(model, [], msg, 'frame')];
-                    }
-                    return [model, withObservedKey(model, [], msg, 'frame')];
-                }
-                if (activeLayer.kind === 'page-modal' && modalKeyMap != null) {
-                    const modalAction = modalKeyMap.handle(msg);
-                    if (modalAction !== undefined) {
-                        return [model, withObservedKey(model, [emitMsgForPage(model.activePageId, modalAction)], msg, 'page')];
-                    }
-                    return [model, withObservedKey(model, [], msg, 'page')];
-                }
-                if (isShellQuitRequest(msg)) {
-                    return applyQuitRequest(model, msg);
-                }
-                const paneAction = activeInputArea?.keyMap?.handle(msg);
-                const pageAction = activePage.keyMap?.handle(msg);
-                const globalAction = options.globalKeys?.handle(msg);
-                const frameAction = frameKeys.handle(msg);
-                const keyPriority = options.keyPriority ?? 'frame-first';
-                if (keyPriority === 'page-first') {
-                    if (paneAction !== undefined) {
-                        return [model, withObservedKey(model, [emitMsgForPage(model.activePageId, paneAction)], msg, 'page')];
-                    }
-                    if (pageAction !== undefined) {
-                        return [model, withObservedKey(model, [emitMsgForPage(model.activePageId, pageAction)], msg, 'page')];
-                    }
-                    if (globalAction !== undefined) {
-                        return [model, withObservedKey(model, [emitMsg(globalAction)], msg, 'global')];
-                    }
-                    if (frameAction !== undefined) {
-                        if (frameAction.type === 'open-search' && options.enableCommandPalette) {
-                            return [openSearchPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        if (frameAction.type === 'open-palette' && options.enableCommandPalette) {
-                            return [openCommandPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                        }
-                        const [nextModel, cmds] = applyFrameAction(frameAction, model, options, pagesById);
-                        return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                    }
-                    return [model, withObservedKey(model, [], msg, 'unhandled')];
-                }
-                if (frameAction !== undefined) {
-                    // Handle palette opening here since applyFrameAction doesn't have access to palette deps
-                    if (frameAction.type === 'open-search' && options.enableCommandPalette) {
-                        return [openSearchPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                    }
-                    if (frameAction.type === 'open-palette' && options.enableCommandPalette) {
-                        return [openCommandPalette(model, frameKeys, options, pagesById), withObservedKey(model, [], msg, 'frame')];
-                    }
-                    const [nextModel, cmds] = applyFrameAction(frameAction, model, options, pagesById);
-                    return [nextModel, withObservedKey(model, cmds, msg, 'frame')];
-                }
-                if (paneAction !== undefined) {
-                    return [model, withObservedKey(model, [emitMsgForPage(model.activePageId, paneAction)], msg, 'page')];
-                }
-                if (globalAction !== undefined) {
-                    return [model, withObservedKey(model, [emitMsg(globalAction)], msg, 'global')];
-                }
-                if (pageAction !== undefined) {
-                    return [model, withObservedKey(model, [emitMsgForPage(model.activePageId, pageAction)], msg, 'page')];
-                }
-                return [model, withObservedKey(model, [], msg, 'unhandled')];
+                return drainShellCommandBuffer(model, resolveRoutedKeyLayer(msg, model));
             }
             if (isMouseMsg(msg)) {
-                const frameResult = handleFrameMouse(msg, model);
-                if (frameResult != null)
-                    return frameResult;
+                const mouseRouteResult = resolveRoutedMouseLayer(msg, model);
+                if (mouseRouteResult.handled) {
+                    return drainShellCommandBuffer(model, mouseRouteResult);
+                }
                 return updateTargetPage(model, model.activePageId, msg);
             }
             // Custom message path: route to originating page when command messages are scoped.
@@ -916,13 +1160,18 @@ export function createFramedApp(options) {
         },
         view(model) {
             const { activePage, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
-            const header = resolveHeaderLine(model, options, pagesById).surface;
-            const helpLine = renderHelpLine(model, activeLayer, options.i18n, resolveNotificationFooterCue(model, options, pagesById));
+            const headerResult = resolveHeaderLine(model, options, pagesById, headerScratch);
+            headerScratch = headerResult.surface;
+            const header = headerResult.surface;
+            helpLineScratch = renderHelpLine(model, activeLayer, options.i18n, resolveNotificationFooterCue(model, options, pagesById), helpLineScratch);
+            const helpLine = helpLineScratch;
             const bodyRect = resolveBodyRect(model, options);
             // Check for maximized pane — if set, render only that pane at full body rect
             const maxState = model.maximizedPaneByPage[model.activePageId];
             const maximizedPaneId = maxState?.maximizedPaneId;
             const frameSurface = getComposedFrameScratch(model.columns, model.rows);
+            // clear() is load-bearing: it resets dim flags left by overlay compositing
+            // on the previous frame. Do not skip or defer this call.
             frameSurface.clear();
             frameSurface.blit(header, 0, 0);
             if (model.rows > 1) {
@@ -933,7 +1182,7 @@ export function createFramedApp(options) {
             const activeTransition = model.activeTransition ?? options.transition;
             if (model.previousPageId != null && model.transitionProgress < 1 && activeTransition && activeTransition !== 'none') {
                 const activeBodyResult = maximizedPaneId
-                    ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId)
+                    ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, paneScratchPool)
                     : renderPageContent(model.activePageId, model, bodyRect, pagesById);
                 activeResult = activeBodyResult;
                 bodySurface = activeBodyResult.surface;
@@ -945,8 +1194,8 @@ export function createFramedApp(options) {
             }
             else {
                 activeResult = maximizedPaneId
-                    ? renderMaximizedPaneInto(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, frameSurface)
-                    : renderPageContentInto(model.activePageId, model, bodyRect, pagesById, frameSurface);
+                    ? renderMaximizedPaneInto(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, frameSurface, bodyRect.row, bodyRect.col, paneScratchPool)
+                    : renderPageContentInto(model.activePageId, model, bodyRect, pagesById, frameSurface, bodyRect.row, bodyRect.col, paneScratchPool);
             }
             const overlays = [];
             if (options.overlayFactory != null) {
@@ -1040,23 +1289,6 @@ function focusPane(model, paneId) {
         },
     };
 }
-function paneHitAtPosition(model, col, row, pagesById, options) {
-    const bodyRect = resolveBodyRect(model, options);
-    const maxState = model.maximizedPaneByPage[model.activePageId];
-    const maximizedPaneId = maxState?.maximizedPaneId;
-    const renderResult = maximizedPaneId
-        ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId)
-        : renderPageContent(model.activePageId, model, bodyRect, pagesById);
-    for (const [paneId, rect] of renderResult.paneRects.entries()) {
-        if (col >= rect.col
-            && col < rect.col + rect.width
-            && row >= rect.row
-            && row < rect.row + rect.height) {
-            return { paneId, rect };
-        }
-    }
-    return undefined;
-}
 function resolveBodyRect(model, options) {
     return frameBodyRect(model.columns, model.rows, options.bodyTopRows ?? 1, options.bodyBottomRows ?? 1);
 }
@@ -1157,54 +1389,6 @@ function isHelpScrollAction(action) {
         || action.type === 'top'
         || action.type === 'bottom';
 }
-function applyHelpScrollAction(model, activePage, action, frameKeys, paletteKeys, options, pagesById) {
-    const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
-    const pagerState = {
-        scroll: {
-            y: overlay.scrollY,
-            maxY: overlay.maxScrollY,
-            x: 0,
-            maxX: 0,
-            totalLines: overlay.maxScrollY + Math.max(1, overlay.body.height - 1),
-            visibleLines: Math.max(1, overlay.body.height - 1),
-        },
-        content: '',
-        width: overlay.body.width,
-        height: overlay.body.height,
-    };
-    let next = pagerState;
-    switch (action.type) {
-        case 'scroll-up':
-            next = pagerScrollBy(pagerState, -1);
-            break;
-        case 'scroll-down':
-            next = pagerScrollBy(pagerState, 1);
-            break;
-        case 'page-up':
-            next = pagerPageUp(pagerState);
-            break;
-        case 'page-down':
-            next = pagerPageDown(pagerState);
-            break;
-        case 'top':
-            next = pagerScrollToTop(pagerState);
-            break;
-        case 'bottom':
-            next = pagerScrollToBottom(pagerState);
-            break;
-    }
-    return {
-        ...model,
-        helpScrollY: next.scroll.y,
-    };
-}
-function applyHelpScroll(model, activePage, delta, frameKeys, paletteKeys, options, pagesById) {
-    const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
-    return {
-        ...model,
-        helpScrollY: Math.max(0, Math.min(overlay.maxScrollY, overlay.scrollY + delta)),
-    };
-}
 function resolveFrameSettings(model, options, pagesById) {
     const activePage = pagesById.get(model.activePageId);
     return options.settings?.({
@@ -1404,26 +1588,6 @@ function cycleNotificationCenterFilter(model, layout) {
             notificationCenterScrollY: 0,
         }, []];
 }
-function isInsideSettingsDrawer(col, row, layout, model) {
-    return col >= layout.startCol
-        && col < layout.startCol + layout.drawerWidth
-        && row >= 0
-        && row < model.rows;
-}
-function settingsRowAtPosition(col, row, model, layout) {
-    if (!isInsideSettingsDrawer(col, row, layout, model))
-        return undefined;
-    if (row <= 0 || row >= model.rows - 1)
-        return undefined;
-    const contentLine = (row - 1) + clampSettingsScroll(model, layout);
-    return layout.rows.find((candidate) => contentLine >= candidate.line && contentLine < candidate.line + candidate.height);
-}
-function isInsideNotificationCenterDrawer(col, row, layout, model) {
-    return col >= layout.startCol
-        && col < layout.startCol + layout.drawerWidth
-        && row >= 0
-        && row < model.rows;
-}
 function renderSettingsDrawer(model, options, pagesById, titleOverride) {
     const layout = resolveSettingsLayout(model, options, pagesById);
     if (layout == null)