@flyingrobots/bijou-tui 5.0.0 → 7.1.0

package/dist/app-frame.js

@@ -4,7 +4,7 @@
  * Provides tabs, pane focus/scroll isolation, shell key handling, help,
  * panel-scoped overlay context, and optional frame-level command palette.
  */
-import { cloneContextWithResolvedTheme, createResolved, createSurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
+import { cloneContextWithResolvedTheme, createSurface, perfOverlaySurface, setDefaultContext, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
 import { createKeyMap, formatKeyCombo } from './keybindings.js';
 import { isKeyMsg, isMouseMsg, isResizeMsg } from './types.js';
 import { quit } from './commands.js';
@@ -15,14 +15,15 @@ import { commandPaletteSurface, commandPaletteKeyMap, } from './command-palette.
 import { restoreLayoutState } from './layout-preset.js';
 import { createNotificationState, dismissNotification, hitTestNotificationStack, notificationsNeedTick, pushNotification, renderNotificationStack, tickNotifications, trimNotificationsToViewport, } from './notification.js';
 import { isFrameScopedMsg, isPageScopedMsg, wrapCmdForPage, emitMsg, emitMsgForPage, wrapFrameMsg, } from './app-frame-types.js';
-import { createFrameKeyMap, frameBodyRect, mergeBindingSources, } 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 { createFrameKeyMap, frameBodyRect, mergeBindingSources, resolveFramePageText, } from './app-frame-utils.js';
+import { renderHelpOverlay, isHelpScrollAction, resolveFrameShellThemeChoices, 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 { frameMessage, frameNotificationFilterLabel, } from './app-frame-i18n.js';
 import { resolveHeaderLine, renderHelpLine, renderPageContent, renderPageContentInto, renderMaximizedPane, renderMaximizedPaneInto, renderTransition, createFramePaneScratchPool, } from './app-frame-render.js';
 import { applyFrameAction, scrollFocusedPane, switchTab, syncPageFrameState, } from './app-frame-actions.js';
 import { handlePaletteKey, openCommandPalette, openSearchPalette, } from './app-frame-palette.js';
+import { createInputActionMap, createInputGestureRecognizer, } from './input-map.js';
 export { emitFrameAction, notify, } from './app-frame-types.js';
 export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, projectFrameControls, underlyingFrameLayer, } from './app-frame-layers.js';
 // ---------------------------------------------------------------------------
@@ -31,6 +32,7 @@ export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStac
 const FRAME_NOTIFICATION_TICK_MS = 40;
 const DEFAULT_FRAME_NOTIFICATION_DURATION_MS = 6_000;
 const SETTINGS_FEEDBACK_TOAST_WIDTH = 40;
+const FRAME_FOOTER_DOUBLE_TAB_MS = 300;
 const EMPTY_RUNTIME_LAYOUTS = createRuntimeRetainedLayouts();
 function createQuitHelpKeys(i18n) {
     const t = (id, fallback) => frameMessage(i18n, id, fallback);
@@ -146,7 +148,7 @@ function cloneShellThemeContext(ctx, resolvedTheme) {
 function readStageDuration(timings, stage) {
     return timings.find((timing) => timing.stage === stage)?.durationMs ?? 0;
 }
-function summarizeFrameTimings(timings, frameBudgetMs) {
+export function summarizeFrameTimings(timings, frameBudgetMs) {
     const frameTimeMs = timings.reduce((total, timing) => total + timing.durationMs, 0);
     return {
         frameTimeMs,
@@ -156,6 +158,36 @@ function summarizeFrameTimings(timings, frameBudgetMs) {
         frameOverBudget: frameBudgetMs != null && frameTimeMs > frameBudgetMs,
     };
 }
+export function renderFramePerfHudOverlay(telemetry, options = {}) {
+    const refreshRate = telemetry.refreshRate ?? options.ctx?.runtime.refreshRate ?? 60;
+    const fps = telemetry.frameTimeMs > 0
+        ? Math.min(refreshRate, 1000 / telemetry.frameTimeMs)
+        : refreshRate;
+    const width = Math.max(12, Math.min(40, telemetry.columns - 2));
+    const surface = perfOverlaySurface({
+        fps,
+        frameTimeMs: telemetry.frameTimeMs,
+        width: telemetry.columns,
+        height: telemetry.rows,
+        extras: [
+            { label: 'view', value: `${telemetry.viewTimeMs.toFixed(2)} ms` },
+            { label: 'diff', value: `${telemetry.diffTimeMs.toFixed(2)} ms` },
+        ],
+    }, {
+        title: frameMessage(options.i18n, 'perfHud.title', 'Perf HUD'),
+        width,
+        showChart: false,
+        borderToken: options.ctx?.border('primary'),
+        bgToken: options.ctx?.surface('elevated'),
+        ctx: options.ctx,
+    });
+    return {
+        content: '',
+        surface,
+        row: 1,
+        col: Math.max(0, telemetry.columns - surface.width - 1),
+    };
+}
 function applyFrameTimingSnapshot(model, snapshot) {
     if (model.frameTimeMs === snapshot.frameTimeMs
         && model.viewTimeMs === snapshot.viewTimeMs
@@ -206,7 +238,8 @@ export function createFramedApp(options) {
     const shellThemeSpecs = options.shellThemes ?? [];
     let defaultFrameCtx = options.ctx ?? resolveSafeCtx();
     let resolvedShellThemes = [];
-    const enableShellThemeSettings = shellThemeSpecs.length > 1;
+    const enableShellThemeSettings = shellThemeSpecs.length > 1
+        || shellThemeSpecs.some((theme) => (theme.modes?.length ?? 0) > 1);
     const usesAmbientDefaultContext = options.ctx == null && defaultFrameCtx != null;
     let frameCtx = options.ctx;
     let frameCtxShellThemeId;
@@ -219,13 +252,7 @@ export function createFramedApp(options) {
             throw new Error('createFramedApp: shellThemes requires options.ctx, app.run({ ctx }), or a default Bijou context');
         }
         defaultFrameCtx ??= baseCtx;
-        resolvedShellThemes = shellThemeSpecs.map((theme) => ({
-            id: theme.id,
-            label: theme.label,
-            description: theme.description,
-            shellTheme: theme,
-            resolvedTheme: createResolved(theme.theme, defaultFrameCtx.theme.noColor, defaultFrameCtx.theme.colorScheme),
-        }));
+        resolvedShellThemes = resolveFrameShellThemeChoices(shellThemeSpecs, defaultFrameCtx);
     }
     if (frameCtx != null) {
         ensureResolvedShellThemes(frameCtx);
@@ -261,6 +288,11 @@ export function createFramedApp(options) {
         }
         options.onShellThemeChange?.({
             shellTheme: nextTheme.shellTheme,
+            shellThemeSpec: nextTheme.shellThemeSpec,
+            shellThemeId: nextTheme.shellThemeId,
+            shellThemeLabel: nextTheme.shellThemeLabel,
+            modeId: nextTheme.modeId,
+            modeLabel: nextTheme.modeLabel,
             ctx: frameCtx,
         });
         return frameCtx;
@@ -270,6 +302,13 @@ 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);
@@ -553,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' }];
@@ -584,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) {
@@ -595,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'
@@ -633,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 }];
         }
@@ -685,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' } }];
         }
@@ -772,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) };
             }
@@ -788,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' }] };
                 }
