@iloveagents/foundry-web-shell 0.1.0

package/AGENTS.md

@@ -0,0 +1,82 @@
+Browser bootstrap for the LastSpace agent UI starter. Published as `@iloveagents/foundry-web-shell`. Composes `@iloveagents/foundry-web-primitives`, `@iloveagents/foundry-agent` (and `@iloveagents/foundry-agent/msal`), and `@iloveagents/foundry-web-ui` into a generic mounting point — customers and modules contribute pages, theme layers, layout extras, tool UIs, and per-request fetch interceptors via the `ChatModule` protocol.
+
+# Architecture
+
+Source-shipping (no build step) — same convention as the other `@lastspace/*` packages.
+
+```
+src/
+  index.ts                 ← public barrel (bootstrapShell, ChatModule, defineChatModule, types)
+  bootstrap-shell.tsx      ← entry point: installs fetch interceptors, calls createRoot
+  shell-app.tsx            ← <BrowserRouter> → AuthProvider → [wrappers outer→inner] → AGUIRuntimeProvider → {toolUIs} → Suspense → Routes
+  shell-layout.tsx         ← generic layout (Sidebar + ChatHeader + ToolPanelLayout + ChatBubble + GlobalSelectionPopover + module layoutExtras)
+  types.ts                 ← ChatModule, ShellPage, AuthAdapter, BootstrapShellOptions
+  auth-default.tsx         ← default authProvider (wraps @iloveagents/foundry-web-ui's AuthProvider; reads MsalAuthConfig from import.meta.env)
+  service-fetch-default.ts ← default fetchFn (createServiceFetch + tokenFetch wiring)
+```
+
+# Public API
+
+```ts
+import { bootstrapShell, defineChatModule, type ChatModule } from "@iloveagents/foundry-web-shell";
+```
+
+`bootstrapShell({ modules, pages, theme, authProvider, strictMode })` mounts the SPA. Each `ChatModule` may contribute:
+
+- `useInit?: () => void` — React hook body called inside the layout (rules-of-hooks apply).
+- `toolUIs?: ReactNode` — rendered inside `<AGUIRuntimeProvider>`.
+- `layoutExtras?: ReactNode` — rendered inside the layout (banners, dialogs, popovers).
+- `wrappers?: ComponentType<{ children }>[]` — applied outer→inner from array.
+- `useThemeLayers?: () => ThemeLayer[]` — hook returning theme layers; merged on top of static `theme` prop.
+- `pages?: { path; element }[]` — appended to Routes; customer `pages` win on path collision. (Sidebar nav items are mutated via `useNavStore.getState().setConfig(...)` inside `useInit` — see Spaces' `useSpacesNavSync` for the pattern.)
+- `fetchInterceptor?: () => void` — installed before `createRoot` (use to install global fetch wrappers).
+
+# Wrapper ordering
+
+```
+<StrictMode>
+  <BrowserRouter>
+    <AuthProvider>
+      {wrappers outer→inner from modules}
+        <AGUIRuntimeProvider>
+          {toolUIs}
+          <Suspense>
+            <Routes>
+              <Route element={<ShellLayout />}>
+                {pages — customer wins on path collision}
+              </Route>
+            </Routes>
+          </Suspense>
+        </AGUIRuntimeProvider>
+      {/wrappers}
+    </AuthProvider>
+  </BrowserRouter>
+</StrictMode>
+```
+
+Asserted by `src/__tests__/wrapper-order.test.tsx`.
+
+# Import boundary (enforced by guard test)
+
+`@iloveagents/foundry-web-shell` MAY import: `@iloveagents/foundry-web-primitives`, `@iloveagents/foundry-web-ui`, `@iloveagents/foundry-agent` (+ subpaths). MUST NOT import `@lastspace/spaces-web-ui` — modules are runtime parameters, never compile-time deps. Enforced by `OPEN_CORE_GRAPH` in `packages/web-ui/src/__tests__/open-core-guards.test.ts`.
+
+`packages/web-shell/src/` MUST stay ≤ 15 files (file-count ceiling, hardFail).
+
+# Theme
+
+`bootstrapShell({ theme })` provides static base layers. Modules' `useThemeLayers()` hooks return additional layers stacked on top in module-array order. Final layers feed `<ThemeRuntimeProvider layers={...}>`.
+
+# Auth
+
+The default `authProvider` reads `VITE_MSAL_CLIENT_ID`, `VITE_MSAL_AUTHORITY`, `VITE_MSAL_API_SCOPE` from `import.meta.env`. Missing keys render the `AuthConfigError` UI. Customers can override with `authProvider={{ Provider: MyAuthProvider }}` for testing or non-MSAL deployments.
+
+# Commands
+
+```bash
+pnpm --filter @iloveagents/foundry-web-shell test:unit   # vitest run
+pnpm --filter @iloveagents/foundry-web-shell typecheck   # tsc --noEmit
+```
+
+# Authoring a module
+
+See [`docs/AUTHORING_A_MODULE.md`](../../docs/AUTHORING_A_MODULE.md).

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iLoveAgents, a brand of Leitwolf GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@iloveagents/foundry-web-shell",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.0.0",
+    "@assistant-ui/react": "^0.12.25",
+    "lucide-react": ">=0.400.0",
+    "zustand": "^5.0.0",
+    "@iloveagents/foundry-agent": "0.1.0",
+    "@iloveagents/foundry-web-primitives": "0.1.0",
+    "@iloveagents/foundry-web-ui": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "vite": "^7.2.2",
+    "vitest": "^4.1.4",
+    "jsdom": "^28.1.0",
+    "@testing-library/react": "^16.0.0"
+  },
+  "scripts": {
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/module-bootstrap.test.tsx

@@ -0,0 +1,142 @@
+/**
+ * Module-bootstrap test.
+ *
+ * Asserts that every ChatModule extension point fires when ShellApp is
+ * rendered. Bypasses bootstrap-shell.tsx (which calls createRoot) and
+ * renders ShellApp directly so we can probe React's tree.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { defineChatModule, type ChatModule, type ShellPage } from "../types.ts";
+
+// Mock the web-ui surface the shell consumes. Don't spread the real
+// module — its top-level zustand stores call window.matchMedia at import
+// time, which jsdom doesn't provide. We only need the symbols ShellApp
+// + ShellLayout import directly.
+vi.mock("@iloveagents/foundry-web-ui", () => ({
+  AuthProvider: ({ children }: { children: ReactNode }) => <>{children}</>,
+  AGUIRuntimeProvider: ({ children }: { children: ReactNode }) => <>{children}</>,
+  Sidebar: () => <div data-testid="sidebar" />,
+  ChatHeader: () => <div data-testid="chat-header" />,
+  ChatBubble: () => <div data-testid="chat-bubble" />,
+  ChatContent: () => <div data-testid="chat-content" />,
+  ToolPanelLayout: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeRuntimeProvider: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeScope: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeDocumentMetadata: () => null,
+  GlobalSelectionPopover: () => null,
+  ContextPins: () => null,
+  TooltipIconButton: ({ children }: { children: ReactNode }) => <>{children}</>,
+  findNavItem: () => undefined,
+  useAppStore: (selector: (s: any) => unknown) =>
+    selector({ setCurrentPage: () => undefined, setNavContext: () => undefined }),
+  useNavStore: (selector: (s: any) => unknown) => selector({ config: [] }),
+  useChatBubbleStore: Object.assign(
+    (selector: (s: any) => unknown) =>
+      selector({
+        isExpanded: false,
+        showPagePanel: false,
+        togglePagePanel: () => undefined,
+      }),
+    { getState: () => ({ close: () => undefined }) },
+  ),
+  useThemeStore: (selector: (s: any) => unknown) => selector({ mode: "system" }),
+}));
+
+vi.mock("@iloveagents/foundry-web-primitives", () => ({
+  cn: (...classes: unknown[]) => classes.filter(Boolean).join(" "),
+}));
+
+vi.mock("@iloveagents/foundry-agent", () => ({
+  createServiceFetch: () => fetch,
+}));
+
+vi.mock("@iloveagents/foundry-agent/msal", () => ({
+  authStore: { getState: () => ({ getAccessToken: () => Promise.resolve("") }) },
+}));
+
+import { ShellApp } from "../shell-app.tsx";
+import type { AuthAdapter } from "../types.ts";
+
+const noopAuth: AuthAdapter = {
+  Provider: ({ children }) => <>{children}</>,
+};
+
+describe("ChatModule bootstrap composition", () => {
+  it("calls every extension point when ShellApp renders", async () => {
+    const useInit = vi.fn();
+    const useThemeLayers = vi.fn(() => []);
+    const wrapperRendered = vi.fn();
+
+    function ProbeWrapper({ children }: { children: ReactNode }) {
+      wrapperRendered();
+      return <div data-testid="probe-wrapper">{children}</div>;
+    }
+
+    const homePage: ShellPage = {
+      path: "/",
+      element: <div data-testid="home-page">home</div>,
+    };
+
+    const moduleHome: ShellPage = {
+      path: "/",
+      element: <div data-testid="module-home">module home</div>,
+    };
+
+    const modulePage: ShellPage = {
+      path: "elsewhere",
+      element: <div data-testid="module-page">module elsewhere</div>,
+    };
+
+    const m: ChatModule = defineChatModule({
+      name: "test",
+      useInit,
+      useThemeLayers,
+      toolUIs: <div data-testid="tool-ui-marker" />,
+      layoutExtras: <div data-testid="layout-extra-marker" />,
+      wrappers: [ProbeWrapper],
+      pages: [moduleHome, modulePage],
+    });
+
+    render(
+      <ShellApp
+        modules={[m]}
+        pages={[homePage]}
+        baseThemeLayers={[]}
+        authProvider={noopAuth}
+        agentFetch={fetch}
+      />,
+    );
+
+    // useInit hook fired.
+    await waitFor(() => expect(useInit).toHaveBeenCalled());
+
+    // useThemeLayers hook fired.
+    expect(useThemeLayers).toHaveBeenCalled();
+
+    // Module wrapper rendered.
+    expect(screen.getByTestId("probe-wrapper")).toBeTruthy();
+    expect(wrapperRendered).toHaveBeenCalled();
+
+    // Tool UI rendered.
+    expect(screen.getByTestId("tool-ui-marker")).toBeTruthy();
+
+    // Layout extra rendered.
+    expect(screen.getByTestId("layout-extra-marker")).toBeTruthy();
+
+    // Customer page wins on path collision (/ resolves to home-page, not module-home).
+    expect(screen.getByTestId("home-page")).toBeTruthy();
+    expect(screen.queryByTestId("module-home")).toBeNull();
+  });
+
+  it("invokes fetchInterceptor (verified by bootstrap-shell test)", () => {
+    // bootstrap-shell.tsx wraps installSpacesFetchInterceptor BEFORE createRoot.
+    // The contract is that ShellApp itself does not invoke it — bootstrap-shell does.
+    // This test just guards the type marker (`defineChatModule` is identity-typed).
+    const interceptor = vi.fn();
+    const m = defineChatModule({ name: "x", fetchInterceptor: interceptor });
+    expect(m.fetchInterceptor).toBe(interceptor);
+    expect(interceptor).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/wrapper-order.test.tsx

@@ -0,0 +1,162 @@
+/**
+ * Wrapper-order test.
+ *
+ * Asserts the contractual outer→inner ordering: BrowserRouter wraps
+ * AuthProvider wraps [module wrappers] wraps AGUIRuntimeProvider wraps
+ * Routes. Uses a depth-marker context — each layer increments the depth
+ * via a Provider, and a probe component reads the depth at render time.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { createContext, useContext, type ReactNode } from "react";
+import { useLocation } from "react-router";
+import { defineChatModule, type ChatModule, type ShellPage } from "../types.ts";
+
+const DepthContext = createContext<number>(-1);
+
+function makeWrapper(label: string, expectedDepth: number) {
+  return function Wrap({ children }: { children: ReactNode }) {
+    const incoming = useContext(DepthContext);
+    // Each wrapper asserts its own depth via the test contract.
+    // Using a side-effect ref so the assertion runs even if children
+    // never resolve (e.g. routing to a no-match path).
+    seen[label] = incoming;
+    return (
+      <DepthContext.Provider value={incoming + 1}>{children}</DepthContext.Provider>
+    );
+  };
+}
+
+const seen: Record<string, number> = {};
+
+// Probe inside the route confirms BrowserRouter is reachable + reports the
+// final inner depth.
+function RouteProbe() {
+  const depth = useContext(DepthContext);
+  const location = useLocation();
+  seen["route-probe"] = depth;
+  seen["route-pathname"] = location.pathname.length;
+  return <div data-testid="route-probe">probe</div>;
+}
+
+// Mock the web-ui surface the shell consumes. AuthProvider +
+// AGUIRuntimeProvider are wrapped with the depth context so the test
+// can probe their nesting order. Don't spread the real module — its
+// stores call window.matchMedia at import time and jsdom doesn't have
+// that.
+vi.mock("@iloveagents/foundry-web-ui", () => ({
+  AuthProvider: ({ children }: { children: ReactNode }) => {
+    const incoming = useContext(DepthContext);
+    seen["auth-provider"] = incoming;
+    return (
+      <DepthContext.Provider value={incoming + 1}>{children}</DepthContext.Provider>
+    );
+  },
+  AGUIRuntimeProvider: ({ children }: { children: ReactNode }) => {
+    const incoming = useContext(DepthContext);
+    seen["agui-runtime"] = incoming;
+    return (
+      <DepthContext.Provider value={incoming + 1}>{children}</DepthContext.Provider>
+    );
+  },
+  Sidebar: () => null,
+  ChatHeader: () => null,
+  ChatBubble: () => null,
+  ChatContent: () => null,
+  ToolPanelLayout: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeRuntimeProvider: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeScope: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ThemeDocumentMetadata: () => null,
+  GlobalSelectionPopover: () => null,
+  ContextPins: () => null,
+  TooltipIconButton: ({ children }: { children: ReactNode }) => <>{children}</>,
+  findNavItem: () => undefined,
+  useAppStore: (selector: (s: any) => unknown) =>
+    selector({ setCurrentPage: () => undefined, setNavContext: () => undefined }),
+  useNavStore: (selector: (s: any) => unknown) => selector({ config: [] }),
+  useChatBubbleStore: Object.assign(
+    (selector: (s: any) => unknown) =>
+      selector({
+        isExpanded: false,
+        showPagePanel: false,
+        togglePagePanel: () => undefined,
+      }),
+    { getState: () => ({ close: () => undefined }) },
+  ),
+  useThemeStore: (selector: (s: any) => unknown) => selector({ mode: "system" }),
+}));
+
+vi.mock("@iloveagents/foundry-web-primitives", () => ({
+  cn: (...classes: unknown[]) => classes.filter(Boolean).join(" "),
+}));
+
+vi.mock("@iloveagents/foundry-agent", () => ({
+  createServiceFetch: () => fetch,
+}));
+
+vi.mock("@iloveagents/foundry-agent/msal", () => ({
+  authStore: { getState: () => ({ getAccessToken: () => Promise.resolve("") }) },
+}));
+
+import { ShellApp } from "../shell-app.tsx";
+import type { AuthAdapter } from "../types.ts";
+// Imported AFTER vi.mock so this resolves to the mocked AuthProvider.
+import { AuthProvider as MockedAuthProvider } from "@iloveagents/foundry-web-ui";
+
+describe("Shell wrapper ordering contract", () => {
+  it("nests BrowserRouter > AuthProvider > [module wrappers] > AGUIRuntimeProvider > Routes", async () => {
+    Object.keys(seen).forEach((k) => delete seen[k]);
+
+    const ModuleWrapperA = makeWrapper("module-a", 2);
+    const ModuleWrapperB = makeWrapper("module-b", 3);
+
+    const m: ChatModule = defineChatModule({
+      name: "test",
+      wrappers: [ModuleWrapperA, ModuleWrapperB],
+    });
+
+    const homePage: ShellPage = {
+      path: "/",
+      element: <RouteProbe />,
+    };
+
+    // The auth adapter under test wraps children with the mocked
+    // AuthProvider from web-ui (which counts depth). In production
+    // defaultAuthAdapter does the same — this just makes the contract
+    // explicit for the test.
+    const auth: AuthAdapter = {
+      Provider: ({ children }: { children: ReactNode }) => (
+        // The vi.mock factory above replaces this provider's runtime impl with one
+        // that ignores `config`, but TypeScript only sees the real component's
+        // signature. Cast to satisfy the prop requirement without a real config.
+        <MockedAuthProvider config={{} as never}>{children}</MockedAuthProvider>
+      ),
+    };
+
+    render(
+      <ShellApp
+        modules={[m]}
+        pages={[homePage]}
+        baseThemeLayers={[]}
+        authProvider={auth}
+        agentFetch={fetch}
+      />,
+    );
+
+    // Wait for the route probe to render.
+    await waitFor(() => expect(seen["route-probe"]).toBeDefined());
+
+    // Layer depths (each Provider sees the incoming depth, then adds 1).
+    // BrowserRouter does not use DepthContext, so the first layer to bump
+    // the depth is AuthProvider (sees depth -1, advances to 0).
+    expect(seen["auth-provider"]).toBe(-1);
+    // ProbeWrapper (the test mock around the AuthProvider mock) ran AFTER
+    // AuthProvider — module wrappers nest INSIDE AuthProvider.
+    expect(seen["module-a"]).toBe(0);
+    expect(seen["module-b"]).toBe(1);
+    // AGUIRuntimeProvider nests INSIDE module wrappers.
+    expect(seen["agui-runtime"]).toBe(2);
+    // RouteProbe nests INSIDE AGUIRuntimeProvider.
+    expect(seen["route-probe"]).toBe(3);
+  });
+});

package/src/auth-default.tsx

@@ -0,0 +1,75 @@
+import type { FC, ReactNode } from "react";
+import { AuthProvider } from "@iloveagents/foundry-web-ui";
+import type { MsalAuthConfig } from "@iloveagents/foundry-agent/msal";
+import type { AuthAdapter } from "./types.ts";
+
+
+
+interface AuthConfigErrorProps {
+  missingKeys: string[];
+}
+
+function AuthConfigError({ missingKeys }: AuthConfigErrorProps) {
+  return (
+    <div className="flex min-h-dvh items-center justify-center bg-background px-6 text-center">
+      <div className="max-w-md rounded-2xl border border-border bg-card px-6 py-5 shadow-sm">
+        <h1 className="text-lg font-semibold text-foreground">Authentication unavailable</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          Missing required MSAL environment variables: {missingKeys.join(", ")}.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Read MSAL configuration from Vite env. Returns the resolved config or the
+ * list of missing keys. The shell renders <AuthConfigError /> when any key
+ * is missing.
+ */
+function readMsalConfigFromEnv(): MsalAuthConfig | { missing: string[] } {
+  const env = import.meta.env;
+  const clientId = env.VITE_MSAL_CLIENT_ID;
+  const authority = env.VITE_MSAL_AUTHORITY;
+  const apiScope = env.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 is string => v !== null);
+  if (missing.length > 0) return { missing };
+  return {
+    clientId: clientId!,
+    authority: authority!,
+    apiScope: apiScope!,
+    redirectUri: window.location.origin,
+  };
+}
+
+/**
+ * Default MSAL-backed auth adapter. Reads VITE_MSAL_* from import.meta.env.
+ * Customers override via `bootstrapShell({ authProvider: { Provider: ... } })`
+ * for tests or non-MSAL deployments.
+ */
+export const defaultAuthAdapter: AuthAdapter = {
+  Provider: ({ children }: { children: ReactNode }) => {
+    const result = readMsalConfigFromEnv();
+    if ("missing" in result) {
+      return <AuthConfigError missingKeys={result.missing} />;
+    }
+    return <AuthProvider config={result}>{children}</AuthProvider>;
+  },
+};
+
+/**
+ * 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: FC<{ adapter?: AuthAdapter; children: ReactNode }> = ({
+  adapter,
+  children,
+}) => {
+  const Adapter = (adapter ?? defaultAuthAdapter).Provider;
+  return <Adapter>{children}</Adapter>;
+};

package/src/bootstrap-shell.tsx

@@ -0,0 +1,49 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ShellApp } from "./shell-app.tsx";
+import type { BootstrapShellOptions } from "./types.ts";
+
+/**
+ * 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: BootstrapShellOptions = {}): void {
+  const {
+    modules = [],
+    pages = [],
+    theme = [],
+    authProvider,
+    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 = (
+    <ShellApp
+      modules={modules}
+      pages={pages}
+      baseThemeLayers={theme}
+      authProvider={authProvider}
+    />
+  );
+
+  // 3. Mount with StrictMode by default.
+  createRoot(root).render(strictMode ? <StrictMode>{tree}</StrictMode> : tree);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { bootstrapShell } from "./bootstrap-shell.tsx";
+export { ShellApp } from "./shell-app.tsx";
+export { ShellLayout } from "./shell-layout.tsx";
+export { defaultAuthAdapter, ShellAuth } from "./auth-default.tsx";
+export { defaultAgentFetch } from "./service-fetch-default.ts";
+export { defineChatModule } from "./types.ts";
+export type {
+  ChatModule,
+  ShellPage,
+  AuthAdapter,
+  BootstrapShellOptions,
+} from "./types.ts";

package/src/service-fetch-default.ts

@@ -0,0 +1,12 @@
+import { createServiceFetch } from "@iloveagents/foundry-agent";
+import { authStore } from "@iloveagents/foundry-agent/msal";
+
+/**
+ * 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.
+ */
+export const defaultAgentFetch: typeof fetch = createServiceFetch({
+  acquireToken: () => authStore.getState().getAccessToken("api"),
+  baseUrl: import.meta.env.VITE_API_BASE_URL,
+});

