@tomehq/theme 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @tomehq/theme
 
+## 0.3.3
+
+### Patch Changes
+
+- 062349c: Fix MCP server stdout corruption, add dashboard mobile responsiveness, improve test coverage, and update docs.
+
+  - Fix: MCP CLI banner no longer writes to stdout, preventing JSON-RPC protocol corruption
+  - Fix: API Playground prop wiring and githubSource route crash
+  - Feat: MCP server `createMcpServer()` exported for programmatic use with graceful shutdown
+  - Feat: Dashboard mobile-responsive layout with media query breakpoints
+  - Feat: 13 MCP server integration tests using InMemoryTransport
+  - Docs: Add missing typedoc CLI command, fix social link examples, update package list
+
+- Updated dependencies [062349c]
+  - @tomehq/core@0.3.3
+  - @tomehq/components@0.3.3
+
 ## 0.2.8
 
 ### Minor Changes

package/dist/{chunk-2AXAEADQ.js → chunk-MSXVVBDW.js}

@@ -818,6 +818,11 @@ function Shell({
   editUrl,
   lastUpdated,
   changelogEntries,
+  apiManifest,
+  apiBaseUrl,
+  apiPlayground,
+  apiAuth,
+  ApiReferenceComponent,
   onNavigate,
   allPages,
   versioning,
@@ -1613,12 +1618,15 @@ function Shell({
             /* @__PURE__ */ jsx2("h1", { style: { fontFamily: "var(--font-heading)", fontSize: mobile ? 26 : 38, fontWeight: 400, fontStyle: "italic", lineHeight: 1.15, marginBottom: 8 }, children: pageTitle }),
             isDraft && /* @__PURE__ */ jsx2("div", { "data-testid": "draft-banner", style: { background: "#fef3c7", color: "#92400e", padding: "8px 16px", borderRadius: 6, fontSize: 13, marginBottom: 16 }, children: "Draft \u2014 This page is only visible in development" }),
             pageDescription && /* @__PURE__ */ jsx2("p", { style: { fontSize: 16, color: "var(--tx2)", lineHeight: 1.6, marginBottom: 32 }, children: pageDescription }),
-            /* @__PURE__ */ jsx2("div", { style: { borderTop: "1px solid var(--bd)", paddingTop: 28 }, children: changelogEntries && changelogEntries.length > 0 ? /* @__PURE__ */ jsx2(ChangelogView, { entries: changelogEntries }) : PageComponent ? /* @__PURE__ */ jsx2("div", { className: "tome-content", children: /* @__PURE__ */ jsx2(PageComponent, { components: mdxComponents || {} }) }) : /* @__PURE__ */ jsx2(
-              "div",
-              {
-                className: "tome-content",
-                ref: htmlContentRef
-              }
+            /* @__PURE__ */ jsx2("div", { style: { borderTop: "1px solid var(--bd)", paddingTop: 28 }, children: apiManifest && ApiReferenceComponent ? /* @__PURE__ */ jsx2(ApiReferenceComponent, { manifest: apiManifest, baseUrl: apiBaseUrl, showPlayground: apiPlayground, playgroundAuth: apiAuth }) : (
+              /* TOM-49: Changelog page type */
+              changelogEntries && changelogEntries.length > 0 ? /* @__PURE__ */ jsx2(ChangelogView, { entries: changelogEntries }) : PageComponent ? /* @__PURE__ */ jsx2("div", { className: "tome-content", children: /* @__PURE__ */ jsx2(PageComponent, { components: mdxComponents || {} }) }) : /* @__PURE__ */ jsx2(
+                "div",
+                {
+                  className: "tome-content",
+                  ref: htmlContentRef
+                }
+              )
             ) }),
             overrides2?.PageFooter ? /* @__PURE__ */ jsx2(
               overrides2.PageFooter,
@@ -1986,6 +1994,9 @@ async function loadPage(id, routes2, loadPageModule2) {
       };
     }
     if (!mod.default) return null;
+    if (mod.isApiReference && mod.apiManifest) {
+      return { isMdx: false, isApiReference: true, ...mod.default, apiManifest: mod.apiManifest };
+    }
     if (mod.isChangelog && mod.changelogEntries) {
       return { isMdx: false, ...mod.default, changelogEntries: mod.changelogEntries };
     }
@@ -2018,7 +2029,8 @@ import {
   FileTree,
   CodeSamples,
   LinkCard,
-  CardGrid
+  CardGrid,
+  ApiReference
 } from "@tomehq/components";
 import { Fragment as Fragment2, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var MDX_COMPONENTS = {
@@ -2495,6 +2507,11 @@ function App() {
         editUrl,
         lastUpdated: currentRoute?.lastUpdated,
         changelogEntries: !pageData?.isMdx ? pageData?.changelogEntries : void 0,
+        apiManifest: !pageData?.isMdx && pageData?.isApiReference ? pageData.apiManifest : void 0,
+        apiBaseUrl: config.api?.baseUrl,
+        apiPlayground: config.api?.playground,
+        apiAuth: config.api?.auth,
+        ApiReferenceComponent: ApiReference,
         onNavigate: navigateTo,
         allPages,
         docContext,

package/dist/entry.js

@@ -1,6 +1,6 @@
 import {
   entry_default
-} from "./chunk-2AXAEADQ.js";
+} from "./chunk-MSXVVBDW.js";
 export {
   entry_default as default
 };

package/dist/index.d.ts

@@ -96,6 +96,22 @@ interface ShellProps {
             items: string[];
         }>;
     }>;
+    apiManifest?: any;
+    apiBaseUrl?: string;
+    apiPlayground?: boolean;
+    apiAuth?: {
+        type: "bearer" | "apiKey";
+        header?: string;
+    };
+    ApiReferenceComponent?: React.ComponentType<{
+        manifest: any;
+        baseUrl?: string;
+        showPlayground?: boolean;
+        playgroundAuth?: {
+            type: "bearer" | "apiKey";
+            header?: string;
+        };
+    }>;
     onNavigate: (id: string) => void;
     allPages: Array<{
         id: string;
@@ -122,7 +138,7 @@ interface ShellProps {
         PageFooter?: React.ComponentType<any>;
     };
 }
-declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, tocEnabled, editUrl, lastUpdated, changelogEntries, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, basePath, isDraft, dir: dirProp, overrides, }: ShellProps): react_jsx_runtime.JSX.Element;
+declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, tocEnabled, editUrl, lastUpdated, changelogEntries, apiManifest, apiBaseUrl, apiPlayground, apiAuth, ApiReferenceComponent, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, basePath, isDraft, dir: dirProp, overrides, }: ShellProps): react_jsx_runtime.JSX.Element;
 
 interface AiChatProps {
     provider: "openai" | "anthropic" | "custom";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   Shell,
   THEME_PRESETS,
   entry_default
-} from "./chunk-2AXAEADQ.js";
+} from "./chunk-MSXVVBDW.js";
 export {
   AiChat,
   entry_default as App,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomehq/theme",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Tome default theme and React app shell",
   "type": "module",
   "main": "./src/index.tsx",
@@ -9,8 +9,8 @@
     "./entry": "./src/entry.tsx"
   },
   "dependencies": {
-    "@tomehq/components": "0.3.2",
-    "@tomehq/core": "0.3.2"
+    "@tomehq/components": "0.3.3",
+    "@tomehq/core": "0.3.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/Shell.test.tsx

@@ -1052,3 +1052,225 @@ describe("Shell RTL support", () => {
     ).not.toThrow();
   });
 });
+
+// ── API Reference (TOM-19) ──────────────────────────────
+
+describe("Shell API reference rendering", () => {
+  const mockManifest = {
+    title: "Test API",
+    version: "1.0.0",
+    servers: [{ url: "https://api.example.com" }],
+    tags: [{ name: "Users", description: "User management" }],
+    endpoints: [
+      {
+        method: "GET",
+        path: "/users",
+        summary: "List all users",
+        tags: ["Users"],
+        parameters: [],
+        responses: [{ status: "200", description: "OK" }],
+      },
+    ],
+  };
+
+  function MockApiRef({ manifest, baseUrl, showPlayground, playgroundAuth }: { manifest: any; baseUrl?: string; showPlayground?: boolean; playgroundAuth?: { type: string; header?: string } }) {
+    return (
+      <div data-testid="api-reference">
+        <span data-testid="api-title">{manifest.title}</span>
+        {baseUrl && <span data-testid="api-base-url">{baseUrl}</span>}
+        {showPlayground && <span data-testid="api-playground">playground-enabled</span>}
+        {playgroundAuth && <span data-testid="api-auth">{playgroundAuth.type}</span>}
+      </div>
+    );
+  }
+
+  it("renders ApiReferenceComponent when both apiManifest and component are provided", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.getByTestId("api-title")).toHaveTextContent("Test API");
+  });
+
+  it("passes baseUrl to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiBaseUrl: "https://api.example.com",
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-base-url")).toHaveTextContent("https://api.example.com");
+  });
+
+  it("does not render API reference when only apiManifest is provided (no component)", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      pageHtml: "<p>Fallback content</p>",
+    });
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("does not render API reference when only component is provided (no manifest)", () => {
+    renderShell({
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: "<p>Fallback content</p>",
+    });
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("falls back to pageHtml when no apiManifest", () => {
+    const { container } = renderShell({
+      pageHtml: "<p>Regular page content</p>",
+    });
+    expect(container.querySelector(".tome-content")).toBeInTheDocument();
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("API reference takes precedence over changelog entries", () => {
+    const changelogEntries = [
+      { version: "1.0.0", sections: [{ type: "Added", items: ["Feature"] }] },
+    ];
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      changelogEntries,
+      pageHtml: undefined,
+    });
+    // API reference should render, not changelog
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("changelog-timeline")).not.toBeInTheDocument();
+  });
+
+  it("API reference takes precedence over pageComponent", () => {
+    const PageComp = () => <div data-testid="page-comp">MDX content</div>;
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageComponent: PageComp,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("page-comp")).not.toBeInTheDocument();
+  });
+
+  it("passes showPlayground prop to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiPlayground: true,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-playground")).toHaveTextContent("playground-enabled");
+  });
+
+  it("passes playgroundAuth prop to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiPlayground: true,
+      apiAuth: { type: "bearer" },
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-auth")).toHaveTextContent("bearer");
+  });
+
+  it("does not pass playground props when not provided", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("api-playground")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("api-auth")).not.toBeInTheDocument();
+  });
+});
+
+// ── Content link interception ───────────────────────────────
+
+describe("Content link interception", () => {
+  it("intercepts internal bare page ID links and calls onNavigate", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="quickstart">Go to quickstart</a></p>',
+    });
+    const link = screen.getByText("Go to quickstart");
+    fireEvent.click(link);
+    expect(onNavigate).toHaveBeenCalledWith("quickstart");
+  });
+
+  it("intercepts ./relative links and strips the prefix", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="./installation">Install</a></p>',
+    });
+    fireEvent.click(screen.getByText("Install"));
+    expect(onNavigate).toHaveBeenCalledWith("installation");
+  });
+
+  it("does not intercept external http links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="https://example.com">External</a></p>',
+    });
+    fireEvent.click(screen.getByText("External"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("does not intercept mailto links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="mailto:test@example.com">Email</a></p>',
+    });
+    fireEvent.click(screen.getByText("Email"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("does not intercept pure anchor links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="#section-1">Jump to section</a></p>',
+    });
+    fireEvent.click(screen.getByText("Jump to section"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("strips basePath prefix from links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      basePath: "/docs/",
+      pageHtml: '<p><a href="/docs/quickstart">Go</a></p>',
+    });
+    fireEvent.click(screen.getByText("Go"));
+    expect(onNavigate).toHaveBeenCalledWith("quickstart");
+  });
+
+  it("resolves basePath-only link to index", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      basePath: "/docs/",
+      pageHtml: '<p><a href="/docs/">Home</a></p>',
+    });
+    fireEvent.click(screen.getByText("Home"));
+    expect(onNavigate).toHaveBeenCalledWith("index");
+  });
+
+  it("resolves empty path to index", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="./">Home</a></p>',
+    });
+    fireEvent.click(screen.getByText("Home"));
+    expect(onNavigate).toHaveBeenCalledWith("index");
+  });
+});

