@flyingrobots/bijou-tui 4.4.0 → 5.0.0

package/dist/app-frame.js

@@ -4,28 +4,27 @@
  * Provides tabs, pane focus/scroll isolation, shell key handling, help,
  * panel-scoped overlay context, and optional frame-level command palette.
  */
-import { createSurface, preparePreferenceSections, preferenceListSurface, resolvePreferenceRowLayout, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
-import { helpViewSurface } from './help.js';
-import { createKeyMap } from './keybindings.js';
+import { cloneContextWithResolvedTheme, createResolved, createSurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
+import { createKeyMap, formatKeyCombo } from './keybindings.js';
 import { isKeyMsg, isMouseMsg, isResizeMsg } from './types.js';
 import { quit } from './commands.js';
-import { compositeSurfaceInto, drawer, modal } from './overlay.js';
+import { runWithLifecycleHooks } from './runtime.js';
+import { compositeSurfaceInto, modal } from './overlay.js';
 import { isShellQuitConfirmAccept, isShellQuitConfirmDismiss, isShellQuitRequest, renderShellQuitOverlay, shouldUseShellQuitConfirm, } from './shell-quit.js';
-import { commandPalette, commandPaletteKeyMap, } from './command-palette.js';
-import { createPagerStateForSurface, pagerSurface, } from './pager.js';
+import { commandPaletteSurface, commandPaletteKeyMap, } from './command-palette.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 { 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, } from './app-frame-utils.js';
-import { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, } from './app-frame-layers.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 { activeFrameLayer, describeFrameRuntimeViewStack, projectFrameControls, } 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 { 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';
-export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, underlyingFrameLayer, } from './app-frame-layers.js';
+export { emitFrameAction, notify, } from './app-frame-types.js';
+export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, projectFrameControls, underlyingFrameLayer, } from './app-frame-layers.js';
 // ---------------------------------------------------------------------------
 // Frame Notification Helpers
 // ---------------------------------------------------------------------------
@@ -33,72 +32,79 @@ 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',
-    'ERROR',
-    'WARNING',
-    'SUCCESS',
-    'INFO',
-];
-const quitHelpKeys = createKeyMap()
-    .group('Exit', (g) => g
-    .bind('q', 'Quit', { type: 'toggle-help' })
-    .bind('escape', 'Quit', { type: 'toggle-help' })
-    .bind('ctrl+c', 'Quit', { type: 'toggle-help' }));
-const helpLayerHelpKeys = createKeyMap()
-    .group('Help', (g) => g
-    .bind('escape', 'Close help', { type: 'noop' })
-    .bind('?', 'Close help', { type: 'noop' })
-    .bind('up', 'Scroll up', { type: 'noop' })
-    .bind('down', 'Scroll down', { type: 'noop' })
-    .bind('j', 'Scroll down', { type: 'noop' })
-    .bind('k', 'Scroll up', { type: 'noop' })
-    .bind('d', 'Page down', { type: 'noop' })
-    .bind('u', 'Page up', { type: 'noop' })
-    .bind('g', 'Top', { type: 'noop' })
-    .bind('shift+g', 'Bottom', { type: 'noop' }));
-const settingsHelpKeys = createKeyMap()
-    .group('Settings', (g) => g
-    .bind('escape', 'Close settings', { type: 'toggle-settings' })
-    .bind('f2', 'Close settings', { type: 'toggle-settings' })
-    .bind('up', 'Previous row', { type: 'scroll-up' })
-    .bind('down', 'Next row', { type: 'scroll-down' })
-    .bind('enter', 'Activate setting', { type: 'toggle-settings' })
-    .bind('space', 'Activate setting', { type: 'toggle-settings' })
-    .bind('j', 'Scroll down', { type: 'scroll-down' })
-    .bind('k', 'Scroll up', { type: 'scroll-up' })
-    .bind('d', 'Page down', { type: 'page-down' })
-    .bind('u', 'Page up', { type: 'page-up' })
-    .bind('g', 'Top', { type: 'top' })
-    .bind('shift+g', 'Bottom', { type: 'bottom' })
-    .bind('/', 'Search', { type: 'open-search' })
-    .bind('ctrl+p', 'Open command palette', { type: 'open-palette' })
-    .bind(':', 'Open command palette', { type: 'open-palette' })
-    .bind('?', 'Toggle help', { type: 'toggle-help' }));
-const notificationCenterHelpKeys = createKeyMap()
-    .group('Notifications', (g) => g
-    .bind('shift+n', 'Close notification center', { type: 'noop' })
-    .bind('up', 'Scroll up', { type: 'noop' })
-    .bind('down', 'Scroll down', { type: 'noop' })
-    .bind('j', 'Scroll down', { type: 'noop' })
-    .bind('k', 'Scroll up', { type: 'noop' })
-    .bind('d', 'Page down', { type: 'noop' })
-    .bind('u', 'Page up', { type: 'noop' })
-    .bind('g', 'Top', { type: 'noop' })
-    .bind('shift+g', 'Bottom', { type: 'noop' })
-    .bind('f', 'Cycle filter', { type: 'noop' })
-    .bind('/', 'Search', { type: 'noop' })
-    .bind('ctrl+p', 'Open command palette', { type: 'noop' })
-    .bind(':', 'Open command palette', { type: 'noop' })
-    .bind('?', 'Toggle help', { type: 'noop' }));
-const quitConfirmHelpKeys = createKeyMap()
-    .group('Quit', (g) => g
-    .bind('y', 'Quit', { type: 'noop' })
-    .bind('enter', 'Quit', { type: 'noop' })
-    .bind('n', 'Stay', { type: 'noop' })
-    .bind('escape', 'Stay', { type: 'noop' })
-    .bind('q', 'Stay', { type: 'noop' }));
+function createQuitHelpKeys(i18n) {
+    const t = (id, fallback) => frameMessage(i18n, id, fallback);
+    return createKeyMap()
+        .group(t('help.group.quit', 'Quit'), (g) => g
+        .bind('q', t('help.key.quit', 'Quit'), { type: 'toggle-help' })
+        .bind('escape', t('help.key.quit', 'Quit'), { type: 'toggle-help' })
+        .bind('ctrl+c', t('help.key.quit', 'Quit'), { type: 'toggle-help' }));
+}
+function createHelpLayerHelpKeys(i18n) {
+    const t = (id, fallback) => frameMessage(i18n, id, fallback);
+    return createKeyMap()
+        .group(t('help.group.help', 'Help'), (g) => g
+        .bind('escape', t('help.key.closeHelp', 'Close help'), { type: 'noop' })
+        .bind('?', t('help.key.closeHelp', 'Close help'), { type: 'noop' })
+        .bind('up', t('key.scrollUp', 'Scroll up'), { type: 'noop' })
+        .bind('down', t('key.scrollDown', 'Scroll down'), { type: 'noop' })
+        .bind('j', t('key.scrollDown', 'Scroll down'), { type: 'noop' })
+        .bind('k', t('key.scrollUp', 'Scroll up'), { type: 'noop' })
+        .bind('d', t('key.pageDown', 'Page down'), { type: 'noop' })
+        .bind('u', t('key.pageUp', 'Page up'), { type: 'noop' })
+        .bind('g', t('key.top', 'Top'), { type: 'noop' })
+        .bind('shift+g', t('key.bottom', 'Bottom'), { type: 'noop' }));
+}
+function createSettingsHelpKeys(i18n) {
+    const t = (id, fallback) => frameMessage(i18n, id, fallback);
+    return createKeyMap()
+        .group(t('help.group.settings', 'Settings'), (g) => g
+        .bind('escape', t('help.key.closeSettings', 'Close settings'), { type: 'toggle-settings' })
+        .bind('f2', t('help.key.closeSettings', 'Close settings'), { type: 'toggle-settings' })
+        .bind('up', t('help.key.previousRow', 'Previous row'), { type: 'scroll-up' })
+        .bind('down', t('help.key.nextRow', 'Next row'), { type: 'scroll-down' })
+        .bind('enter', t('help.key.activateSetting', 'Activate setting'), { type: 'toggle-settings' })
+        .bind('space', t('help.key.activateSetting', 'Activate setting'), { type: 'toggle-settings' })
+        .bind('j', t('key.scrollDown', 'Scroll down'), { type: 'scroll-down' })
+        .bind('k', t('key.scrollUp', 'Scroll up'), { type: 'scroll-up' })
+        .bind('d', t('key.pageDown', 'Page down'), { type: 'page-down' })
+        .bind('u', t('key.pageUp', 'Page up'), { type: 'page-up' })
+        .bind('g', t('key.top', 'Top'), { type: 'top' })
+        .bind('shift+g', t('key.bottom', 'Bottom'), { type: 'bottom' })
+        .bind('/', t('key.search', 'Search'), { type: 'open-search' })
+        .bind('ctrl+p', t('key.openPalette', 'Open command palette'), { type: 'open-palette' })
+        .bind(':', t('key.openPalette', 'Open command palette'), { type: 'open-palette' })
+        .bind('?', t('key.toggleHelp', 'Toggle help'), { type: 'toggle-help' }));
+}
+function createNotificationCenterHelpKeys(i18n) {
+    const t = (id, fallback) => frameMessage(i18n, id, fallback);
+    return createKeyMap()
+        .group(t('help.group.notifications', 'Notifications'), (g) => g
+        .bind('shift+n', t('help.key.closeNotifications', 'Close notification center'), { type: 'noop' })
+        .bind('up', t('key.scrollUp', 'Scroll up'), { type: 'noop' })
+        .bind('down', t('key.scrollDown', 'Scroll down'), { type: 'noop' })
+        .bind('j', t('key.scrollDown', 'Scroll down'), { type: 'noop' })
+        .bind('k', t('key.scrollUp', 'Scroll up'), { type: 'noop' })
+        .bind('d', t('key.pageDown', 'Page down'), { type: 'noop' })
+        .bind('u', t('key.pageUp', 'Page up'), { type: 'noop' })
+        .bind('g', t('key.top', 'Top'), { type: 'noop' })
+        .bind('shift+g', t('key.bottom', 'Bottom'), { type: 'noop' })
+        .bind('f', t('help.key.cycleFilter', 'Cycle filter'), { type: 'noop' })
+        .bind('/', t('key.search', 'Search'), { type: 'noop' })
+        .bind('ctrl+p', t('key.openPalette', 'Open command palette'), { type: 'noop' })
+        .bind(':', t('key.openPalette', 'Open command palette'), { type: 'noop' })
+        .bind('?', t('key.toggleHelp', 'Toggle help'), { type: 'noop' }));
+}
+function createQuitConfirmHelpKeys(i18n) {
+    const t = (id, fallback) => frameMessage(i18n, id, fallback);
+    return createKeyMap()
+        .group(t('help.group.quit', 'Quit'), (g) => g
+        .bind('y', t('help.key.quit', 'Quit'), { type: 'noop' })
+        .bind('enter', t('help.key.quit', 'Quit'), { type: 'noop' })
+        .bind('n', t('help.key.stay', 'Stay'), { type: 'noop' })
+        .bind('escape', t('help.key.stay', 'Stay'), { type: 'noop' })
+        .bind('q', t('help.key.stay', 'Stay'), { type: 'noop' }));
+}
 function resolveFrameNotificationOptions(options) {
     if (options.runtimeNotifications === false) {
         return {
@@ -134,6 +140,48 @@ function createFrameNotificationTickCmd() {
         });
     };
 }