@@ -799,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) {
@@ -1101,21 +1181,22 @@ 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: activePage.title,
+            title: activePageTitle,
             hintSource: workspaceHintSource,
             helpSource: workspaceHelpSource,
             ...pageLayers?.workspace,
         };
         const pageModalLayer = {
-            title: activePage.title,
+            title: activePageTitle,
             hintSource: modalKeyMap ?? activePage.helpSource ?? activePage.keyMap,
             helpSource: mergeBindingSources(quitHelpKeys, modalKeyMap, activePage.helpSource ?? activePage.keyMap),
             ...pageLayers?.['page-modal'],
@@ -1270,7 +1351,11 @@ export function createFramedApp(options) {
                 diffTimeMs: 0,
                 frameBudgetMs: undefined,
                 frameOverBudget: false,
+                perfHudOpen: false,
                 helpOpen: false,
+                footerVisible: true,
+                footerTranslateY: 0,
+                footerAnimationGeneration: 0,
                 helpScrollY: 0,
                 commandPaletteKind: undefined,
                 settingsOpen: false,
@@ -1446,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;
@@ -1551,10 +1641,24 @@ 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({
+                    columns: model.columns,
+                    rows: model.rows,
+                    frameTimeMs: model.frameTimeMs,
+                    viewTimeMs: model.viewTimeMs,
+                    diffTimeMs: model.diffTimeMs,
+                    refreshRate: themedFrameCtx?.runtime.refreshRate,
+                }, {
+                    i18n: options.i18n,
+                    ctx: themedFrameCtx,
+                }));
+            }
             if (bodySurface != null && bodyRect.width > 0 && bodyRect.height > 0) {
                 frameSurface.blit(bodySurface, bodyRect.col, bodyRect.row);
             }
-            return compositeSurfaceInto(frameSurface, frameSurface, overlays, { dim: overlays.length > 0 });
+            return compositeSurfaceInto(frameSurface, frameSurface, overlays, { dim: dimBackground });
         },
         routeRuntimeIssue(issue) {
             if (!frameNotificationOptions.enabled)