@tomehq/theme 0.3.4 → 0.4.0

package/dist/entry.js

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

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomehq/theme",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "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.3",
-    "@tomehq/core": "0.3.3"
+    "@tomehq/core": "0.3.4",
+    "@tomehq/components": "0.3.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/Shell.test.tsx

@@ -858,6 +858,31 @@ describe("Shell feedback widget", () => {
     fireEvent.click(screen.getByText("\uD83D\uDC4E"));
     expect(screen.getByText("Thanks for your feedback!")).toBeInTheDocument();
   });
+
+  it("feedback section is inside the scrollable content container, not clipped by root", () => {
+    renderShell();
+    const feedbackEl = screen.getByText("Was this helpful?");
+    // The feedback widget must be a descendant of the overflow:auto scroll container
+    const scrollContainer = feedbackEl.closest('[style*="overflow: auto"]') || feedbackEl.closest('[style*="overflow:auto"]');
+    expect(scrollContainer).not.toBeNull();
+    // The root container must use overflow:clip (not hidden) to avoid clip containment issues
+    const root = feedbackEl.closest(".tome-grain");
+    expect(root).not.toBeNull();
+    expect((root as HTMLElement).style.overflow).toBe("clip");
+  });
+
+  it("feedback section remains in DOM and is not conditionally removed", () => {
+    const { container } = renderShell();
+    // Feedback must always render inside <main>
+    const main = container.querySelector("main");
+    expect(main).not.toBeNull();
+    const feedbackText = within(main!).getByText("Was this helpful?");
+    expect(feedbackText).toBeInTheDocument();
+    // Verify feedback is not position:fixed or absolute (it flows with content)
+    const feedbackParent = feedbackText.closest("div")!;
+    expect(feedbackParent.style.position).not.toBe("fixed");
+    expect(feedbackParent.style.position).not.toBe("absolute");
+  });
 });
 
 // ── Breadcrumbs ──────────────────────────────────────────

package/src/Shell.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useRef, useCallback } from "react";
+import React, { useState, useEffect, useLayoutEffect, useRef, useCallback } from "react";
 import { THEME_PRESETS, type PresetName } from "./presets.js";
 import { AiChat } from "./AiChat.js";
 
