@elizaos/ui 2.0.3-beta.2 → 2.0.3-beta.4

package/App.js

@@ -2,12 +2,14 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 /**
  * Root App component — routing shell.
  */
+import { isViewVisible, } from "@elizaos/core";
 import { X } from "lucide-react";
 import "./components/chat/chat-source-registration.js";
 import { lazy, Suspense, useCallback, useEffect, useMemo, useState, useSyncExternalStore, } from "react";
 import { createNavigateViewHandler, } from "./app-navigate-view.js";
+import { AppBackground } from "./backgrounds/AppBackground.js";
 import { invokeDesktopBridgeRequest, subscribeDesktopBridgeEvent, } from "./bridge/electrobun-rpc.js";
-import { NAVIGATE_SETTINGS_EVENT, useSlashCommandController, } from "./chat/useSlashCommandController.js";
+import { NAVIGATE_SETTINGS_EVENT, reportUserViewSwitch, useSlashCommandController, } from "./chat/useSlashCommandController.js";
 import { getOverlayAppLazyComponent } from "./components/apps/AppWindowRenderer.helpers.js";
 import { GameViewOverlay } from "./components/apps/GameViewOverlay.js";
 import { getOverlayApp } from "./components/apps/overlay-app-registry.js";
@@ -21,7 +23,6 @@ import { SecretsManagerModalRoot } from "./components/settings/SecretsManagerSec
 import { ActionBanner } from "./components/shell/ActionBanner.js";
 import { AssistantOverlay } from "./components/shell/AssistantOverlay.js";
 import { BugReportModal } from "./components/shell/BugReportModal.js";
-import { ChatAmbientBackground } from "./components/shell/ChatAmbientBackground.js";
 import { ChatSurface } from "./components/shell/ChatSurface.js";
 import { CloudHandoffBanner } from "./components/shell/CloudHandoffBanner.js";
 import { ConnectionFailedBanner } from "./components/shell/ConnectionFailedBanner.js";
@@ -29,6 +30,7 @@ import { ConnectionLostOverlay } from "./components/shell/ConnectionLostOverlay.
 import { ContinuousChatOverlay } from "./components/shell/ContinuousChatOverlay.js";
 import { HomePill } from "./components/shell/HomePill.js";
 import { HomeScreen } from "./components/shell/HomeScreen.js";
+import { HomeSpringboardSurface } from "./components/shell/HomeSpringboardSurface.js";
 import { KioskViewCanvas } from "./components/shell/KioskViewCanvas.js";
 import { NotificationCenter } from "./components/shell/NotificationCenter.js";
 import { ShellControllerProvider } from "./components/shell/ShellControllerContext.js";
@@ -46,12 +48,13 @@ import { CompactOnboarding } from "./first-run/CompactOnboarding.js";
 import { BugReportProvider, useBugReportState, useContextMenu } from "./hooks/index.js";
 import { useAuthStatus } from "./hooks/useAuthStatus.js";
 import { useSecretsManagerShortcut } from "./hooks/useSecretsManagerShortcut.js";
-import { APPS_ENABLED, getAppSlugFromPath, getWindowNavigationPath, isAndroidPhoneSurfaceEnabled, isAospShellEnabled, isRouteRootPath, shouldUseHashNavigation, } from "./navigation/index.js";
+import { APPS_ENABLED, getAppSlugFromPath, getWindowNavigationPath, isAndroidPhoneSurfaceEnabled, isAospShellEnabled, isRouteRootPath, pathForTab, shouldUseHashNavigation, TAB_PATHS, tabFromPath, } from "./navigation/index.js";
 import { isIOS, isNative } from "./platform/init.js";
 import { RetainedLazyComponent } from "./retained-lazy.js";
-import { useApp } from "./state/index.js";
+import { useAppSelector, useAppSelectorShallow, } from "./state/index.js";
 import { isShellPaintable } from "./state/startup-coordinator.js";
 import { VoiceSelfTestShell } from "./voice/voice-selftest/VoiceSelfTestShell.js";
+import { VoiceWorkbenchShell } from "./voice/voice-selftest/VoiceWorkbenchShell.js";
 const MOBILE_NAV_PADDING_CLASS = "pb-[calc(var(--eliza-mobile-nav-offset,0px)+var(--safe-area-bottom,0px)+var(--eliza-continuous-chat-clearance,5.25rem))]";
 // Single source of truth for the lazy route-view chunk loaders. Each
 // lazyNamedView() call registers its import() thunk here so prefetch (below)
