@iloveagents/foundry-web-ui 0.1.0

package/AGENTS.md

@@ -0,0 +1,59 @@
+React UI core for the AG-UI protocol starter — hooks, stores, extension-point registries, assistant-ui adapter shim, ChatPanel, sidebar, layout components. Published as `@iloveagents/foundry-web-ui`.
+
+Depends on `@iloveagents/foundry-web-primitives` (leaf primitives) and `@iloveagents/foundry-agent` (cross-runtime agent transport: AG-UI runner, vanilla stores, MSAL subpath, service-fetch factory).
+
+# Architecture
+
+Relative imports only (no `@/` alias). Cross-package consumers use `@iloveagents/foundry-web-ui`.
+
+```
+src/
+  components/   ← UI components (sidebar, chat, tool-panel, markdown, etc.)
+  lib/          ← React-coupled stores, the assistant-ui adapter shim,
+                  the React MSAL provider, hooks, utilities.
+  ui/           ← shadcn/radix primitives (tooltip, collapsible, dropdown, dialog, popover, select)
+  index.ts      ← barrel export (all public API)
+```
+
+# Import Boundary (enforced by guard test)
+
+- MUST NOT import from `@lastspace/spaces-web-ui`
+- MUST NOT use `@/` path aliases (relative imports only)
+- MUST NOT import from `features/` or `pages/` (those are app-level)
+- Cross-runtime transport (AG-UI runner, registry, vanilla stores, MSAL token store) lives in `@iloveagents/foundry-agent`. Re-exporting it from this package is forbidden by the no-shim rule (#90/#95).
+
+# Extension Points
+
+SPACES and other feature modules plug in via these registries:
+
+- **NavItem.dnd** (`nav-config.ts`): drag-and-drop behavior on sidebar items
+- **NavItem.dimmed / NavItem.badge** (`nav-config.ts`): visual modifiers on sidebar items
+- **NavGroupCreateAction** (`nav-config.ts`): "+ New" actions on nav group headers
+- **NavGroup.collapsedRail** (`nav-config.ts`): module-supplied renderer for the collapsed sidebar rail. Used when a group's collapsed view isn't a flat icon list — e.g. Spaces' "header link + active workspace's root".
+- **NavFooterAction** (`nav-store.ts`): action buttons in the sidebar footer
+- **Panel renderer registry** (`tool-panel-store.ts`): custom content renderers for the side panel (PDF, entity pages)
+- **Citation handler** (`citationStore` in `@iloveagents/foundry-agent`): handles `[n]` citation clicks in markdown
+- **Tool UI** (via `makeAssistantToolUI` from `@assistant-ui/react`): custom rendering for agent tools
+
+# Adding Extension Points
+
+1. Define interface in the relevant store (e.g., `PanelRendererEntry`)
+2. Add registry array + register function to the store
+3. Component reads from registry and delegates rendering
+4. Feature module calls `registerX()` at init time
+
+# AG-UI Adapter
+
+- This package ships an `AGUIAdapterSDK` shim (`src/lib/ag-ui-adapter.ts`) that implements assistant-ui's `ChatModelAdapter` by wrapping `AGUIRunner` from `@iloveagents/foundry-agent`. The runner does the protocol; the shim translates `RunnerEvent`s into cumulative `ChatModelRunResult` yields.
+- `@assistant-ui/react` must stay on **0.12.x or newer** — 0.11.x has a `_getInitializePromise` runtime regression.
+- Tool UIs use `makeAssistantToolUI(...)` (the v0.12 canonical pattern). The legacy `useAssistantToolUI` hook is no longer used.
+- Hook renames per v0.12: `useAssistantApi → useAui`, `useAssistantState → useAuiState`, `useAssistantEvent → useAuiEvent`.
+
+# Client-Side Tools
+
+Tools live in `clientToolRegistry` (vanilla zustand store in `@iloveagents/foundry-agent`). The runner sends schemas to the backend, intercepts `TOOL_CALL_END` for any client-side tool, executes it locally, and replays the assistant + tool messages on the next turn with the same `toolCallId`.
+
+- **`ui_*`** — global tools registered at app init in `lib/client-tools.ts` (`ui_navigate`, `ui_set_theme`, `ui_open_panel`, `ui_select_item`, `ui_update_content`, `ui_highlight`, `ui_get_context`, `ui_confirm`).
+- **`page_*`** — page-specific tools registered via `usePageTools([{ name, description, parameters, execute }])`.
+
+Custom tool UIs are top-level `makeAssistantToolUI(...)` constants rendered as children inside the `AssistantRuntimeProvider` tree (see `client-tool-executor.tsx`).

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/README.md

@@ -0,0 +1,41 @@
+# @iloveagents/foundry-web-ui
+
+React UI core for the AG-UI protocol agent starter. Provides hooks, stores, extension-point registries, the AG-UI adapter, ChatPanel, sidebar, and layout components. Depends on `@iloveagents/foundry-web-primitives` for leaf primitives (Button, Input, Field, Checkbox, Textarea, `cn`).
+
+## Install
+
+```bash
+pnpm add @iloveagents/foundry-web-ui @iloveagents/foundry-web-primitives
+```
+
+## Usage
+
+```tsx
+import {
+  AGUIRuntimeProvider,
+  Sidebar,
+  ChatContent,
+  ToolPanel,
+  useAppStore,
+  usePageTools,
+} from "@iloveagents/foundry-web-ui";
+import { cn } from "@iloveagents/foundry-web-primitives";
+```
+
+Consumed as TypeScript source (no build step). Requires Tailwind v4 `@source` directives for both packages:
+
+```css
+@source "../../packages/web-primitives/src";
+@source "../../packages/web-ui/src";
+```
+
+## Extension Points
+
+Feature modules (like SPACES) plug into `@iloveagents/foundry-web-ui` via registries — no direct imports needed:
+
+- **NavItem.dnd** — drag-and-drop behavior on sidebar items
+- **Panel renderer registry** — custom content renderers for the side panel
+- **Citation handler** — handles `[n]` citation clicks in markdown
+- **Tool UI** — custom rendering for agent tools via `useAssistantToolUI`
+
+See [AGENTS.md](./AGENTS.md) for architecture details and import boundary rules.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@iloveagents/foundry-web-ui",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.0.0",
+    "@assistant-ui/react": "^0.12.25",
+    "@assistant-ui/react-markdown": "^0.12.9",
+    "@ag-ui/client": "^0.0.52",
+    "@ag-ui/core": "^0.0.52",
+    "zustand": "^5.0.0",
+    "lucide-react": ">=0.400.0",
+    "@azure/msal-browser": "^5.0.0",
+    "@azure/msal-react": "^5.0.0",
+    "@iloveagents/foundry-agent": "0.1.0",
+    "@iloveagents/foundry-web-primitives": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@azure/msal-browser": {
+      "optional": true
+    },
+    "@azure/msal-react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-collapsible": "^1.1.0",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.0",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-slot": "^1.2.0",
+    "@radix-ui/react-tooltip": "^1.2.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^3.5.0",
+    "react-markdown": "^10.0.0",
+    "remark-gfm": "^4.0.0",
+    "shiki": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "@types/react": "^19.2.2",
+    "vitest": "^4.1.4",
+    "jsdom": "^28.1.0"
+  },
+  "scripts": {
+    "test:unit": "vitest run"
+  }
+}

