@flyingrobots/bijou-tui 4.4.1 → 7.0.0

package/dist/app-frame.js

@@ -4,101 +4,109 @@
  * Provides tabs, pane focus/scroll isolation, shell key handling, help,
  * panel-scoped overlay context, and optional frame-level command palette.
  */
-import { cloneContextWithResolvedTheme, createResolved, createSurface, setDefaultContext, preparePreferenceSections, preferenceListSurface, resolvePreferenceRowLayout, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
-import { helpViewSurface } from './help.js';
-import { createKeyMap } from './keybindings.js';
+import { cloneContextWithResolvedTheme, createResolved, createSurface, perfOverlaySurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
+import { createKeyMap, formatKeyCombo } from './keybindings.js';
 import { isKeyMsg, isMouseMsg, isResizeMsg } from './types.js';
 import { quit } from './commands.js';
-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 { commandPaletteSurface, commandPaletteKeyMap, } from './command-palette.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 { 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 { createFrameKeyMap, frameBodyRect, mergeBindingSources, resolveFramePageText, } from './app-frame-utils.js';
+import { renderHelpOverlay, isHelpScrollAction, resolveCurrentShellTheme, resolveNextShellTheme, resolveShellThemeForContext, resolveFrameSettings, resolveFrameNotificationCenter, resolveSettingsLayout, resolveNotificationCenterLayout, resolveInputAreas, findInputAreaByPaneId, moveSettingsFocus, scrollSettingsBy, clampSettingsScroll, scrollNotificationCenterBy, cycleNotificationCenterFilter, clampSettingsFocus, renderSettingsDrawer, renderNotificationCenterDrawer, resolveNotificationFooterCue, } from './app-frame-overlays.js';
+import { 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';
+import { createInputActionMap, createInputGestureRecognizer, } from './input-map.js';
+export { emitFrameAction, notify, } from './app-frame-types.js';
+export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, projectFrameControls, 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 FRAME_FOOTER_DOUBLE_TAB_MS = 300;
 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 {
@@ -137,78 +145,45 @@ function createFrameNotificationTickCmd() {
 function cloneShellThemeContext(ctx, resolvedTheme) {
     return cloneContextWithResolvedTheme(ctx, resolvedTheme);
 }
-function resolveShellThemeOptionsText(shellThemes, i18n) {
-    const labels = shellThemes.map((theme) => theme.label);
-    if (labels.length === 0)
-        return '';
-    if (i18n == null)
-        return labels.join(', ');
-    return i18n.formatList(labels, i18n.locale);
-}
-function resolveCurrentShellTheme(shellThemes, activeShellThemeId) {
-    return shellThemes.find((theme) => theme.id === activeShellThemeId) ?? shellThemes[0];
-}
-function resolveNextShellTheme(shellThemes, activeShellThemeId) {
-    if (shellThemes.length === 0)
-        return undefined;
-    const currentIndex = Math.max(0, shellThemes.findIndex((theme) => theme.id === activeShellThemeId));
-    return shellThemes[(currentIndex + 1) % shellThemes.length];
+function readStageDuration(timings, stage) {
+    return timings.find((timing) => timing.stage === stage)?.durationMs ?? 0;
 }
-function resolveShellThemeForContext(shellThemes, ctx) {
-    if (ctx == null)
-        return undefined;
-    return shellThemes.find((theme) => theme.resolvedTheme.theme === ctx.theme.theme);
-}
-function mergeShellThemeSettings(settings, shellThemes, activeShellThemeId, i18n) {
-    if (shellThemes.length < 2)
-        return settings;
-    const currentTheme = resolveCurrentShellTheme(shellThemes, activeShellThemeId);
-    const nextTheme = resolveNextShellTheme(shellThemes, activeShellThemeId);
-    if (currentTheme == null || nextTheme == null)
-        return settings;
-    const row = {
-        id: FRAME_SHELL_THEME_ROW_ID,
-        label: frameMessage(i18n, 'settings.shellTheme.label', 'Shell theme'),
-        description: currentTheme.description ?? frameMessage(i18n, 'settings.shellTheme.description', 'Current theme: {theme}. Options: {options}.', {
-            theme: currentTheme.label,
-            options: resolveShellThemeOptionsText(shellThemes, i18n),
-        }),
-        valueLabel: currentTheme.label,
-        kind: 'choice',
-        feedback: {
-            title: frameMessage(i18n, 'settings.title', 'Settings'),
-            message: frameMessage(i18n, 'settings.shellTheme.feedback', 'Shell theme set to {theme}.', { theme: nextTheme.label }),
-        },
+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,
     };
-    const shellSectionTitle = frameMessage(i18n, 'settings.section.shell', 'Shell');
-    if (settings == null) {
-        return {
-            title: frameMessage(i18n, 'settings.title', 'Settings'),
-            sections: [{ id: 'shell', title: shellSectionTitle, rows: [row] }],
-        };
-    }
-    const shellSectionIndex = settings.sections.findIndex((section) => section.id === 'shell');
-    if (shellSectionIndex >= 0) {
-        const shellSection = settings.sections[shellSectionIndex];
-        const existingRowIndex = shellSection.rows.findIndex((existingRow) => existingRow.id === FRAME_SHELL_THEME_ROW_ID);
-        const nextRows = existingRowIndex >= 0
-            ? shellSection.rows.map((existingRow, index) => (index === existingRowIndex ? row : existingRow))
-            : [...shellSection.rows, row];
-        return {
-            ...settings,
-            sections: settings.sections.map((section, index) => (index === shellSectionIndex
-                ? { ...shellSection, rows: nextRows }
-                : section)),
-        };
+}
+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 {
-        ...settings,
-        sections: [
-            { id: 'shell', title: shellSectionTitle, rows: [row] },
-            ...settings.sections,
-        ],
+        ...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
 // ---------------------------------------------------------------------------
 /**
@@ -230,28 +205,40 @@ export function createFramedApp(options) {
     if (!pagesById.has(defaultPageId)) {
         throw new Error(`createFramedApp: defaultPageId "${defaultPageId}" not found in pages`);
     }
-    const defaultFrameCtx = options.ctx ?? resolveSafeCtx();
-    if (options.shellThemes != null && options.shellThemes.length > 0 && defaultFrameCtx == null) {
-        throw new Error('createFramedApp: shellThemes requires options.ctx or a default Bijou context');
-    }
-    const resolvedShellThemes = options.shellThemes?.map((theme) => ({
-        id: theme.id,
-        label: theme.label,
-        description: theme.description,
-        shellTheme: theme,
-        resolvedTheme: createResolved(theme.theme, defaultFrameCtx.theme.noColor, defaultFrameCtx.theme.colorScheme),
-    })) ?? [];
-    const enableShellThemeSettings = resolvedShellThemes.length > 1;
-    const initialShellTheme = resolveShellThemeForContext(resolvedShellThemes, defaultFrameCtx)
-        ?? resolvedShellThemes[0];
+    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 = resolveShellThemeForContext(resolvedShellThemes, frameCtx)?.id;
+    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);
@@ -266,11 +253,12 @@ export function createFramedApp(options) {
         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) {
+        if (usesAmbientDefaultContext && !useRunScopedFrameCtx) {
             setDefaultContext(frameCtx);
         }
         options.onShellThemeChange?.({
@@ -284,11 +272,24 @@ export function createFramedApp(options) {
         enableNotifications: options.notificationCenter != null || options.runtimeNotifications !== false,
         i18n: options.i18n,
     });
+    const frameInputRecognizer = createInputGestureRecognizer({
+        doubleTapMs: FRAME_FOOTER_DOUBLE_TAB_MS,
+    });
+    const frameInputActions = createInputActionMap()
+        .bind('frame.footer.doubleTab', 'Toggle footer', [
+        { deviceId: 'keyboard', featureId: 'key.tab', type: 'double-tap' },
+    ], { type: 'toggle-footer' });
+    const quitHelpKeys = createQuitHelpKeys(options.i18n);
+    const helpLayerHelpKeys = createHelpLayerHelpKeys(options.i18n);
+    const settingsHelpKeys = createSettingsHelpKeys(options.i18n);
+    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' },
@@ -297,6 +298,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
@@ -305,6 +349,36 @@ export function createFramedApp(options) {
         }
         return composedFrameScratch;
     }
+    function renderFramePerfHudOverlay(model, ctx) {
+        const refreshRate = ctx?.runtime.refreshRate ?? 60;
+        const fps = model.frameTimeMs > 0
+            ? Math.min(refreshRate, 1000 / model.frameTimeMs)
+            : refreshRate;
+        const width = Math.max(12, Math.min(40, model.columns - 2));
+        const surface = perfOverlaySurface({
+            fps,
+            frameTimeMs: model.frameTimeMs,
+            width: model.columns,
+            height: model.rows,
+            extras: [
+                { label: 'view', value: `${model.viewTimeMs.toFixed(2)} ms` },
+                { label: 'diff', value: `${model.diffTimeMs.toFixed(2)} ms` },
+            ],
+        }, {
+            title: frameMessage(options.i18n, 'perfHud.title', 'Perf HUD'),
+            width,
+            showChart: false,
+            borderToken: ctx?.border('primary'),
+            bgToken: ctx?.surface('elevated'),
+            ctx,
+        });
+        return {
+            content: '',
+            surface,
+            row: 1,
+            col: Math.max(0, model.columns - surface.width - 1),
+        };
+    }
     function closeCommandPalette(model) {
         return {
             ...model,
@@ -402,11 +476,18 @@ export function createFramedApp(options) {
             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, resolvedShellThemes);
+            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
@@ -511,6 +592,23 @@ export function createFramedApp(options) {
         }
         return [{ type: 'observed-key', msg, route }, { type: 'open-quit-confirm' }];
     }
+    function resolveFrameInputActionCommands(msg, route) {
+        const inputEvent = frameInputRecognizer.observeKey(msg, resolveClock(resolveFrameCtx()).now());
+        const inputAction = frameInputActions.handle(inputEvent);
+        if (inputAction == null || msg.ctrl || msg.alt || msg.shift) {
+            return undefined;
+        }
+        return [{ type: 'observed-key', msg, route }, { type: 'apply-frame-action', action: inputAction }];
+    }
+    function routeForFrameInputAction(layerKind) {
+        if (layerKind === 'search' || layerKind === 'command-palette')
+            return 'palette';
+        if (layerKind === 'help')
+            return 'help';
+        if (layerKind === 'page-modal')
+            return 'page';
+        return 'frame';
+    }
     function resolveFrameActionCommands(msg, action, route) {
         if (action.type === 'open-search' && options.enableCommandPalette) {
             return [{ type: 'observed-key', msg, route }, { type: 'open-search-palette' }];
@@ -542,6 +640,9 @@ export function createFramedApp(options) {
         if (frameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'close-palette' }, { type: 'apply-frame-action', action: frameAction }];
         }
+        if (frameAction?.type === 'toggle-perf-hud') {
+            return [obs, { type: 'apply-frame-action', action: frameAction }];
+        }
         return [obs, { type: 'palette-key', msg }];
     }
     function handleHelpLayerKeyCommands(msg) {
@@ -553,6 +654,9 @@ export function createFramedApp(options) {
             return quitRequestCommands(msg, 'help');
         }
         const helpAction = frameKeys.handle(msg);
+        if (helpAction?.type === 'toggle-perf-hud') {
+            return [obs, { type: 'apply-frame-action', action: helpAction }];
+        }
         if (helpAction && isHelpScrollAction(helpAction)) {
             const action = helpAction.type === 'scroll-down' ? 'down'
                 : helpAction.type === 'scroll-up' ? 'up'
@@ -591,6 +695,9 @@ export function createFramedApp(options) {
         if (settingsFrameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'apply-frame-action', action: settingsFrameAction }];
         }
+        if (settingsFrameAction?.type === 'toggle-perf-hud') {
+            return [obs, { type: 'apply-frame-action', action: settingsFrameAction }];
+        }
         if (!msg.ctrl && !msg.alt && msg.key === 'up') {
             return [obs, { type: 'settings-focus-move', delta: -1 }];
         }
@@ -643,6 +750,9 @@ export function createFramedApp(options) {
         if (centerFrameAction?.type === 'toggle-notifications') {
             return [obs, { type: 'apply-frame-action', action: centerFrameAction }];
         }
+        if (centerFrameAction?.type === 'toggle-perf-hud') {
+            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' } }];
         }
@@ -706,7 +816,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 }];
@@ -728,6 +840,10 @@ export function createFramedApp(options) {
             const frameLayer = layer.model;
             if (frameLayer == null)
                 return undefined;
+            const inputActionCommands = resolveFrameInputActionCommands(msg, routeForFrameInputAction(frameLayer.kind));
+            if (inputActionCommands != null) {
+                return { handled: true, commands: inputActionCommands };
+            }
             if (frameLayer.kind === 'search' || frameLayer.kind === 'command-palette') {
                 return { handled: true, commands: handlePaletteLayerKeyCommands(msg, frameLayer.kind) };
             }
@@ -744,6 +860,10 @@ export function createFramedApp(options) {
             }
             if (frameLayer.kind === 'quit-confirm') {
                 const obs = { type: 'observed-key', msg, route: 'frame' };
+                const frameAction = frameKeys.handle(msg);
+                if (frameAction?.type === 'toggle-perf-hud') {
+                    return { handled: true, commands: [obs, { type: 'apply-frame-action', action: frameAction }] };
+                }
                 if (isShellQuitConfirmAccept(msg)) {
                     return { handled: true, commands: [obs, { type: 'close-quit-confirm' }, { type: 'quit' }] };
                 }
@@ -755,6 +875,10 @@ export function createFramedApp(options) {
             if (frameLayer.kind === 'page-modal') {
                 const { modalKeyMap } = context;
                 const obs = { type: 'observed-key', msg, route: 'page' };
+                const frameAction = frameKeys.handle(msg);
+                if (frameAction?.type === 'toggle-perf-hud') {
+                    return { handled: true, commands: [obs, { type: 'apply-frame-action', action: frameAction }] };
+                }
                 if (modalKeyMap != null) {
                     const modalAction = modalKeyMap.handle(msg);
                     if (modalAction !== undefined) {
@@ -779,27 +903,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 themedFrameCtx = resolveFrameThemeCtx(model.activeShellThemeId);
-        const renderResult = maximizedPaneId
-            ? renderMaximizedPane(model.activePageId, model, bodyRect, pagesById, maximizedPaneId, paneScratchPool, themedFrameCtx)
-            : renderPageContent(model.activePageId, model, bodyRect, pagesById, themedFrameCtx);
-        return renderResult.paneRects;
-    }
-    function buildWorkspaceLayoutTree(model) {
-        const header = resolveHeaderLine(model, options, pagesById, headerScratch, resolveFrameThemeCtx(model.activeShellThemeId));
-        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));
@@ -809,6 +921,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;
@@ -1008,7 +1169,7 @@ export function createFramedApp(options) {
         }
         return helpLineOverride ?? mergeBindingSources(frameKeys, options.globalKeys, activeInputArea?.helpSource ?? activeInputArea?.keyMap, activePage.helpSource ?? activePage.keyMap);
     }
-    function resolveLayerMetadata(model, activePage, activeInputArea, modalKeyMap) {
+    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);
@@ -1020,23 +1181,29 @@ export function createFramedApp(options) {
         const quitHint = frameMessage(options.i18n, 'quit.footer', 'Y quit • N stay');
         const paletteTitle = model.commandPaletteTitle
             ?? frameMessage(options.i18n, 'palette.title', 'Command Palette');
+        const activePageTitle = resolveFramePageText(activePage.title, activePageModel) ?? '';
         const searchTitle = model.commandPaletteTitle
-            ?? activePage.searchTitle
+            ?? resolveFramePageText(activePage.searchTitle, activePageModel)
             ?? frameMessage(options.i18n, 'search.title', 'Search');
         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: activePageTitle,
+            hintSource: workspaceHintSource,
+            helpSource: workspaceHelpSource,
+            ...pageLayers?.workspace,
+        };
+        const pageModalLayer = {
+            title: activePageTitle,
+            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,
@@ -1071,12 +1238,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,
@@ -1084,9 +1250,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) {
@@ -1173,11 +1341,21 @@ 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,
+                perfHudOpen: false,
                 helpOpen: false,
+                footerVisible: true,
+                footerTranslateY: 0,
+                footerAnimationGeneration: 0,
                 helpScrollY: 0,
                 commandPaletteKind: undefined,
                 settingsOpen: false,
@@ -1196,6 +1374,13 @@ 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) {
@@ -1236,6 +1421,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);
@@ -1316,7 +1515,7 @@ export function createFramedApp(options) {
         },
         view(model) {
             const themedFrameCtx = resolveFrameThemeCtx(model.activeShellThemeId);
-            const { activePage, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
+            const { controlProjection, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
             const headerResult = resolveHeaderLine(model, options, pagesById, headerScratch, themedFrameCtx);
             headerScratch = headerResult.surface;
             const header = headerResult.surface;
@@ -1332,7 +1531,12 @@ export function createFramedApp(options) {
             frameSurface.clear();
             frameSurface.blit(header, 0, 0);
             if (model.rows > 1) {
-                frameSurface.blit(helpLine, 0, model.rows - 1);
+                const footerVisible = model.footerVisible ?? true;
+                const footerTranslateY = Math.max(0, Math.min(1, model.footerTranslateY ?? (footerVisible ? 0 : 1)));
+                const footerRow = model.rows - helpLine.height + Math.floor(footerTranslateY * helpLine.height);
+                if (footerRow < model.rows) {
+                    frameSurface.blit(helpLine, 0, footerRow);
+                }
             }
             let activeResult;
             let bodySurface;
@@ -1354,6 +1558,7 @@ export function createFramedApp(options) {
                     ? 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({
@@ -1388,7 +1593,11 @@ export function createFramedApp(options) {
                 }
             }
             if (model.helpOpen) {
-                const helpOverlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById, resolvedShellThemes);
+                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'))
@@ -1432,10 +1641,14 @@ export function createFramedApp(options) {
             if (model.quitConfirmOpen) {
                 overlays.push(renderShellQuitOverlay(model.columns, model.rows, options.i18n, themedFrameCtx));
             }
+            const dimBackground = overlays.length > 0;
+            if (model.perfHudOpen) {
+                overlays.push(renderFramePerfHudOverlay(model, themedFrameCtx));
+            }
             if (bodySurface != null && bodyRect.width > 0 && bodyRect.height > 0) {
                 frameSurface.blit(bodySurface, bodyRect.col, bodyRect.row);
             }
-            return compositeSurfaceInto(frameSurface, frameSurface, overlays, { dim: overlays.length > 0 });
+            return compositeSurfaceInto(frameSurface, frameSurface, overlays, { dim: dimBackground });
         },
         routeRuntimeIssue(issue) {
             if (!frameNotificationOptions.enabled)
@@ -1443,7 +1656,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)
@@ -1459,431 +1732,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, shellThemes) {
-    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, shellThemes);
-    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';
-}
-const FRAME_SHELL_THEME_ROW_ID = '__frame-shell-theme__';
-function resolveFrameSettings(model, options, pagesById, shellThemes) {
-    const activePage = pagesById.get(model.activePageId);
-    const provided = options.settings?.({
-        model,
-        activePage,
-        pageModel: model.pageModels[model.activePageId],
-    });
-    return mergeShellThemeSettings(provided, shellThemes, model.activeShellThemeId, options.i18n);
-}
-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, shellThemes) {
-    const settings = resolveFrameSettings(model, options, pagesById, shellThemes);
-    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,
-                behavior: row.id === FRAME_SHELL_THEME_ROW_ID ? 'cycle-shell-theme' : undefined,
-            });
-            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, ctx) {
-    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, ctx);
-    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, shellThemes, titleOverride, ctx) {
-    const layout = resolveSettingsLayout(model, options, pagesById, shellThemes);
-    if (layout == null)
-        return undefined;
-    const scrollY = clampSettingsScroll(model, layout);
-    const content = renderSettingsSurface(layout, model, ctx);
-    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,
-        width: layout.drawerWidth,
-        screenWidth: model.columns,
-        screenHeight: model.rows,
-    });
-}
-function renderNotificationCenterDrawer(model, options, pagesById, titleOverride, ctx) {
-    const layout = resolveNotificationCenterLayout(model, options, pagesById, ctx);
-    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,
-        borderToken: ctx?.border('primary'),
-        bgToken: ctx?.surface('elevated'),
-        ctx,
-        width: layout.drawerWidth,
-        screenWidth: model.columns,
-        screenHeight: model.rows,
-    });
-}
-function renderSettingsSurface(layout, model, ctx) {
-    const focusedIndex = clampSettingsFocus(model, layout);
-    return preferenceListSurface(layout.preferenceSections, {
-        width: layout.contentWidth,
-        selectedRowId: layout.rows[focusedIndex]?.row.id,
-        ctx,
-        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, ctx) {
-    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