@@ -82,12 +85,13 @@ import { getAppShellPageRegistrySnapshot, listAppShellPages, subscribeAppShellPa
 // remaining page views are lazy-split below.
 import { CharacterEditor } from "./components/character/CharacterEditor.js";
 import { DesktopTabBar } from "./components/desktop/DesktopTabBar.js";
+import { SpringboardSurface } from "./components/pages/SpringboardSurface.js";
 import { FineTuningView } from "./components/training/injected.js";
 import { DynamicViewLoader } from "./components/views/DynamicViewLoader.js";
-import { useAvailableViews, } from "./hooks/useAvailableViews.js";
+import { useAvailableViews, useRoutableViews, } from "./hooks/useAvailableViews.js";
 import { useDesktopTabs } from "./hooks/useDesktopTabs.js";
-import { useIsDeveloperMode } from "./state/useDeveloperMode.js";
-const ViewCatalog = lazyNamedView(() => import("./components/pages/ViewCatalog.js"), "ViewCatalog");
+import { useEnabledViewKinds } from "./state/useViewKinds.js";
+const BackgroundView = lazyNamedView(() => import("./components/pages/BackgroundView.js"), "BackgroundView");
 const AutomationsFeed = lazyNamedView(() => import("./components/pages/AutomationsFeed.js"), "AutomationsFeed");
 const BrowserWorkspaceView = lazyNamedView(() => import("./components/pages/BrowserWorkspaceView.js"), "BrowserWorkspaceView");
 const TranscriptsPageView = lazyNamedView(() => import("./components/transcripts/TranscriptsPage.js"), "TranscriptsPage");
@@ -104,6 +108,7 @@ const StreamView = lazyNamedView(() => import("./components/pages/StreamView.js"
 // inside the LazyViewBoundary Suspense below, and none is imported statically
 // elsewhere in the app graph, so the dynamic boundary actually defers load.
 const DatabasePageView = lazyNamedView(() => import("./components/pages/DatabasePageView.js"), "DatabasePageView");
+const FilesView = lazyNamedView(() => import("./components/pages/FilesView.js"), "FilesView");
 const LogsView = lazyNamedView(() => import("./components/pages/LogsView.js"), "LogsView");
 const MemoryViewerView = lazyNamedView(() => import("./components/pages/MemoryViewerView.js"), "MemoryViewerView");
 const PluginsPageView = lazyNamedView(() => import("./components/pages/PluginsPageView.js"), "PluginsPageView");
@@ -200,6 +205,8 @@ function readShellMode() {
         return "onboarding-overlay";
     if (raw === "voice-selftest")
         return "voice-selftest";
+    if (raw === "voice-workbench")
+        return "voice-workbench";
     if (raw === "launcher")
         return "launcher";
     if (raw === "kiosk")
@@ -242,8 +249,8 @@ function KioskShell() {
 function TabScrollView({ children, className = "", }) {
     return (_jsx(AppWorkspaceChrome, { testId: "tab-scroll-view", main: _jsx("div", { "data-shell-scroll-region": "true", className: `eliza-continuous-chat-scroll flex-1 min-h-0 min-w-0 w-full overflow-y-auto pb-[var(--eliza-continuous-chat-clearance,5.25rem)] ${className}`, children: children }) }));
 }
-function TabContentView({ children }) {
-    return (_jsx(AppWorkspaceChrome, { testId: "tab-content-view", main: _jsx("div", { "data-shell-content-region": "true", className: "eliza-continuous-chat-scroll flex flex-col flex-1 min-h-0 min-w-0 w-full overflow-hidden pb-[var(--eliza-continuous-chat-clearance,5.25rem)]", children: children }) }));
+function TabContentView({ children, surface = "opaque", }) {
+    return (_jsx(AppWorkspaceChrome, { testId: "tab-content-view", surface: surface, main: _jsx("div", { "data-shell-content-region": "true", className: "eliza-continuous-chat-scroll flex flex-col flex-1 min-h-0 min-w-0 w-full overflow-hidden pb-[var(--eliza-continuous-chat-clearance,5.25rem)]", children: children }) }));
 }
 function useAppShellPageRegistryVersion() {
     return useSyncExternalStore(subscribeAppShellPages, getAppShellPageRegistrySnapshot, getAppShellPageRegistrySnapshot);
@@ -254,7 +261,7 @@ function useAppShellPageRegistryVersion() {
  * `app.navTabs` declaration. Returns `null` when no plugin claims the tab.
  */
 function useResolvedDynamicPage(tab) {
-    const { plugins } = useApp();
+    const plugins = useAppSelector((s) => s.plugins);
     const registryVersion = useAppShellPageRegistryVersion();
     return useMemo(() => {
         void registryVersion;
@@ -265,6 +272,8 @@ function useResolvedDynamicPage(tab) {
                 id: registered.id,
                 pluginId: registered.pluginId,
                 developerOnly: registered.developerOnly === true,
+                viewKind: registered.viewKind,
+                backgroundPolicy: registered.backgroundPolicy,
                 registration: registered,
             };
         }
@@ -280,6 +289,9 @@ function useResolvedDynamicPage(tab) {
                     id: navTab.id,
                     pluginId: plugin.id,
                     developerOnly: plugin.app?.developerOnly === true || navTab.developerOnly === true,
+                    // A nav tab's own kind wins; otherwise inherit the app's kind.
+                    viewKind: navTab.viewKind ?? plugin.app?.viewKind,
+                    backgroundPolicy: navTab.backgroundPolicy,
                     registration: reg,
                     componentExport: navTab.componentExport,
                 };
@@ -347,8 +359,8 @@ function WalletInventoryPage() {
     }
     return _jsx(RegisteredAppShellPage, { registration: registration });
 }
-function visibleDynamicPage(page, developerModeEnabled) {
-    return Boolean(page && (developerModeEnabled || !page.developerOnly));
+function visibleDynamicPage(page, enabledKinds) {
+    return Boolean(page && isViewVisible(page, enabledKinds));
 }
 /**
  * Whether the active app-shell page wants to render edge-to-edge with no host
@@ -363,6 +375,79 @@ function useTabIsFullBleed(tab) {
         return listAppShellPages().some((entry) => entry.id === tab && entry.fullBleed === true);
     }, [registryVersion, tab]);
 }
+function useCurrentNavigationPath() {
+    const [navigationPath, setNavigationPath] = useState(() => typeof window === "undefined" ? "/" : getWindowNavigationPath());
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const handleNavigationChange = () => {
+            setNavigationPath(getWindowNavigationPath());
+        };
+        window.addEventListener("hashchange", handleNavigationChange);
+        window.addEventListener("popstate", handleNavigationChange);
+        return () => {
+            window.removeEventListener("hashchange", handleNavigationChange);
+            window.removeEventListener("popstate", handleNavigationChange);
+        };
+    }, []);
+    return navigationPath;
+}
+function normalizeBackgroundPolicy(policy) {
+    return policy === "shared" ? "shared" : "opaque";
+}
+function builtinRouteBackgroundPolicy(tab, navigationPath) {
+    const normalizedPath = trimmedNavigationPath(navigationPath);
+    if (tab === "chat" || tab === "background")
+        return "shared";
+    if (tab === "settings" || tab === "voice")
+        return "shared";
+    if (tab === "views" && normalizedPath === "/views")
+        return "shared";
+    if (tab === "apps" && normalizedPath === "/apps")
+        return "shared";
+    return null;
+}
+function resolveActiveScreenBackgroundPolicy({ tab, navigationPath, availableViews, viewLayout, }) {
+    if (viewLayout)
+        return "opaque";
+    const appShellPageForRoute = findAppShellPageForRoute(navigationPath);
+    if (appShellPageForRoute) {
+        return normalizeBackgroundPolicy(appShellPageForRoute.backgroundPolicy);
+    }
+    const appSlug = tab === "apps" || tab === "views"
+        ? getAppSlugFromPath(navigationPath)
+        : null;
+    const remoteView = findRemoteViewForRoute(availableViews, navigationPath, tab, appSlug);
+    if (remoteView)
+        return normalizeBackgroundPolicy(remoteView.backgroundPolicy);
+    const appShellPageForTab = listAppShellPages().find((entry) => entry.id === tab);
+    if (appShellPageForTab) {
+        return normalizeBackgroundPolicy(appShellPageForTab.backgroundPolicy);
+    }
+    const builtinPolicy = builtinRouteBackgroundPolicy(tab, navigationPath);
+    if (builtinPolicy)
+        return builtinPolicy;
+    const registeredView = availableViews.find((view) => view.builtin !== true &&
+        (view.id === tab ||
+            view.path === navigationPath ||
+            view.path === trimmedNavigationPath(navigationPath)));
+    if (registeredView) {
+        return normalizeBackgroundPolicy(registeredView.backgroundPolicy);
+    }
+    return "opaque";
+}
+function useActiveScreenBackgroundPolicy({ tab, navigationPath, availableViews, viewLayout, }) {
+    const registryVersion = useAppShellPageRegistryVersion();
+    return useMemo(() => {
+        void registryVersion;
+        return resolveActiveScreenBackgroundPolicy({
+            tab,
+            navigationPath,
+            availableViews,
+            viewLayout,
+        });
+    }, [availableViews, navigationPath, registryVersion, tab, viewLayout]);
+}
 function trimmedNavigationPath(navigationPath) {
     return navigationPath.length > 1 && navigationPath.endsWith("/")
         ? navigationPath.slice(0, -1)
@@ -385,6 +470,7 @@ function remoteViewMatchesTab(view, tab, appSlug) {
 const SHELL_RESERVED_PATHS = new Set([
     "/views",
     "/apps",
+    "/character/documents",
     "/apps/plugins",
     "/apps/skills",
     "/apps/trajectories",
@@ -395,10 +481,14 @@ const SHELL_RESERVED_PATHS = new Set([
     "/apps/logs",
     "/apps/tasks",
 ]);
+const SHELL_RESERVED_TABS = new Set(Object.keys(TAB_PATHS));
 function findRemoteViewForRoute(views, navigationPath, tab, appSlug) {
     const normalizedPath = trimmedNavigationPath(navigationPath);
     if (SHELL_RESERVED_PATHS.has(normalizedPath))
         return undefined;
+    if (tab !== "views" && tab !== "apps" && SHELL_RESERVED_TABS.has(tab)) {
+        return undefined;
+    }
     return (views.find((view) => remoteViewAvailable(view) && view.path === normalizedPath) ??
         views.find((view) => remoteViewAvailable(view) && remoteViewMatchesTab(view, tab, appSlug)));
 }
@@ -407,6 +497,10 @@ function renderRemoteView(view) {
         return null;
     return (_jsx(TabContentView, { children: _jsx(DynamicViewLoader, { bundleUrl: view.bundleUrl, componentExport: view.componentExport, viewId: view.id, viewType: view.viewType }) }));
 }
+function findAppShellPageForRoute(navigationPath) {
+    const normalizedPath = trimmedNavigationPath(navigationPath);
+    return listAppShellPages().find((entry) => trimmedNavigationPath(entry.path) === normalizedPath);
+}
 function viewLayoutLabel(layout) {
     return layout.mode === "split" ? "Split view" : "Tiled views";
 }
@@ -431,16 +525,26 @@ function ViewLayoutSurface({ availableViews, layout, onClear, }) {
         .map((viewId) => availableViews.find((view) => view.id === viewId))
         .filter((view) => Boolean(view));
     const paneClassName = "flex min-h-[18rem] min-w-0 flex-col overflow-hidden border border-border/45 bg-bg";
-    return (_jsx(TabContentView, { children: _jsxs("section", { "data-testid": "view-layout-surface", className: "flex h-full min-h-0 min-w-0 flex-1 flex-col bg-bg", children: [_jsxs("header", { className: "flex min-h-12 shrink-0 items-center justify-between gap-3 border-b border-border/45 px-3", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("span", { className: "truncate text-sm font-medium text-txt", children: viewLayoutLabel(layout) }), _jsx("span", { className: "shrink-0 text-xs tabular-nums text-muted", children: entries.length })] }), _jsx("button", { type: "button", "aria-label": "Close layout", title: "Close layout", "data-testid": "view-layout-close", onClick: onClear, className: "inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-sm text-muted transition-colors hover:bg-border/35 hover:text-txt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2", children: _jsx(X, { className: "h-4 w-4", "aria-hidden": true }) })] }), _jsx("div", { className: `grid min-h-0 flex-1 gap-2 overflow-auto p-2 ${viewLayoutGridClass(layout, entries.length)} eliza-continuous-chat-scroll pb-[calc(0.5rem+var(--eliza-continuous-chat-clearance,5.25rem))]`, children: entries.length > 0 ? (entries.map((view) => (_jsxs("section", { "data-testid": `view-layout-pane-${view.id}`, className: paneClassName, children: [_jsx("div", { className: "flex h-9 shrink-0 items-center border-b border-border/35 px-2.5", children: _jsx("span", { className: "truncate text-xs font-medium text-muted", children: view.label }) }), _jsx("div", { className: "min-h-0 min-w-0 flex-1 overflow-hidden", children: view.bundleUrl ? (_jsx(DynamicViewLoader, { bundleUrl: view.bundleUrl, componentExport: view.componentExport, viewId: view.id, viewType: view.viewType })) : (_jsxs("div", { className: "flex h-full min-h-0 items-center justify-center px-4 text-center text-sm text-muted", children: [view.label, " is not available as a dynamic view."] })) })] }, view.id)))) : (_jsx("div", { className: "flex min-h-[18rem] items-center justify-center border border-border/45 px-4 text-center text-sm text-muted", children: "Requested views are not available." })) })] }) }));
+    const routeOverrideForView = (view) => {
+        const navigationPath = view.path ??
+            (SHELL_RESERVED_TABS.has(view.id)
+                ? pathForTab(view.id)
+                : `/apps/${view.id}`);
+        return {
+            navigationPath,
+            tab: tabFromPath(navigationPath) ?? view.id,
+        };
+    };
+    return (_jsx(TabContentView, { children: _jsxs("section", { "data-testid": "view-layout-surface", className: "flex h-full min-h-0 min-w-0 flex-1 flex-col bg-bg", children: [_jsxs("header", { className: "flex min-h-12 shrink-0 items-center justify-between gap-3 border-b border-border/45 px-3", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("span", { className: "truncate text-sm font-medium text-txt", children: viewLayoutLabel(layout) }), _jsx("span", { className: "shrink-0 text-xs tabular-nums text-muted", children: entries.length })] }), _jsx("button", { type: "button", "aria-label": "Close layout", title: "Close layout", "data-testid": "view-layout-close", onClick: onClear, className: "inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-sm text-muted transition-colors hover:bg-border/35 hover:text-txt    ", children: _jsx(X, { className: "h-4 w-4", "aria-hidden": true }) })] }), _jsx("div", { className: `grid min-h-0 flex-1 gap-2 overflow-auto p-2 ${viewLayoutGridClass(layout, entries.length)} eliza-continuous-chat-scroll pb-[calc(0.5rem+var(--eliza-continuous-chat-clearance,5.25rem))]`, children: entries.length > 0 ? (entries.map((view) => (_jsxs("section", { "data-testid": `view-layout-pane-${view.id}`, className: paneClassName, children: [_jsx("div", { className: "flex h-9 shrink-0 items-center border-b border-border/35 px-2.5", children: _jsx("span", { className: "truncate text-xs font-medium text-muted", children: view.label }) }), _jsx("div", { className: "min-h-0 min-w-0 flex-1 overflow-hidden", children: view.bundleUrl ? (_jsx(DynamicViewLoader, { bundleUrl: view.bundleUrl, componentExport: view.componentExport, viewId: view.id, viewType: view.viewType })) : (_jsx(ViewRouter, { routeOverride: routeOverrideForView(view) })) })] }, view.id)))) : (_jsx("div", { className: "flex min-h-[18rem] items-center justify-center border border-border/45 px-4 text-center text-sm text-muted", children: "Requested views are not available." })) })] }) }));
 }
 /**
  * Fallback shown when a view/tab is unavailable. Chat is the always-present
  * ContinuousChatOverlay that floats over every view — views never embed an
- * inline ChatView — so an unavailable view falls back to the app/view
- * launcher, not a chat surface.
+ * inline ChatView — so an unavailable view falls back to the Springboard page
+ * of the retained Home/Springboard surface, not a chat surface.
  */
 function ViewUnavailableFallback() {
-    return (_jsx(TabContentView, { children: _jsx(ViewCatalog, {}) }));
+    return _jsx(HomeScreenMount, { initialPage: "springboard" });
 }
 function renderPhoneSurface(enabled, Component) {
     return enabled ? (_jsx(TabContentView, { children: _jsx(Component, {}) })) : (_jsx(ViewUnavailableFallback, {}));
@@ -448,7 +552,10 @@ function renderPhoneSurface(enabled, Component) {
 function renderAppsSurface(navigationPath) {
     if (!APPS_ENABLED)
         return _jsx(ViewUnavailableFallback, {});
-    return (_jsx(TabContentView, { children: getAppSlugFromPath(navigationPath) ? _jsx(AppsPageView, {}) : _jsx(ViewCatalog, {}) }));
+    if (!getAppSlugFromPath(navigationPath)) {
+        return _jsx(HomeScreenMount, { initialPage: "springboard" });
+    }
+    return (_jsx(TabContentView, { children: _jsx(AppsPageView, {}) }));
 }
 function renderStaticViewRouterTab({ tab, androidPhoneSurfaceEnabled, navigationPath, settingsInitialSection, }) {
     const directViews = {
@@ -462,14 +569,15 @@ function renderStaticViewRouterTab({ tab, androidPhoneSurfaceEnabled, navigation
         tasks: (_jsx(TabContentView, { children: _jsx(TasksPageView, {}) })),
         automations: _jsx(AutomationsFeed, {}),
         triggers: _jsx(AutomationsFeed, {}),
-        voice: (_jsx(TabContentView, { children: _jsx(SettingsView, { initialSection: "identity" }, "settings-identity") })),
-        settings: (_jsx(TabContentView, { children: _jsx(SettingsView, { initialSection: settingsInitialSection ?? undefined }, "settings-root") })),
+        voice: (_jsx(TabContentView, { surface: "transparent", children: _jsx(SettingsView, { initialSection: "identity" }, "settings-identity") })),
+        settings: (_jsx(TabContentView, { surface: "transparent", children: _jsx(SettingsView, { initialSection: settingsInitialSection ?? undefined }, "settings-root") })),
         plugins: (_jsx(TabContentView, { children: _jsx(PluginsPageView, {}) })),
         skills: (_jsx(TabContentView, { children: _jsx(SkillsView, {}) })),
         trajectories: (_jsx(TabContentView, { children: _jsx(TrajectoriesView, {}) })),
         transcripts: (_jsx(TabContentView, { children: _jsx(TranscriptsPageView, {}) })),
         relationships: (_jsx(TabContentView, { children: _jsx(RelationshipsView, {}) })),
         memories: (_jsx(TabContentView, { children: _jsx(MemoryViewerView, {}) })),
+        files: (_jsx(TabScrollView, { children: _jsx(FilesView, {}) })),
         runtime: (_jsx(TabContentView, { children: _jsx(RuntimeView, {}) })),
         database: (_jsx(TabContentView, { children: _jsx(DatabasePageView, {}) })),
         logs: (_jsx(TabContentView, { children: _jsx(LogsView, {}) })),
@@ -487,10 +595,15 @@ function renderStaticViewRouterTab({ tab, androidPhoneSurfaceEnabled, navigation
     if (tab === "views" || tab === "apps") {
         return renderAppsSurface(navigationPath);
     }
+    if (tab === "background") {
+        // Rendered directly (no opaque TabContentView chrome) so the live app
+        // background shows through behind the controls.
+        return _jsx(BackgroundView, {});
+    }
     if (tab === "character" ||
         tab === "character-select" ||
         tab === "documents") {
-        return (_jsx(TabContentView, { children: _jsx(CharacterEditor, {}) }));
+        return (_jsx(TabContentView, { children: _jsx(CharacterEditor, { initialPage: tab === "documents" ? "documents" : undefined }) }));
     }
     if (tab === "inventory") {
         return (_jsx(TabScrollView, { children: _jsx(WalletInventoryPage, {}) }));
@@ -500,13 +613,18 @@ function renderStaticViewRouterTab({ tab, androidPhoneSurfaceEnabled, navigation
     }
     return directViews[tab] ?? _jsx(ViewUnavailableFallback, {});
 }
-function renderViewRouterContent({ tab, dynamicPage, dynamicAppPage, developerModeEnabled, navigationPath, availableViews, appSlug, androidPhoneSurfaceEnabled, settingsInitialSection, }) {
-    if (visibleDynamicPage(dynamicPage, developerModeEnabled)) {
+function renderViewRouterContent({ tab, dynamicPage, dynamicAppPage, enabledKinds, navigationPath, availableViews, appSlug, androidPhoneSurfaceEnabled, settingsInitialSection, }) {
+    if (visibleDynamicPage(dynamicPage, enabledKinds)) {
         return (_jsx(TabContentView, { children: _jsx(DynamicPluginPage, { resolved: dynamicPage }) }));
     }
-    if (visibleDynamicPage(dynamicAppPage, developerModeEnabled)) {
+    if (visibleDynamicPage(dynamicAppPage, enabledKinds)) {
         return (_jsx(TabContentView, { children: _jsx(DynamicPluginPage, { resolved: dynamicAppPage }) }));
     }
+    const appShellPageForRoute = findAppShellPageForRoute(navigationPath);
+    if (appShellPageForRoute &&
+        isViewVisible(appShellPageForRoute, enabledKinds)) {
+        return (_jsx(TabContentView, { children: _jsx(RegisteredAppShellPage, { registration: appShellPageForRoute }) }));
+    }
     const remoteView = findRemoteViewForRoute(availableViews, navigationPath, tab, appSlug);
     if (remoteView?.bundleUrl)
         return renderRemoteView(remoteView);
@@ -517,17 +635,24 @@ function renderViewRouterContent({ tab, dynamicPage, dynamicAppPage, developerMo
         settingsInitialSection,
     });
 }
-function ViewRouter({ settingsInitialSection, }) {
-    const { tab } = useApp();
+function ViewRouter({ routeOverride, settingsInitialSection, }) {
+    const activeTab = useAppSelector((s) => s.tab);
+    const tab = routeOverride?.tab ?? activeTab;
     const androidPhoneSurfaceEnabled = isAndroidPhoneSurfaceEnabled();
     const dynamicPage = useResolvedDynamicPage(tab);
-    const [navigationPath, setNavigationPath] = useState(() => typeof window === "undefined" ? "/" : getWindowNavigationPath());
+    const [navigationPath, setNavigationPath] = useState(() => routeOverride?.navigationPath ??
+        (typeof window === "undefined" ? "/" : getWindowNavigationPath()));
+    const routeOverridePath = routeOverride?.navigationPath;
     const appSlug = tab === "apps" || tab === "views"
         ? getAppSlugFromPath(navigationPath)
         : null;
     const dynamicAppPage = useResolvedDynamicPage(appSlug ?? "");
-    const developerModeEnabled = useIsDeveloperMode();
+    const enabledKinds = useEnabledViewKinds();
     useEffect(() => {
+        if (routeOverridePath) {
+            setNavigationPath(routeOverridePath);
+            return;
+        }
         if (typeof window === "undefined")
             return;
         const navEvt = shouldUseHashNavigation() ? "hashchange" : "popstate";
@@ -536,7 +661,7 @@ function ViewRouter({ settingsInitialSection, }) {
         };
         window.addEventListener(navEvt, handleNavigationChange);
         return () => window.removeEventListener(navEvt, handleNavigationChange);
-    }, []);
+    }, [routeOverridePath]);
     // Available views from /api/views — used to route to DynamicViewLoader
     // when a tab ID matches a view entry that ships a remote bundle URL.
     const { views: availableViews } = useAvailableViews();
@@ -544,7 +669,7 @@ function ViewRouter({ settingsInitialSection, }) {
         tab,
         dynamicPage,
         dynamicAppPage,
-        developerModeEnabled,
+        enabledKinds,
         navigationPath,
         availableViews,
         appSlug,
@@ -562,6 +687,10 @@ function greetingForTimeOfDay() {
     return "Good evening! What would you like to do?";
 }
 const APP_SHELL_CLASS = "flex flex-col flex-1 min-h-0 w-full font-body text-txt bg-bg";
+// Home/Springboard and Background opt into the unified app background (mounted
+// once at the shell root), so their shell is transparent — no `bg-bg` to paint
+// over it. Every other view keeps the opaque shell (its own background).
+const APP_SHELL_CLASS_TRANSPARENT = "flex flex-col flex-1 min-h-0 w-full font-body text-txt";
 function CompanionShellContent(props) {
     if (props.uiShellMode === "companion" &&
         props.isCompanionTab &&
@@ -577,9 +706,10 @@ function ChatRouteShellContent(props) {
     // The /chat route is the ambient conversational home: open space behind the
     // always-present ContinuousChatOverlay (mounted at the shell root), which is
     // the whole chat experience. Ask it anything, or ask it to open a view ("show
-    // me the coding view") which surfaces over this base. The home is wordless —
-    // a warm, gently pulsing orange field, no greeting text.
-    return (_jsx("div", { className: APP_SHELL_CLASS, children: _jsxs("div", { className: "relative flex min-h-0 min-w-0 flex-1 items-center justify-center overflow-hidden", children: [_jsx(ChatAmbientBackground, {}), _jsx(HomeScreenMount, {}), _jsx(CustomActionsPanel, { open: props.customActionsPanelOpen, onClose: () => props.setCustomActionsPanelOpen(false), onOpenEditor: (action) => {
+    // me the coding view") which surfaces over this base. The home is wordless,
+    // sitting directly on the unified app background (mounted once at the shell
+    // root) — its shell is transparent so that background shows through.
+    return (_jsx("div", { className: APP_SHELL_CLASS_TRANSPARENT, children: _jsxs("div", { className: "relative flex min-h-0 min-w-0 flex-1 items-center justify-center overflow-hidden", children: [_jsx(HomeScreenMount, { initialPage: "home" }), _jsx(CustomActionsPanel, { open: props.customActionsPanelOpen, onClose: () => props.setCustomActionsPanelOpen(false), onOpenEditor: (action) => {
                         props.setEditingAction(action ?? null);
                         props.setCustomActionsEditorOpen(true);
                     } })] }) }, "chat-shell"));
@@ -587,8 +717,11 @@ function ChatRouteShellContent(props) {
 function routedShellMainClass(tab) {
     // One tight page gutter for every routed view: minimal top so headers sit
     // right under the chrome, a small side gutter, modest bottom. Views that own
-    // their full surface (browser/apps/views) still get zero padding.
-    const pagePadding = tab === "browser" || tab === "apps" || tab === "views"
+    // their full surface (browser/apps/views/background) still get zero padding.
+    const pagePadding = tab === "browser" ||
+        tab === "apps" ||
+        tab === "views" ||
+        tab === "background"
         ? ""
         : "px-2 sm:px-3 pt-2 pb-4";
     const mobilePadding = tab === "browser" ? "" : MOBILE_NAV_PADDING_CLASS;
@@ -602,7 +735,14 @@ function routedShellMainClass(tab) {
  * per-view.
  */
 function RoutedShellContent(props) {
-    return (_jsxs("div", { className: APP_SHELL_CLASS, children: [props.desktopTabBar, _jsx("main", { className: routedShellMainClass(props.tab), children: props.viewLayout ? (_jsx(ViewLayoutSurface, { availableViews: props.availableViewsForLayout, layout: props.viewLayout, onClear: props.onClearViewLayout })) : (_jsx(ViewRouter, { settingsInitialSection: props.settingsInitialSection })) })] }, `tab-shell-${props.tab}`));
+    // Routes with `backgroundPolicy: "shared"` intentionally sit on the unified
+    // Home/Springboard background. Every other route is opaque; the shell root
+    // also paints a full-window underlay so status/home-indicator safe areas do
+    // not expose the shared background around app views.
+    const shellClass = props.screenBackgroundPolicy === "shared"
+        ? APP_SHELL_CLASS_TRANSPARENT
+        : APP_SHELL_CLASS;
+    return (_jsxs("div", { className: shellClass, children: [props.desktopTabBar, _jsx("main", { className: routedShellMainClass(props.tab), children: props.viewLayout ? (_jsx(ViewLayoutSurface, { availableViews: props.availableViewsForLayout, layout: props.viewLayout, onClear: props.onClearViewLayout })) : (_jsx(ViewRouter, { settingsInitialSection: props.settingsInitialSection })) })] }, `tab-shell-${props.tab}`));
 }
 /**
  * Edge-to-edge surface for pages that register `fullBleed` — no tab bar, no
@@ -643,7 +783,10 @@ function ShellFoundationMount() {
  */
 function ContinuousChatOverlayMount() {
     const controller = useShellControllerContext();
-    const { characterData, agentStatus } = useApp();
+    const { characterData, agentStatus } = useAppSelectorShallow((s) => ({
+        characterData: s.characterData,
+        agentStatus: s.agentStatus,
+    }));
     const slash = useSlashCommandController();
     if (!controller)
         return null;
@@ -654,31 +797,58 @@ function ContinuousChatOverlayMount() {
     return (_jsx(ContinuousChatOverlay, { controller: controller, agentName: agentName, slash: slash }));
 }
 /**
- * The iOS-style home dashboard for the /chat route — clock, recent activity,
- * recent messages, a customizable widget area, and pinned view tiles. Sits
- * behind the always-present chat overlay. Wires tile taps to the real nav:
+ * The iOS-style home dashboard for the /chat route — recent activity, recent
+ * messages, and a customizable widget area. Sits beside the retained
+ * Springboard page behind the always-present chat overlay. Wires tile taps to the real nav:
  * builtin tabs via setTab, plugin/remote views via the eliza:navigate:view event.
  */
-function HomeScreenMount() {
-    const { setTab } = useApp();
+function HomeScreenMount({ initialPage = "home", }) {
+    const setTab = useAppSelector((s) => s.setTab);
+    const { views } = useAvailableViews();
     // Host apps can override the home screen via the `homeScreen` boot-config slot
     // (whitelabel seam); fall back to the built-in HomeScreen.
     const { homeScreen: HomeScreenOverride } = useBootConfig();
     const onOpenTile = useCallback((target) => {
         if (target.kind === "tab") {
             setTab(target.tab);
+            // Report the tab id as a surface so the proactive decider reacts to
+            // user-initiated tile navigation (#8792). Fire-and-forget.
+            reportUserViewSwitch(target.tab);
         }
         else {
             window.dispatchEvent(new CustomEvent("eliza:navigate:view", {
                 detail: { viewPath: target.path },
             }));
+            // The tile only carries a path; resolve the registered view id so the
+            // decider keys off the same id the rest of the navigation bus uses
+            // (#8792). Skip the report when no view is registered at that path.
+            const viewId = views.find((v) => v.path === target.path)?.id;
+            if (viewId)
+                reportUserViewSwitch(viewId, target.path);
         }
-    }, [setTab]);
+    }, [setTab, views]);
     const Home = HomeScreenOverride ?? HomeScreen;
-    return (_jsx(Home, { onOpenTile: onOpenTile, showNativeOsTiles: isAospShellEnabled() }));
+    const home = useMemo(() => (_jsx(Home, { onOpenTile: onOpenTile, showNativeOsTiles: isAospShellEnabled() })), [Home, onOpenTile]);
+    const springboard = useMemo(() => _jsx(SpringboardSurface, {}), []);
+    return (_jsx("div", { className: "relative min-h-0 min-w-0 flex-1 self-stretch overflow-hidden", children: _jsx(HomeSpringboardSurface, { home: home, springboard: springboard, initialPage: initialPage }) }));
 }
 export function App() {
-    const { startupError, startupCoordinator, retryStartup, tab, setTab, setState, actionNotice, activeOverlayApp, uiTheme, backendConnection, activeGameViewerUrl, gameOverlayEnabled, uiShellMode, t, } = useApp();
+    const { startupError, startupCoordinator, retryStartup, tab, setTab, setState, actionNotice, activeOverlayApp, uiTheme, backendConnection, activeGameViewerUrl, gameOverlayEnabled, uiShellMode, t, } = useAppSelectorShallow((s) => ({
+        startupError: s.startupError,
+        startupCoordinator: s.startupCoordinator,
+        retryStartup: s.retryStartup,
+        tab: s.tab,
+        setTab: s.setTab,
+        setState: s.setState,
+        actionNotice: s.actionNotice,
+        activeOverlayApp: s.activeOverlayApp,
+        uiTheme: s.uiTheme,
+        backendConnection: s.backendConnection,
+        activeGameViewerUrl: s.activeGameViewerUrl,
+        gameOverlayEnabled: s.gameOverlayEnabled,
+        uiShellMode: s.uiShellMode,
+        t: s.t,
+    }));
     const { companionShell: CompanionShell } = useBootConfig();
     const isPopout = useIsPopout();
     const shellMode = useShellMode();
@@ -703,6 +873,7 @@ export function App() {
     const resolvedOverlayApp = overlayAppActive && activeOverlayApp
         ? getOverlayApp(activeOverlayApp)
         : undefined;
+    const overlayAppSurfaceActive = Boolean(resolvedOverlayApp);
     const contextMenu = useContextMenu();
     useSecretsManagerShortcut();
     // Warm a small, device-aware subset of lazy route chunks once the shell is
@@ -773,8 +944,17 @@ export function App() {
     // Desktop tab bar — persisted pinned tabs for the Electrobun shell.
     const { tabs: desktopTabs, openTab: openDesktopTab, closeTab: closeDesktopTab, } = useDesktopTabs();
     const [activeDesktopTabId, setActiveDesktopTabId] = useState(null);
-    const { views: availableViewsForDesktopTabs } = useAvailableViews();
+    const { views: availableViewsForDesktopTabs } = useRoutableViews();
     const [viewLayout, setViewLayout] = useState(null);
+    const navigationPath = useCurrentNavigationPath();
+    const screenBackgroundPolicy = useActiveScreenBackgroundPolicy({
+        tab,
+        navigationPath,
+        availableViews: availableViewsForDesktopTabs,
+        viewLayout,
+    });
+    const renderSharedAppBackground = screenBackgroundPolicy === "shared" && !overlayAppSurfaceActive;
+    const renderOpaqueAppBackground = screenBackgroundPolicy === "opaque" || overlayAppSurfaceActive;
     const [editingAction, setEditingAction] = useState(null);
     const [desktopShuttingDown, setDesktopShuttingDown] = useState(false);
     const isCompanionTab = tab === "companion";
@@ -823,7 +1003,7 @@ export function App() {
     // Handle agent-dispatched view navigation events.
     // The VIEWS action (and future agent commands) dispatch this event to navigate
     // the user to a specific view by path or view ID.
-    // When the target is "/views" or "/apps" (the ViewCatalog), we also
+    // When the target is "/views" or "/apps" (legacy launcher aliases), we also
     // directly set the tab so the nav bar becomes visible.
     // On desktop, also open the view as a desktop tab if desktopTabEnabled.
     useEffect(() => {
@@ -904,6 +1084,7 @@ export function App() {
         catch {
             // sandboxed — ignore
         }
+        reportUserViewSwitch(viewId, dtab.path);
     }, [desktopTabs]);
     const handleDesktopTabClose = useCallback((viewId) => {
         setViewLayout(null);
@@ -945,7 +1126,7 @@ export function App() {
     // shellContent is memoized before early returns to satisfy the Rules of Hooks.
     // Deps are local state/callbacks — not high-frequency AppContext fields like
     // ptySessions/agentStatus — so CompanionSceneHost stays stable across polls.
-    const shellContent = useMemo(() => (_jsx(ShellContent, { CompanionShell: CompanionShell, actionNotice: actionNotice, availableViewsForLayout: availableViewsForDesktopTabs, customActionsPanelOpen: customActionsPanelOpen, desktopTabBar: desktopTabBar, isChat: isChat, isCompanionTab: isCompanionTab, isFullBleed: isFullBleed, setCustomActionsEditorOpen: setCustomActionsEditorOpen, setCustomActionsPanelOpen: setCustomActionsPanelOpen, setEditingAction: setEditingAction, settingsInitialSection: settingsInitialSection, tab: tab, uiShellMode: uiShellMode, viewLayout: viewLayout, onClearViewLayout: handleClearViewLayout })), [
+    const shellContent = useMemo(() => (_jsx(ShellContent, { CompanionShell: CompanionShell, actionNotice: actionNotice, availableViewsForLayout: availableViewsForDesktopTabs, customActionsPanelOpen: customActionsPanelOpen, desktopTabBar: desktopTabBar, isChat: isChat, isCompanionTab: isCompanionTab, isFullBleed: isFullBleed, screenBackgroundPolicy: screenBackgroundPolicy, setCustomActionsEditorOpen: setCustomActionsEditorOpen, setCustomActionsPanelOpen: setCustomActionsPanelOpen, setEditingAction: setEditingAction, settingsInitialSection: settingsInitialSection, tab: tab, uiShellMode: uiShellMode, viewLayout: viewLayout, onClearViewLayout: handleClearViewLayout })), [
         CompanionShell,
         tab,
         uiShellMode,
@@ -953,6 +1134,7 @@ export function App() {
         actionNotice,
         isChat,
         isFullBleed,
+        screenBackgroundPolicy,
         customActionsPanelOpen,
         settingsInitialSection,
         desktopTabBar,
@@ -971,6 +1153,12 @@ export function App() {
     if (shellMode === "voice-selftest") {
         return _jsx(VoiceSelfTestShell, {});
     }
+    // Multi-turn voice SCENARIO player — drives a declarative VoiceScenario through
+    // the real STT->agent->TTS loop turn-by-turn and reports a per-turn verdict.
+    // Self-contained (its own ElizaClient + AudioContext); no app chrome / gate.
+    if (shellMode === "voice-workbench") {
+        return _jsx(VoiceWorkbenchShell, {});
+    }
     // OS chat-overlay window — render JUST the floating assistant pill +
     // waveform over a transparent background, no app chrome or onboarding gate.
     if (shellMode === "chat-overlay") {
@@ -1014,11 +1202,24 @@ export function App() {
     // the chat composer queues sends until first-turn capability fades in; views
     // show their own loading states until the runtime is live). No deprecated
     // first-run overlays — the coordinator handled all of that before this point.
-    return (_jsx(BugReportProvider, { value: bugReport, children: _jsxs(ShellControllerProvider, { children: [_jsxs("div", { className: "flex h-[100dvh] w-full max-w-full flex-col overflow-hidden", 
+    return (_jsx(BugReportProvider, { value: bugReport, children: _jsxs(ShellControllerProvider, { children: [_jsxs("div", { 
+                    // SAFE-AREA FILL INVARIANT (do not break): this root stays
+                    // `position: relative` ONLY. It must NEVER acquire compositor,
+                    // filter, perspective, or containment declarations. Any of those
+                    // makes this element the containing block for the fixed background
+                    // layers below (the opaque `app-opaque-background` underlay and the
+                    // `AppBackground` wallpaper), so instead of anchoring to the viewport
+                    // they would anchor to this padded box (top = safe-area-top) — leaving
+                    // an unfilled band under the notch (the WKWebView host color, brand
+                    // orange, would show through). Keeping the backgrounds viewport-fixed
+                    // is what lets every view fill edge-to-edge under the notch while the
+                    // `paddingTop` below keeps CONTENT notch-aware. Locked by
+                    // App.safe-area-fill.test.ts.
+                    className: "relative flex h-[100dvh] w-full max-w-full flex-col overflow-hidden", 
                     // Reserve the status-bar safe area so view headers + back buttons sit
                     // below the status bar. Top banners bleed their bg back up through it
                     // via `.mobile-top-banner:first-child` (see styles.css). No-op on web.
-                    style: { paddingTop: "var(--safe-area-top, 0px)" }, children: [_jsx(ConnectionFailedBanner, {}), _jsx(SystemWarningBanner, {}), _jsx(ActionBanner, {}), _jsx(CloudHandoffBanner, {}), shellContent] }), resolvedOverlayApp &&
+                    style: { paddingTop: "var(--safe-area-top, 0px)" }, children: [_jsx(AppBackground, { visible: renderSharedAppBackground }), renderSharedAppBackground && isSettingsPage ? (_jsx("div", { "aria-hidden": "true", "data-testid": "app-background-scrim", className: "pointer-events-none fixed inset-0 z-[1] bg-bg/55" })) : null, renderOpaqueAppBackground ? (_jsx("div", { "aria-hidden": "true", "data-testid": "app-opaque-background", className: "pointer-events-none fixed inset-0 z-0 bg-bg" })) : null, _jsxs("div", { className: "relative z-10 flex min-h-0 w-full flex-1 flex-col", children: [_jsx(ConnectionFailedBanner, {}), _jsx(SystemWarningBanner, {}), _jsx(ActionBanner, {}), _jsx(CloudHandoffBanner, {}), shellContent] })] }), resolvedOverlayApp &&
                     (() => {
                         const exitToApps = () => {
                             setState("activeOverlayApp", null);

package/agent-surface/AgentSurfaceContext.d.ts

@@ -8,7 +8,7 @@
  * component (React Fast Refresh-compatible).
  */
 import { type ReactNode } from "react";
-import type { AgentViewType } from "./types";
+import type { AgentViewType } from "./types.js";
 export interface AgentSurfaceProviderProps {
     viewId: string;
     viewType?: AgentViewType;