+function cloneShellThemeContext(ctx, resolvedTheme) {
+    return cloneContextWithResolvedTheme(ctx, resolvedTheme);
+}
+function readStageDuration(timings, stage) {
+    return timings.find((timing) => timing.stage === stage)?.durationMs ?? 0;
+}
+function summarizeFrameTimings(timings, frameBudgetMs) {
+    const frameTimeMs = timings.reduce((total, timing) => total + timing.durationMs, 0);
+    return {
+        frameTimeMs,
+        viewTimeMs: readStageDuration(timings, 'Layout'),
+        diffTimeMs: readStageDuration(timings, 'Diff'),
+        frameBudgetMs,
+        frameOverBudget: frameBudgetMs != null && frameTimeMs > frameBudgetMs,
+    };
+}
+function applyFrameTimingSnapshot(model, snapshot) {
+    if (model.frameTimeMs === snapshot.frameTimeMs
+        && model.viewTimeMs === snapshot.viewTimeMs
+        && model.diffTimeMs === snapshot.diffTimeMs
+        && model.frameBudgetMs === snapshot.frameBudgetMs
+        && model.frameOverBudget === snapshot.frameOverBudget) {
+        return model;
+    }
+    return {
+        ...model,
+        frameTimeMs: snapshot.frameTimeMs,
+        viewTimeMs: snapshot.viewTimeMs,
+        diffTimeMs: snapshot.diffTimeMs,
+        frameBudgetMs: snapshot.frameBudgetMs,
+        frameOverBudget: snapshot.frameOverBudget,
+    };
+}
+function resolveFrameBudgetMs(runOptions, fallbackCtx) {
+    if (runOptions?.frameBudgetMs != null)
+        return runOptions.frameBudgetMs;
+    const refreshRate = runOptions?.ctx?.runtime.refreshRate ?? fallbackCtx?.runtime.refreshRate;
+    if (refreshRate == null || !Number.isFinite(refreshRate) || refreshRate <= 0) {
+        return undefined;
+    }
+    return 1_000 / refreshRate;
+}
 // Factory
 // ---------------------------------------------------------------------------
 /**
@@ -155,16 +203,84 @@ export function createFramedApp(options) {
     if (!pagesById.has(defaultPageId)) {
         throw new Error(`createFramedApp: defaultPageId "${defaultPageId}" not found in pages`);
     }
+    const shellThemeSpecs = options.shellThemes ?? [];
+    let defaultFrameCtx = options.ctx ?? resolveSafeCtx();
+    let resolvedShellThemes = [];
+    const enableShellThemeSettings = shellThemeSpecs.length > 1;
+    const usesAmbientDefaultContext = options.ctx == null && defaultFrameCtx != null;
+    let frameCtx = options.ctx;
+    let frameCtxShellThemeId;
+    let useRunScopedFrameCtx = false;
+    function ensureResolvedShellThemes(explicitCtx) {
+        if (shellThemeSpecs.length === 0 || resolvedShellThemes.length > 0)
+            return;
+        const baseCtx = explicitCtx ?? frameCtx ?? options.ctx ?? resolveSafeCtx();
+        if (baseCtx == null) {
+            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),
+        }));
+    }
+    if (frameCtx != null) {
+        ensureResolvedShellThemes(frameCtx);
+        frameCtxShellThemeId = resolveShellThemeForContext(resolvedShellThemes, frameCtx)?.id;
+    }
+    function resolveFrameCtx() {
+        return frameCtx ?? options.ctx ?? resolveSafeCtx();
+    }
+    function resolveFrameThemeCtx(activeShellThemeId) {
+        const baseCtx = resolveFrameCtx();
+        ensureResolvedShellThemes(baseCtx);
+        if (defaultFrameCtx == null)
+            return baseCtx;
+        const activeTheme = resolveCurrentShellTheme(resolvedShellThemes, activeShellThemeId);
+        if (activeTheme == null)
+            return baseCtx;
+        if (frameCtx != null && frameCtxShellThemeId === activeTheme.id) {
+            return frameCtx;
+        }
+        if (resolveShellThemeForContext(resolvedShellThemes, baseCtx)?.id === activeTheme.id) {
+            return baseCtx;
+        }
+        return cloneShellThemeContext(defaultFrameCtx, activeTheme.resolvedTheme);
+    }
+    function publishShellThemeContext(nextTheme) {
+        ensureResolvedShellThemes(resolveFrameCtx());
+        if (defaultFrameCtx == null)
+            return resolveFrameCtx();
+        frameCtx = cloneShellThemeContext(defaultFrameCtx, nextTheme.resolvedTheme);
+        frameCtxShellThemeId = nextTheme.id;
+        if (usesAmbientDefaultContext && !useRunScopedFrameCtx) {
+            setDefaultContext(frameCtx);
+        }
+        options.onShellThemeChange?.({
+            shellTheme: nextTheme.shellTheme,
+            ctx: frameCtx,
+        });
+        return frameCtx;
+    }
     const frameKeys = createFrameKeyMap({
-        enableSettings: options.settings != null,
+        enableSettings: options.settings != null || enableShellThemeSettings,
         enableNotifications: options.notificationCenter != null || options.runtimeNotifications !== false,
         i18n: options.i18n,
     });
+    const quitHelpKeys = createQuitHelpKeys(options.i18n);
+    const helpLayerHelpKeys = createHelpLayerHelpKeys(options.i18n);
+    const settingsHelpKeys = createSettingsHelpKeys(options.i18n);
+    const notificationCenterHelpKeys = createNotificationCenterHelpKeys(options.i18n);
+    const quitConfirmHelpKeys = createQuitConfirmHelpKeys(options.i18n);
     const frameNotificationOptions = resolveFrameNotificationOptions(options);
     let composedFrameScratch = null;
     let headerScratch;
     let helpLineScratch;
     const paneScratchPool = createFramePaneScratchPool();
+    let workspaceLayoutCache;
     const paletteKeys = commandPaletteKeyMap({
         focusNext: { type: 'cp-next' },
         focusPrev: { type: 'cp-prev' },
@@ -173,6 +289,49 @@ export function createFramedApp(options) {
         select: { type: 'cp-select' },
         close: { type: 'cp-close' },
     });
+    function bindingComboKey(binding) {
+        const combo = binding.combo;
+        return `${combo.key}|${combo.ctrl ? 1 : 0}|${combo.alt ? 1 : 0}|${combo.shift ? 1 : 0}`;
+    }
+    function findBindingForMessage(bindings, msg) {
+        const comboKey = `${msg.key}|${msg.ctrl ? 1 : 0}|${msg.alt ? 1 : 0}|${msg.shift ? 1 : 0}`;
+        return bindings.find((binding) => binding.enabled && bindingComboKey(binding) === comboKey);
+    }
+    function queueFrameKeyCollisionWarning(model, msg, teaCmds) {
+        if (!frameNotificationOptions.enabled)
+            return model;
+        if ((options.keyPriority ?? 'frame-first') !== 'frame-first')
+            return model;
+        if (model.warnedFrameKeyCollisionPages[model.activePageId])
+            return model;
+        const activePage = pagesById.get(model.activePageId);
+        if (activePage?.keyMap == null)
+            return model;
+        const pageBinding = findBindingForMessage(activePage.keyMap.bindings(), msg);
+        const frameBinding = findBindingForMessage(frameKeys.bindings(), msg);
+        if (pageBinding == null || frameBinding == null)
+            return model;
+        const warningCmd = async () => wrapFrameMsg({
+            type: 'runtime-issue',
+            issue: {
+                level: 'warning',
+                source: 'runtime',
+                message: `Page "${model.activePageId}" key binding ${formatKeyCombo(pageBinding.combo)} `
+                    + `("${pageBinding.description}") is shadowed by the frame binding `
+                    + `"${frameBinding.description}" under keyPriority="frame-first". `
+                    + `Use keyPriority: 'page-first' or choose a different page binding.`,
+                atMs: resolveClock(resolveFrameCtx()).now(),
+            },
+        });
+        teaCmds.push(warningCmd);
+        return {
+            ...model,
+            warnedFrameKeyCollisionPages: {
+                ...model.warnedFrameKeyCollisionPages,
+                [model.activePageId]: true,
+            },
+        };
+    }
     function getComposedFrameScratch(width, height) {
         if (composedFrameScratch == null
             || composedFrameScratch.width !== width
@@ -221,30 +380,35 @@ export function createFramedApp(options) {
         // --- settings ---
         'settings-focus-move': (model, cmd) => {
             const c = cmd;
-            const layout = resolveSettingsLayout(model, options, pagesById);
+            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);
+            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);
+            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);
+            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);
+                teaCmds.push(...cmds);
+                return nextModel;
+            }
             if (hitRow.row.action === undefined || hitRow.row.enabled === false || hitRow.row.kind === 'info') {
                 return focusedModel;
             }
@@ -255,29 +419,36 @@ export function createFramedApp(options) {
         // --- notification center ---
         'notification-center-scroll': (model, cmd) => {
             const c = cmd;
-            const layout = resolveNotificationCenterLayout(model, options, pagesById);
+            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);
+            const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
             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);
+            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;
         },
+        '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 activePage = pagesById.get(model.activePageId);
-            const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
+            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 = c.action === 'down' ? 3
                 : c.action === 'up' ? -3
@@ -337,7 +508,7 @@ export function createFramedApp(options) {
             const c = cmd;
             if (!frameNotificationOptions.enabled)
                 return model;
-            const nowMs = resolveClock(resolveSafeCtx()).now();
+            const nowMs = resolveClock(resolveFrameCtx()).now();
             const [nextModel, cmds] = applyFrameNotificationState(model, dismissNotification(model.runtimeNotifications, c.notificationId, nowMs), nowMs);
             teaCmds.push(...cmds);
             return nextModel;
@@ -436,7 +607,7 @@ export function createFramedApp(options) {
         return [obs];
     }
     function handleSettingsLayerKeyCommands(msg, model) {
-        const layout = resolveSettingsLayout(model, options, pagesById);
+        const layout = resolveSettingsLayout(model, options, pagesById, resolvedShellThemes);
         if (layout == null)
             return undefined;
         const obs = { type: 'observed-key', msg, route: 'frame' };
@@ -489,7 +660,10 @@ export function createFramedApp(options) {
         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') {
+            if (row != null
+                && row.row.enabled !== false
+                && row.row.kind !== 'info'
+                && (row.behavior === 'cycle-shell-theme' || row.row.action !== undefined)) {
                 return [obs, { type: 'activate-settings-row', rowIndex: row.index }];
             }
             return [obs];
@@ -497,7 +671,7 @@ export function createFramedApp(options) {
         return [obs];
     }
     function handleNotificationCenterLayerKeyCommands(msg, model) {
-        const layout = resolveNotificationCenterLayout(model, options, pagesById);
+        const layout = resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId));
         if (layout == null)
             return undefined;
         const obs = { type: 'observed-key', msg, route: 'frame' };
@@ -574,7 +748,9 @@ export function createFramedApp(options) {
         }
         // frame-first (default)
         if (frameAction !== undefined) {
-            return resolveFrameActionCommands(msg, frameAction, 'frame');
+            return pageAction !== undefined
+                ? [...resolveFrameActionCommands(msg, frameAction, 'frame'), { type: 'warn-frame-key-collision', msg }]
+                : resolveFrameActionCommands(msg, frameAction, 'frame');
         }
         if (paneAction !== undefined) {
             return [{ type: 'observed-key', msg, route: 'page' }, { type: 'emit-page-msg', pageId: model.activePageId, msg: paneAction }];
@@ -647,26 +823,15 @@ export function createFramedApp(options) {
             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}`, {
+    function buildWorkspaceLayoutTreeFromPaneRects(model, paneRects, tabTargets) {
+        const resolvedTabTargets = tabTargets ?? resolveHeaderLine(model, options, pagesById, headerScratch, resolveFrameThemeCtx(model.activeShellThemeId)).tabTargets;
+        const tabChildren = resolvedTabTargets.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));
@@ -676,6 +841,55 @@ export function createFramedApp(options) {
             createShellRetainedLayoutNode('workspace-body', bodyRect, paneChildren),
         ]);
     }
+    function rememberWorkspaceLayout(model, paneRects, tabTargets) {
+        const activePageId = model.activePageId;
+        const next = {
+            activePageId,
+            activePageModel: model.pageModels[activePageId],
+            columns: model.columns,
+            rows: model.rows,
+            visibilityState: model.minimizedByPage[activePageId],
+            dockState: model.dockStateByPage[activePageId],
+            splitRatioOverrides: model.splitRatioOverrides,
+            maximizedPaneId: model.maximizedPaneByPage[activePageId]?.maximizedPaneId,
+            paneRects,
+            tree: buildWorkspaceLayoutTreeFromPaneRects(model, paneRects, tabTargets),
+        };
+        workspaceLayoutCache = next;
+        return next;
+    }
+    function matchesWorkspaceLayoutCache(model) {
+        if (workspaceLayoutCache == null)
+            return false;
+        const activePageId = model.activePageId;
+        return workspaceLayoutCache.activePageId === activePageId
+            && workspaceLayoutCache.activePageModel === model.pageModels[activePageId]
+            && workspaceLayoutCache.columns === model.columns
+            && workspaceLayoutCache.rows === model.rows
+            && workspaceLayoutCache.visibilityState === model.minimizedByPage[activePageId]
+            && workspaceLayoutCache.dockState === model.dockStateByPage[activePageId]
+            && workspaceLayoutCache.splitRatioOverrides === model.splitRatioOverrides
+            && workspaceLayoutCache.maximizedPaneId === model.maximizedPaneByPage[activePageId]?.maximizedPaneId;
+    }
+    function resolveWorkspaceLayout(model) {
+        if (matchesWorkspaceLayoutCache(model)) {
+            return workspaceLayoutCache;
+        }
+        const bodyRect = resolveBodyRect(model, options);
+        const maxState = model.maximizedPaneByPage[model.activePageId];
+        const maximizedPaneId = maxState?.maximizedPaneId;
+        const themedFrameCtx = resolveFrameThemeCtx(model.activeShellThemeId);
+        const renderResult = maximizedPaneId
+            ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, paneScratchPool, themedFrameCtx)
+            : renderPageContent(model.activePageId, model, bodyRect, pagesById, themedFrameCtx);
+        return rememberWorkspaceLayout(model, renderResult.paneRects);
+    }
+    function resolveWorkspacePaneRects(model) {
+        return resolveWorkspaceLayout(model).paneRects;
+    }
+    function buildWorkspaceLayoutTree(model) {
+        return resolveWorkspaceLayout(model).tree;
+    }
     function buildSettingsRowChildren(model, layout) {
         const scrollY = clampSettingsScroll(model, layout);
         const viewportTop = 1;
@@ -698,7 +912,9 @@ export function createFramedApp(options) {
     }
     function resolveFrameMouseRuntimeLayouts(model) {
         let layouts = EMPTY_RUNTIME_LAYOUTS;
-        const settingsLayout = model.settingsOpen ? resolveSettingsLayout(model, options, pagesById) : undefined;
+        const settingsLayout = model.settingsOpen
+            ? resolveSettingsLayout(model, options, pagesById, resolvedShellThemes)
+            : undefined;
         if (settingsLayout != null) {
             layouts = retainRuntimeLayout(layouts, {
                 viewId: 'settings',
@@ -710,7 +926,9 @@ export function createFramedApp(options) {
                 }, buildSettingsRowChildren(model, settingsLayout)),
             });
         }
-        const notificationCenterLayout = model.notificationCenterOpen ? resolveNotificationCenterLayout(model, options, pagesById) : undefined;
+        const notificationCenterLayout = model.notificationCenterOpen
+            ? resolveNotificationCenterLayout(model, options, pagesById, resolveFrameThemeCtx(model.activeShellThemeId))
+            : undefined;
         if (notificationCenterLayout != null) {
             layouts = retainRuntimeLayout(layouts, {
                 viewId: 'notification-center',
@@ -790,7 +1008,7 @@ export function createFramedApp(options) {
                         screenHeight: model.rows,
                         margin: frameNotificationOptions.margin,
                         gap: frameNotificationOptions.gap,
-                        ctx: resolveSafeCtx() ?? undefined,
+                        ctx: resolveFrameThemeCtx(model.activeShellThemeId) ?? undefined,
                     }, msg.col, msg.row);
                     if (notificationTarget?.kind === 'dismiss') {
                         cmds.push({ type: 'dismiss-notification', notificationId: notificationTarget.item.id });
@@ -871,8 +1089,8 @@ export function createFramedApp(options) {
         }
         return helpLineOverride ?? mergeBindingSources(frameKeys, options.globalKeys, activeInputArea?.helpSource ?? activeInputArea?.keyMap, activePage.helpSource ?? activePage.keyMap);
     }
-    function resolveLayerMetadata(model, activePage, activeInputArea, modalKeyMap) {
-        const settings = resolveFrameSettings(model, options, pagesById);
+    function resolveLayerMetadata(model, activePage, activePageModel, activeInputArea, modalKeyMap) {
+        const settings = resolveFrameSettings(model, options, pagesById, resolvedShellThemes);
         const notificationCenter = resolveFrameNotificationCenter(model, options, pagesById);
         const workspaceHintSource = resolveWorkspaceHintSource(model, activePage, activeInputArea);
         const workspaceHelpSource = resolveWorkspaceHelpSource(activePage, activeInputArea);
@@ -889,17 +1107,22 @@ export function createFramedApp(options) {
         const notificationsTitle = notificationCenter == null
             ? frameMessage(options.i18n, 'notifications.title', 'Notifications')
             : `${notificationCenter.title} • ${frameNotificationFilterLabel(options.i18n, notificationCenter.activeFilter)}`;
+        const pageLayers = activePage.layers?.(activePageModel);
+        const workspaceLayer = {
+            title: activePage.title,
+            hintSource: workspaceHintSource,
+            helpSource: workspaceHelpSource,
+            ...pageLayers?.workspace,
+        };
+        const pageModalLayer = {
+            title: activePage.title,
+            hintSource: modalKeyMap ?? activePage.helpSource ?? activePage.keyMap,
+            helpSource: mergeBindingSources(quitHelpKeys, modalKeyMap, activePage.helpSource ?? activePage.keyMap),
+            ...pageLayers?.['page-modal'],
+        };
         return {
-            workspace: {
-                title: activePage.title,
-                hintSource: workspaceHintSource,
-                helpSource: workspaceHelpSource,
-            },
-            'page-modal': {
-                title: activePage.title,
-                hintSource: modalKeyMap ?? activePage.helpSource ?? activePage.keyMap,
-                helpSource: mergeBindingSources(quitHelpKeys, modalKeyMap, activePage.helpSource ?? activePage.keyMap),
-            },
+            workspace: workspaceLayer,
+            'page-modal': pageModalLayer,
             settings: {
                 title: settings?.title ?? frameMessage(options.i18n, 'settings.title', 'Settings'),
                 hintSource: settingsHint,
@@ -934,12 +1157,11 @@ export function createFramedApp(options) {
     }
     function resolvePresentedLayerContext(model) {
         const { activePage, activePageModel, inputAreas, activeInputArea, modalKeyMap, pageModalOpen, } = resolveLayerContext(model);
-        const layerStack = describeFrameLayerStack(model, {
+        const layerMetadata = resolveLayerMetadata(model, activePage, activePageModel, activeInputArea, modalKeyMap);
+        const controlProjection = projectFrameControls(model, {
             pageModalOpen,
-            layers: resolveLayerMetadata(model, activePage, activeInputArea, modalKeyMap),
+            layers: layerMetadata,
         });
-        const activeLayer = layerStack[layerStack.length - 1];
-        const underlyingLayer = layerStack.length > 1 ? layerStack[layerStack.length - 2] : undefined;
         return {
             activePage,
             activePageModel,
@@ -947,9 +1169,11 @@ export function createFramedApp(options) {
             activeInputArea,
             modalKeyMap,
             pageModalOpen,
-            layerStack,
-            activeLayer,
-            underlyingLayer,
+            layerMetadata,
+            controlProjection,
+            layerStack: controlProjection.layerStack,
+            activeLayer: controlProjection.activeLayer,
+            underlyingLayer: controlProjection.underlyingLayer,
         };
     }
     function updateTargetPage(model, targetPageId, targetMsg) {
@@ -982,19 +1206,15 @@ export function createFramedApp(options) {
         }
         return [nextModel, []];
     }
-    function activateSettingsRow(model, row) {
-        if (row.action === undefined || row.enabled === false || row.kind === 'info') {
-            return [model, []];
-        }
-        const cmds = [emitMsgForPage(model.activePageId, row.action)];
+    function pushSettingsFeedback(model, row) {
         if (!frameNotificationOptions.enabled) {
-            return [model, cmds];
+            return [model, []];
         }
         const feedback = row.feedback ?? {
             title: 'Setting updated',
             message: `${row.label} updated.`,
         };
-        const nowMs = resolveClock(resolveSafeCtx()).now();
+        const nowMs = resolveClock(resolveFrameCtx()).now();
         const notifications = pushNotification(model.runtimeNotifications, {
             title: feedback.title ?? 'Setting updated',
             message: feedback.message,
@@ -1005,9 +1225,28 @@ export function createFramedApp(options) {
             durationMs: feedback.durationMs ?? 2_500,
             overflow: frameNotificationOptions.overflow,
         }, nowMs);
-        const [nextModel, notificationCmds] = applyFrameNotificationState(model, notifications, nowMs);
+        return applyFrameNotificationState(model, notifications, nowMs);
+    }
+    function activateSettingsRow(model, row) {
+        if (row.action === undefined || row.enabled === false || row.kind === 'info') {
+            return [model, []];
+        }
+        const cmds = [emitMsgForPage(model.activePageId, row.action)];
+        const [nextModel, notificationCmds] = pushSettingsFeedback(model, row);
         return [nextModel, [...cmds, ...notificationCmds]];
     }
+    function cycleShellThemeSetting(model, row) {
+        const nextTheme = resolveNextShellTheme(resolvedShellThemes, model.activeShellThemeId);
+        if (nextTheme == null) {
+            return [model, []];
+        }
+        publishShellThemeContext(nextTheme);
+        const [nextModel, notificationCmds] = pushSettingsFeedback({
+            ...model,
+            activeShellThemeId: nextTheme.id,
+        }, row);
+        return [nextModel, notificationCmds];
+    }
     const app = {
         init() {
             const pageModels = {};
@@ -1021,10 +1260,16 @@ export function createFramedApp(options) {
                 activePageId: defaultPageId,
                 pageOrder,
                 pageModels,
+                warnedFrameKeyCollisionPages: {},
                 focusedPaneByPage: {},
                 scrollByPage: {},
                 columns: Math.max(1, options.initialColumns ?? 80),
                 rows: Math.max(1, options.initialRows ?? 24),
+                frameTimeMs: 0,
+                viewTimeMs: 0,
+                diffTimeMs: 0,
+                frameBudgetMs: undefined,
+                frameOverBudget: false,
                 helpOpen: false,
                 helpScrollY: 0,
                 commandPaletteKind: undefined,
@@ -1044,7 +1289,18 @@ export function createFramedApp(options) {
                 runtimeNotifications: createNotificationState(),
                 runtimeNotificationHistoryFilter: 'ALL',
                 runtimeNotificationLoopActive: false,
+                activeShellThemeId: undefined,
             };
+            ensureResolvedShellThemes(resolveFrameCtx());
+            const initialShellTheme = resolveShellThemeForContext(resolvedShellThemes, resolveFrameCtx())
+                ?? resolvedShellThemes[0];
+            model = {
+                ...model,
+                activeShellThemeId: initialShellTheme?.id,
+            };
+            if (initialShellTheme != null) {
+                publishShellThemeContext(initialShellTheme);
+            }
             for (const pageId of pageOrder) {
                 model = syncPageFrameState(model, pageId, pagesById);
             }
@@ -1080,6 +1336,20 @@ export function createFramedApp(options) {
                     }, action.issue.atMs);
                     return applyFrameNotificationState(model, notifications, action.issue.atMs);
                 }
+                if (action.type === 'push-notification') {
+                    if (!frameNotificationOptions.enabled)
+                        return [model, []];
+                    const nowMs = resolveClock(resolveFrameCtx()).now();
+                    const notifications = pushNotification(model.runtimeNotifications, {
+                        ...action.notification,
+                        placement: action.notification.placement ?? frameNotificationOptions.placement,
+                        durationMs: action.notification.durationMs === undefined
+                            ? frameNotificationOptions.durationMs
+                            : action.notification.durationMs,
+                        overflow: action.notification.overflow ?? frameNotificationOptions.overflow,
+                    }, nowMs);
+                    return applyFrameNotificationState(model, notifications, nowMs);
+                }
                 if (action.type === 'notification-tick') {
                     const notifications = tickNotifications(model.runtimeNotifications, action.atMs);
                     return applyFrameNotificationState(model, notifications, action.atMs, true);
@@ -1159,11 +1429,12 @@ export function createFramedApp(options) {
             return updateTargetPage(model, model.activePageId, msg);
         },
         view(model) {
-            const { activePage, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
-            const headerResult = resolveHeaderLine(model, options, pagesById, headerScratch);
+            const themedFrameCtx = resolveFrameThemeCtx(model.activeShellThemeId);
+            const { controlProjection, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
+            const headerResult = resolveHeaderLine(model, options, pagesById, headerScratch, themedFrameCtx);
             headerScratch = headerResult.surface;
             const header = headerResult.surface;
-            helpLineScratch = renderHelpLine(model, activeLayer, options.i18n, resolveNotificationFooterCue(model, options, pagesById), helpLineScratch);
+            helpLineScratch = renderHelpLine(model, activeLayer, options.i18n, resolveNotificationFooterCue(model, options, pagesById), helpLineScratch, themedFrameCtx);
             const helpLine = helpLineScratch;
             const bodyRect = resolveBodyRect(model, options);
             // Check for maximized pane — if set, render only that pane at full body rect
@@ -1182,21 +1453,22 @@ 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, paneScratchPool)
-                    : renderPageContent(model.activePageId, model, bodyRect, pagesById);
+                    ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, paneScratchPool, themedFrameCtx)
+                    : renderPageContent(model.activePageId, model, bodyRect, pagesById, themedFrameCtx);
                 activeResult = activeBodyResult;
                 bodySurface = activeBodyResult.surface;
-                const ctx = resolveSafeCtx();
+                const ctx = themedFrameCtx;
                 if (ctx) {
-                    const prevResult = renderPageContent(model.previousPageId, model, bodyRect, pagesById);
+                    const prevResult = renderPageContent(model.previousPageId, model, bodyRect, pagesById, themedFrameCtx);
                     bodySurface = renderTransition(prevResult.surface, activeBodyResult.surface, activeTransition, model.transitionProgress, bodyRect.width, bodyRect.height, ctx, model.transitionFrame);
                 }
             }
             else {
                 activeResult = maximizedPaneId
-                    ? 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);
+                    ? renderMaximizedPaneInto(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, frameSurface, bodyRect.row, bodyRect.col, paneScratchPool, themedFrameCtx)
+                    : renderPageContentInto(model.activePageId, model, bodyRect, pagesById, frameSurface, bodyRect.row, bodyRect.col, paneScratchPool, themedFrameCtx);
             }
+            rememberWorkspaceLayout(model, activeResult.paneRects, headerResult.tabTargets);
             const overlays = [];
             if (options.overlayFactory != null) {
                 overlays.push(...options.overlayFactory({
@@ -1207,7 +1479,7 @@ export function createFramedApp(options) {
                 }));
             }
             if (frameNotificationOptions.enabled) {
-                const ctx = resolveSafeCtx();
+                const ctx = themedFrameCtx;
                 overlays.push(...renderNotificationStack(model.runtimeNotifications, {
                     screenWidth: model.columns,
                     screenHeight: model.rows,
@@ -1218,20 +1490,24 @@ export function createFramedApp(options) {
             }
             if (model.settingsOpen) {
                 const settingsLayer = layerStack.find((layer) => layer.kind === 'settings');
-                const settingsOverlay = renderSettingsDrawer(model, options, pagesById, settingsLayer?.title);
+                const settingsOverlay = renderSettingsDrawer(model, options, pagesById, resolvedShellThemes, settingsLayer?.title, themedFrameCtx);
                 if (settingsOverlay != null) {
                     overlays.push(settingsOverlay);
                 }
             }
             if (model.notificationCenterOpen) {
                 const notificationLayer = layerStack.find((layer) => layer.kind === 'notification-center');
-                const notificationCenterOverlay = renderNotificationCenterDrawer(model, options, pagesById, notificationLayer?.title);
+                const notificationCenterOverlay = renderNotificationCenterDrawer(model, options, pagesById, notificationLayer?.title, themedFrameCtx);
                 if (notificationCenterOverlay != null) {
                     overlays.push(notificationCenterOverlay);
                 }
             }
             if (model.helpOpen) {
-                const helpOverlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
+                const helpSource = controlProjection.helpSource;
+                if (helpSource == null) {
+                    throw new Error('createFramedApp: help layer projection is missing a help source');
+                }
+                const helpOverlay = renderHelpOverlay(model, helpSource, options.i18n);
                 overlays.push(modal({
                     title: activeLayer.kind === 'help'
                         ? (activeLayer.title ?? frameMessage(options.i18n, 'help.title', 'Keyboard Help'))
@@ -1240,6 +1516,9 @@ export function createFramedApp(options) {
                     hint: typeof activeLayer.hintSource === 'string'
                         ? activeLayer.hintSource
                         : frameMessage(options.i18n, 'help.hint', 'j/k scroll • d/u page • g/G top/bottom • mouse wheel • ?/Esc close'),
+                    borderToken: themedFrameCtx?.border('primary'),
+                    bgToken: themedFrameCtx?.surface('elevated'),
+                    ctx: themedFrameCtx,
                     width: helpOverlay.body.width + 4,
                     screenWidth: model.columns,
                     screenHeight: model.rows,
@@ -1247,7 +1526,11 @@ export function createFramedApp(options) {
             }
             if (model.commandPalette != null) {
                 const paletteWidth = Math.max(20, Math.min(80, model.columns - 4));
-                const paletteBody = commandPalette(model.commandPalette, { width: Math.max(16, paletteWidth - 4) });
+                const paletteBody = commandPaletteSurface(model.commandPalette, {
+                    width: Math.max(16, paletteWidth - 4),
+                    ctx: themedFrameCtx,
+                    showScrollbar: false,
+                });
                 const paletteLayer = activeLayer.kind === 'search' || activeLayer.kind === 'command-palette'
                     ? activeLayer
                     : undefined;
@@ -1257,13 +1540,16 @@ export function createFramedApp(options) {
                     hint: typeof paletteLayer?.hintSource === 'string'
                         ? paletteLayer.hintSource
                         : frameMessage(options.i18n, 'palette.hint', 'Enter select • Esc close'),
+                    borderToken: themedFrameCtx?.border('primary'),
+                    bgToken: themedFrameCtx?.surface('elevated'),
+                    ctx: themedFrameCtx,
                     width: paletteWidth,
                     screenWidth: model.columns,
                     screenHeight: model.rows,
                 }));
             }
             if (model.quitConfirmOpen) {
-                overlays.push(renderShellQuitOverlay(model.columns, model.rows, options.i18n));
+                overlays.push(renderShellQuitOverlay(model.columns, model.rows, options.i18n, themedFrameCtx));
             }
             if (bodySurface != null && bodyRect.width > 0 && bodyRect.height > 0) {
                 frameSurface.blit(bodySurface, bodyRect.col, bodyRect.row);
@@ -1276,7 +1562,67 @@ export function createFramedApp(options) {
             return wrapFrameMsg({ type: 'runtime-issue', issue });
         },
     };
-    return app;
+    const framedApp = app;
+    let hostedRunActive = false;
+    framedApp.run = async (runOptions) => {
+        if (hostedRunActive) {
+            throw new Error('createFramedApp: concurrent app.run() calls on the same framed app are not supported');
+        }
+        hostedRunActive = true;
+        const previousFrameCtx = frameCtx;
+        const previousFrameCtxShellThemeId = frameCtxShellThemeId;
+        const previousDefaultFrameCtx = defaultFrameCtx;
+        const previousResolvedShellThemes = resolvedShellThemes;
+        const runtimeCtx = runOptions?.ctx;
+        if (runtimeCtx != null && options.ctx == null) {
+            useRunScopedFrameCtx = true;
+            frameCtx = runtimeCtx;
+            defaultFrameCtx = runtimeCtx;
+            resolvedShellThemes = [];
+            ensureResolvedShellThemes(runtimeCtx);
+            frameCtxShellThemeId = resolveShellThemeForContext(resolvedShellThemes, runtimeCtx)?.id;
+        }
+        const frameBudgetMs = resolveFrameBudgetMs(runOptions, resolveFrameCtx());
+        let pendingTimingSnapshot;
+        let needsTimingHydrationRender = true;
+        try {
+            await runWithLifecycleHooks(framedApp, {
+                ...runOptions,
+                mouse: runOptions?.mouse ?? true,
+            }, {
+                beforeRender(model) {
+                    if (pendingTimingSnapshot == null)
+                        return model;
+                    return applyFrameTimingSnapshot(model, pendingTimingSnapshot);
+                },
+                afterRender({ timings }) {
+                    pendingTimingSnapshot = summarizeFrameTimings(timings, frameBudgetMs);
+                    if (!needsTimingHydrationRender)
+                        return;
+                    needsTimingHydrationRender = false;
+                    return { requestRender: true };
+                },
+            });
+        }
+        finally {
+            hostedRunActive = false;
+            useRunScopedFrameCtx = false;
+            frameCtx = previousFrameCtx;
+            frameCtxShellThemeId = previousFrameCtxShellThemeId;
+            defaultFrameCtx = previousDefaultFrameCtx;
+            resolvedShellThemes = previousResolvedShellThemes;
+        }
+    };
+    return framedApp;
+}
+/**
+ * Create and immediately run a batteries-included framed shell.
+ *
+ * This is the one-call hosted path for users who want the frame to own the
+ * runtime pump while `run(app)` remains the low-level TEA contract.
+ */
+export async function runFramedApp(options, runOptions) {
+    await createFramedApp(options).run(runOptions);
 }
 function focusPane(model, paneId) {
     if (model.focusedPaneByPage[model.activePageId] === paneId)
@@ -1292,426 +1638,4 @@ function focusPane(model, paneId) {
 function resolveBodyRect(model, options) {
     return frameBodyRect(model.columns, model.rows, options.bodyTopRows ?? 1, options.bodyBottomRows ?? 1);
 }
-function renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById) {
-    const activePageModel = model.pageModels[model.activePageId];
-    const activeInputArea = findInputAreaByPaneId(resolveInputAreas(activePage, activePageModel), model.focusedPaneByPage[model.activePageId]);
-    const modalKeyMap = activePage.modalKeyMap?.(activePageModel);
-    const settings = resolveFrameSettings(model, options, pagesById);
-    const notificationCenter = resolveFrameNotificationCenter(model, options, pagesById);
-    const workspaceHintSource = options.helpLineSource?.({
-        model,
-        activePage,
-        frameKeys,
-        globalKeys: options.globalKeys,
-    });
-    const workspaceHelpSource = mergeBindingSources(frameKeys, quitHelpKeys, options.globalKeys, activeInputArea?.helpSource ?? activeInputArea?.keyMap, activePage.helpSource ?? activePage.keyMap);
-    const layerStack = describeFrameLayerStack(model, {
-        pageModalOpen: modalKeyMap != null,
-        layers: {
-            workspace: {
-                title: activePage.title,
-                hintSource: typeof workspaceHintSource === 'string'
-                    ? workspaceHintSource
-                    : workspaceHintSource ?? mergeBindingSources(frameKeys, options.globalKeys, activeInputArea?.helpSource ?? activeInputArea?.keyMap, activePage.helpSource ?? activePage.keyMap),
-                helpSource: workspaceHelpSource,
-            },
-            'page-modal': {
-                title: activePage.title,
-                hintSource: modalKeyMap ?? activePage.helpSource ?? activePage.keyMap,
-                helpSource: mergeBindingSources(quitHelpKeys, modalKeyMap, activePage.helpSource ?? activePage.keyMap),
-            },
-            settings: {
-                title: settings?.title ?? frameMessage(options.i18n, 'settings.title', 'Settings'),
-                hintSource: frameMessage(options.i18n, 'settings.footer', 'F2/Esc close • ↑/↓ rows • Enter toggle • / search • q quit'),
-                helpSource: mergeBindingSources(settingsHelpKeys, quitHelpKeys),
-            },
-            help: {
-                title: frameMessage(options.i18n, 'help.title', 'Keyboard Help'),
-                hintSource: frameMessage(options.i18n, 'help.hint', 'j/k scroll • d/u page • g/G top/bottom • mouse wheel • ?/Esc close'),
-                helpSource: helpLayerHelpKeys,
-            },
-            'notification-center': {
-                title: notificationCenter == null
-                    ? frameMessage(options.i18n, 'notifications.title', 'Notifications')
-                    : `${notificationCenter.title} • ${frameNotificationFilterLabel(options.i18n, notificationCenter.activeFilter)}`,
-                hintSource: frameMessage(options.i18n, 'notifications.footer', 'Shift+N close • f filter • j/k scroll • q quit'),
-                helpSource: mergeBindingSources(notificationCenterHelpKeys, quitHelpKeys),
-            },
-            search: {
-                title: model.commandPaletteTitle ?? activePage.searchTitle ?? frameMessage(options.i18n, 'search.title', 'Search'),
-                hintSource: frameMessage(options.i18n, 'palette.hint', 'Enter select • Esc close'),
-                helpSource: mergeBindingSources(paletteKeys, quitHelpKeys),
-            },
-            'command-palette': {
-                title: model.commandPaletteTitle ?? frameMessage(options.i18n, 'palette.title', 'Command Palette'),
-                hintSource: frameMessage(options.i18n, 'palette.hint', 'Enter select • Esc close'),
-                helpSource: mergeBindingSources(paletteKeys, quitHelpKeys),
-            },
-            'quit-confirm': {
-                title: frameMessage(options.i18n, 'quit.title', 'Quit?'),
-                hintSource: frameMessage(options.i18n, 'quit.footer', 'Y quit • N stay'),
-                helpSource: quitConfirmHelpKeys,
-            },
-        },
-    });
-    const beneathHelpLayer = layerStack.length > 1 ? layerStack[layerStack.length - 2] : undefined;
-    const source = beneathHelpLayer?.helpSource ?? workspaceHelpSource;
-    const maxDialogWidth = Math.max(28, Math.min(model.columns - 4, 88));
-    const bodyWidth = Math.max(20, maxDialogWidth - 4);
-    const helpSurface = helpViewSurface(source, {
-        title: undefined,
-        width: bodyWidth,
-    });
-    const pagerHeight = Math.max(4, Math.min(helpSurface.height + 1, Math.max(4, model.rows - 8)));
-    const pagerState = createPagerStateForSurface(helpSurface, {
-        width: bodyWidth,
-        height: pagerHeight,
-    });
-    const scrollY = Math.max(0, Math.min(model.helpScrollY, pagerState.scroll.maxY));
-    const scrolledState = {
-        ...pagerState,
-        scroll: {
-            ...pagerState.scroll,
-            y: scrollY,
-        },
-    };
-    return {
-        body: pagerSurface(helpSurface, scrolledState, { showScrollbar: true, showStatus: true }),
-        maxScrollY: pagerState.scroll.maxY,
-        scrollY,
-    };
-}
-function isHelpScrollAction(action) {
-    return action.type === 'scroll-up'
-        || action.type === 'scroll-down'
-        || action.type === 'page-up'
-        || action.type === 'page-down'
-        || action.type === 'top'
-        || action.type === 'bottom';
-}
-function resolveFrameSettings(model, options, pagesById) {
-    const activePage = pagesById.get(model.activePageId);
-    return options.settings?.({
-        model,
-        activePage,
-        pageModel: model.pageModels[model.activePageId],
-    });
-}
-function resolveFrameNotificationCenter(model, options, pagesById) {
-    const activePage = pagesById.get(model.activePageId);
-    const pageModel = model.pageModels[model.activePageId];
-    const provided = options.notificationCenter?.({
-        model,
-        activePage,
-        pageModel,
-        runtimeNotifications: model.runtimeNotifications,
-    });
-    if (provided != null) {
-        const filters = provided.filters != null && provided.filters.length > 0
-            ? provided.filters
-            : DEFAULT_NOTIFICATION_CENTER_FILTERS;
-        const activeFilter = filters.includes(provided.activeFilter ?? 'ALL')
-            ? (provided.activeFilter ?? 'ALL')
-            : filters[0];
-        return {
-            title: provided.title ?? frameMessage(options.i18n, 'notifications.title', 'Notifications'),
-            state: provided.state,
-            filters,
-            activeFilter,
-            onFilterChange: provided.onFilterChange,
-        };
-    }
-    if (options.runtimeNotifications === false)
-        return undefined;
-    return {
-        title: frameMessage(options.i18n, 'notifications.title', 'Notifications'),
-        state: model.runtimeNotifications,
-        filters: DEFAULT_NOTIFICATION_CENTER_FILTERS,
-        activeFilter: model.runtimeNotificationHistoryFilter,
-    };
-}
-function resolveSettingsLayout(model, options, pagesById) {
-    const settings = resolveFrameSettings(model, options, pagesById);
-    if (settings == null)
-        return undefined;
-    const sections = settings.sections.filter((section) => section.rows.length > 0);
-    if (sections.length === 0)
-        return undefined;
-    const drawerWidth = resolveSettingsDrawerWidth(model.columns);
-    const anchor = frameStartAnchor(options.i18n);
-    const startCol = anchor === 'left' ? 0 : Math.max(0, model.columns - drawerWidth);
-    const contentWidth = Math.max(16, drawerWidth - 4);
-    const preferenceSections = preparePreferenceSections(toPreferenceSections(sections));
-    const rows = [];
-    let line = 0;
-    for (let sectionIndex = 0; sectionIndex < preferenceSections.length; sectionIndex++) {
-        const section = preferenceSections[sectionIndex];
-        if (sectionIndex > 0) {
-            line += 1;
-        }
-        line += 1;
-        line += 1;
-        for (let rowIndex = 0; rowIndex < section.rows.length; rowIndex++) {
-            const preparedRow = section.rows[rowIndex];
-            const row = sections[sectionIndex].rows[rowIndex];
-            const rowLayout = resolvePreferenceRowLayout(preparedRow, contentWidth);
-            rows.push({
-                index: rows.length,
-                line,
-                height: rowLayout.height,
-                row,
-            });
-            line += rowLayout.height;
-            if (rowIndex < section.rows.length - 1) {
-                line += 1;
-            }
-        }
-    }
-    const contentHeight = Math.max(1, model.rows - 2);
-    const totalLines = Math.max(1, line);
-    const maxScrollY = Math.max(0, totalLines - contentHeight);
-    return {
-        settings: {
-            ...settings,
-            sections,
-        },
-        preferenceSections,
-        rows,
-        anchor,
-        startCol,
-        drawerWidth,
-        contentWidth,
-        contentHeight,
-        totalLines,
-        maxScrollY,
-    };
-}
-function resolveNotificationCenterDrawerWidth(columns) {
-    const boundedColumns = Math.max(28, columns);
-    return Math.min(Math.max(32, Math.floor(boundedColumns * 0.34)), Math.max(32, boundedColumns - 4), 52);
-}
-function resolveNotificationCenterLayout(model, options, pagesById) {
-    const center = resolveFrameNotificationCenter(model, options, pagesById);
-    if (center == null)
-        return undefined;
-    const drawerWidth = resolveNotificationCenterDrawerWidth(model.columns);
-    const anchor = frameEndAnchor(options.i18n);
-    const startCol = anchor === 'left' ? 0 : Math.max(0, model.columns - drawerWidth);
-    const contentWidth = Math.max(18, drawerWidth - 4);
-    const content = renderNotificationCenterSurface(center, contentWidth, options.i18n);
-    const contentHeight = Math.max(1, model.rows - 2);
-    const pagerState = createPagerStateForSurface(content, {
-        width: contentWidth,
-        height: contentHeight,
-    });
-    return {
-        center,
-        anchor,
-        startCol,
-        drawerWidth,
-        contentWidth,
-        contentHeight,
-        content,
-        maxScrollY: pagerState.scroll.maxY,
-    };
-}
-function resolveSettingsDrawerWidth(columns) {
-    const boundedColumns = Math.max(24, columns);
-    return Math.min(Math.max(28, Math.floor(boundedColumns * 0.3)), Math.max(28, boundedColumns - 4), 42);
-}
-function clampSettingsFocus(model, layout) {
-    if (layout.rows.length === 0)
-        return 0;
-    return Math.max(0, Math.min(model.settingsFocusIndex, layout.rows.length - 1));
-}
-function clampSettingsScroll(model, layout) {
-    return Math.max(0, Math.min(model.settingsScrollY, layout.maxScrollY));
-}
-function resolveInputAreas(page, pageModel) {
-    return page.inputAreas?.(pageModel) ?? [];
-}
-function findInputAreaByPaneId(inputAreas, paneId) {
-    if (paneId == null)
-        return undefined;
-    return inputAreas.find((area) => area.paneId === paneId);
-}
-function ensureSettingsRangeVisible(startLine, height, scrollY, visibleLines, maxScrollY) {
-    let next = scrollY;
-    const endLine = startLine + Math.max(1, height) - 1;
-    if (startLine < next) {
-        next = startLine;
-    }
-    else if (endLine >= next + visibleLines) {
-        next = endLine - visibleLines + 1;
-    }
-    return Math.max(0, Math.min(next, maxScrollY));
-}
-function moveSettingsFocus(model, layout, delta) {
-    if (layout.rows.length === 0)
-        return model;
-    const nextFocus = Math.max(0, Math.min(clampSettingsFocus(model, layout) + delta, layout.rows.length - 1));
-    const focusedRow = layout.rows[nextFocus];
-    return {
-        ...model,
-        settingsFocusIndex: nextFocus,
-        settingsScrollY: ensureSettingsRangeVisible(focusedRow.line, focusedRow.height, clampSettingsScroll(model, layout), layout.contentHeight, layout.maxScrollY),
-    };
-}
-function scrollSettingsBy(model, layout, delta) {
-    return {
-        ...model,
-        settingsScrollY: Math.max(0, Math.min(clampSettingsScroll(model, layout) + delta, layout.maxScrollY)),
-    };
-}
-function scrollNotificationCenterBy(model, layout, delta) {
-    return {
-        ...model,
-        notificationCenterScrollY: Math.max(0, Math.min(model.notificationCenterScrollY + delta, layout.maxScrollY)),
-    };
-}
-function cycleNotificationCenterFilter(model, layout) {
-    const filters = layout.center.filters;
-    if (filters.length < 2)
-        return [model, []];
-    const currentIndex = Math.max(0, filters.indexOf(layout.center.activeFilter));
-    const nextFilter = filters[(currentIndex + 1) % filters.length];
-    if (layout.center.onFilterChange != null) {
-        const action = layout.center.onFilterChange(nextFilter);
-        return [{
-                ...model,
-                notificationCenterScrollY: 0,
-            }, action === undefined ? [] : [emitMsgForPage(model.activePageId, action)]];
-    }
-    return [{
-            ...model,
-            runtimeNotificationHistoryFilter: nextFilter,
-            notificationCenterScrollY: 0,
-        }, []];
-}
-function renderSettingsDrawer(model, options, pagesById, titleOverride) {
-    const layout = resolveSettingsLayout(model, options, pagesById);
-    if (layout == null)
-        return undefined;
-    const scrollY = clampSettingsScroll(model, layout);
-    const content = renderSettingsSurface(layout, model);
-    const pagerState = createPagerStateForSurface(content, {
-        width: layout.contentWidth,
-        height: layout.contentHeight,
-    });
-    const scrolledState = {
-        ...pagerState,
-        scroll: {
-            ...pagerState.scroll,
-            y: scrollY,
-        },
-    };
-    const body = pagerSurface(content, scrolledState, {
-        showScrollbar: layout.maxScrollY > 0,
-        showStatus: false,
-    });
-    return drawer({
-        anchor: layout.anchor,
-        title: titleOverride ?? layout.settings.title ?? frameMessage(options.i18n, 'settings.title', 'Settings'),
-        content: body,
-        borderToken: layout.settings.borderToken,
-        bgToken: layout.settings.bgToken,
-        ctx: resolveSafeCtx() ?? undefined,
-        width: layout.drawerWidth,
-        screenWidth: model.columns,
-        screenHeight: model.rows,
-    });
-}
-function renderNotificationCenterDrawer(model, options, pagesById, titleOverride) {
-    const layout = resolveNotificationCenterLayout(model, options, pagesById);
-    if (layout == null)
-        return undefined;
-    const pagerState = createPagerStateForSurface(layout.content, {
-        width: layout.contentWidth,
-        height: layout.contentHeight,
-    });
-    const scrolledState = {
-        ...pagerState,
-        scroll: {
-            ...pagerState.scroll,
-            y: Math.max(0, Math.min(model.notificationCenterScrollY, layout.maxScrollY)),
-        },
-    };
-    const body = pagerSurface(layout.content, scrolledState, {
-        showScrollbar: layout.maxScrollY > 0,
-        showStatus: false,
-    });
-    return drawer({
-        anchor: layout.anchor,
-        title: titleOverride ?? `${layout.center.title} • ${frameNotificationFilterLabel(options.i18n, layout.center.activeFilter)}`,
-        content: body,
-        width: layout.drawerWidth,
-        screenWidth: model.columns,
-        screenHeight: model.rows,
-    });
-}
-function renderSettingsSurface(layout, model) {
-    const focusedIndex = clampSettingsFocus(model, layout);
-    return preferenceListSurface(layout.preferenceSections, {
-        width: layout.contentWidth,
-        selectedRowId: layout.rows[focusedIndex]?.row.id,
-        ctx: resolveSafeCtx() ?? undefined,
-        theme: layout.settings.listTheme,
-    });
-}
-function toPreferenceSections(sections) {
-    return sections.map((section) => ({
-        id: section.id,
-        title: section.title,
-        rows: section.rows.map((row) => toPreferenceRow(row)),
-    }));
-}
-function toPreferenceRow(row) {
-    return {
-        id: row.id,
-        label: row.label,
-        description: row.description,
-        valueLabel: row.valueLabel,
-        kind: row.kind,
-        checked: row.checked,
-        enabled: row.enabled,
-    };
-}
-function resolveNotificationFooterCue(model, options, pagesById) {
-    const center = resolveFrameNotificationCenter(model, options, pagesById);
-    if (center == null)
-        return undefined;
-    const liveCount = center.state.items.length;
-    const archivedCount = countNotificationHistory(center.state, center.activeFilter);
-    return frameNotificationCue(options.i18n, liveCount, archivedCount);
-}
-function renderNotificationCenterSurface(center, width, i18n) {
-    const ctx = resolveSafeCtx() ?? undefined;
-    const rows = [
-        insetLineSurface(`Live: ${center.state.items.length} • Archived: ${center.state.history.length}`, width),
-        insetLineSurface(`Filter: ${frameNotificationFilterLabel(i18n, center.activeFilter)}`, width),
-    ];
-    const liveItems = [...center.state.items].sort((left, right) => right.updatedAtMs - left.updatedAtMs || right.id - left.id);
-    if (liveItems.length > 0) {
-        rows.push(createSurface(width, 1));
-        rows.push(insetLineSurface(ctx == null ? 'Current stack' : ctx.style.bold('Current stack'), width));
-        rows.push(createSurface(width, 1));
-        for (let index = 0; index < liveItems.length; index++) {
-            rows.push(renderNotificationReviewEntrySurface(liveItems[index], {
-                width,
-                ctx,
-                metaLabel: `${liveItems[index].variant} • live`,
-            }));
-            if (index < liveItems.length - 1)
-                rows.push(createSurface(width, 1));
-        }
-    }
-    rows.push(createSurface(width, 1));
-    rows.push(renderNotificationHistorySurface(center.state, {
-        width,
-        height: Number.MAX_SAFE_INTEGER,
-        filter: center.activeFilter,
-        ctx,
-    }));
-    return vstackSurface(...rows);
-}
 //# sourceMappingURL=app-frame.js.map