package/src/__tests__/no-spaces-imports.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Guard test: @iloveagents/foundry-web-ui must never import from @lastspace/spaces-web-ui.
+ * This prevents SPACES code from leaking back into the React UI core package.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+function findFiles(dir: string, ext: string[]): string[] {
+  const results: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (entry === "node_modules" || entry === "__tests__") continue;
+    if (statSync(full).isDirectory()) {
+      results.push(...findFiles(full, ext));
+    } else if (ext.some((e) => full.endsWith(e))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+describe("@iloveagents/foundry-web-ui import boundaries", () => {
+  const srcDir = join(import.meta.dirname!, "..");
+  const files = findFiles(srcDir, [".ts", ".tsx"]);
+
+  it("must not import from @lastspace/spaces-web-ui", () => {
+    const violations: string[] = [];
+    for (const file of files) {
+      const content = readFileSync(file, "utf-8");
+      if (content.includes("@lastspace/spaces-web-ui")) {
+        violations.push(file.replace(srcDir + "/", ""));
+      }
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it("must not import from @content-editor/react (legacy name)", () => {
+    const violations: string[] = [];
+    for (const file of files) {
+      const content = readFileSync(file, "utf-8");
+      if (content.includes("@content-editor/react")) {
+        violations.push(file.replace(srcDir + "/", ""));
+      }
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it("must not use @/ path aliases (uses relative imports)", () => {
+    const violations: string[] = [];
+    for (const file of files) {
+      const content = readFileSync(file, "utf-8");
+      if (/from ["']@\//.test(content)) {
+        violations.push(file.replace(srcDir + "/", ""));
+      }
+    }
+    expect(violations).toEqual([]);
+  });
+});

package/src/__tests__/open-core-guards.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Open-core packaging guards.
+ *
+ * Three data-driven guards (the customer-isolation + Python guards from the
+ * lastspace-origin version were dropped — foundry-ui is TS-only, no
+ * customer-specific code lives here):
+ *
+ *  1. Banned imports inside `packages/agent/src/` — no React, no DOM, no
+ *     `@assistant-ui/*`, no bare `"zustand"`. The MSAL subpath is the
+ *     single exception that may import `@azure/msal-browser`.
+ *  2. Open-core import-direction graph — each `@iloveagents/foundry-*`
+ *     package may only import from a declared subset of siblings.
+ *  3. File-count ceiling on `packages/web-shell/src` — the shell stays
+ *     thin (composition layer, not application surface).
+ *  4. Version-pin parity — shared deps in `pnpm-workspace.yaml` overrides
+ *     stay in sync across workspace `package.json` files.
+ */
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const ROOT = join(import.meta.dirname!, "../../../..");
+
+// ----------------------------------------------------------------------------
+// Configs
+// ----------------------------------------------------------------------------
+
+/**
+ * Open-core package import graph. For each package, list which `@iloveagents/*`
+ * packages it MAY import. Empty array = none.
+ *
+ * Packages that do not yet exist on disk are skipped at runtime by
+ * `findPackageDir` so future packages can be wired in here ahead of their
+ * extraction.
+ */
+const OPEN_CORE_GRAPH: Record<string, string[]> = {
+  "@iloveagents/foundry-agent": [],
+  "@iloveagents/foundry-web-primitives": [],
+  "@iloveagents/foundry-web-ui": [
+    "@iloveagents/foundry-web-primitives",
+    "@iloveagents/foundry-agent",
+  ],
+  "@iloveagents/foundry-web-shell": [
+    "@iloveagents/foundry-web-primitives",
+    "@iloveagents/foundry-web-ui",
+    "@iloveagents/foundry-agent",
+  ],
+};
+
+/**
+ * Banned bare-package imports inside `packages/agent/src/`.
+ *
+ * `@iloveagents/foundry-agent` is the cross-runtime transport — pure TS, zero React,
+ * zero `@assistant-ui/*`. The MSAL subpath (`packages/agent/src/msal/`) may
+ * pull in `@azure/msal-browser` (dynamic import keeps it optional). Bare
+ * `"zustand"` is banned everywhere — must use `"zustand/vanilla"`.
+ */
+const AGENT_BANNED_IMPORTS = [
+  { specifier: "react", scope: "all" as const },
+  { specifier: "react-dom", scope: "all" as const },
+  { specifier: "react/jsx-runtime", scope: "all" as const },
+  { specifierPrefix: "@assistant-ui/", scope: "all" as const },
+  { specifier: "@azure/msal-react", scope: "all" as const },
+  // bare "zustand" is the React entry — agent must use "zustand/vanilla".
+  { specifierExact: "zustand", scope: "all" as const },
+  // msal-browser is allowed only under src/msal/.
+  { specifier: "@azure/msal-browser", scope: "non-msal" as const },
+];
+
+/** File-count ceiling: `packages/web-shell/src` is hard-capped at 15 — the
+ *  shell is a thin composition layer (bootstrapShell + ChatModule wiring +
+ *  auth provider seam), not application surface. Growth indicates leakage.
+ */
+const FILE_COUNT_CEILINGS = [
+  { path: "packages/web-shell/src", ceiling: 15, hardFail: true },
+];
+
+/**
+ * Shared deps where all consumers must agree on the major version.
+ * Rooted in `pnpm-workspace.yaml` overrides — once a customer's package.json
+ * declares an incompatible major, pnpm overrides hide the drift at install
+ * time, but the public package metadata is wrong.
+ */
+const SHARED_DEPS_REQUIRED_MAJOR = [
+  { name: "react-router", expectedMajor: "7" },
+  { name: "@assistant-ui/react", expectedMajor: "0" },
+  { name: "@ag-ui/client", expectedMajor: "0" },
+  { name: "@ag-ui/core", expectedMajor: "0" },
+];
+
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+
+function findFiles(dir: string, exts: string[], skip: Set<string>): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (skip.has(entry)) continue;
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) out.push(...findFiles(full, exts, skip));
+    else if (exts.some((e) => full.endsWith(e))) out.push(full);
+  }
+  return out;
+}
+
+function findPackageDir(name: string): string | null {
+  const pkgDir = join(ROOT, "packages");
+  if (!existsSync(pkgDir)) return null;
+  for (const entry of readdirSync(pkgDir)) {
+    const candidate = join(pkgDir, entry);
+    const pkgJsonPath = join(candidate, "package.json");
+    if (existsSync(pkgJsonPath)) {
+      try {
+        const json = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+        if (json.name === name) return candidate;
+      } catch {
+        /* ignore malformed */
+      }
+    }
+  }
+  return null;
+}
+
+function importsOf(content: string): string[] {
+  const out: string[] = [];
+  // ES imports + dynamic imports + re-exports
+  const re = /(?:import|export|require)\s*[^"';]*?["']([^"']+)["']/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(content)) !== null) out.push(m[1]);
+  return out;
+}
+
+// ----------------------------------------------------------------------------
+// Tests
+// ----------------------------------------------------------------------------
+
+describe("open-core guards", () => {
+  // 1. Agent package: no React / no assistant-ui / no bare zustand
+  describe("@iloveagents/foundry-agent banned-import guard", () => {
+    const agentRoot = findPackageDir("@iloveagents/foundry-agent");
+
+    if (!agentRoot) {
+      it.skip("agent package not yet extracted", () => undefined);
+    } else {
+      const files = findFiles(
+        join(agentRoot, "src"),
+        [".ts", ".tsx"],
+        new Set(["node_modules", "dist", "__tests__"]),
+      );
+
+      function isUnderMsal(filePath: string): boolean {
+        const rel = relative(agentRoot!, filePath);
+        return rel.startsWith(`src/msal/`) || rel.startsWith(`src${"/"}msal${"/"}`);
+      }
+
+      for (const rule of AGENT_BANNED_IMPORTS) {
+        const label =
+          (rule as { specifier?: string }).specifier ??
+          (rule as { specifierPrefix?: string }).specifierPrefix ??
+          (rule as { specifierExact?: string }).specifierExact!;
+
+        it(`no source file imports "${label}" (scope: ${rule.scope})`, () => {
+          const violations: string[] = [];
+          for (const file of files) {
+            if (rule.scope === "non-msal" && isUnderMsal(file)) continue;
+            const content = readFileSync(file, "utf-8");
+            for (const imp of importsOf(content)) {
+              const matches =
+                ("specifierExact" in rule && imp === rule.specifierExact) ||
+                ("specifier" in rule && imp === rule.specifier) ||
+                ("specifierPrefix" in rule &&
+                  rule.specifierPrefix !== undefined &&
+                  imp.startsWith(rule.specifierPrefix));
+              if (matches) violations.push(`${relative(ROOT, file)} -> ${imp}`);
+            }
+          }
+          expect(
+            violations,
+            `${label} import leaked into packages/agent/src/${
+              rule.scope === "non-msal" ? " (outside msal/)" : ""
+            }`,
+          ).toEqual([]);
+        });
+      }
+    }
+  });
+
+  // 2. Open-core import graph
+  describe("open-core package import graph", () => {
+    for (const [pkg, allowed] of Object.entries(OPEN_CORE_GRAPH)) {
+      it(`${pkg} only imports from [${allowed.join(", ") || "none"}]`, () => {
+        const dir = findPackageDir(pkg);
+        if (!dir) return; // package not yet extracted — skip
+        const files = findFiles(
+          join(dir, "src"),
+          [".ts", ".tsx"],
+          new Set(["node_modules", "dist", "__tests__"]),
+        );
+        const violations: string[] = [];
+        for (const file of files) {
+          const content = readFileSync(file, "utf-8");
+          for (const imp of importsOf(content)) {
+            // Foundry-ui packages must never import from @lastspace/* (commercial
+            // downstream); allow-listing is enforced for sibling @iloveagents/* deps.
+            if (imp.startsWith("@lastspace/")) {
+              violations.push(`${relative(ROOT, file)} -> ${imp} (lastspace import forbidden)`);
+              continue;
+            }
+            if (!imp.startsWith("@iloveagents/")) continue;
+            // Self-imports allowed (subpath exports etc).
+            if (imp === pkg || imp.startsWith(`${pkg}/`)) continue;
+            // Strip subpath off the imported package.
+            const importedPkg = imp.split("/").slice(0, 2).join("/");
+            if (!allowed.includes(importedPkg)) {
+              violations.push(`${relative(ROOT, file)} -> ${imp}`);
+            }
+          }
+        }
+        expect(violations, `${pkg} imported a forbidden package`).toEqual([]);
+      });
+    }
+  });
+
+  // 3. File-count ceiling (warning + optional hard-fail)
+  describe("file-count ceilings on host directories", () => {
+    for (const { path, ceiling, hardFail } of FILE_COUNT_CEILINGS) {
+      it(`${path} ${hardFail ? "must" : "should"} stay ≤ ${ceiling} files`, () => {
+        const dir = join(ROOT, path);
+        if (!existsSync(dir)) return;
+        const files = findFiles(
+          dir,
+          [".ts", ".tsx", ".py"],
+          new Set(["node_modules", ".venv", "__pycache__", "dist", "__tests__"]),
+        );
+        if (hardFail) {
+          expect(
+            files.length,
+            `${path} has ${files.length} files; ceiling is ${ceiling}. Move features into packages.`,
+          ).toBeLessThanOrEqual(ceiling);
+        } else {
+          // Warning-mode: log if over ceiling but don't fail. Flip to hardFail
+          // once host-shell extraction (#98) lands.
+          if (files.length > ceiling) {
+            // eslint-disable-next-line no-console
+            console.warn(
+              `[file-count guard] ${path} has ${files.length} files (ceiling ${ceiling}). Hard-fail enabled once #98 lands.`,
+            );
+          }
+          expect(files.length).toBeGreaterThanOrEqual(0); // always passes; just records
+        }
+      });
+    }
+  });
+
+  // 4. Version-pin parity
+  describe("shared deps stay in sync across workspace package.jsons", () => {
+    function workspacePackageJsons(): { dir: string; json: Record<string, unknown> }[] {
+      const out: { dir: string; json: Record<string, unknown> }[] = [];
+      for (const base of ["packages"]) {
+        const baseDir = join(ROOT, base);
+        if (!existsSync(baseDir)) continue;
+        for (const entry of readdirSync(baseDir)) {
+          const dir = join(baseDir, entry);
+          const pkgJson = join(dir, "package.json");
+          if (existsSync(pkgJson)) {
+            try {
+              out.push({ dir, json: JSON.parse(readFileSync(pkgJson, "utf-8")) });
+            } catch {
+              /* ignore */
+            }
+          }
+        }
+      }
+      return out;
+    }
+
+    function depMajor(spec: string): string | null {
+      // Strip leading ^, ~, >=, =, etc.
+      const m = spec.match(/(\d+)/);
+      return m ? m[1] : null;
+    }
+
+    for (const { name, expectedMajor } of SHARED_DEPS_REQUIRED_MAJOR) {
+      it(`${name} declared at major ${expectedMajor} in every package.json that declares it`, () => {
+        const violations: string[] = [];
+        for (const { dir, json } of workspacePackageJsons()) {
+          const buckets = ["dependencies", "peerDependencies", "devDependencies"] as const;
+          for (const bucket of buckets) {
+            const deps = (json[bucket] ?? {}) as Record<string, string>;
+            const spec = deps[name];
+            if (!spec) continue;
+            const major = depMajor(spec);
+            if (major !== expectedMajor) {
+              violations.push(`${relative(ROOT, dir)} ${bucket}.${name}=${spec}`);
+            }
+          }
+        }
+        expect(
+          violations,
+          `${name} version drift detected; pnpm-workspace.yaml override hides it at install time but published metadata is wrong`,
+        ).toEqual([]);
+      });
+    }
+  });
+});

package/src/__tests__/theme-runtime.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  getThemePreset,
+  mergeThemeDefinitions,
+  resolveThemeRuntime,
+} from "../lib/theme-runtime.ts";
+
+describe("theme runtime", () => {
+  it("merges sparse definitions in precedence order", () => {
+    const merged = mergeThemeDefinitions(
+      {
+        light: {
+          primary: "oklch(0.4 0.2 280)",
+          foreground: "oklch(0.2 0.01 280)",
+        },
+      },
+      {
+        light: {
+          primary: "oklch(0.5 0.19 260)",
+        },
+        status: {
+          light: {
+            success: "oklch(0.6 0.15 150)",
+          },
+        },
+      },
+    );
+
+    expect(merged.light?.primary).toBe("oklch(0.5 0.19 260)");
+    expect(merged.light?.foreground).toBe("oklch(0.2 0.01 280)");
+    expect(merged.status?.light?.success).toBe("oklch(0.6 0.15 150)");
+  });
+
+  it("resolves scoped layers on top of the preset", () => {
+    const runtime = resolveThemeRuntime(
+      [
+        {
+          id: "global-theme",
+          basePreset: "foundry-violet",
+          definition: {
+            light: {
+              primary: "oklch(0.45 0.18 300)",
+            },
+            sidebar: {
+              light: {
+                sidebar: "oklch(0.98 0.01 300)",
+              },
+            },
+          },
+        },
+        {
+          id: "workspace-theme",
+          definition: {
+            light: {
+              primary: "oklch(0.52 0.16 240)",
+            },
+          },
+        },
+      ],
+      "light",
+    );
+
+    expect(runtime.mode).toBe("light");
+    expect(runtime.sources.map((layer) => layer.id)).toEqual([
+      "global-theme",
+      "workspace-theme",
+    ]);
+    expect(runtime.definition.light?.primary).toBe("oklch(0.52 0.16 240)");
+    expect(runtime.variables["--primary" as keyof typeof runtime.variables]).toBe(
+      "oklch(0.52 0.16 240)",
+    );
+    expect(runtime.variables["--sidebar" as keyof typeof runtime.variables]).toBe(
+      "oklch(0.98 0.01 300)",
+    );
+    expect(runtime.variables["--success" as keyof typeof runtime.variables]).toBeTruthy();
+  });
+
+  it("falls back to the default preset for unknown names", () => {
+    expect(getThemePreset("unknown-preset")).toEqual(getThemePreset("foundry-violet"));
+  });
+});