@elizaos/ui 2.0.0-alpha.385 → 2.0.0-alpha.392

package/packages/app-core/src/components/pages/AppDetailsView.js

@@ -0,0 +1,289 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * AppDetailsView — config + diagnostics + widgets + Launch button page
+ * for apps that need it (those with `hasDetailsPage: true` in their
+ * descriptor, or any registry/catalog app with launch params).
+ *
+ * Mounted by AppsView when the apps sub-path is `/apps/<slug>/details`.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { Pin, PinOff, Settings as SettingsIcon, TriangleAlert, } from "lucide-react";
+import { useRegistryCatalog } from "../apps/useRegistryCatalog";
+import { invokeDesktopBridgeRequest } from "../../bridge";
+import { useApp } from "../../state/useApp";
+import { findAppBySlug, getAppSlug } from "../apps/helpers";
+import { getInternalToolAppDescriptors, getInternalToolAppHasDetailsPage, getInternalToolAppTargetTab, getInternalToolApps, isInternalToolApp, } from "../apps/internal-tool-apps";
+import { getAllOverlayApps, isOverlayApp, overlayAppToRegistryInfo, } from "../apps/overlay-app-registry";
+import { loadPerAppConfig, savePerAppConfig, subscribePerAppConfig, } from "../apps/per-app-config";
+import { getLaunchHistoryForApp, recordLaunchAttempt, } from "../apps/launch-history";
+import { isWidgetVisible, loadChatSidebarVisibility, saveChatSidebarVisibility, widgetVisibilityKey, } from "../../widgets/visibility";
+import { getWidgetComponent } from "../../widgets/registry";
+function pluginIdFromName(name) {
+    return name.replace(/^@elizaos\/app-/, "");
+}
+function resolveAppFromSlug(slug, catalog) {
+    // Internal tool by slug
+    const internal = getInternalToolAppDescriptors().find((d) => d.windowPath === `/apps/${slug}`);
+    if (internal) {
+        const info = getInternalToolApps().find((a) => a.name === internal.name);
+        if (info) {
+            return {
+                source: "internal-tool",
+                info,
+                pluginId: pluginIdFromName(internal.name),
+                windowPath: internal.windowPath ?? `/apps/${slug}`,
+            };
+        }
+    }
+    // Overlay app by slug
+    const overlay = getAllOverlayApps().find((a) => getAppSlug(a.name) === slug && isOverlayApp(a.name));
+    if (overlay) {
+        return {
+            source: "overlay",
+            info: overlayAppToRegistryInfo(overlay),
+            pluginId: pluginIdFromName(overlay.name),
+            windowPath: `/apps/${slug}`,
+        };
+    }
+    // Catalog/registry app by slug
+    const catalogHit = findAppBySlug(catalog, slug);
+    if (catalogHit) {
+        return {
+            source: "catalog",
+            info: catalogHit,
+            pluginId: pluginIdFromName(catalogHit.name),
+            windowPath: `/apps/${slug}`,
+        };
+    }
+    return null;
+}
+function sourceLabel(source) {
+    switch (source) {
+        case "internal-tool":
+            return "Internal Tool";
+        case "overlay":
+            return "Overlay App";
+        case "catalog":
+            return "Catalog App";
+        default:
+            return "Unknown";
+    }
+}
+function formatTimestamp(value) {
+    try {
+        return new Date(value).toLocaleString();
+    }
+    catch {
+        return String(value);
+    }
+}
+function SectionHeader({ children }) {
+    return (_jsx("h3", { className: "text-xs-tight font-semibold uppercase tracking-[0.18em] text-accent", children: children }));
+}
+function ChipList({ items }) {
+    if (items.length === 0) {
+        return _jsx("span", { className: "text-xs text-muted", children: "None declared" });
+    }
+    return (_jsx("div", { className: "flex flex-wrap gap-1.5", children: items.map((item) => (_jsx("span", { className: "rounded-full border border-border/60 bg-card/50 px-2 py-0.5 text-xs text-muted", children: item }, item))) }));
+}
+function WidgetPreview({ declaration, pluginId, }) {
+    const Component = useMemo(() => getWidgetComponent(pluginId, declaration.id), [declaration.id, pluginId]);
+    if (!Component) {
+        return (_jsx("div", { className: "rounded-md border border-border/40 bg-card/30 px-3 py-2 text-xs text-muted", children: "No bundled component for this widget \u2014 preview unavailable." }));
+    }
+    return (_jsx("div", { className: "rounded-md border border-border/40 bg-card/30 p-3", children: _jsx(Component, { pluginId: pluginId, events: [], clearEvents: () => { } }) }));
+}
+export function AppDetailsView({ slug, onLaunched, }) {
+    const { plugins, appRuns, t, setTab, setState, setActionNotice } = useApp();
+    // Catalog of registry apps for slug → app resolution.
+    const { catalog: registryCatalog, error: catalogError } = useRegistryCatalog();
+    const catalog = registryCatalog ?? [];
+    const resolved = useMemo(() => resolveAppFromSlug(slug, catalog), [catalog, slug]);
+    // Per-app config (launch mode, alwaysOnTop, free-form settings).
+    const [config, setConfig] = useState(() => loadPerAppConfig(slug));
+    useEffect(() => {
+        setConfig(loadPerAppConfig(slug));
+        return subscribePerAppConfig(slug, setConfig);
+    }, [slug]);
+    const updateConfig = useCallback((next) => {
+        const merged = {
+            launchMode: next.launchMode ?? config.launchMode,
+            alwaysOnTop: next.alwaysOnTop !== undefined ? next.alwaysOnTop : config.alwaysOnTop,
+            settings: next.settings ?? config.settings,
+        };
+        setConfig(merged);
+        savePerAppConfig(slug, merged);
+    }, [config, slug]);
+    // Widget visibility — re-uses the existing chat-sidebar visibility store.
+    const [visibility, setVisibility] = useState(() => loadChatSidebarVisibility());
+    const toggleWidget = useCallback((decl, enabled) => {
+        const key = widgetVisibilityKey(decl.pluginId, decl.id);
+        const nextOverrides = { ...visibility.overrides, [key]: enabled };
+        const next = { overrides: nextOverrides };
+        setVisibility(next);
+        saveChatSidebarVisibility(next);
+    }, [visibility]);
+    // Widgets owned by this app's plugin. Server-declared widgets carry
+    // `slot: string`; narrow to the WidgetSlot literal union here so the
+    // rest of the component can rely on it.
+    const widgets = useMemo(() => {
+        if (!resolved)
+            return [];
+        const ownPlugin = plugins?.find((p) => p.id === resolved.pluginId);
+        const raw = ownPlugin?.widgets ?? [];
+        return raw.map((decl) => ({
+            ...decl,
+            slot: decl.slot,
+        }));
+    }, [plugins, resolved]);
+    const [expandedWidget, setExpandedWidget] = useState(null);
+    // Launch history for diagnostics.
+    const [history, setHistory] = useState([]);
+    useEffect(() => {
+        if (resolved)
+            setHistory(getLaunchHistoryForApp(resolved.info.name));
+    }, [resolved]);
+    // Recent runs (live).
+    const recentRuns = useMemo(() => {
+        if (!resolved || !appRuns)
+            return [];
+        return appRuns.filter((r) => r.appName === resolved.info.name).slice(0, 5);
+    }, [appRuns, resolved]);
+    // Launch action.
+    const [launching, setLaunching] = useState(false);
+    const launchedRef = useRef(false);
+    const handleLaunch = useCallback(async () => {
+        if (!resolved || launching)
+            return;
+        setLaunching(true);
+        launchedRef.current = false;
+        try {
+            if (config.launchMode === "inline") {
+                // Inline: for internal tools, switch the main shell tab; for
+                // overlays, set activeOverlayApp; otherwise fall back to window.
+                if (resolved.source === "internal-tool") {
+                    const tab = getInternalToolAppTargetTab(resolved.info.name);
+                    if (tab) {
+                        setTab(tab);
+                        launchedRef.current = true;
+                        recordLaunchAttempt({
+                            appName: resolved.info.name,
+                            timestamp: Date.now(),
+                            succeeded: true,
+                            diagnostics: [],
+                        });
+                        setHistory(getLaunchHistoryForApp(resolved.info.name));
+                        onLaunched?.({ mode: "inline", slug });
+                        return;
+                    }
+                }
+                if (resolved.source === "overlay") {
+                    setState("activeOverlayApp", resolved.info.name);
+                    launchedRef.current = true;
+                    recordLaunchAttempt({
+                        appName: resolved.info.name,
+                        timestamp: Date.now(),
+                        succeeded: true,
+                        diagnostics: [],
+                    });
+                    setHistory(getLaunchHistoryForApp(resolved.info.name));
+                    onLaunched?.({ mode: "inline", slug });
+                    return;
+                }
+                // Fall through to window mode — inline not supported for this app.
+            }
+            // Window mode (default).
+            const created = await invokeDesktopBridgeRequest({
+                rpcMethod: "desktopOpenAppWindow",
+                ipcChannel: "desktop:openAppWindow",
+                params: {
+                    slug,
+                    title: resolved.info.displayName ?? resolved.info.name,
+                    path: resolved.windowPath,
+                    alwaysOnTop: config.alwaysOnTop,
+                },
+            });
+            if (!created?.id) {
+                throw new Error("Desktop bridge declined to open the window.");
+            }
+            launchedRef.current = true;
+            recordLaunchAttempt({
+                appName: resolved.info.name,
+                timestamp: Date.now(),
+                succeeded: true,
+                diagnostics: [],
+            });
+            setHistory(getLaunchHistoryForApp(resolved.info.name));
+            onLaunched?.({ mode: "window", slug });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            recordLaunchAttempt({
+                appName: resolved.info.name,
+                timestamp: Date.now(),
+                succeeded: false,
+                diagnostics: [],
+                errorMessage: message,
+            });
+            setHistory(getLaunchHistoryForApp(resolved.info.name));
+            setActionNotice(t("appdetails.LaunchFailed", {
+                defaultValue: `Could not launch ${resolved.info.displayName}: ${message}`,
+            }), "error", 4000);
+        }
+        finally {
+            setLaunching(false);
+        }
+    }, [
+        config.alwaysOnTop,
+        config.launchMode,
+        launching,
+        onLaunched,
+        resolved,
+        setActionNotice,
+        setState,
+        setTab,
+        slug,
+        t,
+    ]);
+    if (catalogError && !resolved) {
+        return (_jsxs("div", { className: "flex h-full min-h-0 w-full flex-col items-center justify-center gap-2 p-6 text-center text-sm text-muted", children: [_jsx(TriangleAlert, { className: "h-5 w-5 text-accent" }), _jsx("span", { children: catalogError })] }));
+    }
+    if (!resolved) {
+        return (_jsxs("div", { className: "flex h-full min-h-0 w-full items-center justify-center text-sm text-muted", children: ["Loading ", slug, "\u2026"] }));
+    }
+    const isInternal = resolved.source === "internal-tool";
+    const supportsInlineMode = isInternal || resolved.source === "overlay";
+    return (_jsxs("div", { className: "device-layout mx-auto flex w-full max-w-4xl flex-col gap-6 px-4 py-6 lg:px-6", children: [_jsxs("header", { className: "flex flex-col gap-3 border-b border-border/35 pb-5 sm:flex-row sm:items-center sm:justify-between", children: [_jsxs("div", { className: "flex items-center gap-4", children: [resolved.info.heroImage ? (_jsx("img", { src: resolved.info.heroImage, alt: "", className: "h-14 w-14 rounded-lg border border-border/40 object-cover" })) : (_jsx("div", { className: "flex h-14 w-14 items-center justify-center rounded-lg border border-border/40 bg-card/40 text-xs uppercase text-muted", children: (resolved.info.displayName ?? resolved.info.name)
+                                    .slice(0, 2)
+                                    .toUpperCase() })), _jsxs("div", { className: "min-w-0", children: [_jsx("h2", { className: "truncate text-base font-semibold text-foreground", children: resolved.info.displayName ?? resolved.info.name }), _jsx("p", { className: "truncate text-xs text-muted", children: resolved.info.name }), _jsxs("div", { className: "mt-1 flex flex-wrap items-center gap-2 text-[10px] uppercase tracking-[0.16em] text-muted", children: [_jsx("span", { children: sourceLabel(resolved.source) }), recentRuns.length > 0 ? (_jsxs("span", { className: "rounded-full bg-accent/15 px-2 py-0.5 text-accent", children: [recentRuns.length, " running"] })) : null] })] })] }), _jsx("button", { type: "button", onClick: handleLaunch, disabled: launching, className: "rounded-full bg-accent px-5 py-2 text-xs font-semibold uppercase tracking-[0.16em] text-accent-foreground transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60", children: launching
+                            ? "Launching…"
+                            : `Launch ${resolved.info.displayName ?? "App"}` })] }), _jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeader, { children: "About" }), resolved.info.description ? (_jsx("p", { className: "text-sm text-muted", children: resolved.info.description })) : null, _jsx(ChipList, { items: resolved.info.capabilities ?? [] })] }), recentRuns.length > 0 ? (_jsxs("section", { className: "flex flex-col gap-2", children: [_jsx(SectionHeader, { children: "Recent Runs" }), _jsx("ul", { className: "flex flex-col gap-1 text-xs text-muted", children: recentRuns.map((run) => (_jsxs("li", { className: "flex items-center justify-between rounded-md border border-border/40 bg-card/30 px-3 py-1.5", children: [_jsx("span", { className: "truncate", children: run.runId }), _jsx("span", { className: "ml-2 shrink-0 uppercase tracking-[0.14em]", children: run.status })] }, run.runId))) })] })) : null, _jsxs("section", { className: "flex flex-col gap-2", children: [_jsx(SectionHeader, { children: "Launch Diagnostics" }), history.length === 0 ? (_jsx("p", { className: "text-xs text-muted", children: "No launch history yet." })) : (_jsx("ul", { className: "flex flex-col gap-1 text-xs", children: history.slice(0, 5).map((entry) => (_jsxs("li", { className: "rounded-md border border-border/40 bg-card/30 px-3 py-1.5", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-muted", children: formatTimestamp(entry.timestamp) }), _jsx("span", { className: entry.succeeded
+                                                ? "text-accent"
+                                                : "text-destructive", children: entry.succeeded ? "OK" : "FAILED" })] }), entry.errorMessage ? (_jsx("p", { className: "mt-1 text-muted", children: entry.errorMessage })) : null] }, entry.timestamp))) }))] }), widgets.length > 0 ? (_jsxs("section", { className: "flex flex-col gap-2", children: [_jsx(SectionHeader, { children: "Widgets" }), _jsx("ul", { className: "flex flex-col gap-2", children: widgets.map((decl) => {
+                            const visible = isWidgetVisible(decl, visibility.overrides);
+                            const widgetKey = widgetVisibilityKey(decl.pluginId, decl.id);
+                            const expanded = expandedWidget === widgetKey;
+                            return (_jsxs("li", { className: "rounded-md border border-border/40 bg-card/30", children: [_jsxs("div", { className: "flex items-center justify-between gap-3 px-3 py-2", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "truncate text-sm font-medium text-foreground", children: decl.label }), _jsx("div", { className: "truncate text-[10px] uppercase tracking-[0.14em] text-muted", children: decl.slot })] }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [_jsx("button", { type: "button", onClick: () => setExpandedWidget(expanded ? null : widgetKey), className: "rounded-full border border-border/60 px-2 py-0.5 text-[10px] uppercase tracking-[0.14em] text-muted transition-colors hover:text-foreground", children: expanded ? "Hide" : "Preview" }), _jsxs("label", { className: "inline-flex cursor-pointer items-center gap-1.5 text-xs", children: [_jsx("input", { type: "checkbox", checked: visible, onChange: (event) => toggleWidget(decl, event.currentTarget.checked), className: "h-3.5 w-3.5 accent-accent" }), _jsx("span", { className: "text-muted", children: "Show" })] })] })] }), expanded ? (_jsx("div", { className: "border-t border-border/40 p-3", children: _jsx(WidgetPreview, { declaration: decl, pluginId: resolved.pluginId }) })) : null] }, widgetKey));
+                        }) })] })) : null, _jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeader, { children: "Config" }), _jsxs("fieldset", { className: "flex flex-col gap-2 rounded-md border border-border/40 bg-card/30 p-3", children: [_jsxs("legend", { className: "px-1 text-xs uppercase tracking-[0.14em] text-muted", children: [_jsx(SettingsIcon, { className: "mr-1 inline h-3 w-3" }), " Launch Mode"] }), _jsxs("label", { className: "flex cursor-pointer items-center gap-2 text-sm", children: [_jsx("input", { type: "radio", checked: config.launchMode === "window", onChange: () => updateConfig({ launchMode: "window" }), className: "h-3.5 w-3.5 accent-accent" }), _jsx("span", { children: "Open in dedicated window" })] }), _jsxs("label", { className: `flex items-center gap-2 text-sm ${supportsInlineMode
+                                    ? "cursor-pointer"
+                                    : "cursor-not-allowed opacity-50"}`, children: [_jsx("input", { type: "radio", checked: config.launchMode === "inline", disabled: !supportsInlineMode, onChange: () => updateConfig({ launchMode: "inline" }), className: "h-3.5 w-3.5 accent-accent" }), _jsxs("span", { children: ["Replace current view in main window", !supportsInlineMode ? " (not supported for this app)" : ""] })] })] }), _jsxs("label", { className: `inline-flex items-center gap-2 self-start rounded-full border border-border/60 bg-card/40 px-3 py-1.5 text-xs ${config.launchMode === "window"
+                            ? "cursor-pointer"
+                            : "cursor-not-allowed opacity-50"}`, children: [_jsx("input", { type: "checkbox", checked: config.alwaysOnTop, disabled: config.launchMode !== "window", onChange: (event) => updateConfig({ alwaysOnTop: event.currentTarget.checked }), className: "h-3.5 w-3.5 accent-accent" }), config.alwaysOnTop ? (_jsx(Pin, { className: "h-3.5 w-3.5", "aria-hidden": "true" })) : (_jsx(PinOff, { className: "h-3.5 w-3.5", "aria-hidden": "true" })), _jsx("span", { children: "Keep this app's window on top" })] })] })] }));
+}
+/**
+ * Convenience: does this slug resolve to an app that wants the details
+ * page? Used by AppsView.handleLaunch to decide whether to navigate to
+ * /apps/<slug>/details or call openAppRouteWindow directly.
+ *
+ * Only apps that explicitly declare `hasDetailsPage: true` (today: a
+ * handful of internal tools with real config / runtime knobs) route
+ * through the details page. Catalog and overlay apps launch directly —
+ * launching is the primary action; the user only needs the extra step
+ * when there's config worth touching first.
+ */
+export function appNeedsDetailsPage(name) {
+    if (isInternalToolApp(name)) {
+        return getInternalToolAppHasDetailsPage(name);
+    }
+    return false;
+}

