@flyingrobots/bijou-tui 4.2.0 → 4.4.1

package/dist/app-frame.js

@@ -4,14 +4,14 @@
  * 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 { cloneContextWithResolvedTheme, createResolved, createSurface, setDefaultContext, preparePreferenceSections, preferenceListSurface, resolvePreferenceRowLayout, resolveClock, resolveSafeCtx, } from '@flyingrobots/bijou';
 import { helpViewSurface } from './help.js';
 import { createKeyMap } from './keybindings.js';
 import { isKeyMsg, isMouseMsg, isResizeMsg } from './types.js';
 import { quit } from './commands.js';
 import { compositeSurfaceInto, drawer, modal } from './overlay.js';
 import { isShellQuitConfirmAccept, isShellQuitConfirmDismiss, isShellQuitRequest, renderShellQuitOverlay, shouldUseShellQuitConfirm, } from './shell-quit.js';
-import { commandPalette, commandPaletteKeyMap, } from './command-palette.js';
+import { 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';
@@ -22,7 +22,7 @@ import { createFrameKeyMap, frameBodyRect, mergeBindingSources, } from './app-fr
 import { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, } from './app-frame-layers.js';
 import { applyRuntimeCommandBuffer, bufferRuntimeRouteResult, createRuntimeBuffers, createRuntimeRetainedLayouts, retainRuntimeLayout, routeRuntimeInput, } from './runtime-engine.js';
 import { frameEndAnchor, frameMessage, frameNotificationCue, frameNotificationFilterLabel, frameStartAnchor, } from './app-frame-i18n.js';
-import { resolveHeaderLine, renderHelpLine, renderPageContent, renderPageContentInto, renderMaximizedPane, renderMaximizedPaneInto, renderTransition, } from './app-frame-render.js';
+import { resolveHeaderLine, renderHelpLine, renderPageContent, renderPageContentInto, renderMaximizedPane, renderMaximizedPaneInto, renderTransition, createFramePaneScratchPool, } from './app-frame-render.js';
 import { applyFrameAction, scrollFocusedPane, switchTab, syncPageFrameState, } from './app-frame-actions.js';
 import { handlePaletteKey, openCommandPalette, openSearchPalette, } from './app-frame-palette.js';
 export { activeFrameLayer, describeFrameLayerStack, describeFrameRuntimeViewStack, underlyingFrameLayer, } from './app-frame-layers.js';
@@ -134,6 +134,81 @@ 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 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 }),
+        },
+    };
+    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)),
+        };
+    }
+    return {
+        ...settings,
+        sections: [
+            { id: 'shell', title: shellSectionTitle, rows: [row] },
+            ...settings.sections,
+        ],
+    };
+}
 // Factory
 // ---------------------------------------------------------------------------
 /**
@@ -155,13 +230,65 @@ 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 usesAmbientDefaultContext = options.ctx == null && defaultFrameCtx != null;
+    let frameCtx = options.ctx;
+    let frameCtxShellThemeId = resolveShellThemeForContext(resolvedShellThemes, frameCtx)?.id;
+    function resolveFrameCtx() {
+        return frameCtx ?? options.ctx ?? resolveSafeCtx();
+    }
+    function resolveFrameThemeCtx(activeShellThemeId) {
+        const baseCtx = resolveFrameCtx();
+        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) {
+        if (defaultFrameCtx == null)
+            return resolveFrameCtx();
+        frameCtx = cloneShellThemeContext(defaultFrameCtx, nextTheme.resolvedTheme);
+        frameCtxShellThemeId = nextTheme.id;
+        if (usesAmbientDefaultContext) {
+            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 frameNotificationOptions = resolveFrameNotificationOptions(options);
     let composedFrameScratch = null;
+    let headerScratch;
+    let helpLineScratch;
+    const paneScratchPool = createFramePaneScratchPool();
     const paletteKeys = commandPaletteKeyMap({
         focusNext: { type: 'cp-next' },
         focusPrev: { type: 'cp-prev' },
@@ -218,30 +345,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;
             }
@@ -252,18 +384,18 @@ 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);
@@ -274,7 +406,7 @@ export function createFramedApp(options) {
         'help-scroll': (model, cmd) => {
             const c = cmd;
             const activePage = pagesById.get(model.activePageId);
-            const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById);
+            const overlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById, resolvedShellThemes);
             const viewportHeight = Math.max(1, overlay.body.height - 1);
             const delta = c.action === 'down' ? 3
                 : c.action === 'up' ? -3
@@ -334,7 +466,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;
@@ -433,7 +565,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' };
@@ -486,7 +618,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];
@@ -494,7 +629,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' };
@@ -648,13 +783,15 @@ export function createFramedApp(options) {
         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)
-            : renderPageContent(model.activePageId, model, bodyRect, pagesById);
+            ? 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);
+        const header = resolveHeaderLine(model, options, pagesById, headerScratch, resolveFrameThemeCtx(model.activeShellThemeId));
+        headerScratch = header.surface;
         const tabChildren = header.tabTargets.map((target) => createShellRetainedLayoutNode(`tab:${target.pageId}`, {
             row: 0,
             col: target.startCol,
@@ -694,7 +831,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',
@@ -706,7 +845,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',
@@ -786,7 +927,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 });
@@ -868,7 +1009,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) {
-        const settings = resolveFrameSettings(model, options, pagesById);
+        const settings = resolveFrameSettings(model, options, pagesById, resolvedShellThemes);
         const notificationCenter = resolveFrameNotificationCenter(model, options, pagesById);
         const workspaceHintSource = resolveWorkspaceHintSource(model, activePage, activeInputArea);
         const workspaceHelpSource = resolveWorkspaceHelpSource(activePage, activeInputArea);
@@ -978,19 +1119,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,
@@ -1001,9 +1138,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 = {};
@@ -1040,7 +1196,11 @@ export function createFramedApp(options) {
                 runtimeNotifications: createNotificationState(),
                 runtimeNotificationHistoryFilter: 'ALL',
                 runtimeNotificationLoopActive: false,
+                activeShellThemeId: initialShellTheme?.id,
             };
+            if (initialShellTheme != null) {
+                publishShellThemeContext(initialShellTheme);
+            }
             for (const pageId of pageOrder) {
                 model = syncPageFrameState(model, pageId, pagesById);
             }
@@ -1155,14 +1315,20 @@ export function createFramedApp(options) {
             return updateTargetPage(model, model.activePageId, msg);
         },
         view(model) {
+            const themedFrameCtx = resolveFrameThemeCtx(model.activeShellThemeId);
             const { activePage, layerStack, activeLayer, } = resolvePresentedLayerContext(model);
-            const header = resolveHeaderLine(model, options, pagesById).surface;
-            const helpLine = renderHelpLine(model, activeLayer, options.i18n, resolveNotificationFooterCue(model, options, pagesById));
+            const headerResult = resolveHeaderLine(model, options, pagesById, headerScratch, themedFrameCtx);
+            headerScratch = headerResult.surface;
+            const header = headerResult.surface;
+            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
             const maxState = model.maximizedPaneByPage[model.activePageId];
             const maximizedPaneId = maxState?.maximizedPaneId;
             const frameSurface = getComposedFrameScratch(model.columns, model.rows);
+            // clear() is load-bearing: it resets dim flags left by overlay compositing
+            // on the previous frame. Do not skip or defer this call.
             frameSurface.clear();
             frameSurface.blit(header, 0, 0);
             if (model.rows > 1) {
@@ -1173,20 +1339,20 @@ 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)
-                    : 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)
-                    : renderPageContentInto(model.activePageId, model, bodyRect, pagesById, frameSurface);
+                    ? 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);
             }
             const overlays = [];
             if (options.overlayFactory != null) {
@@ -1198,7 +1364,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,
@@ -1209,20 +1375,20 @@ 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 helpOverlay = renderHelpOverlay(model, activePage, frameKeys, paletteKeys, options, pagesById, resolvedShellThemes);
                 overlays.push(modal({
                     title: activeLayer.kind === 'help'
                         ? (activeLayer.title ?? frameMessage(options.i18n, 'help.title', 'Keyboard Help'))
@@ -1231,6 +1397,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,
@@ -1238,7 +1407,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;
@@ -1248,13 +1421,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);
@@ -1283,11 +1459,11 @@ 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) {
+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);
+    const settings = resolveFrameSettings(model, options, pagesById, shellThemes);
     const notificationCenter = resolveFrameNotificationCenter(model, options, pagesById);
     const workspaceHintSource = options.helpLineSource?.({
         model,
@@ -1380,13 +1556,15 @@ function isHelpScrollAction(action) {
         || action.type === 'top'
         || action.type === 'bottom';
 }
-function resolveFrameSettings(model, options, pagesById) {
+const FRAME_SHELL_THEME_ROW_ID = '__frame-shell-theme__';
+function resolveFrameSettings(model, options, pagesById, shellThemes) {
     const activePage = pagesById.get(model.activePageId);
-    return options.settings?.({
+    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);
@@ -1421,8 +1599,8 @@ function resolveFrameNotificationCenter(model, options, pagesById) {
         activeFilter: model.runtimeNotificationHistoryFilter,
     };
 }
-function resolveSettingsLayout(model, options, pagesById) {
-    const settings = resolveFrameSettings(model, options, pagesById);
+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);
@@ -1451,6 +1629,7 @@ function resolveSettingsLayout(model, options, pagesById) {
                 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) {
@@ -1481,7 +1660,7 @@ 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) {
+function resolveNotificationCenterLayout(model, options, pagesById, ctx) {
     const center = resolveFrameNotificationCenter(model, options, pagesById);
     if (center == null)
         return undefined;
@@ -1489,7 +1668,7 @@ function resolveNotificationCenterLayout(model, options, pagesById) {
     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 content = renderNotificationCenterSurface(center, contentWidth, options.i18n, ctx);
     const contentHeight = Math.max(1, model.rows - 2);
     const pagerState = createPagerStateForSurface(content, {
         width: contentWidth,
@@ -1579,12 +1758,12 @@ function cycleNotificationCenterFilter(model, layout) {
             notificationCenterScrollY: 0,
         }, []];
 }
-function renderSettingsDrawer(model, options, pagesById, titleOverride) {
-    const layout = resolveSettingsLayout(model, options, pagesById);
+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);
+    const content = renderSettingsSurface(layout, model, ctx);
     const pagerState = createPagerStateForSurface(content, {
         width: layout.contentWidth,
         height: layout.contentHeight,
@@ -1606,14 +1785,14 @@ function renderSettingsDrawer(model, options, pagesById, titleOverride) {
         content: body,
         borderToken: layout.settings.borderToken,
         bgToken: layout.settings.bgToken,
-        ctx: resolveSafeCtx() ?? undefined,
+        ctx,
         width: layout.drawerWidth,
         screenWidth: model.columns,
         screenHeight: model.rows,
     });
 }
-function renderNotificationCenterDrawer(model, options, pagesById, titleOverride) {
-    const layout = resolveNotificationCenterLayout(model, options, pagesById);
+function renderNotificationCenterDrawer(model, options, pagesById, titleOverride, ctx) {
+    const layout = resolveNotificationCenterLayout(model, options, pagesById, ctx);
     if (layout == null)
         return undefined;
     const pagerState = createPagerStateForSurface(layout.content, {
@@ -1635,17 +1814,20 @@ function renderNotificationCenterDrawer(model, options, pagesById, titleOverride
         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) {
+function renderSettingsSurface(layout, model, ctx) {
     const focusedIndex = clampSettingsFocus(model, layout);
     return preferenceListSurface(layout.preferenceSections, {
         width: layout.contentWidth,
         selectedRowId: layout.rows[focusedIndex]?.row.id,
-        ctx: resolveSafeCtx() ?? undefined,
+        ctx,
         theme: layout.settings.listTheme,
     });
 }
@@ -1675,8 +1857,7 @@ function resolveNotificationFooterCue(model, options, pagesById) {
     const archivedCount = countNotificationHistory(center.state, center.activeFilter);
     return frameNotificationCue(options.i18n, liveCount, archivedCount);
 }
-function renderNotificationCenterSurface(center, width, i18n) {
-    const ctx = resolveSafeCtx() ?? undefined;
+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),