@iloveagents/foundry-web-shell 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,24 @@
+# @iloveagents/foundry-web-shell
+
+Browser bootstrap and layout package for Foundry UI apps.
+
+`web-shell` mounts the SPA with `bootstrapShell`, wires routes/modules, applies
+theme layers, chooses auth, and hosts `@iloveagents/foundry-web-ui`.
+
+## Usage
+
+```tsx
+import { bootstrapShell } from "@iloveagents/foundry-web-shell";
+
+bootstrapShell({
+  pages,
+  modules,
+  theme,
+});
+```
+
+The default auth adapter is MSAL-backed and reads `VITE_MSAL_CLIENT_ID`,
+`VITE_MSAL_AUTHORITY`, and `VITE_MSAL_API_SCOPE`. Starter/demo apps can pass a
+custom `authProvider` and `agentFetch` for local unauthenticated development.
+
+This package publishes built ESM JavaScript and `.d.ts` declarations.

package/dist/auth-default.d.ts

@@ -0,0 +1,18 @@
+import type { FC, ReactNode } from "react";
+import type { AuthAdapter } from "./types.js";
+/**
+ * Default MSAL-backed auth adapter. Reads VITE_MSAL_* from runtime config
+ * (`window.__APP_CONFIG__`) with `import.meta.env` fallback for local dev.
+ * Customers override via `bootstrapShell({ authProvider: { Provider: ... } })`
+ * for tests or non-MSAL deployments.
+ */
+export declare const defaultAuthAdapter: AuthAdapter;
+/**
+ * Tiny wrapper that picks the default or override adapter and renders it.
+ * Kept as a separate component so the wrapper-order test can probe it
+ * easily.
+ */
+export declare const ShellAuth: FC<{
+    adapter?: AuthAdapter;
+    children: ReactNode;
+}>;

package/dist/auth-default.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AuthProvider } from "@iloveagents/foundry-web-ui";
+import { runtimeConfig } from "./runtime-config.js";
+function AuthConfigError({ missingKeys }) {
+    return (_jsx("div", { className: "flex min-h-dvh items-center justify-center bg-background px-6 text-center", children: _jsxs("div", { className: "max-w-md rounded-2xl border border-border bg-card px-6 py-5 shadow-sm", children: [_jsx("h1", { className: "text-lg font-semibold text-foreground", children: "Authentication unavailable" }), _jsxs("p", { className: "mt-2 text-sm text-muted-foreground", children: ["Missing required MSAL environment variables: ", missingKeys.join(", "), "."] })] }) }));
+}
+/**
+ * Read MSAL configuration. Prefers runtime config (`window.__APP_CONFIG__`,
+ * injected by the container at startup) and falls back to build-time Vite env
+ * (`import.meta.env`) for local dev — see {@link runtimeConfig}. Returns the
+ * resolved config or the list of missing keys; the shell renders
+ * <AuthConfigError /> when any key is missing.
+ */
+function readMsalConfig() {
+    const clientId = runtimeConfig("VITE_MSAL_CLIENT_ID");
+    const authority = runtimeConfig("VITE_MSAL_AUTHORITY");
+    const apiScope = runtimeConfig("VITE_MSAL_API_SCOPE");
+    const missing = [
+        !clientId ? "VITE_MSAL_CLIENT_ID" : null,
+        !authority ? "VITE_MSAL_AUTHORITY" : null,
+        !apiScope ? "VITE_MSAL_API_SCOPE" : null,
+    ].filter((v) => v !== null);
+    if (missing.length > 0)
+        return { missing };
+    return {
+        clientId,
+        authority,
+        apiScope,
+        redirectUri: window.location.origin,
+    };
+}
+/**
+ * Default MSAL-backed auth adapter. Reads VITE_MSAL_* from runtime config
+ * (`window.__APP_CONFIG__`) with `import.meta.env` fallback for local dev.
+ * Customers override via `bootstrapShell({ authProvider: { Provider: ... } })`
+ * for tests or non-MSAL deployments.
+ */
+export const defaultAuthAdapter = {
+    Provider: ({ children }) => {
+        const result = readMsalConfig();
+        if ("missing" in result) {
+            return _jsx(AuthConfigError, { missingKeys: result.missing });
+        }
+        return _jsx(AuthProvider, { config: result, children: children });
+    },
+};
+/**
+ * Tiny wrapper that picks the default or override adapter and renders it.
+ * Kept as a separate component so the wrapper-order test can probe it
+ * easily.
+ */
+export const ShellAuth = ({ adapter, children, }) => {
+    const Adapter = (adapter ?? defaultAuthAdapter).Provider;
+    return _jsx(Adapter, { children: children });
+};