package/packages/app-core/src/components/pages/AppsView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppsView.d.ts","sourceRoot":"","sources":["../../../../../../../app-core/src/components/pages/AppsView.tsx"],"names":[],"mappings":"AAyCA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AA4J1D,wBAAgB,QAAQ,4CAo/BvB"}
+{"version":3,"file":"AppsView.d.ts","sourceRoot":"","sources":["../../../../../../../app-core/src/components/pages/AppsView.tsx"],"names":[],"mappings":"AA0CA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAoJ1D,wBAAgB,QAAQ,4CAolCvB"}

package/packages/app-core/src/components/pages/AppsView.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { PageLayout } from "@elizaos/ui";
 import { Pin, PinOff } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -10,10 +10,11 @@ import { openExternalUrl } from "../../utils";
 import { AppsCatalogGrid } from "../apps/AppsCatalogGrid";
 import { AppsSidebar } from "../apps/AppsSidebar";
 import { filterAppsForCatalog, findAppBySlug, getAppSlug, } from "../apps/helpers";
-import { getInternalToolApps, getInternalToolAppTargetTab, } from "../apps/internal-tool-apps";
+import { getInternalToolApps, getInternalToolAppTargetTab, getInternalToolAppWindowPath, } from "../apps/internal-tool-apps";
 import { getAllOverlayApps, isOverlayApp, overlayAppToRegistryInfo, } from "../apps/overlay-app-registry";
 import { RunningAppsRow } from "../apps/RunningAppsRow";
 import { resolveEmbeddedViewerUrl, shouldUseEmbeddedAppViewer, } from "../apps/viewer-auth";