package/src/shell-app.tsx

@@ -0,0 +1,111 @@
+import { type ReactNode, Suspense, useMemo } from "react";
+import { BrowserRouter, Routes, Route } from "react-router";
+import { AGUIRuntimeProvider } from "@iloveagents/foundry-web-ui";
+import type { ThemeLayer } from "@iloveagents/foundry-web-ui";
+import type { ChatModule, AuthAdapter, ShellPage } from "./types.ts";
+import { ShellAuth } from "./auth-default.tsx";
+import { ShellLayout } from "./shell-layout.tsx";
+import { defaultAgentFetch } from "./service-fetch-default.ts";
+
+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 function ShellApp({
+  modules,
+  pages,
+  baseThemeLayers,
+  authProvider,
+  agentFetch,
+}: ShellAppProps) {
+  // 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: ShellPage[] = [];
+    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: React.ComponentType<{ children: ReactNode }>[] = [];
+    for (const m of modules) {
+      for (const W of m.wrappers ?? []) out.push(W);
+    }
+    return out;
+  }, [modules]);
+
+  // Aggregate module toolUIs.
+  const toolUIs: ReactNode[] = [];
+  for (const m of modules) {
+    if (m.toolUIs) {
+      toolUIs.push(<ToolUIGroup key={m.name}>{m.toolUIs}</ToolUIGroup>);
+    }
+  }
+
+  const fetchFn = agentFetch ?? defaultAgentFetch;
+
+  return (
+    <BrowserRouter>
+      <ShellAuth adapter={authProvider}>
+        <ComposedWrappers wrappers={wrappers}>
+          <AGUIRuntimeProvider fetchFn={fetchFn}>
+            {toolUIs}
+            <Suspense fallback={null}>
+              <Routes>
+                <Route element={<ShellLayout modules={modules} baseThemeLayers={baseThemeLayers} />}>
+                  {mergedPages.map((p) => (
+                    <Route key={p.path} path={p.path === "/" ? undefined : p.path} index={p.path === "/"} element={p.element} />
+                  ))}
+                </Route>
+              </Routes>
+            </Suspense>
+          </AGUIRuntimeProvider>
+        </ComposedWrappers>
+      </ShellAuth>
+    </BrowserRouter>
+  );
+}
+
+function ToolUIGroup({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}
+
+interface ComposedWrappersProps {
+  wrappers: React.ComponentType<{ children: ReactNode }>[];
+  children: ReactNode;
+}
+
+/**
+ * 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 }: ComposedWrappersProps) {
+  let tree: ReactNode = children;
+  // Iterate in reverse so wrappers[0] ends up outermost.
+  for (let i = wrappers.length - 1; i >= 0; i--) {
+    const W = wrappers[i];
+    tree = <W>{tree}</W>;
+  }
+  return <>{tree}</>;
+}

package/src/shell-layout.tsx

@@ -0,0 +1,171 @@
+import { type ReactNode, 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,
+  type ThemeLayer,
+} from "@iloveagents/foundry-web-ui";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { X } from "lucide-react";
+import type { ChatModule } from "./types.ts";
+
+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 function ShellLayout({ modules, baseThemeLayers }: ShellLayoutProps) {
+  // 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: ThemeLayer[] = [];
+  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 = <Outlet />;
+
+  // Aggregate module layoutExtras into a single fragment.
+  const layoutExtras: ReactNode[] = [];
+  for (const m of modules) {
+    if (m.layoutExtras) {
+      layoutExtras.push(<ModuleExtra key={m.name}>{m.layoutExtras}</ModuleExtra>);
+    }
+  }
+
+  return (
+    <ThemeRuntimeProvider layers={themeLayers} mode={themeMode}>
+      <ThemeScope className="flex h-dvh flex-col overflow-hidden bg-background text-foreground">
+        <ThemeDocumentMetadata />
+        {layoutExtras}
+
+        <div className="flex min-h-0 flex-1 overflow-hidden">
+          <Sidebar />
+
+          {isExpanded ? (
+            <ToolPanelLayout>
+              <div className="flex h-full min-w-0 flex-1 overflow-hidden">
+                <div className="flex min-w-0 flex-1 flex-col overflow-hidden">
+                  <ChatHeader />
+                  <ChatContent />
+                </div>
+
+                {showPagePanel && (
+                  <div
+                    className={cn(
+                      "hidden h-full shrink-0 border-l border-border bg-background xl:flex xl:flex-col",
+                    )}
+                    style={{ width: 600 }}
+                  >
+                    <PagePanelActions />
+                    <div className="flex-1 flex flex-col min-h-0 overflow-hidden">{page}</div>
+                  </div>
+                )}
+              </div>
+            </ToolPanelLayout>
+          ) : (
+            <ToolPanelLayout>
+              <div className="flex flex-1 flex-col overflow-hidden">
+                <ChatHeader />
+                {page}
+              </div>
+            </ToolPanelLayout>
+          )}
+        </div>
+
+        <ChatBubble />
+        <GlobalSelectionPopover />
+      </ThemeScope>
+    </ThemeRuntimeProvider>
+  );
+}
+
+function ModuleExtra({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}
+
+function PagePanelActions() {
+  const togglePagePanel = useChatBubbleStore((s) => s.togglePagePanel);
+
+  return (
+    <div className="shrink-0 flex items-center justify-end px-4 py-3 border-b border-border">
+      <div className="flex items-center gap-0.5">
+        <ContextPins compact flyoutDirection="down" />
+        <TooltipIconButton tooltip="Close panel" size="icon" onClick={togglePagePanel}>
+          <X className="size-4" />
+        </TooltipIconButton>
+      </div>
+    </div>
+  );
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ThemeLayer } from "@iloveagents/foundry-web-ui";
+
+/** Route entry contributed by a module or the host app. */
+export interface ShellPage {
+  path: string;
+  element: ReactNode;
+}
+
+/**
+ * A ChatModule is the unit of composition for `bootstrapShell`. Each field is
+ * optional — modules contribute what they need:
+ *
+ * - `useInit`: React hook body called once per layout render (rules-of-hooks
+ *   apply). Use for cross-store sync, registry registration, etc.
+ *   Modules wanting to mutate `useNavStore` config (sidebar nav items)
+ *   do it inside `useInit` — see Spaces' `useSpacesNavSync()` for the
+ *   canonical pattern.
+ * - `toolUIs`: ReactNode rendered inside `<AGUIRuntimeProvider>`. Use to
+ *   register `makeAssistantToolUI` instances.
+ * - `layoutExtras`: ReactNode rendered inside the shell layout (banners,
+ *   global dialogs, popovers).
+ * - `wrappers`: ComponentType<{children}>[] applied outer→inner from the
+ *   array. Wrap providers like SpacesQueryProvider here.
+ * - `useThemeLayers`: hook returning ThemeLayer[]; merged on top of the
+ *   static `theme` prop in module-array order.
+ * - `pages`: ShellPage[] appended to Routes; customer-supplied `pages` win
+ *   on path collision.
+ * - `fetchInterceptor`: zero-arg installer called once before `createRoot`.
+ *   Use to install `window.fetch` wrappers.
+ */
+export interface ChatModule {
+  name: string;
+  useInit?: () => void;
+  toolUIs?: ReactNode;
+  layoutExtras?: ReactNode;
+  wrappers?: ComponentType<{ children: ReactNode }>[];
+  useThemeLayers?: () => ThemeLayer[];
+  pages?: ShellPage[];
+  fetchInterceptor?: () => void;
+}
+
+/**
+ * Adapter for plugging in an auth Provider. The Provider renders children
+ * once authenticated and is responsible for resolving its own config
+ * (the default reads MSAL settings from `import.meta.env`). Tests and
+ * non-MSAL deployments override with a different Provider.
+ */
+export interface AuthAdapter {
+  Provider: ComponentType<{ children: ReactNode }>;
+}
+
+export interface BootstrapShellOptions {
+  modules?: ChatModule[];
+  /** Customer-supplied pages — win over module pages on `path` collision. */
+  pages?: ShellPage[];
+  /** Static base theme layers; modules' useThemeLayers stack on top. */
+  theme?: ThemeLayer[];
+  /** Override default MSAL-backed auth provider (e.g. for tests). */
+  authProvider?: AuthAdapter;
+  /** Wrap the tree in <StrictMode>. Default: true. */
+  strictMode?: boolean;
+  /** DOM element to mount into. Default: document.getElementById("root"). */
+  rootElement?: HTMLElement;
+}
+
+/** Pass-through helper that adds nothing at runtime — pure type marker. */
+export function defineChatModule(m: ChatModule): ChatModule {
+  return m;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    globals: false,
+    include: ["src/**/__tests__/**/*.test.{ts,tsx}"],
+  },
+});