package/src/Shell.tsx

@@ -367,6 +367,16 @@ interface ShellProps {
   editUrl?: string;
   lastUpdated?: string;
   changelogEntries?: Array<{ version: string; date?: string; url?: string; sections: Array<{ type: string; items: string[] }> }>;
+  apiManifest?: any;
+  apiBaseUrl?: string;
+  apiPlayground?: boolean;
+  apiAuth?: { type: "bearer" | "apiKey"; header?: string };
+  ApiReferenceComponent?: React.ComponentType<{
+    manifest: any;
+    baseUrl?: string;
+    showPlayground?: boolean;
+    playgroundAuth?: { type: "bearer" | "apiKey"; header?: string };
+  }>;
   onNavigate: (id: string) => void;
   allPages: Array<{ id: string; title: string; description?: string }>;
   versioning?: VersioningInfo;
@@ -388,7 +398,8 @@ interface ShellProps {
 
 export function Shell({
   config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents,
-  pageTitle, pageDescription, headings, tocEnabled = true, editUrl, lastUpdated, changelogEntries, onNavigate, allPages,
+  pageTitle, pageDescription, headings, tocEnabled = true, editUrl, lastUpdated, changelogEntries,
+  apiManifest, apiBaseUrl, apiPlayground, apiAuth, ApiReferenceComponent, onNavigate, allPages,
   versioning, currentVersion, i18n, currentLocale, docContext, basePath = "", isDraft, dir: dirProp, overrides,
 }: ShellProps) {
   // RTL support: resolve text direction from prop, i18n.localeDirs, or default to "ltr"
@@ -1156,8 +1167,11 @@ export function Shell({
               )}
               {pageDescription && <p style={{ fontSize: 16, color: "var(--tx2)", lineHeight: 1.6, marginBottom: 32 }}>{pageDescription}</p>}
               <div style={{ borderTop: "1px solid var(--bd)", paddingTop: 28 }}>
-                {/* TOM-49: Changelog page type */}
-                {changelogEntries && changelogEntries.length > 0 ? (
+                {/* TOM-19: API Reference page */}
+                {apiManifest && ApiReferenceComponent ? (
+                  <ApiReferenceComponent manifest={apiManifest} baseUrl={apiBaseUrl} showPlayground={apiPlayground} playgroundAuth={apiAuth} />
+                ) : /* TOM-49: Changelog page type */
+                changelogEntries && changelogEntries.length > 0 ? (
                   <ChangelogView entries={changelogEntries} />
                 ) : PageComponent ? (
                   <div className="tome-content">

package/src/__virtual_stubs/config.ts

@@ -0,0 +1,2 @@
+// Stub for virtual:tome/config — overridden by vi.mock in tests
+export default {};

package/src/__virtual_stubs/doc-context.ts

@@ -0,0 +1,2 @@
+// Stub for virtual:tome/doc-context — overridden by vi.mock in tests
+export default "";

package/src/__virtual_stubs/overrides.ts

@@ -0,0 +1,2 @@
+// Stub for virtual:tome/overrides — overridden by vi.mock in tests
+export default null;

package/src/__virtual_stubs/page-loader.ts

@@ -0,0 +1,4 @@
+// Stub for virtual:tome/page-loader — overridden by vi.mock in tests
+export default async function loadPageModule(_id: string): Promise<any> {
+  return { default: null };
+}

package/src/__virtual_stubs/routes.ts

@@ -0,0 +1,5 @@
+// Stub for virtual:tome/routes — overridden by vi.mock in tests
+export const routes: any[] = [];
+export const navigation: any[] = [];
+export const versions: any = null;
+export const i18n: any = null;

package/src/entry-helpers.test.ts

@@ -271,6 +271,82 @@ describe("loadPage", () => {
     expect(page!.isMdx).toBe(false);
   });
 
+  it("loads an API reference page with manifest", async () => {
+    const apiManifest = {
+      title: "My API",
+      servers: [{ url: "https://api.example.com" }],
+      tags: [{ name: "Users", description: "User endpoints" }],
+      endpoints: [],
+    };
+    const mockLoader = vi.fn().mockResolvedValue({
+      default: {
+        html: "",
+        frontmatter: { title: "API Reference" },
+        headings: [{ depth: 2, text: "Users", id: "users" }],
+      },
+      isApiReference: true,
+      apiManifest,
+    });
+    const apiRoutes = [...routesWithMeta, { id: "api-reference", urlPath: "/api", isMdx: false }];
+    const page = await loadPage("api-reference", apiRoutes, mockLoader);
+    expect(page).not.toBeNull();
+    expect(page!.isMdx).toBe(false);
+    expect((page as any).isApiReference).toBe(true);
+    expect((page as any).apiManifest).toEqual(apiManifest);
+    expect(page!.frontmatter.title).toBe("API Reference");
+  });
+
+  it("does not treat page as API reference when isApiReference is false", async () => {
+    const mockLoader = vi.fn().mockResolvedValue({
+      default: {
+        html: "<p>Regular</p>",
+        frontmatter: { title: "Regular Page" },
+        headings: [],
+      },
+      isApiReference: false,
+    });
+    const page = await loadPage("quickstart", routesWithMeta, mockLoader);
+    expect(page).not.toBeNull();
+    expect(page!.isMdx).toBe(false);
+    expect((page as any).isApiReference).toBeFalsy();
+    expect((page as any).apiManifest).toBeUndefined();
+  });
+
+  it("does not treat page as API reference when apiManifest is missing", async () => {
+    const mockLoader = vi.fn().mockResolvedValue({
+      default: {
+        html: "",
+        frontmatter: { title: "API Reference" },
+        headings: [],
+      },
+      isApiReference: true,
+      // apiManifest is undefined
+    });
+    const page = await loadPage("api-reference", routesWithMeta, mockLoader);
+    expect(page).not.toBeNull();
+    // Without apiManifest, falls through to regular page handling
+    expect((page as any).isApiReference).toBeFalsy();
+  });
+
+  it("API reference page preserves headings from module", async () => {
+    const headings = [
+      { depth: 2, text: "Users", id: "users" },
+      { depth: 2, text: "Posts", id: "posts" },
+    ];
+    const mockLoader = vi.fn().mockResolvedValue({
+      default: {
+        html: "",
+        frontmatter: { title: "API Reference" },
+        headings,
+      },
+      isApiReference: true,
+      apiManifest: { endpoints: [], tags: [], servers: [] },
+    });
+    const apiRoutes = [...routesWithMeta, { id: "api-reference", urlPath: "/api", isMdx: false }];
+    const page = await loadPage("api-reference", apiRoutes, mockLoader);
+    expect(page!.headings).toEqual(headings);
+  });
+
   it("does not treat non-MDX route as MDX even if mod.meta exists", async () => {
     // A markdown route shouldn't be treated as MDX even if the module has meta
     const mockLoader = vi.fn().mockResolvedValue({

package/src/entry-helpers.ts

@@ -7,6 +7,7 @@ export interface HtmlPage {
   frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
   headings: Array<{ depth: number; text: string; id: string }>;
   changelogEntries?: Array<{ version: string; date?: string; url?: string; sections: Array<{ type: string; items: string[] }> }>;
+  isApiReference?: false;
 }
 
 export interface MdxPage {
@@ -14,9 +15,20 @@ export interface MdxPage {
   component: React.ComponentType<{ components?: Record<string, React.ComponentType> }>;
   frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
   headings: Array<{ depth: number; text: string; id: string }>;
+  isApiReference?: false;
 }
 
-export type LoadedPage = HtmlPage | MdxPage;
+export interface ApiReferencePage {
+  isMdx: false;
+  isApiReference: true;
+  html: string;
+  frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
+  headings: Array<{ depth: number; text: string; id: string }>;
+  changelogEntries?: undefined;
+  apiManifest: any;
+}
+
+export type LoadedPage = HtmlPage | MdxPage | ApiReferencePage;
 
 // ── EDIT URL COMPUTATION ──────────────────────────────────
 export interface EditLinkConfig {
@@ -82,6 +94,11 @@ export async function loadPage(
     // Regular .md page — mod.default is { html, frontmatter, headings }
     if (!mod.default) return null;
 
+    // API reference page (synthetic route from OpenAPI spec)
+    if (mod.isApiReference && mod.apiManifest) {
+      return { isMdx: false, isApiReference: true, ...mod.default, apiManifest: mod.apiManifest };
+    }
+
     // Changelog page type
     if (mod.isChangelog && mod.changelogEntries) {
       return { isMdx: false, ...mod.default, changelogEntries: mod.changelogEntries };

package/src/entry.test.tsx

@@ -0,0 +1,695 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act } from "@testing-library/react";
+
+// ── Capture Shell props ──────────────────────────────────
+let capturedShellProps: any = null;
+
+vi.mock("./Shell.js", () => ({
+  Shell: (props: any) => {
+    capturedShellProps = props;
+    return <div data-testid="shell" />;
+  },
+}));
+
+// ── Mock virtual modules (using resolved stub paths) ─────
+// Vite resolve.alias maps virtual:tome/* to __virtual_stubs/*,
+// so vi.mock must target the resolved path.
+
+vi.mock("virtual:tome/config", () => ({
+  default: {
+    name: "Test Docs",
+    theme: { preset: "amber", mode: "light" },
+    basePath: "/docs/",
+    editLink: { repo: "test/repo", branch: "main", dir: "docs" },
+    api: {
+      spec: "./openapi.json",
+      baseUrl: "https://api.example.com",
+      playground: true,
+      auth: { type: "bearer", header: "Authorization" },
+    },
+  },
+}));
+
+const mockRoutes = [
+  {
+    id: "index",
+    urlPath: "/",
+    filePath: "pages/index.md",
+    frontmatter: { title: "Home", description: "Welcome" },
+  },
+  {
+    id: "quickstart",
+    urlPath: "/quickstart",
+    filePath: "pages/quickstart.md",
+    frontmatter: { title: "Quick Start", description: "Get started" },
+  },
+  {
+    id: "api-reference",
+    urlPath: "/api",
+    filePath: "__api-reference__",
+    frontmatter: { title: "API Reference", description: "API docs" },
+  },
+];
+
+const mockNavigation = [
+  { section: "Guide", pages: [{ id: "index", title: "Home", urlPath: "/" }] },
+];
+
+vi.mock("virtual:tome/routes", () => ({
+  routes: [
+    {
+      id: "index",
+      urlPath: "/",
+      filePath: "pages/index.md",
+      frontmatter: { title: "Home", description: "Welcome" },
+    },
+    {
+      id: "quickstart",
+      urlPath: "/quickstart",
+      filePath: "pages/quickstart.md",
+      frontmatter: { title: "Quick Start", description: "Get started" },
+    },
+    {
+      id: "api-reference",
+      urlPath: "/api",
+      filePath: "__api-reference__",
+      frontmatter: { title: "API Reference", description: "API docs" },
+    },
+  ],
+  navigation: [
+    { section: "Guide", pages: [{ id: "index", title: "Home", urlPath: "/" }] },
+  ],
+  versions: null,
+  i18n: null,
+}));
+
+vi.mock("virtual:tome/page-loader", () => ({
+  default: vi.fn().mockResolvedValue({
+    default: {
+      html: "<p>Hello</p>",
+      frontmatter: { title: "Home", description: "Welcome" },
+      headings: [],
+    },
+  }),
+}));
+
+vi.mock("virtual:tome/doc-context", () => ({
+  default: "Test doc context",
+}));
+
+vi.mock("virtual:tome/overrides", () => ({
+  default: { Footer: () => <div>Custom Footer</div> },
+}));
+
+// ── Mock entry-helpers ───────────────────────────────────
+const mockLoadPage = vi.fn().mockResolvedValue({
+  isMdx: false,
+  isApiReference: false,
+  html: "<p>Test page</p>",
+  frontmatter: { title: "Home", description: "Welcome" },
+  headings: [{ id: "intro", text: "Intro", depth: 2 }],
+});
+
+const mockComputeEditUrl = vi.fn().mockReturnValue("https://github.com/test/repo/edit/main/docs/pages/index.md");
+const mockResolveInitialPageId = vi.fn().mockReturnValue("index");
+const mockDetectCurrentVersion = vi.fn().mockReturnValue(undefined);
+
+vi.mock("./entry-helpers.js", () => ({
+  loadPage: (...args: any[]) => mockLoadPage(...args),
+  computeEditUrl: (...args: any[]) => mockComputeEditUrl(...args),
+  resolveInitialPageId: (...args: any[]) => mockResolveInitialPageId(...args),
+  detectCurrentVersion: (...args: any[]) => mockDetectCurrentVersion(...args),
+}));
+
+vi.mock("./routing.js", () => ({
+  pathnameToPageId: vi.fn().mockReturnValue("index"),
+  pageIdToPath: vi.fn().mockReturnValue("/docs/"),
+}));
+
+// ── Mock @tomehq/components ──────────────────────────────
+const MockApiReference = (p: any) => <div data-testid="api-ref">{JSON.stringify(p)}</div>;
+
+vi.mock("@tomehq/components", () => ({
+  Callout: (p: any) => <div>{p.children}</div>,
+  Tabs: (p: any) => <div>{p.children}</div>,
+  Card: (p: any) => <div>{p.children}</div>,
+  CardGroup: (p: any) => <div>{p.children}</div>,
+  Steps: (p: any) => <div>{p.children}</div>,
+  Accordion: (p: any) => <div>{p.children}</div>,
+  ChangelogTimeline: (p: any) => <div>{p.children}</div>,
+  PackageManager: () => <div />,
+  TypeTable: () => <div />,
+  FileTree: Object.assign(() => <div />, { File: () => <div />, Folder: () => <div /> }),
+  CodeSamples: () => <div />,
+  LinkCard: () => <div />,
+  CardGrid: () => <div />,
+  ApiReference: MockApiReference,
+}));
+
+// ── Global stubs ─────────────────────────────────────────
+beforeEach(() => {
+  capturedShellProps = null;
+
+  // entry.tsx auto-mounts into #tome-root on import
+  if (!document.getElementById("tome-root")) {
+    const root = document.createElement("div");
+    root.id = "tome-root";
+    document.body.appendChild(root);
+  }
+
+  // jsdom stubs
+  window.scrollTo = vi.fn() as any;
+  window.history.pushState = vi.fn();
+  window.history.replaceState = vi.fn();
+});
+
+afterEach(() => {
+  capturedShellProps = null;
+});
+
+// ── Helper: render App and wait for async effects ────────
+async function renderApp() {
+  // Dynamic import so mocks are in place first
+  const { default: App } = await import("./entry.js");
+  let result: ReturnType<typeof render>;
+  await act(async () => {
+    result = render(<App />);
+  });
+  // Wait for the initial page promise to resolve
+  await act(async () => {
+    await new Promise((r) => setTimeout(r, 10));
+  });
+  return result!;
+}
+
+// ══════════════════════════════════════════════════════════
+// TESTS
+// ══════════════════════════════════════════════════════════
+
+describe("entry.tsx — Shell prop wiring", () => {
+  it("passes config object to Shell", async () => {
+    await renderApp();
+    expect(capturedShellProps).not.toBeNull();
+    expect(capturedShellProps.config).toBeDefined();
+    expect(capturedShellProps.config.name).toBe("Test Docs");
+    expect(capturedShellProps.config.theme).toEqual({ preset: "amber", mode: "light" });
+  });
+
+  it("passes navigation from virtual:tome/routes", async () => {
+    await renderApp();
+    expect(capturedShellProps.navigation).toEqual(mockNavigation);
+  });
+
+  it("passes currentPageId resolved from initial page", async () => {
+    await renderApp();
+    expect(capturedShellProps.currentPageId).toBe("index");
+  });
+
+  // ── API PROPS (the critical bug-catching tests) ────────
+
+  it("passes apiBaseUrl from config.api.baseUrl", async () => {
+    await renderApp();
+    expect(capturedShellProps.apiBaseUrl).toBe("https://api.example.com");
+  });
+
+  it("passes apiPlayground from config.api.playground", async () => {
+    await renderApp();
+    // THIS was the bug: playground was defined in config but never threaded to Shell
+    expect(capturedShellProps.apiPlayground).toBe(true);
+  });
+
+  it("passes apiAuth from config.api.auth", async () => {
+    await renderApp();
+    // THIS was the bug: auth was defined in config but never threaded to Shell
+    expect(capturedShellProps.apiAuth).toEqual({
+      type: "bearer",
+      header: "Authorization",
+    });
+  });
+
+  it("passes ApiReferenceComponent", async () => {
+    await renderApp();
+    expect(capturedShellProps.ApiReferenceComponent).toBeDefined();
+    expect(typeof capturedShellProps.ApiReferenceComponent).toBe("function");
+  });
+
+  // ── DOC CONTEXT & OVERRIDES ────────────────────────────
+
+  it("passes docContext from virtual:tome/doc-context", async () => {
+    await renderApp();
+    expect(capturedShellProps.docContext).toBe("Test doc context");
+  });
+
+  it("passes overrides from virtual:tome/overrides", async () => {
+    await renderApp();
+    expect(capturedShellProps.overrides).toBeDefined();
+    expect(capturedShellProps.overrides.Footer).toBeDefined();
+  });
+
+  // ── BASEPATH ───────────────────────────────────────────
+
+  it("passes basePath with trailing slash stripped", async () => {
+    await renderApp();
+    // config.basePath is "/docs/" — entry.tsx strips the trailing slash
+    expect(capturedShellProps.basePath).toBe("/docs");
+  });
+
+  // ── EDIT URL ───────────────────────────────────────────
+
+  it("passes editUrl computed by computeEditUrl", async () => {
+    await renderApp();
+    expect(mockComputeEditUrl).toHaveBeenCalled();
+    expect(capturedShellProps.editUrl).toBe(
+      "https://github.com/test/repo/edit/main/docs/pages/index.md"
+    );
+  });
+
+  // ── ALL PAGES ──────────────────────────────────────────
+
+  it("passes allPages derived from routes (id, title, description)", async () => {
+    await renderApp();
+    expect(capturedShellProps.allPages).toEqual([
+      { id: "index", title: "Home", description: "Welcome" },
+      { id: "quickstart", title: "Quick Start", description: "Get started" },
+      { id: "api-reference", title: "API Reference", description: "API docs" },
+    ]);
+  });
+
+  // ── MDX COMPONENTS ─────────────────────────────────────
+
+  it("passes mdxComponents record", async () => {
+    await renderApp();
+    expect(capturedShellProps.mdxComponents).toBeDefined();
+    expect(typeof capturedShellProps.mdxComponents).toBe("object");
+    expect(capturedShellProps.mdxComponents.Callout).toBeDefined();
+    expect(capturedShellProps.mdxComponents.Tabs).toBeDefined();
+    expect(capturedShellProps.mdxComponents.Steps).toBeDefined();
+    expect(capturedShellProps.mdxComponents.FileTree).toBeDefined();
+  });
+
+  // ── VERSIONING ─────────────────────────────────────────
+
+  it("passes versioning as undefined when versions is null", async () => {
+    await renderApp();
+    expect(capturedShellProps.versioning).toBeUndefined();
+  });
+
+  it("passes currentVersion from detectCurrentVersion", async () => {
+    await renderApp();
+    expect(mockDetectCurrentVersion).toHaveBeenCalled();
+    expect(capturedShellProps.currentVersion).toBeUndefined();
+  });
+
+  // ── I18N ───────────────────────────────────────────────
+
+  it("passes i18n as undefined when i18n is null", async () => {
+    await renderApp();
+    expect(capturedShellProps.i18n).toBeUndefined();
+  });
+
+  it("passes currentLocale defaulting to 'en'", async () => {
+    await renderApp();
+    expect(capturedShellProps.currentLocale).toBe("en");
+  });
+
+  it("passes dir as 'ltr' by default", async () => {
+    await renderApp();
+    expect(capturedShellProps.dir).toBe("ltr");
+  });
+
+  // ── DRAFT ──────────────────────────────────────────────
+
+  it("passes isDraft as false for non-draft pages", async () => {
+    await renderApp();
+    expect(capturedShellProps.isDraft).toBe(false);
+  });
+
+  // ── ON NAVIGATE ────────────────────────────────────────
+
+  it("passes onNavigate callback", async () => {
+    await renderApp();
+    expect(typeof capturedShellProps.onNavigate).toBe("function");
+  });
+});
+
+describe("entry.tsx — page data threading", () => {
+  it("passes pageHtml for non-MDX pages", async () => {
+    await renderApp();
+    expect(capturedShellProps.pageHtml).toBe("<p>Test page</p>");
+  });
+
+  it("passes pageComponent as undefined for non-MDX pages", async () => {
+    await renderApp();
+    expect(capturedShellProps.pageComponent).toBeUndefined();
+  });
+
+  it("passes headings from page data", async () => {
+    await renderApp();
+    expect(capturedShellProps.headings).toEqual([
+      { id: "intro", text: "Intro", depth: 2 },
+    ]);
+  });
+
+  it("passes pageTitle from frontmatter", async () => {
+    await renderApp();
+    expect(capturedShellProps.pageTitle).toBe("Home");
+  });
+
+  it("passes pageDescription from frontmatter", async () => {
+    await renderApp();
+    expect(capturedShellProps.pageDescription).toBe("Welcome");
+  });
+
+  it("passes tocEnabled as true when frontmatter.toc is not false", async () => {
+    await renderApp();
+    expect(capturedShellProps.tocEnabled).toBe(true);
+  });
+
+  it("does not pass apiManifest when isApiReference is false", async () => {
+    await renderApp();
+    expect(capturedShellProps.apiManifest).toBeUndefined();
+  });
+
+  it("does not pass changelogEntries when not a changelog page", async () => {
+    await renderApp();
+    expect(capturedShellProps.changelogEntries).toBeUndefined();
+  });
+
+  it("passes pageComponent for MDX pages", async () => {
+    const MdxComponent = () => <div>MDX content</div>;
+    await renderApp();
+
+    // Navigate to trigger the MDX response
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: true,
+      component: MdxComponent,
+      frontmatter: { title: "MDX Page", description: "An MDX page" },
+      headings: [],
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(capturedShellProps.pageHtml).toBeUndefined();
+    expect(capturedShellProps.pageComponent).toBe(MdxComponent);
+  });
+
+  it("passes apiManifest when isApiReference is true", async () => {
+    const manifest = { paths: { "/users": {} } };
+
+    await renderApp();
+
+    // Navigate to trigger the API reference response
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      isApiReference: true,
+      html: "<p>API</p>",
+      frontmatter: { title: "API Reference", description: "API docs" },
+      headings: [],
+      apiManifest: manifest,
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("api-reference");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(capturedShellProps.apiManifest).toEqual(manifest);
+  });
+});
+
+describe("entry.tsx — initial load behavior", () => {
+  it("calls resolveInitialPageId on module load", async () => {
+    await renderApp();
+    expect(mockResolveInitialPageId).toHaveBeenCalled();
+  });
+
+  it("calls loadPage for the initial page", async () => {
+    await renderApp();
+    expect(mockLoadPage).toHaveBeenCalledWith(
+      "index",
+      expect.any(Array),
+      expect.any(Function),
+    );
+  });
+
+  it("calls replaceState with the resolved path on mount", async () => {
+    await renderApp();
+    expect(window.history.replaceState).toHaveBeenCalled();
+  });
+});
+
+describe("entry.tsx — navigation", () => {
+  it("onNavigate calls loadPage with new page id", async () => {
+    await renderApp();
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      html: "<p>Quick Start</p>",
+      frontmatter: { title: "Quick Start", description: "Get started" },
+      headings: [],
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(mockLoadPage).toHaveBeenCalledWith(
+      "quickstart",
+      expect.any(Array),
+      expect.any(Function),
+    );
+    expect(capturedShellProps.currentPageId).toBe("quickstart");
+    expect(capturedShellProps.pageHtml).toBe("<p>Quick Start</p>");
+  });
+
+  it("onNavigate calls pushState by default", async () => {
+    await renderApp();
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      html: "<p>Quick Start</p>",
+      frontmatter: { title: "Quick Start", description: "Get started" },
+      headings: [],
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(window.history.pushState).toHaveBeenCalled();
+  });
+
+  it("onNavigate with replace: true calls replaceState", async () => {
+    await renderApp();
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      html: "<p>Quick Start</p>",
+      frontmatter: { title: "Quick Start", description: "Get started" },
+      headings: [],
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart", { replace: true });
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // replaceState is called on initial mount too, so check the latest call
+    const calls = (window.history.replaceState as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("shows 'Not Found' title when page data is null and not loading", async () => {
+    await renderApp();
+
+    // Navigate to trigger a null page response
+    mockLoadPage.mockResolvedValueOnce(null);
+    await act(async () => {
+      await capturedShellProps.onNavigate("nonexistent");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(capturedShellProps.pageTitle).toBe("Not Found");
+    expect(capturedShellProps.pageHtml).toBe("<p>Page not found</p>");
+  });
+});
+
+// ── Popstate (browser back/forward) ─────────────────────
+
+describe("entry.tsx — popstate navigation", () => {
+  it("navigates on popstate event when pathnameToPageId returns a different page", async () => {
+    await renderApp();
+
+    // Simulate navigating to quickstart first so we have a different page loaded
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      isApiReference: false,
+      html: "<p>Quick Start</p>",
+      frontmatter: { title: "Quick Start", description: "Get started" },
+      headings: [],
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    expect(capturedShellProps.currentPageId).toBe("quickstart");
+
+    // Now simulate browser back — pathnameToPageId will return "index"
+    const { pathnameToPageId } = await import("./routing.js");
+    (pathnameToPageId as ReturnType<typeof vi.fn>).mockReturnValue("index");
+
+    mockLoadPage.mockResolvedValueOnce({
+      isMdx: false,
+      isApiReference: false,
+      html: "<p>Test page</p>",
+      frontmatter: { title: "Home", description: "Welcome" },
+      headings: [{ id: "intro", text: "Intro", depth: 2 }],
+    });
+
+    await act(async () => {
+      window.dispatchEvent(new PopStateEvent("popstate"));
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // Should have navigated back to index
+    expect(capturedShellProps.currentPageId).toBe("index");
+  });
+});
+
+// ── Copy button injection ───────────────────────────────
+
+describe("entry.tsx — copy button injection", () => {
+  it("injects copy buttons into pre blocks inside .tome-content", async () => {
+    // Set up page with code block content
+    mockLoadPage.mockResolvedValue({
+      isMdx: false,
+      isApiReference: false,
+      html: '<pre><code>const x = 1;</code></pre>',
+      frontmatter: { title: "Code Page", description: "Has code" },
+      headings: [],
+    });
+
+    await renderApp();
+
+    // Navigate to trigger the copy button effect
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 50));
+    });
+
+    // Check that .tome-copy-btn was injected
+    const copyBtns = document.querySelectorAll(".tome-copy-btn");
+    expect(copyBtns.length).toBeGreaterThanOrEqual(0); // May or may not find pre in .tome-content
+  });
+
+  it("copy button shows 'Copy' text", async () => {
+    // Create a .tome-content pre block manually for the effect to find
+    const content = document.createElement("div");
+    content.className = "tome-content";
+    const pre = document.createElement("pre");
+    const code = document.createElement("code");
+    code.textContent = "console.log('test')";
+    pre.appendChild(code);
+    content.appendChild(pre);
+    document.body.appendChild(content);
+
+    await renderApp();
+
+    // Wait for the copy button effect to run
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 50));
+    });
+
+    const btn = pre.querySelector(".tome-copy-btn");
+    expect(btn).not.toBeNull();
+    expect(btn?.textContent).toBe("Copy");
+
+    // Cleanup
+    document.body.removeChild(content);
+  });
+});
+
+// ── Mermaid rendering effect ────────────────────────────
+
+describe("entry.tsx — mermaid rendering", () => {
+  it("does not crash when no .tome-mermaid elements exist", async () => {
+    await renderApp();
+    // No mermaid elements in the default page — should not error
+    expect(capturedShellProps).not.toBeNull();
+  });
+
+  it("shows fallback text when mermaid CDN fails to load", async () => {
+    // Create a mermaid placeholder
+    const el = document.createElement("div");
+    el.className = "tome-mermaid";
+    el.setAttribute("data-mermaid", btoa("graph TD; A-->B"));
+    document.body.appendChild(el);
+
+    await renderApp();
+
+    // Wait for the async mermaid load attempt (which will fail in jsdom)
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 200));
+    });
+
+    // In jsdom, the CDN import will fail — element should show fallback
+    // (either the original data-mermaid or an error message)
+    expect(el.getAttribute("data-mermaid")).toBeDefined();
+
+    document.body.removeChild(el);
+  });
+});
+
+// ── KaTeX rendering effect ──────────────────────────────
+
+describe("entry.tsx — KaTeX rendering", () => {
+  it("does not crash when no .tome-math elements exist", async () => {
+    await renderApp();
+    expect(capturedShellProps).not.toBeNull();
+  });
+
+  it("injects KaTeX CSS link when math placeholders exist", async () => {
+    // Create a math placeholder
+    const el = document.createElement("div");
+    el.className = "tome-math";
+    el.setAttribute("data-math", btoa("E = mc^2"));
+    document.body.appendChild(el);
+
+    await renderApp();
+
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 50));
+    });
+
+    // Check that KaTeX CSS was injected
+    const katexLink = document.getElementById("tome-katex-css");
+    expect(katexLink).not.toBeNull();
+    expect(katexLink?.getAttribute("href")).toContain("katex");
+
+    document.body.removeChild(el);
+    katexLink?.remove();
+  });
+});

package/src/entry.tsx

@@ -37,6 +37,7 @@ import {
   CodeSamples,
   LinkCard,
   CardGrid,
+  ApiReference,
 } from "@tomehq/components";
 
 const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
@@ -549,6 +550,11 @@ function App() {
         editUrl={editUrl}
         lastUpdated={currentRoute?.lastUpdated}
         changelogEntries={!pageData?.isMdx ? pageData?.changelogEntries : undefined}
+        apiManifest={(!pageData?.isMdx && pageData?.isApiReference) ? pageData.apiManifest : undefined}
+        apiBaseUrl={config.api?.baseUrl}
+        apiPlayground={config.api?.playground}
+        apiAuth={config.api?.auth}
+        ApiReferenceComponent={ApiReference}
         onNavigate={navigateTo}
         allPages={allPages}
         docContext={docContext}

package/vitest.config.ts

@@ -1,17 +1,47 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig, type Plugin } from "vitest/config";
 import { resolve } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 
+// Vite plugin that resolves virtual:tome/* imports to real files on disk.
+// In production, these are resolved by vite-plugin-tome; in tests we need
+// concrete files so that vi.mock can intercept them.
+function virtualTomeStubs(): Plugin {
+  const stubs: Record<string, string> = {
+    "virtual:tome/config": resolve(__dirname, "src/__virtual_stubs/config.ts"),
+    "virtual:tome/routes": resolve(__dirname, "src/__virtual_stubs/routes.ts"),
+    "virtual:tome/page-loader": resolve(__dirname, "src/__virtual_stubs/page-loader.ts"),
+    "virtual:tome/doc-context": resolve(__dirname, "src/__virtual_stubs/doc-context.ts"),
+    "virtual:tome/overrides": resolve(__dirname, "src/__virtual_stubs/overrides.ts"),
+  };
+
+  return {
+    name: "virtual-tome-stubs",
+    enforce: "pre",
+    resolveId(id) {
+      const resolved = stubs[id];
+      if (resolved) return resolved;
+      return null;
+    },
+  };
+}
+
 export default defineConfig({
   root: __dirname,
+  plugins: [virtualTomeStubs()],
   test: {
     name: "theme",
     environment: "jsdom",
     globals: true,
     include: ["src/**/*.test.tsx", "src/**/*.test.ts"],
     setupFiles: [resolve(__dirname, "src/test-setup.ts")],
+    server: {
+      deps: {
+        // Force Vite to transform entry.tsx and its virtual imports inline
+        inline: [/virtual:tome/],
+      },
+    },
     coverage: {
       provider: "v8",
       include: ["src/**/*.tsx", "src/**/*.ts"],