+import { AppDetailsView, appNeedsDetailsPage } from "./AppDetailsView";
 export { shouldShowAppInAppsView } from "../apps/helpers";
 /** Max items retained in launch history. */
 const RECENT_APPS_LIMIT = 10;
@@ -25,21 +26,6 @@ const APPS_SIDEBAR_MAX_WIDTH = 520;
 const APP_WINDOW_LAUNCH_ENABLED_KEY = "milady:apps:window:launch-enabled";
 const APP_WINDOW_ALWAYS_ON_TOP_KEY = "milady:apps:window:always-on-top";
 const APP_WINDOW_HEARTBEAT_MS = 15_000;
-function nativeSurfaceForInternalToolTab(tab) {
-    switch (tab) {
-        case "plugins":
-            return "plugins";
-        case "connectors":
-            return "connectors";
-        case "browser":
-            return "browser";
-        case "automations":
-        case "triggers":
-            return "triggers";
-        default:
-            return null;
-    }
-}
 function clampWidth(value) {
     return Math.min(Math.max(value, APPS_SIDEBAR_MIN_WIDTH), APPS_SIDEBAR_MAX_WIDTH);
 }
@@ -90,6 +76,23 @@ function loadInitialAppWindowLaunchEnabled() {
 function getCurrentAppsPath() {
     return getWindowNavigationPath();
 }
+/**
+ * Parse the current apps sub-path into `{slug, action}`. Action recognizes
+ * `details` for `/apps/<slug>/details`. Anything else is treated as a
+ * direct app surface (`action: null`).
+ */
+function parseAppsRoute(path) {
+    if (!path.startsWith("/apps/"))
+        return { slug: null, action: null };
+    const after = path.slice("/apps/".length).replace(/[?#].*$/, "");
+    if (!after)
+        return { slug: null, action: null };
+    const [slug, sub] = after.split("/");
+    return {
+        slug: slug || null,
+        action: sub === "details" ? "details" : null,
+    };
+}
 function resolveDesktopViewerUrl(viewerUrl) {
     const resolved = resolveEmbeddedViewerUrl(viewerUrl);
     if (!resolved)
@@ -140,7 +143,7 @@ export function AppsView() {
     const [sidebarCollapsed, setSidebarCollapsed] = useState(loadInitialSidebarCollapsed);
     const [sidebarWidth, setSidebarWidth] = useState(loadInitialSidebarWidth);
     const [appWindowLaunchEnabled, setAppWindowLaunchEnabled] = useState(loadInitialAppWindowLaunchEnabled);
-    const [appWindowAlwaysOnTop, setAppWindowAlwaysOnTop] = useState(loadInitialAppWindowAlwaysOnTop);
+    const [appWindowAlwaysOnTop] = useState(loadInitialAppWindowAlwaysOnTop);
     const [isAppWindow] = useState(isAppWindowRoute);
     const [appWindows, setAppWindows] = useState([]);
     const [busyAppWindowId, setBusyAppWindowId] = useState(null);
@@ -165,15 +168,9 @@ export function AppsView() {
             /* ignore */
         }
     }, []);
-    const handleAppWindowAlwaysOnTopChange = useCallback((next) => {
-        setAppWindowAlwaysOnTop(next);
-        try {
-            window.localStorage.setItem(APP_WINDOW_ALWAYS_ON_TOP_KEY, String(next));
-        }
-        catch {
-            /* ignore */
-        }
-    }, []);
+    // Upstream re-added handleAppWindowAlwaysOnTopChange but we removed the
+    // global toggle UI on this branch — keep only the launch-enabled handler
+    // upstream added (which still has UI in the catalog grid header).
     const handleAppWindowLaunchEnabledChange = useCallback((next) => {
         setAppWindowLaunchEnabled(next);
         try {
@@ -234,10 +231,18 @@ export function AppsView() {
     const hasActiveRun = Boolean(activeGameRun);
     const hasCurrentGame = currentGameViewerUrl.length > 0 &&
         activeGameRun?.viewerAttachment === "attached";
-    /** Push or replace the browser URL to reflect the active app (or browse). */
-    const pushAppsUrl = useCallback((slug) => {
+    /**
+     * Push or replace the browser URL to reflect the active app (or browse).
+     * `subPath` is appended after the slug so `/apps/<slug>/details` shows
+     * the details page instead of launching directly.
+     */
+    const pushAppsUrl = useCallback((slug, subPath) => {
         try {
-            const path = slug ? `/apps/${slug}` : "/apps";
+            const path = slug
+                ? subPath
+                    ? `/apps/${slug}/${subPath}`
+                    : `/apps/${slug}`
+                : "/apps";
             if (shouldUseHashNavigation()) {
                 window.location.hash = path;
             }
@@ -249,6 +254,50 @@ export function AppsView() {
             /* ignore — sandboxed iframe or SSR */
         }
     }, []);
+    // Track the current `/apps/<slug>/details` slug for the details-page
+    // routing. Listens to hashchange + popstate so back/forward navigation
+    // unmounts AppDetailsView correctly.
+    const [appsDetailsSlug, setAppsDetailsSlug] = useState(() => parseAppsRoute(getCurrentAppsPath()).action === "details"
+        ? parseAppsRoute(getCurrentAppsPath()).slug
+        : null);
+    useEffect(() => {
+        const handle = () => {
+            const parsed = parseAppsRoute(getCurrentAppsPath());
+            setAppsDetailsSlug(parsed.action === "details" ? parsed.slug : null);
+        };
+        window.addEventListener("hashchange", handle);
+        window.addEventListener("popstate", handle);
+        return () => {
+            window.removeEventListener("hashchange", handle);
+            window.removeEventListener("popstate", handle);
+        };
+    }, []);
+    // Bun side fires this when a menu/tray click hits an app that declares
+    // `hasDetailsPage: true`. We switch to the apps tab and navigate the
+    // hash to /apps/<slug>/details so AppDetailsView mounts.
+    useEffect(() => {
+        return subscribeDesktopBridgeEvent({
+            rpcMessage: "desktopAppDetailsRequested",
+            ipcChannel: "desktop:appDetailsRequested",
+            listener: (payload) => {
+                if (!payload ||
+                    typeof payload !== "object" ||
+                    typeof payload.slug !== "string") {
+                    return;
+                }
+                const slug = payload.slug;
+                if (!slug)
+                    return;
+                setTab("apps");
+                setState("appsSubTab", "browse");
+                // Update state directly: pushAppsUrl uses replaceState in non-hash
+                // routing mode, which fires no event, so the hashchange/popstate
+                // listener wouldn't pick it up.
+                setAppsDetailsSlug(slug);
+                pushAppsUrl(slug, "details");
+            },
+        });
+    }, [pushAppsUrl, setState, setTab]);
     const sortedRuns = useMemo(() => [...appRuns].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)), [appRuns]);
     const mergeRun = useCallback((run) => {
         const nextRuns = [
@@ -387,16 +436,27 @@ export function AppsView() {
         setState("recentApps", next);
     }, [recentApps, setState]);
     const openAppRouteWindow = useCallback(async (app) => {
+        // Upstream gate: opt-in toggle for the per-app native window
+        // experience (lives in the catalog grid header).
         if (!appWindowLaunchEnabled || isAppWindow || !isElectrobunRuntime()) {
             return false;
         }
-        const nativeSurface = nativeSurfaceForInternalToolTab(getInternalToolAppTargetTab(app.name));
-        if (nativeSurface) {
+        // Internal tools that have an explicit windowPath open as their own
+        // app window (Ghost-style). The renderer parses `appWindow=1` + the
+        // hash route and renders the matching tab. This supersedes upstream's
+        // `desktopOpenSurfaceWindow` + `nativeSurfaceForInternalToolTab` path
+        // (the surface-bridge approach was removed when AppWindowRenderer
+        // landed — see the apps-as-windows refactor).
+        const internalWindowPath = getInternalToolAppWindowPath(app.name);
+        if (internalWindowPath) {
+            const slug = getAppSlug(app.name);
             const created = await invokeDesktopBridgeRequest({
-                rpcMethod: "desktopOpenSurfaceWindow",
-                ipcChannel: "desktop:openSurfaceWindow",
+                rpcMethod: "desktopOpenAppWindow",
+                ipcChannel: "desktop:openAppWindow",
                 params: {
-                    surface: nativeSurface,
+                    slug,
+                    title: app.displayName ?? app.name,
+                    path: internalWindowPath,
                     alwaysOnTop: appWindowAlwaysOnTop,
                 },
             });
@@ -415,7 +475,7 @@ export function AppsView() {
             ]);
             pushRecentApp(app.name);
             setState("appsSubTab", "browse");
-            pushAppsUrl(getAppSlug(app.name));
+            pushAppsUrl(slug);
             setActionNotice(t("appsview.OpenedInDesktopWindow", {
                 defaultValue: `${app.displayName ?? app.name} opened in a desktop window.`,
                 name: app.displayName ?? app.name,
@@ -427,6 +487,7 @@ export function AppsView() {
             rpcMethod: "desktopOpenAppWindow",
             ipcChannel: "desktop:openAppWindow",
             params: {
+                slug,
                 title: app.displayName ?? app.name,
                 path: `/apps/${encodeURIComponent(slug)}`,
                 alwaysOnTop: appWindowAlwaysOnTop,
@@ -518,16 +579,42 @@ export function AppsView() {
     }, [appWindowAlwaysOnTop, mergeRun, pushAppsUrl, setActionNotice, setState, t]);
     const handleLaunch = useCallback(async (app) => {
         slugAutoLaunchDone.current = true;
-        const openedRouteWindow = await openAppRouteWindow(app).catch(() => false);
-        if (openedRouteWindow)
+        // Apps that declare config / runtime / widgets show a Details page
+        // first so the user can review settings before launching. The Launch
+        // button on AppDetailsView is what eventually calls the bridge or
+        // navigates inline. Skip when we're already inside an app window
+        // (the slug lives there, not in the main shell).
+        if (!isAppWindow && appNeedsDetailsPage(app.name)) {
+            const slug = getAppSlug(app.name);
+            pushRecentApp(app.name);
+            setState("appsSubTab", "browse");
+            pushAppsUrl(slug, "details");
             return;
+        }
+        // In Electrobun, try to open the app's dedicated native window via
+        // `openAppRouteWindow` — slug-deduped + per-app bounds, Ghost-style.
+        // The helper itself respects the user's `appWindowLaunchEnabled`
+        // toggle: when off it returns false, and we fall through to the
+        // web-style launch path (catalog → client.launchApp + iframe-attach;
+        // internal tool → setTab; overlay → activeOverlayApp). That gives
+        // the toggle a real opt-out semantics instead of bricking launches.
+        if (isElectrobunRuntime()) {
+            const openedRouteWindow = await openAppRouteWindow(app).catch(() => false);
+            if (openedRouteWindow)
+                return;
+            // openAppRouteWindow returned false → either the toggle is off,
+            // we're already inside an app window, or the bridge declined.
+            // Continue to the web-fallback paths below so the click isn't a
+            // dead-end.
+        }
+        // Web fallback: internal tools switch tabs in the shell.
         const internalToolTab = getInternalToolAppTargetTab(app.name);
         if (internalToolTab) {
             pushRecentApp(app.name);
             setTab(internalToolTab);
             return;
         }
-        // Overlay apps (e.g. companion) are local-only — launch without server round-trip
+        // Web fallback: overlay apps (e.g. companion) mount inside the shell.
         if (isOverlayApp(app.name)) {
             pushRecentApp(app.name);
             setState("activeOverlayApp", app.name);
@@ -611,7 +698,12 @@ export function AppsView() {
     useEffect(() => {
         if (slugAutoLaunchDone.current || apps.length === 0)
             return;
-        const slug = getAppSlugFromPath(getCurrentAppsPath());
+        const parsed = parseAppsRoute(getCurrentAppsPath());
+        // /apps/<slug>/details is handled by the details renderer below; never
+        // auto-launch from it (would loop straight back to details).
+        if (parsed.action === "details")
+            return;
+        const slug = parsed.slug ?? getAppSlugFromPath(getCurrentAppsPath());
         slugAutoLaunchDone.current = true;
         if (!slug)
             return;
@@ -801,10 +893,10 @@ export function AppsView() {
         }
     }, [busyAppWindowId, setActionNotice, t]);
     const appsSidebar = (_jsx(AppsSidebar, { apps: apps, browseApps: browseApps, runs: sortedRuns, activeAppNames: activeAppNames, favoriteAppNames: favoriteAppNames, selectedAppName: activeGameRun?.appName ?? null, collapsed: sidebarCollapsed, onCollapsedChange: handleSidebarCollapsedChange, width: sidebarWidth, onWidthChange: handleSidebarWidthChange, minWidth: APPS_SIDEBAR_MIN_WIDTH, maxWidth: APPS_SIDEBAR_MAX_WIDTH, onLaunchApp: (app) => void handleLaunch(app), onOpenRun: (run) => void handleOpenRun(run) }));
-    return (_jsx(PageLayout, { className: "h-full bg-transparent", "data-testid": "apps-shell", sidebar: appsSidebar, contentInnerClassName: "w-full", contentClassName: "![scrollbar-width:none] [&::-webkit-scrollbar]:!hidden", children: _jsxs("div", { className: "device-layout mx-auto flex w-full max-w-6xl flex-col gap-4 px-4 py-4 lg:px-6", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-b border-border/35 pb-3", children: [_jsx("div", { className: "min-w-0", children: _jsx("h2", { className: "text-xs-tight font-semibold uppercase tracking-[0.18em] text-accent", children: "App Windows" }) }), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsxs("label", { className: "inline-flex cursor-pointer items-center gap-2 rounded-full border border-border/60 bg-card/60 px-3 py-1.5 text-xs font-medium text-muted transition-colors hover:text-foreground", children: [_jsx("input", { type: "checkbox", "aria-label": "Open apps in windows", className: "h-3.5 w-3.5 accent-accent", checked: appWindowLaunchEnabled, onChange: (event) => handleAppWindowLaunchEnabledChange(event.currentTarget.checked) }), _jsx("span", { children: "Open apps in windows" })] }), _jsxs("label", { className: "inline-flex cursor-pointer items-center gap-2 rounded-full border border-border/60 bg-card/60 px-3 py-1.5 text-xs font-medium text-muted transition-colors hover:text-foreground", children: [_jsx("input", { type: "checkbox", "aria-label": "Keep new windows on top", className: "h-3.5 w-3.5 accent-accent", checked: appWindowAlwaysOnTop, onChange: (event) => handleAppWindowAlwaysOnTopChange(event.currentTarget.checked) }), appWindowAlwaysOnTop ? (_jsx(Pin, { className: "h-3.5 w-3.5", "aria-hidden": "true" })) : (_jsx(PinOff, { className: "h-3.5 w-3.5", "aria-hidden": "true" })), _jsx("span", { children: "Keep new windows on top" })] })] })] }), appWindows.length > 0 ? (_jsx("section", { "data-testid": "app-window-controls", className: "flex flex-wrap items-center gap-2", children: appWindows.map((windowRecord) => {
+    return (_jsx(PageLayout, { className: "h-full bg-transparent", "data-testid": "apps-shell", sidebar: appsSidebar, contentInnerClassName: "w-full", contentClassName: "![scrollbar-width:none] [&::-webkit-scrollbar]:!hidden", children: _jsxs("div", { className: "device-layout mx-auto flex w-full max-w-6xl flex-col gap-4 px-4 py-4 lg:px-6", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-b border-border/35 pb-3", children: [_jsx("div", { className: "min-w-0", children: _jsx("h2", { className: "text-xs-tight font-semibold uppercase tracking-[0.18em] text-accent", children: "App Windows" }) }), _jsxs("label", { className: "inline-flex cursor-pointer items-center gap-2 rounded-full border border-border/60 bg-card/60 px-3 py-1.5 text-xs font-medium text-muted transition-colors hover:text-foreground", children: [_jsx("input", { type: "checkbox", "aria-label": "Open apps in windows", className: "h-3.5 w-3.5 accent-accent", checked: appWindowLaunchEnabled, onChange: (event) => handleAppWindowLaunchEnabledChange(event.currentTarget.checked) }), _jsx("span", { children: "Open apps in windows" })] })] }), appWindows.length > 0 ? (_jsx("section", { "data-testid": "app-window-controls", className: "flex flex-wrap items-center gap-2", children: appWindows.map((windowRecord) => {
                         const busy = busyAppWindowId === windowRecord.id;
                         return (_jsxs("div", { className: "inline-flex min-w-0 items-center gap-2 rounded-full border border-border/55 bg-card/70 px-3 py-1.5 text-xs text-muted", children: [_jsx("span", { className: "max-w-44 truncate font-medium text-foreground", children: windowRecord.displayName }), _jsxs("button", { type: "button", className: "inline-flex items-center gap-1.5 rounded-full border border-border/60 px-2 py-1 text-[0.68rem] font-semibold uppercase tracking-[0.16em] text-muted transition-colors hover:border-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-60", onClick: () => void handleToggleAppWindowAlwaysOnTop(windowRecord), disabled: busy, "aria-label": windowRecord.alwaysOnTop
                                         ? `Let ${windowRecord.displayName} act like a normal window`
                                         : `Keep ${windowRecord.displayName} on top`, children: [windowRecord.alwaysOnTop ? (_jsx(PinOff, { className: "h-3.5 w-3.5", "aria-hidden": "true" })) : (_jsx(Pin, { className: "h-3.5 w-3.5", "aria-hidden": "true" })), windowRecord.alwaysOnTop ? "Normal" : "On top"] })] }, windowRecord.id));
-                    }) })) : null, hasActiveRun ? (_jsx("div", { className: "flex flex-wrap items-center justify-between gap-3", children: _jsx("button", { type: "button", className: "rounded-full border border-ok/35 bg-ok/10 px-3 py-1.5 text-xs-tight font-medium text-ok transition-colors hover:bg-ok/15", onClick: handleOpenCurrentGame, children: hasCurrentGame ? "Live viewer" : "Active run" }) })) : null, _jsx(RunningAppsRow, { runs: sortedRuns, catalogApps: apps, busyRunId: busyRunId, onOpenRun: (run) => void handleOpenRun(run), onStopRun: (run) => void handleStopRun(run), stoppingRunId: stoppingRunId }), _jsx(AppsCatalogGrid, { activeAppNames: activeAppNames, error: error, favoriteAppNames: favoriteAppNames, loading: loading, searchQuery: searchQuery, visibleApps: visibleApps, onLaunch: (app) => void handleLaunch(app), onToggleFavorite: handleToggleFavorite })] }) }));
+                    }) })) : null, hasActiveRun ? (_jsx("div", { className: "flex flex-wrap items-center justify-between gap-3", children: _jsx("button", { type: "button", className: "rounded-full border border-ok/35 bg-ok/10 px-3 py-1.5 text-xs-tight font-medium text-ok transition-colors hover:bg-ok/15", onClick: handleOpenCurrentGame, children: hasCurrentGame ? "Live viewer" : "Active run" }) })) : null, appsDetailsSlug ? (_jsx(AppDetailsView, { slug: appsDetailsSlug, onLaunched: () => pushAppsUrl() })) : (_jsxs(_Fragment, { children: [_jsx(RunningAppsRow, { runs: sortedRuns, catalogApps: apps, busyRunId: busyRunId, onOpenRun: (run) => void handleOpenRun(run), onStopRun: (run) => void handleStopRun(run), stoppingRunId: stoppingRunId }), _jsx(AppsCatalogGrid, { activeAppNames: activeAppNames, error: error, favoriteAppNames: favoriteAppNames, loading: loading, searchQuery: searchQuery, visibleApps: visibleApps, onLaunch: (app) => void handleLaunch(app), onToggleFavorite: handleToggleFavorite })] }))] }) }));
 }

package/packages/app-core/src/components/shell/StartupShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StartupShell.d.ts","sourceRoot":"","sources":["../../../../../../../app-core/src/components/shell/StartupShell.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkEH,wBAAgB,YAAY,mDAkP3B"}
+{"version":3,"file":"StartupShell.d.ts","sourceRoot":"","sources":["../../../../../../../app-core/src/components/shell/StartupShell.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiEH,wBAAgB,YAAY,mDA4O3B"}

package/packages/app-core/src/components/shell/StartupShell.js

@@ -49,9 +49,8 @@ function phaseToStatusKey(phase) {
 /**
  * Returns true when the cloud-provisioned bootstrap session has NOT yet been
  * established for this page load. After a successful exchange the UI writes
- * sessionStorage["milady_session"] — we treat presence of that key as
- * "bootstrap done" for P0. P1 will retire sessionStorage in favour of an
- * HttpOnly cookie set by the server.
+ * sessionStorage["milady_session"] as a renderer-side marker; the server-owned
+ * HttpOnly cookie remains the actual auth boundary.
  */
 function needsBootstrapSession() {
     try {
@@ -148,12 +147,10 @@ export function StartupShell() {
             if (needsBootstrapSession()) {
                 // Cloud-provisioned but no session yet. Lock the dashboard and show
                 // the bootstrap wizard step. Fail closed: we do NOT advance.
-                console.log("[eliza][startup] Cloud-provisioned container — bootstrap session required");
                 setShowBootstrap(true);
                 return;
             }
             // Cloud-provisioned and session already established — skip the wizard.
-            console.log("[eliza][startup] Cloud-provisioned container with session — skipping wizard");
             setState("onboardingComplete", true);
             coordinatorDispatchRef.current({ type: "ONBOARDING_COMPLETE" });
         })