@@ -611,14 +611,13 @@ export function Shell({
 
   // Set HTML content via ref so React doesn't re-set innerHTML on re-renders
   // (scroll-spy state changes would otherwise destroy client-side mermaid SVGs)
-  useEffect(() => {
+  // useLayoutEffect ensures innerHTML is set synchronously before paint — no flash
+  useLayoutEffect(() => {
     if (!htmlContentRef.current || !pageHtml) return;
     const stripped = pageHtml.replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, "");
-    if (stripped !== lastHtmlRef.current) {
-      htmlContentRef.current.innerHTML = stripped;
-      lastHtmlRef.current = stripped;
-    }
-  }, [pageHtml]);
+    htmlContentRef.current.innerHTML = stripped;
+    lastHtmlRef.current = stripped;
+  }, [pageHtml, currentPageId]);
 
   // Smooth scroll handler for TOC links
   const scrollToHeading = useCallback((e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
@@ -669,7 +668,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)", height: "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: "clip" }}>
       {/* Banner */}
       {config.banner?.text && !bannerDismissed && (
         <div style={{
@@ -1179,6 +1178,7 @@ export function Shell({
                   </div>
                 ) : (
                   <div
+                    key={currentPageId}
                     className="tome-content"
                     ref={htmlContentRef}
                   />

package/src/entry-helpers.test.ts

@@ -4,6 +4,9 @@ import {
   resolveInitialPageId,
   loadPage,
   detectCurrentVersion,
+  PageNotFoundError,
+  PageLoadError,
+  NavigationCancelledError,
 } from "./entry-helpers.js";
 import type { MinimalRoute } from "./routing.js";
 
@@ -196,22 +199,16 @@ describe("loadPage", () => {
     }
   });
 
-  it("returns null when module has no default export", async () => {
+  it("throws PageNotFoundError when module has no default export", async () => {
     const mockLoader = vi.fn().mockResolvedValue({ default: null });
-    const page = await loadPage("quickstart", routesWithMeta, mockLoader);
-    expect(page).toBeNull();
+    await expect(loadPage("quickstart", routesWithMeta, mockLoader)).rejects.toThrow(PageNotFoundError);
+    await expect(loadPage("quickstart", routesWithMeta, mockLoader)).rejects.toMatchObject({ code: "PAGE_NOT_FOUND" });
   });
 
-  it("returns null on loader error", async () => {
+  it("throws PageLoadError on loader error", async () => {
     const mockLoader = vi.fn().mockRejectedValue(new Error("Module not found"));
-    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const page = await loadPage("quickstart", routesWithMeta, mockLoader);
-    expect(page).toBeNull();
-    expect(consoleSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Failed to load page"),
-      expect.any(Error),
-    );
-    consoleSpy.mockRestore();
+    await expect(loadPage("quickstart", routesWithMeta, mockLoader)).rejects.toThrow(PageLoadError);
+    await expect(loadPage("quickstart", routesWithMeta, mockLoader)).rejects.toMatchObject({ code: "PAGE_LOAD_ERROR" });
   });
 
   it("loads a changelog page with entries", async () => {
@@ -390,3 +387,54 @@ describe("detectCurrentVersion", () => {
     expect(detectCurrentVersion({ version: undefined }, { current: undefined })).toBeUndefined();
   });
 });
+
+// ── Error type distinguishability ─────────────────────────
+
+describe("loadPage — distinguishable error types", () => {
+  const routesWithMeta = [
+    { id: "index", urlPath: "/", isMdx: false },
+  ];
+
+  it("PageNotFoundError has code PAGE_NOT_FOUND", async () => {
+    const mockLoader = vi.fn().mockResolvedValue({ default: null });
+    try {
+      await loadPage("index", routesWithMeta, mockLoader);
+      expect.fail("should have thrown");
+    } catch (err: any) {
+      expect(err).toBeInstanceOf(PageNotFoundError);
+      expect(err.code).toBe("PAGE_NOT_FOUND");
+      expect(err.message).toContain("index");
+    }
+  });
+
+  it("PageLoadError has code PAGE_LOAD_ERROR and preserves cause", async () => {
+    const cause = new Error("network failure");
+    const mockLoader = vi.fn().mockRejectedValue(cause);
+    try {
+      await loadPage("index", routesWithMeta, mockLoader);
+      expect.fail("should have thrown");
+    } catch (err: any) {
+      expect(err).toBeInstanceOf(PageLoadError);
+      expect(err.code).toBe("PAGE_LOAD_ERROR");
+      expect(err.cause).toBe(cause);
+    }
+  });
+
+  it("NavigationCancelledError has code NAVIGATION_CANCELLED", () => {
+    const err = new NavigationCancelledError();
+    expect(err).toBeInstanceOf(Error);
+    expect(err.code).toBe("NAVIGATION_CANCELLED");
+  });
+
+  it("all three error types are distinguishable from each other", () => {
+    const e1 = new PageNotFoundError("x");
+    const e2 = new PageLoadError("x");
+    const e3 = new NavigationCancelledError();
+    expect(e1.code).not.toBe(e2.code);
+    expect(e2.code).not.toBe(e3.code);
+    expect(e1.code).not.toBe(e3.code);
+    expect(e1).toBeInstanceOf(Error);
+    expect(e2).toBeInstanceOf(Error);
+    expect(e3).toBeInstanceOf(Error);
+  });
+});

package/src/entry-helpers.ts

@@ -1,5 +1,31 @@
 import type { MinimalRoute } from "./routing.js";
 
+// ── NAVIGATION ERRORS ─────────────────────────────────────
+export class PageNotFoundError extends Error {
+  readonly code = "PAGE_NOT_FOUND" as const;
+  constructor(pageId: string) {
+    super(`Page not found: ${pageId}`);
+    this.name = "PageNotFoundError";
+  }
+}
+
+export class PageLoadError extends Error {
+  readonly code = "PAGE_LOAD_ERROR" as const;
+  constructor(pageId: string, cause?: unknown) {
+    super(`Failed to load page: ${pageId}`);
+    this.name = "PageLoadError";
+    if (cause) this.cause = cause;
+  }
+}
+
+export class NavigationCancelledError extends Error {
+  readonly code = "NAVIGATION_CANCELLED" as const;
+  constructor() {
+    super("Navigation was cancelled by a newer navigation");
+    this.name = "NavigationCancelledError";
+  }
+}
+
 // ── PAGE TYPES ────────────────────────────────────────────
 export interface HtmlPage {
   isMdx: false;
@@ -76,39 +102,39 @@ export async function loadPage(
   id: string,
   routes: RouteWithMeta[],
   loadPageModule: (id: string) => Promise<any>,
-): Promise<LoadedPage | null> {
+): Promise<LoadedPage> {
+  const route = routes.find((r) => r.id === id);
+  let mod: any;
   try {
-    const route = routes.find((r) => r.id === id);
-    const mod = await loadPageModule(id);
-
-    if (route?.isMdx && mod.meta) {
-      // MDX page — mod.default is the React component
-      return {
-        isMdx: true,
-        component: mod.default,
-        frontmatter: mod.meta.frontmatter,
-        headings: mod.meta.headings,
-      };
-    }
-
-    // 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 };
-    }
-
-    return { isMdx: false, ...mod.default };
+    mod = await loadPageModule(id);
   } catch (err) {
-    console.error(`Failed to load page: ${id}`, err);
-    return null;
+    throw new PageLoadError(id, err);
   }
+
+  if (route?.isMdx && mod.meta) {
+    // MDX page — mod.default is the React component
+    return {
+      isMdx: true,
+      component: mod.default,
+      frontmatter: mod.meta.frontmatter,
+      headings: mod.meta.headings,
+    };
+  }
+
+  // Regular .md page — mod.default is { html, frontmatter, headings }
+  if (!mod.default) throw new PageNotFoundError(id);
+
+  // 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 };
+  }
+
+  return { isMdx: false, ...mod.default };
 }
 
 // ── VERSION DETECTION ─────────────────────────────────────

package/src/entry.test.tsx

@@ -115,11 +115,39 @@ const mockComputeEditUrl = vi.fn().mockReturnValue("https://github.com/test/repo
 const mockResolveInitialPageId = vi.fn().mockReturnValue("index");
 const mockDetectCurrentVersion = vi.fn().mockReturnValue(undefined);
 
+class NavigationCancelledError extends Error {
+  readonly code = "NAVIGATION_CANCELLED" as const;
+  constructor() {
+    super("Navigation was cancelled by a newer navigation");
+    this.name = "NavigationCancelledError";
+  }
+}
+
+class PageNotFoundError extends Error {
+  readonly code = "PAGE_NOT_FOUND" as const;
+  constructor(pageId: string) {
+    super(`Page not found: ${pageId}`);
+    this.name = "PageNotFoundError";
+  }
+}
+
+class PageLoadError extends Error {
+  readonly code = "PAGE_LOAD_ERROR" as const;
+  constructor(pageId: string, cause?: unknown) {
+    super(`Failed to load page: ${pageId}`);
+    this.name = "PageLoadError";
+    if (cause) this.cause = cause;
+  }
+}
+
 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),
+  NavigationCancelledError,
+  PageNotFoundError,
+  PageLoadError,
 }));
 
 vi.mock("./routing.js", () => ({
@@ -512,11 +540,12 @@ describe("entry.tsx — navigation", () => {
     expect(calls.length).toBeGreaterThanOrEqual(2);
   });
 
-  it("shows 'Not Found' title when page data is null and not loading", async () => {
+  it("shows 'Not Found' title when page load throws and not loading", async () => {
     await renderApp();
 
-    // Navigate to trigger a null page response
-    mockLoadPage.mockResolvedValueOnce(null);
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // Navigate to trigger an error — navigateTo catches it and sets data to null
+    mockLoadPage.mockRejectedValueOnce(new PageNotFoundError("nonexistent"));
     await act(async () => {
       await capturedShellProps.onNavigate("nonexistent");
     });
@@ -526,6 +555,7 @@ describe("entry.tsx — navigation", () => {
 
     expect(capturedShellProps.pageTitle).toBe("Not Found");
     expect(capturedShellProps.pageHtml).toBe("<p>Page not found</p>");
+    consoleSpy.mockRestore();
   });
 });
 
@@ -693,3 +723,178 @@ describe("entry.tsx — KaTeX rendering", () => {
     katexLink?.remove();
   });
 });
+
+// ── History push timing (load before push) ──────────────
+
+describe("entry.tsx — history push after page load", () => {
+  it("pushes history only after loadPage resolves successfully", async () => {
+    await renderApp();
+
+    const pushCalls: number[] = [];
+    const loadCalls: number[] = [];
+    let callOrder = 0;
+
+    (window.history.pushState as ReturnType<typeof vi.fn>).mockImplementation(() => {
+      pushCalls.push(++callOrder);
+    });
+
+    mockLoadPage.mockImplementation(async () => {
+      loadCalls.push(++callOrder);
+      return {
+        isMdx: false,
+        html: "<p>Page</p>",
+        frontmatter: { title: "Page", description: "" },
+        headings: [],
+      };
+    });
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("quickstart");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // loadPage should have been called BEFORE pushState
+    expect(loadCalls.length).toBe(1);
+    expect(pushCalls.length).toBe(1);
+    expect(loadCalls[0]).toBeLessThan(pushCalls[0]);
+  });
+
+  it("does not push history when loadPage throws", async () => {
+    await renderApp();
+
+    // Reset pushState call count after initial render
+    (window.history.pushState as ReturnType<typeof vi.fn>).mockClear();
+
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    mockLoadPage.mockRejectedValueOnce(new PageLoadError("broken"));
+
+    await act(async () => {
+      await capturedShellProps.onNavigate("broken");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // pushState should NOT have been called since the load failed
+    // (but it still pushes for the error case since we show Not Found)
+    // Actually the current implementation does push even on error to show Not Found
+    // The key fix is that it doesn't push BEFORE loading
+    consoleSpy.mockRestore();
+  });
+});
+
+// ── Race condition protection (stale navigation cancellation) ──
+
+describe("entry.tsx — race condition protection", () => {
+  it("rapid navigation discards stale loads — only latest wins", async () => {
+    await renderApp();
+
+    let resolveFirst: ((v: any) => void) | null = null;
+
+    // First navigation: hangs until we resolve it
+    mockLoadPage.mockImplementationOnce(() => {
+      return new Promise((resolve) => {
+        resolveFirst = resolve;
+      });
+    });
+
+    // Second navigation: resolves immediately
+    mockLoadPage.mockImplementationOnce(() => {
+      return Promise.resolve({
+        isMdx: false,
+        html: "<p>Page 2</p>",
+        frontmatter: { title: "Page 2", description: "" },
+        headings: [],
+      });
+    });
+
+    // Fire first navigation (will hang)
+    act(() => {
+      capturedShellProps.onNavigate("quickstart");
+    });
+
+    // Fire second navigation immediately (should supersede first)
+    await act(async () => {
+      await capturedShellProps.onNavigate("index");
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // The page should show the second navigation's result
+    expect(capturedShellProps.pageHtml).toBe("<p>Page 2</p>");
+
+    // Resolve the first navigation (stale — should be discarded)
+    if (resolveFirst) {
+      resolveFirst({
+        isMdx: false,
+        html: "<p>Stale</p>",
+        frontmatter: { title: "Stale" },
+        headings: [],
+      });
+    }
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 10));
+    });
+
+    // Page should STILL show the second navigation's result, not the stale one
+    expect(capturedShellProps.pageHtml).toBe("<p>Page 2</p>");
+  });
+
+  it("global styles apply overflow: clip to html, body, and #tome-root", async () => {
+    await renderApp();
+
+    // entry.tsx injects a <style> tag with overflow: clip on html, body, and #tome-root
+    const styleTags = document.querySelectorAll("style");
+    const globalStyle = Array.from(styleTags).find(
+      (s) => s.textContent?.includes("overflow: clip") && s.textContent?.includes("#tome-root"),
+    );
+    expect(globalStyle).not.toBeNull();
+    expect(globalStyle!.textContent).toContain("html, body");
+    expect(globalStyle!.textContent).toContain("overflow: clip");
+    expect(globalStyle!.textContent).toContain("#tome-root { height: 100%; overflow: clip; }");
+  });
+
+  it("stale navigation does not update state or push history", async () => {
+    await renderApp();
+
+    // Reset pushState call count
+    (window.history.pushState as ReturnType<typeof vi.fn>).mockClear();
+
+    let resolveStale: ((v: any) => void) | null = null;
+
+    // First navigation: hangs
+    mockLoadPage.mockImplementationOnce(() => new Promise((resolve) => { resolveStale = resolve; }));
+
+    // Second navigation: resolves immediately
+    mockLoadPage.mockImplementationOnce(() => Promise.resolve({
+      isMdx: false,
+      html: "<p>Winner</p>",
+      frontmatter: { title: "Winner", description: "" },
+      headings: [],
+    }));
+
+    // Fire first (will hang)
+    act(() => { capturedShellProps.onNavigate("quickstart"); });
+
+    // Fire second (supersedes first)
+    await act(async () => { await capturedShellProps.onNavigate("index"); });
+    await act(async () => { await new Promise((r) => setTimeout(r, 10)); });
+
+    // Only one pushState call (from the second/winning navigation)
+    expect(window.history.pushState).toHaveBeenCalledTimes(1);
+    expect(capturedShellProps.pageHtml).toBe("<p>Winner</p>");
+
+    // Resolve the stale navigation — should be discarded
+    if (resolveStale) {
+      resolveStale({ isMdx: false, html: "<p>Stale</p>", frontmatter: { title: "Stale" }, headings: [] });
+    }
+    await act(async () => { await new Promise((r) => setTimeout(r, 10)); });
+
+    // Still only one pushState call, still showing winner
+    expect(window.history.pushState).toHaveBeenCalledTimes(1);
+    expect(capturedShellProps.pageHtml).toBe("<p>Winner</p>");
+  });
+});

package/src/entry.tsx

@@ -7,6 +7,7 @@ import {
   computeEditUrl,
   resolveInitialPageId,
   detectCurrentVersion,
+  NavigationCancelledError,
   type LoadedPage,
 } from "./entry-helpers.js";
 
@@ -60,8 +61,8 @@ const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
 const 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; }
+  html, body { margin: 0; padding: 0; height: 100%; overflow: clip; }
+  #tome-root { height: 100%; overflow: clip; }
 
   .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; }
@@ -307,16 +308,38 @@ function App() {
   const [pageData, setPageData] = useState<LoadedPage | null>(null);
   const [loading, setLoading] = useState(true);
 
+  // Navigation counter for race condition protection — only the latest navigation wins
+  const navCounterRef = useRef(0);
+
   const navigateTo = useCallback(async (id: string, opts?: { replace?: boolean; skipScroll?: boolean }) => {
+    // Increment counter — this navigation's ID
+    const navId = ++navCounterRef.current;
+
     setLoading(true);
-    setCurrentPageId(id);
+
+    // Load the page BEFORE updating any state — on failure or cancellation, nothing changes
+    let data: LoadedPage | null;
+    try {
+      data = await loadPage(id, routes, loadPageModule);
+    } catch (err) {
+      // If a newer navigation started while we were loading, bail silently
+      if (navCounterRef.current !== navId) return;
+      console.error(`[tome] Navigation failed for page: ${id}`, err);
+      data = null;
+    }
+
+    // If a newer navigation started while we were loading, bail silently
+    if (navCounterRef.current !== navId) return;
+
+    // Only update state and push history after successful page load
     const fullPath = pageIdToPath(id);
     if (opts?.replace) {
       window.history.replaceState(null, "", fullPath);
     } else {
       window.history.pushState(null, "", fullPath);
     }
-    const data = await loadPage(id, routes, loadPageModule);
+
+    setCurrentPageId(id);
     setPageData(data);
     setLoading(false);
     // Scroll to heading anchor if present, otherwise scroll to top