@tomehq/theme 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @tomehq/theme
 
+## 0.3.4
+
+### Patch Changes
+
+- f03e6c2: Fix page scrolling beyond viewport bounds in all directions. Lock layout to 100vh with overflow hidden on html, body, and root container.
+
+## 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-QYINBNMJ.js}

@@ -818,6 +818,11 @@ function Shell({
   editUrl,
   lastUpdated,
   changelogEntries,
+  apiManifest,
+  apiBaseUrl,
+  apiPlayground,
+  apiAuth,
+  ApiReferenceComponent,
   onNavigate,
   allPages,
   versioning,
@@ -1049,7 +1054,7 @@ function Shell({
   const PageComponent = pageComponent;
   const bannerLink = config2.banner?.link;
   const bannerIsInternal = bannerLink ? bannerLink.startsWith("#") || basePath2 && bannerLink.startsWith(basePath2 + "/") : false;
-  return /* @__PURE__ */ jsxs2("div", { dir, className: "tome-grain", style: { ...cssVars, color: "var(--tx)", background: "var(--bg)", fontFamily: "var(--font-body)", minHeight: "100vh", overflow: "hidden" }, children: [
+  return /* @__PURE__ */ jsxs2("div", { dir, className: "tome-grain", style: { ...cssVars, color: "var(--tx)", background: "var(--bg)", fontFamily: "var(--font-body)", height: "100vh", overflow: "hidden" }, children: [
     config2.banner?.text && !bannerDismissed && /* @__PURE__ */ jsxs2("div", { style: {
       display: "flex",
       alignItems: "center",
@@ -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 = {
@@ -2040,6 +2052,9 @@ var MDX_COMPONENTS = {
 var contentStyles = `
   @import url('https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@300;400;500;600;700&family=Cormorant+Garamond:ital,wght@0,300;0,400;0,600;0,700;1,300;1,400;1,700&family=Fira+Code:wght@400;500;600&display=swap');
 
+  html, body { margin: 0; padding: 0; height: 100%; overflow: hidden; }
+  #tome-root { height: 100%; overflow: hidden; }
+
   .tome-content h1 { display: none; }
   .tome-content h2 { font-family: var(--font-body); font-size: 1.35em; font-weight: 600; margin-top: 2em; margin-bottom: 0.5em; display: flex; align-items: center; gap: 10px; letter-spacing: 0.01em; }
   .tome-content h2::before { content: "#"; font-family: var(--font-heading); font-size: 1.2em; font-weight: 300; font-style: italic; color: var(--ac); opacity: 0.5; }
@@ -2495,6 +2510,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-QYINBNMJ.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-QYINBNMJ.js";
 export {
   AiChat,
   entry_default as App,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomehq/theme",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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"
@@ -658,7 +669,7 @@ export function Shell({
   const bannerIsInternal = bannerLink ? (bannerLink.startsWith("#") || (basePath && bannerLink.startsWith(basePath + "/"))) : false;
 
   return (
-    <div dir={dir} className="tome-grain" style={{ ...cssVars as React.CSSProperties, color: "var(--tx)", background: "var(--bg)", fontFamily: "var(--font-body)", minHeight: "100vh", overflow: "hidden" }}>
+    <div dir={dir} className="tome-grain" style={{ ...cssVars as React.CSSProperties, color: "var(--tx)", background: "var(--bg)", fontFamily: "var(--font-body)", height: "100vh", overflow: "hidden" }}>
       {/* Banner */}
       {config.banner?.text && !bannerDismissed && (
         <div style={{
@@ -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 };