package/dist/bootstrap-shell.d.ts

@@ -0,0 +1,11 @@
+import type { BootstrapShellOptions } from "./types.js";
+/**
+ * Mount the agent UI into the DOM.
+ *
+ * Composition pipeline:
+ *   1. Run each module's `fetchInterceptor` (BEFORE createRoot so window.fetch
+ *      wrappers are in place by the first React render).
+ *   2. createRoot on `rootElement` (default: #root).
+ *   3. Wrap `<ShellApp>` in <StrictMode> unless `strictMode === false`.
+ */
+export declare function bootstrapShell(opts?: BootstrapShellOptions): void;

package/dist/bootstrap-shell.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ShellApp } from "./shell-app.js";
+/**
+ * Mount the agent UI into the DOM.
+ *
+ * Composition pipeline:
+ *   1. Run each module's `fetchInterceptor` (BEFORE createRoot so window.fetch
+ *      wrappers are in place by the first React render).
+ *   2. createRoot on `rootElement` (default: #root).
+ *   3. Wrap `<ShellApp>` in <StrictMode> unless `strictMode === false`.
+ */
+export function bootstrapShell(opts = {}) {
+    const { modules = [], pages = [], theme = [], authProvider, agentFetch, strictMode = true, rootElement, } = opts;
+    // 1. Install module fetch interceptors before React mounts.
+    for (const m of modules) {
+        m.fetchInterceptor?.();
+    }
+    // 2. Resolve mount target.
+    const root = rootElement ?? document.getElementById("root");
+    if (!root) {
+        throw new Error("[@iloveagents/foundry-web-shell] No mount target — pass `rootElement` or ensure a #root element exists.");
+    }
+    const tree = (_jsx(ShellApp, { modules: modules, pages: pages, baseThemeLayers: theme, authProvider: authProvider, agentFetch: agentFetch }));
+    // 3. Mount with StrictMode by default.
+    createRoot(root).render(strictMode ? _jsx(StrictMode, { children: tree }) : tree);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { bootstrapShell } from "./bootstrap-shell.js";
+export { ShellApp } from "./shell-app.js";
+export { ShellLayout } from "./shell-layout.js";
+export { defaultAuthAdapter, ShellAuth } from "./auth-default.js";
+export { defaultAgentFetch } from "./service-fetch-default.js";
+export { runtimeConfig } from "./runtime-config.js";
+export { defineChatModule } from "./types.js";
+export type { ChatModule, ChatConversationConfig, ShellPage, AuthAdapter, BootstrapShellOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { bootstrapShell } from "./bootstrap-shell.js";
+export { ShellApp } from "./shell-app.js";
+export { ShellLayout } from "./shell-layout.js";
+export { defaultAuthAdapter, ShellAuth } from "./auth-default.js";
+export { defaultAgentFetch } from "./service-fetch-default.js";
+export { runtimeConfig } from "./runtime-config.js";
+export { defineChatModule } from "./types.js";

package/dist/runtime-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime configuration reader.
+ *
+ * The web app ships as a SINGLE prebuilt container image that must boot
+ * correctly for any customer / environment without a rebuild. Per-env values
+ * (API base URL, MSAL client/authority/scopes) therefore arrive at RUNTIME —
+ * the container entrypoint writes a small `/config.js` from env vars that sets
+ * `window.__APP_CONFIG__`, loaded before the app bundle.
+ *
+ * `runtimeConfig(key)` resolves, in order:
+ *   1. `window.__APP_CONFIG__[key]`  — runtime config injected by the container
+ *   2. `import.meta.env[key]`        — build-time Vite env (local `pnpm dev`)
+ *   3. `""`                          — absent
+ *
+ * Keeping `import.meta.env` as the fallback means local dev is unchanged: there
+ * is no `/config.js` in dev, so `window.__APP_CONFIG__` is undefined and the
+ * existing `VITE_*` values from `.env` are used exactly as before.
+ *
+ * The window cast is inline (no `declare global`) so this can be duplicated in
+ * sibling packages without conflicting global augmentations.
+ */
+export declare function runtimeConfig(key: string): string;

package/{src/runtime-config.ts → dist/runtime-config.js}

@@ -19,12 +19,11 @@
  * The window cast is inline (no `declare global`) so this can be duplicated in
  * sibling packages without conflicting global augmentations.
  */
-export function runtimeConfig(key: string): string {
-  const fromWindow =
-    typeof window !== "undefined"
-      ? (window as { __APP_CONFIG__?: Record<string, string | undefined> })
-          .__APP_CONFIG__?.[key]
-      : undefined;
-  const fromEnv = (import.meta.env as Record<string, string | undefined>)[key];
-  return fromWindow ?? fromEnv ?? "";
+export function runtimeConfig(key) {
+    const fromWindow = typeof window !== "undefined"
+        ? window
+            .__APP_CONFIG__?.[key]
+        : undefined;
+    const fromEnv = import.meta.env[key];
+    return fromWindow ?? fromEnv ?? "";
 }

package/dist/service-fetch-default.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default agent fetch client wired to the MSAL token store and the host's
+ * Vite env. Customers can build their own via `createServiceFetch` from
+ * `@iloveagents/foundry-agent` if they need different acquireToken / baseUrl behavior.
+ *
+ * Forward the optional ``{ forceRefresh }`` argument that the fetch
+ * interceptor passes on the 401 retry path. Without it, the retry would
+ * still ask MSAL for a cached token and the long-lived-tab 401 loop never
+ * recovers.
+ *
+ * ``recoverFromHardAuthFailure`` kicks in when even the force-refresh
+ * retry comes back with 401 — at that point the silent path is
+ * exhausted and only a fresh ``loginRedirect`` will produce a token
+ * the resource server accepts (server-side policy / audience / claims
+ * have drifted under the cached identity).
+ */
+export declare const defaultAgentFetch: typeof fetch;

package/{src/service-fetch-default.ts → dist/service-fetch-default.js}

@@ -1,7 +1,6 @@
 import { createServiceFetch } from "@iloveagents/foundry-agent";
 import { authStore } from "@iloveagents/foundry-agent/msal";
-import { runtimeConfig } from "./runtime-config.ts";
-
+import { runtimeConfig } from "./runtime-config.js";
 /**
  * Default agent fetch client wired to the MSAL token store and the host's
  * Vite env. Customers can build their own via `createServiceFetch` from
@@ -18,9 +17,8 @@ import { runtimeConfig } from "./runtime-config.ts";
  * the resource server accepts (server-side policy / audience / claims
  * have drifted under the cached identity).
  */
-export const defaultAgentFetch: typeof fetch = createServiceFetch({
-  acquireToken: (options) => authStore.getState().getAccessToken("api", options),
-  recoverFromHardAuthFailure: (reason) =>
-    authStore.getState().recoverFromHardAuthFailure(reason),
-  baseUrl: runtimeConfig("VITE_API_BASE_URL"),
+export const defaultAgentFetch = createServiceFetch({
+    acquireToken: (options) => authStore.getState().getAccessToken("api", options),
+    recoverFromHardAuthFailure: (reason) => authStore.getState().recoverFromHardAuthFailure(reason),
+    baseUrl: runtimeConfig("VITE_API_BASE_URL"),
 });

package/dist/shell-app.d.ts

@@ -0,0 +1,18 @@
+import type { ThemeLayer } from "@iloveagents/foundry-web-ui";
+import type { ChatModule, AuthAdapter, ShellPage } from "./types.js";
+interface ShellAppProps {
+    modules: ChatModule[];
+    pages: ShellPage[];
+    baseThemeLayers: ThemeLayer[];
+    authProvider?: AuthAdapter;
+    /** Test seam — overrides defaultAgentFetch. */
+    agentFetch?: typeof fetch;
+}
+/**
+ * Inner shell component — pure React (no `createRoot`). Imported by
+ * `bootstrap-shell.tsx` for production and by `__tests__/` for assertions.
+ *
+ * Wrapper ordering is contractual; see `wrapper-order.test.tsx`.
+ */
+export declare function ShellApp({ modules, pages, baseThemeLayers, authProvider, agentFetch, }: ShellAppProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/shell-app.js

@@ -0,0 +1,227 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Suspense, useCallback, useMemo, useRef } from "react";
+import { BrowserRouter, Routes, Route, useLocation } from "react-router";
+import { AGUIRuntimeProvider } from "@iloveagents/foundry-web-ui";
+import { ShellAuth } from "./auth-default.js";
+import { ShellLayout } from "./shell-layout.js";
+import { defaultAgentFetch } from "./service-fetch-default.js";
+/**
+ * Inner shell component — pure React (no `createRoot`). Imported by
+ * `bootstrap-shell.tsx` for production and by `__tests__/` for assertions.
+ *
+ * Wrapper ordering is contractual; see `wrapper-order.test.tsx`.
+ */
+export function ShellApp({ modules, pages, baseThemeLayers, authProvider, agentFetch, }) {
+    // Merge module pages with customer pages — customer wins on path collision
+    // (last-wins). Stable order: customer pages first (they appear in Routes
+    // before module pages, and React Router matches the FIRST matching route).
+    const mergedPages = useMemo(() => {
+        const seen = new Set(pages.map((p) => p.path));
+        const moduleRoutes = [];
+        for (const m of modules) {
+            for (const p of m.pages ?? []) {
+                if (!seen.has(p.path)) {
+                    seen.add(p.path);
+                    moduleRoutes.push(p);
+                }
+            }
+        }
+        return [...pages, ...moduleRoutes];
+    }, [pages, modules]);
+    // Compose module wrappers outer→inner from each module's array.
+    const wrappers = useMemo(() => {
+        const out = [];
+        for (const m of modules) {
+            for (const W of m.wrappers ?? [])
+                out.push(W);
+        }
+        return out;
+    }, [modules]);
+    // Aggregate module toolUIs.
+    const toolUIs = [];
+    for (const m of modules) {
+        if (m.toolUIs) {
+            toolUIs.push(_jsx(ToolUIGroup, { children: m.toolUIs }, m.name));
+        }
+    }
+    const fetchFn = agentFetch ?? defaultAgentFetch;
+    // Aggregate chatConversation configs from all modules. First-match
+    // wins at URL-match time (rare to have more than one anyway).
+    const chatConversationConfigs = useMemo(() => modules.flatMap((m) => (m.chatConversation ? [m.chatConversation] : [])), [modules]);
+    return (_jsx(BrowserRouter, { children: _jsx(ShellAuth, { adapter: authProvider, children: _jsx(ComposedWrappers, { wrappers: wrappers, children: _jsx(ChatConversationAwareRuntime, { fetchFn: fetchFn, configs: chatConversationConfigs, toolUIs: toolUIs, children: _jsx(Suspense, { fallback: null, children: _jsx(Routes, { children: _jsx(Route, { element: _jsx(ShellLayout, { modules: modules, baseThemeLayers: baseThemeLayers }), children: mergedPages.map((p) => (_jsx(Route, { path: p.path === "/" ? undefined : p.path, index: p.path === "/", element: p.element }, p.path))) }) }) }) }) }) }) }));
+}
+/**
+ * Reads the current pathname (only meaningful inside ``<BrowserRouter>``),
+ * matches it against any module-declared :type:`ChatConversationConfig`,
+ * and hands the matched config + URL-extracted id down into
+ * :type:`AGUIRuntimeProvider` as a :type:`AGUIHistoryAdapterFactory`.
+ *
+ * Why a factory (not a pre-built adapter)
+ * =======================================
+ * The history adapter needs *both* the URL-extracted conversation id
+ * (when present) *and* the AG-UI adapter's freshly-minted thread id
+ * (always set — covers fresh chats). The AG-UI adapter only exists
+ * once :type:`AGUIRuntimeProvider` mounts, so the factory is invoked
+ * inside that mount with both pieces available. This makes "fresh
+ * chats also persist" a built-in property of the contract, not an
+ * afterthought.
+ */
+function ChatConversationAwareRuntime({ children, toolUIs, fetchFn, configs, }) {
+    const { pathname } = useLocation();
+    // Pick the matching config (URL-pattern match) OR fall back to the
+    // first config registered — modules without a URL match still want
+    // their fresh-chat persistence. With ≥1 config the runtime always
+    // gets a factory; without configs it stays in the legacy in-memory
+    // mode.
+    const { config, urlMatch } = useMemo(() => {
+        for (const cfg of configs) {
+            const m = pathname.match(cfg.pathPattern);
+            if (m && m[1]) {
+                return { config: cfg, urlMatch: m[1] };
+            }
+        }
+        return { config: configs[0], urlMatch: undefined };
+    }, [pathname, configs]);
+    if (!config) {
+        // No chatConversation configs registered → legacy in-memory
+        // runtime, no history / no sticky concerns.
+        return (_jsxs(AGUIRuntimeProvider, { fetchFn: fetchFn, children: [toolUIs, children] }));
+    }
+    // Per-config child component, KEYED by config identity. Why a
+    // key/child split: ``config.useStickyConversationId`` is optional.
+    // Calling it inline with the optional chain ``config?.useSticky?.()``
+    // would be a Rules-of-Hooks violation the moment a second
+    // ChatConversationConfig registers with different hook-shape — URL
+    // navigation flips which cfg matches, the hook count flips, React
+    // crashes. The key makes a config swap a full remount, which is a
+    // legitimate way to change the hook lineage without violating the
+    // rules. ``configIndex`` is stable per config because ``configs`` is
+    // memoised in ShellApp.
+    const configIndex = configs.indexOf(config);
+    if (config.useStickyConversationId) {
+        return (_jsx(StickyAwareRuntime, { config: config, useSticky: config.useStickyConversationId, urlMatch: urlMatch, fetchFn: fetchFn, toolUIs: toolUIs, children: children }, `sticky:${configIndex}`));
+    }
+    return (_jsx(UrlOnlyRuntime, { config: config, urlMatch: urlMatch, fetchFn: fetchFn, toolUIs: toolUIs, children: children }, `url:${configIndex}`));
+}
+/**
+ * Branch for configs that DECLARE :attr:`useStickyConversationId`.
+ * Calls the hook unconditionally so React's hook-count invariant
+ * holds across every render of this mount.
+ */
+function StickyAwareRuntime({ config, useSticky, urlMatch, fetchFn, toolUIs, children, }) {
+    const sticky = useSticky();
+    return (_jsx(RuntimeBody, { config: config, sticky: sticky, urlMatch: urlMatch, fetchFn: fetchFn, toolUIs: toolUIs, children: children }));
+}
+/**
+ * Branch for configs that DO NOT declare :attr:`useStickyConversationId`.
+ * No hook is ever called for sticky state — the runtime threadId
+ * follows URL match and the shell-minted fresh UUID only.
+ */
+function UrlOnlyRuntime({ config, urlMatch, fetchFn, toolUIs, children }) {
+    return (_jsx(RuntimeBody, { config: config, sticky: null, urlMatch: urlMatch, fetchFn: fetchFn, toolUIs: toolUIs, children: children }));
+}
+/**
+ * Shared rendering body — same useRef/useMemo/useCallback shape for
+ * both branches. The hook lineage here is stable per mount because
+ * the parent decides which branch (and which key) to use.
+ */
+function RuntimeBody({ config, sticky, urlMatch, fetchFn, toolUIs, children, }) {
+    // Pre-mint a fresh UUID so the runtime's ``threadId`` is set from
+    // the very first render — never goes through ``undefined → defined``,
+    // which would otherwise force a remount of the assistant-ui runtime
+    // (and wipe in-flight messages) the moment the user sent their first
+    // message on a fresh chat. The backend collapse (``conversation_id ==
+    // agui_thread_id``) ensures the id the runtime uses from the start
+    // matches the row the lazy ``ensureConversationId`` creates — same
+    // value, no mid-conversation switch.
+    //
+    // Mint a new one only when the user actually starts a new thread:
+    // ``sticky`` transitions from a value back to ``null`` (the module
+    // clears it on the ``/`` "New Thread" landing).
+    const freshIdRef = useRef(_genUuid());
+    const prevStickyRef = useRef(sticky);
+    if (sticky === null && prevStickyRef.current !== null) {
+        // User just navigated back to "/" (New Thread). The previous chat
+        // is being abandoned; mint a fresh UUID for the next session.
+        freshIdRef.current = _genUuid();
+    }
+    prevStickyRef.current = sticky;
+    // Effective id seen by AGUIRuntimeProvider — always defined.
+    //
+    // Priority order matters and is intentional:
+    //   1. ``urlMatch`` — when the user is on ``/chat/<id>`` the URL is
+    //      ALWAYS the authoritative conversation. This MUST come before
+    //      ``sticky`` because of a stale-render race on cross-chat
+    //      navigation:
+    //        - User is on ``/chat/A``. ``active-chat-store`` holds ``A``.
+    //          So ``sticky = A``.
+    //        - User clicks a Recents row for ``B`` →
+    //          ``react-router`` updates pathname to ``/chat/B``.
+    //        - On the synchronous render that follows, ``urlMatch`` is
+    //          ``B`` (read from ``useLocation``) but
+    //          ``useTrackActiveChatFromUrl``'s ``useEffect`` hasn't run
+    //          yet — so ``sticky`` is still ``A``.
+    //        - With ``sticky ?? urlMatch`` we'd compute
+    //          ``effectiveThreadId = A``, bind the AG-UI adapter to ``A``,
+    //          and the first message the user sends would create a NEW
+    //          row at ``A``'s old thread id while the URL says ``B``.
+    //          Symptoms: TWO active dots in the sidebar (URL highlights
+    //          row ``B``, the new row's id activates the dot on a
+    //          freshly-appeared "Untitled chat"); resume appears to
+    //          mint a new conversation; messages land on the wrong row.
+    //      Putting ``urlMatch`` first eliminates the race entirely: when
+    //      the URL says we're on chat ``B``, the runtime targets ``B``
+    //      from the very first render, regardless of stale store state.
+    //   2. ``sticky`` — for non-chat URLs (``/spaces``, ``/tasks`` …)
+    //      ``urlMatch`` is ``undefined``. ``sticky`` keeps the popout
+    //      chat "live" while the user browses elsewhere.
+    //   3. ``freshIdRef.current`` — brand-new chat on ``/`` with no
+    //      sticky and no URL match. Pre-minted so the runtime's
+    //      ``threadId`` is defined from the first render (no
+    //      ``undefined → defined`` remount of assistant-ui).
+    const effectiveThreadId = urlMatch ?? sticky ?? freshIdRef.current;
+    const historyAdapterFactory = useCallback((args) => config.buildHistoryAdapter({
+        urlMatch: args.urlMatch,
+        aguiThreadId: args.aguiThreadId,
+    }), [config]);
+    return (_jsxs(AGUIRuntimeProvider, { fetchFn: fetchFn, threadId: effectiveThreadId, 
+        // ``urlMatch`` carries the URL-derived resume signal verbatim.
+        // ``effectiveThreadId`` is always defined (sticky / urlMatch /
+        // freshly minted UUID) so passing it in place of ``urlMatch``
+        // would erase the "fresh vs resumed" distinction the history
+        // adapter needs to decide whether to load() past messages.
+        urlMatch: urlMatch, historyAdapterFactory: historyAdapterFactory, children: [toolUIs, children] }));
+}
+function ToolUIGroup({ children }) {
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * RFC 4122 v4 UUID. Use ``crypto.randomUUID`` when available; fall
+ * back to a math-random shim for the rare environments without it
+ * (older Safari on non-HTTPS dev hosts). The shim is fine for our
+ * use — these UUIDs identify a conversation row in our backend; they
+ * don't need cryptographic strength.
+ */
+function _genUuid() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Apply the wrappers array outer→inner. wrappers[0] is the outermost; the
+ * last entry is closest to children. Pure render-time composition; no state.
+ */
+function ComposedWrappers({ wrappers, children }) {
+    let tree = children;
+    // Iterate in reverse so wrappers[0] ends up outermost.
+    for (let i = wrappers.length - 1; i >= 0; i--) {
+        const W = wrappers[i];
+        tree = _jsx(W, { children: tree });
+    }
+    return _jsx(_Fragment, { children: tree });
+}

package/dist/shell-layout.d.ts

@@ -0,0 +1,19 @@
+import { type ThemeLayer } from "@iloveagents/foundry-web-ui";
+import type { ChatModule } from "./types.js";
+interface ShellLayoutProps {
+    modules: ChatModule[];
+    baseThemeLayers: ThemeLayer[];
+}
+/**
+ * Generic app layout — rendered as the outlet for the customer's routes.
+ *
+ * Each module contributes:
+ * - `useInit`: hook body run here so React's rules-of-hooks apply.
+ * - `useThemeLayers`: theme layers stacked above `baseThemeLayers`.
+ * - `layoutExtras`: rendered as a sibling group inside <ThemeScope>.
+ *
+ * The shell knows nothing about Spaces — `useSpacesInit`, dialogs, banners
+ * all flow through the module protocol.
+ */
+export declare function ShellLayout({ modules, baseThemeLayers }: ShellLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/shell-layout.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { Outlet, useLocation } from "react-router";
+import { Sidebar, ToolPanelLayout, ChatHeader, ChatBubble, ThemeDocumentMetadata, ThemeRuntimeProvider, ThemeScope, GlobalSelectionPopover, ChatContent, ContextPins, TooltipIconButton, useAppStore, useNavStore, findNavItem, useChatBubbleStore, useThemeStore, } from "@iloveagents/foundry-web-ui";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { X } from "lucide-react";
+/**
+ * Generic app layout — rendered as the outlet for the customer's routes.
+ *
+ * Each module contributes:
+ * - `useInit`: hook body run here so React's rules-of-hooks apply.
+ * - `useThemeLayers`: theme layers stacked above `baseThemeLayers`.
+ * - `layoutExtras`: rendered as a sibling group inside <ThemeScope>.
+ *
+ * The shell knows nothing about Spaces — `useSpacesInit`, dialogs, banners
+ * all flow through the module protocol.
+ */
+export function ShellLayout({ modules, baseThemeLayers }) {
+    // Module init hooks — called in registration order. Rules-of-hooks
+    // require a stable count, so module additions/removals across renders
+    // are forbidden (ChatModule[] is meant to be a static prop).
+    for (const m of modules) {
+        m.useInit?.();
+    }
+    // Module theme-layer hooks — flatten and merge above the static base.
+    const moduleLayers = [];
+    for (const m of modules) {
+        if (m.useThemeLayers) {
+            for (const layer of m.useThemeLayers()) {
+                moduleLayers.push(layer);
+            }
+        }
+    }
+    const themeLayers = [...baseThemeLayers, ...moduleLayers];
+    const themeMode = useThemeStore((s) => s.mode);
+    const { pathname } = useLocation();
+    const isExpanded = useChatBubbleStore((s) => s.isExpanded);
+    const showPagePanel = useChatBubbleStore((s) => s.showPagePanel);
+    // Collapse expanded chat when navigating to root (already full-screen there).
+    useEffect(() => {
+        if (pathname === "/" && isExpanded) {
+            useChatBubbleStore.getState().close();
+        }
+    }, [pathname, isExpanded]);
+    // Sync route + navigation context to app store.
+    const setCurrentPage = useAppStore((s) => s.setCurrentPage);
+    const setNavContext = useAppStore((s) => s.setNavContext);
+    const navConfig = useNavStore((s) => s.config);
+    useEffect(() => {
+        setCurrentPage(pathname);
+        const found = findNavItem(navConfig, pathname);
+        const mergedInstructions = [found?.groupInstructions, found?.item.contextInstructions]
+            .filter(Boolean)
+            .join("\n");
+        setNavContext({
+            group: found?.group ?? null,
+            groupDescription: found?.groupDescription ?? null,
+            groupMeta: found?.groupMeta ?? {},
+            label: found?.item.label ?? pathname,
+            description: found?.item.description ?? null,
+            meta: found?.item.meta ?? {},
+            contextInstructions: mergedInstructions || null,
+        });
+    }, [pathname, navConfig, setCurrentPage, setNavContext]);
+    // Page content (Outlet) — always rendered to keep page tools and context alive.
+    const page = _jsx(Outlet, {});
+    // Aggregate module layoutExtras into a single fragment.
+    const layoutExtras = [];
+    for (const m of modules) {
+        if (m.layoutExtras) {
+            layoutExtras.push(_jsx(ModuleExtra, { children: m.layoutExtras }, m.name));
+        }
+    }
+    return (_jsx(ThemeRuntimeProvider, { layers: themeLayers, mode: themeMode, children: _jsxs(ThemeScope, { className: "flex h-dvh flex-col overflow-hidden bg-background text-foreground", children: [_jsx(ThemeDocumentMetadata, {}), layoutExtras, _jsxs("div", { className: "flex min-h-0 flex-1 overflow-hidden", children: [_jsx(Sidebar, {}), isExpanded ? (_jsx(ToolPanelLayout, { children: _jsxs("div", { className: "flex h-full min-w-0 flex-1 overflow-hidden", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col overflow-hidden", children: [_jsx(ChatHeader, {}), _jsx(ChatContent, {})] }), showPagePanel && (_jsxs("div", { className: cn("hidden h-full shrink-0 border-l border-border bg-background xl:flex xl:flex-col"), style: { width: 600 }, children: [_jsx(PagePanelActions, {}), _jsx("div", { className: "flex-1 flex flex-col min-h-0 overflow-hidden", children: page })] }))] }) })) : (_jsx(ToolPanelLayout, { children: _jsxs("div", { className: "flex flex-1 flex-col overflow-hidden", children: [_jsx(ChatHeader, {}), page] }) }))] }), _jsx(ChatBubble, {}), _jsx(GlobalSelectionPopover, {})] }) }));
+}
+function ModuleExtra({ children }) {
+    return _jsx(_Fragment, { children: children });
+}
+function PagePanelActions() {
+    const togglePagePanel = useChatBubbleStore((s) => s.togglePagePanel);
+    return (_jsx("div", { className: "shrink-0 flex items-center justify-end px-4 py-3 border-b border-border", children: _jsxs("div", { className: "flex items-center gap-0.5", children: [_jsx(ContextPins, { compact: true, flyoutDirection: "down" }), _jsx(TooltipIconButton, { tooltip: "Close panel", size: "icon", onClick: togglePagePanel, children: _jsx(X, { className: "size-4" }) })] }) }));
+}