seemore 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seemore",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Let AI write the Markdown. Let seemore show it better — zero config documentation framework.",
   "license": "MIT",
   "type": "module",

package/src/app/entry.prerender.tsx

@@ -1,5 +1,6 @@
-import { StrictMode } from 'react';
-import { renderToString } from 'react-dom/server';
+import { Writable } from 'node:stream';
+import { StrictMode, type ReactNode } from 'react';
+import { renderToPipeableStream } from 'react-dom/server';
 import { RouterProvider, createMemoryRouter } from 'react-router';
 import { config } from 'virtual:seemore/config';
 import { toBasename, withBase } from '../shared/base.js';
@@ -15,7 +16,7 @@ export interface RenderResult {
 /**
  * The prerender driver.
  *
- * The page's module is loaded first, so `use()` resolves synchronously and `renderToString`
+ * The page's module is loaded first, so `use()` resolves synchronously and the renderer
  * emits the complete article rather than a Suspense fallback. No route has a loader, so the
  * memory router is initialised the moment it is created.
  */
@@ -27,15 +28,82 @@ export async function render(url: string): Promise<RenderResult> {
     initialEntries: [withBase(config.base, url)],
   });
 
-  const html = renderToString(
+  const { html, failures } = await renderToHtml(
     <StrictMode>
       <RouterProvider router={router} />
     </StrictMode>,
   );
 
+  // React hands a render error to the nearest Suspense boundary and carries on. Without this
+  // the page would be written out as the loading fallback — an empty shell — and the build
+  // would report it as a success.
+  if (failures.length > 0) throw prerenderError(url, failures[0]);
+
   return { html, head: head(url) };
 }
 
+/**
+ * The whole tree as one string, plus anything that threw while rendering it.
+ *
+ * `renderToString` would be shorter, but it swallows render errors: its own `onError` is
+ * internal and a failed subtree is silently replaced by its Suspense fallback. The streaming
+ * renderer reports them, and piping only once `onAllReady` has fired keeps the output the
+ * same complete markup — no fallbacks, no streaming scripts.
+ */
+function renderToHtml(element: ReactNode): Promise<{ html: string; failures: unknown[] }> {
+  return new Promise((resolve) => {
+    const failures: unknown[] = [];
+    const chunks: Buffer[] = [];
+
+    const sink = new Writable({
+      write(chunk: Buffer, _encoding, done) {
+        chunks.push(Buffer.from(chunk));
+        done();
+      },
+    });
+    sink.on('finish', () => {
+      resolve({ html: Buffer.concat(chunks).toString('utf8'), failures });
+    });
+
+    const stream = renderToPipeableStream(element, {
+      onError(error: unknown) {
+        failures.push(error);
+      },
+      onAllReady() {
+        stream.pipe(sink);
+      },
+      // Nothing was rendered at all: there is no markup to hand back, and `failures` already
+      // holds the reason.
+      onShellError() {
+        resolve({ html: '', failures });
+      },
+    });
+  });
+}
+
+/** Components an MDX file can use without importing anything. */
+const PROVIDED_COMPONENTS = 'Callout, Card, Cards, CodeBlockTabs, Mermaid, D2 and Pdf';
+
+/**
+ * A page that threw, reported the way the rest of the build reports problems: the file it
+ * came from, what went wrong, and — for the common case of an MDX file reaching for a
+ * component that is not there — the fix.
+ */
+function prerenderError(url: string, cause: unknown): Error {
+  const file = findRoute(url)?.file;
+  const message = cause instanceof Error ? cause.message : String(cause);
+  const undefinedComponent = /Expected component `(.+?)` to be defined/.exec(message);
+
+  const hint =
+    undefinedComponent === null
+      ? ''
+      : `\n\n  \`<${undefinedComponent[1]}>\` is not one of the components seemore provides ` +
+        `(${PROVIDED_COMPONENTS}), and a Markdown file has no imports to add one with. ` +
+        `Remove it, or write the markup by hand.`;
+
+  return new Error(`${file ?? url} failed to render.\n\n  ${message}${hint}`, { cause });
+}
+
 export function listRoutes(): string[] {
   return routeEntries().map((entry) => entry.url);
 }

package/src/app/layout/DocsLayout.tsx

@@ -1,11 +1,10 @@
-import { use } from 'react';
 import type * as PageTree from 'fumadocs-core/page-tree';
 import { TreeContextProvider } from 'fumadocs-ui/contexts/tree';
 import { SidebarProvider } from 'fumadocs-ui/components/sidebar/base';
 import { ArrowRight, Pencil } from 'lucide-react';
 import { config } from 'virtual:seemore/config';
-import type { PageModule, RouteEntry } from '../../shared/types.js';
-import { loadPage } from '../lib/pages.js';
+import type { RouteEntry } from '../../shared/types.js';
+import { usePageModule } from '../lib/pages.js';
 import { useRouteUrl } from '../router.js';
 import { feature } from '../lib/features.js';
 import { pruneTree, usePageTree } from '../lib/tree.js';
@@ -43,9 +42,9 @@ export function DocPage({ entry }: { entry: RouteEntry }) {
   const url = useRouteUrl();
   const tree = feature('navigation.prune') ? pruneTree(full, url) : full;
 
-  // `use()` on the cached module promise: already-loaded pages render synchronously, which
-  // is what makes `renderToString` emit a complete page.
-  const page = use(loadPage(entry) as Promise<PageModule>);
+  // `use()` on the cached module promise, inside the hook: already-loaded pages render
+  // synchronously, which is what makes `renderToString` emit a complete page.
+  const page = usePageModule(entry);
   const Content = page.default;
 
   usePrefetch();
@@ -109,6 +108,34 @@ export function NotFound() {
   );
 }
 
+/**
+ * A page whose own markup threw — an `.mdx` file reaching for a component seemore does not
+ * provide, most often. `seemore build` refuses to write such a page at all; here, in the dev
+ * server and on client-side navigation, the reason replaces the article, because React
+ * unmounts the whole app when nothing catches the error and a blank screen says nothing.
+ */
+export function PageError({ message }: { message: string }) {
+  return (
+    <div className="seemore-shell">
+      <Header />
+      <div className="seemore-body">
+        <Sidebar />
+
+        <main className="seemore-main">
+          <article className="seemore-article prose">
+            <h1>This page failed to render</h1>
+            <pre>
+              <code>{message}</code>
+            </pre>
+          </article>
+
+          <SiteFooter />
+        </main>
+      </div>
+    </div>
+  );
+}
+
 /**
  * The generated index: when no `index.md` or root `README.md` claims `/`, the home address
  * lists every page instead of apologising.

package/src/app/lib/pages.ts

@@ -1,4 +1,4 @@
-import { useSyncExternalStore } from 'react';
+import { use, useSyncExternalStore } from 'react';
 import { getRoutes, subscribeRoutes } from 'virtual:seemore/routes';
 import type { PageModule, RouteEntry } from '../../shared/types.js';
 
@@ -8,26 +8,48 @@ import type { PageModule, RouteEntry } from '../../shared/types.js';
  * The promise is annotated with `status`/`value`, the convention React's `use()` reads, so a
  * module that is already loaded renders synchronously — which is what lets `renderToString`
  * produce a complete page with no Suspense fallback in the output.
+ *
+ * Entries are keyed by URL and stamped with the route's content `version`. A URL can outlive
+ * its module: in dev, a body edit keeps the address and replaces the file behind it, and the
+ * cached promise would be the last thing still holding the old component. Fast Refresh does
+ * not step in — MDX emits a named `toc` export beside the default one, so the React plugin
+ * declines the module and invalidates it instead, and that invalidation is absorbed by the
+ * route store's own `accept()`. The version is how the cache notices on its own.
  */
 type Tracked = Promise<PageModule> & {
   status?: 'pending' | 'fulfilled' | 'rejected';
   value?: PageModule;
   reason?: unknown;
+  version: string;
+  /** A replacement already loading for a newer version, so an edit is fetched once. */
+  next?: Tracked;
 };
 
 const cache = new Map<string, Tracked>();
 
 let index = buildIndex();
 
-// The route list is replaced whenever the corpus changes, so the lookup is rebuilt with it
-// and pages that no longer exist stop holding on to their modules.
-subscribeRoutes(() => {
+// Bumped whenever a cached module is swapped for a newer version, so a page that is on
+// screen re-renders onto the new one. Route changes have their own store; this one is only
+// for replacements, which arrive later, once the new module has actually loaded.
+let generation = 0;
+const swapListeners = new Set<() => void>();
+
+subscribeRoutes(() => onRoutesChanged());
+
+/**
+ * Rebuild the lookup and drop pages that no longer exist. A page that still exists keeps its
+ * entry even if its content changed: the version check in `loadPage` handles that, and it
+ * keeps the old module on screen until the new one is ready rather than dropping to a
+ * loading fallback. Exported for the pages test.
+ */
+export function onRoutesChanged(): void {
   index = buildIndex();
   // Deleting the current entry while iterating a Map is well defined.
   for (const url of cache.keys()) {
     if (!index.has(url)) cache.delete(url);
   }
-});
+}
 
 function buildIndex(): Map<string, RouteEntry> {
   return new Map(getRoutes().map((entry) => [entry.url, entry]));
@@ -47,11 +69,61 @@ export function useRouteEntry(url: string): RouteEntry | undefined {
   return entries.find((entry) => entry.url === url);
 }
 
+/** The page's module, re-rendering when an edit replaces it. Suspends until first loaded. */
+export function usePageModule(entry: RouteEntry): PageModule {
+  useSyncExternalStore(subscribeSwaps, getGeneration, getGeneration);
+  return use(loadPage(entry) as Promise<PageModule>);
+}
+
+/** Exported for the pages test; components go through `usePageModule`. */
+export function subscribeSwaps(listener: () => void): () => void {
+  swapListeners.add(listener);
+  return () => {
+    swapListeners.delete(listener);
+  };
+}
+
+function getGeneration(): number {
+  return generation;
+}
+
 export function loadPage(entry: RouteEntry): Tracked {
   const existing = cache.get(entry.url);
-  if (existing !== undefined) return existing;
+  if (existing === undefined) {
+    const fresh = track(entry);
+    cache.set(entry.url, fresh);
+    return fresh;
+  }
+  if (existing.version === entry.version) return existing;
+
+  // Only a rendered module is worth keeping on screen while its replacement loads. A pending
+  // or failed one is not: hand over immediately, so a fixed file suspends on the fix instead
+  // of re-throwing the error it just corrected.
+  if (existing.status !== 'fulfilled') {
+    const fresh = track(entry);
+    cache.set(entry.url, fresh);
+    return fresh;
+  }
 
+  if (existing.next?.version !== entry.version) {
+    const fresh = track(entry);
+    existing.next = fresh;
+    const settle = () => {
+      // The page may have been deleted, or this URL may already be on a later version — the
+      // next render compares versions again, so the only wrong move is resurrecting a URL.
+      if (!index.has(entry.url)) return;
+      cache.set(entry.url, fresh);
+      generation += 1;
+      for (const listener of swapListeners) listener();
+    };
+    fresh.then(settle, settle);
+  }
+  return existing;
+}
+
+function track(entry: RouteEntry): Tracked {
   const promise = entry.load() as Tracked;
+  promise.version = entry.version;
   promise.status = 'pending';
   promise.then(
     (value) => {
@@ -63,8 +135,6 @@ export function loadPage(entry: RouteEntry): Tracked {
       promise.reason = reason;
     },
   );
-
-  cache.set(entry.url, promise);
   return promise;
 }
 

package/src/app/router.tsx

@@ -1,7 +1,8 @@
-import { Suspense } from 'react';
+import { Component, Suspense, type ReactNode } from 'react';
 import { useLocation, type RouteObject } from 'react-router';
 import { decodePath } from '../shared/base.js';
-import { DocPage, DocsLayout, NotFound, Overview } from './layout/DocsLayout.js';
+import type { RouteEntry } from '../shared/types.js';
+import { DocPage, DocsLayout, NotFound, Overview, PageError } from './layout/DocsLayout.js';
 import { useRouteEntry } from './lib/pages.js';
 
 /** The current route URL: React Router has already removed the basename. */
@@ -14,12 +15,50 @@ export function useRouteUrl(): string {
 function Page() {
   const url = useRouteUrl();
   const entry = useRouteEntry(url);
+  // Keyed by address, so navigating away from a page that threw starts clean rather than
+  // carrying its error to every page after it. Reset by content version, so in dev an edit
+  // that fixes the file gets to render — a boundary in its error state has unmounted the
+  // children, and nothing else is left in the tree to try again.
+  return (
+    <PageErrorBoundary key={url} resetKey={entry?.version}>
+      <PageContent url={url} entry={entry} />
+    </PageErrorBoundary>
+  );
+}
+
+function PageContent({ url, entry }: { url: string; entry: RouteEntry | undefined }) {
   if (entry !== undefined) return <DocPage entry={entry} />;
   // A folder with no `index.md` or root `README.md` still gets a home address: a generated
   // list of every page, not an apology.
   return url === '/' ? <Overview /> : <NotFound />;
 }
 
+/**
+ * The only error boundary in the app. Render errors come from page content — the rest of the
+ * tree is seemore's own — so this sits around the page and nothing else.
+ */
+class PageErrorBoundary extends Component<
+  { children: ReactNode; resetKey: string | undefined },
+  { message: string | undefined }
+> {
+  override state: { message: string | undefined } = { message: undefined };
+
+  static getDerivedStateFromError(error: unknown): { message: string } {
+    return { message: error instanceof Error ? error.message : String(error) };
+  }
+
+  override componentDidUpdate(previous: { resetKey: string | undefined }): void {
+    if (this.state.message !== undefined && previous.resetKey !== this.props.resetKey) {
+      this.setState({ message: undefined });
+    }
+  }
+
+  override render() {
+    if (this.state.message !== undefined) return <PageError message={this.state.message} />;
+    return this.props.children;
+  }
+}
+
 /**
  * One catch-all route, matched against `virtual:seemore/routes` at render time.
  *

package/src/shared/types.ts

@@ -62,6 +62,8 @@ export interface RouteEntry {
   absPath: string;
   title: string;
   description: string | null;
+  /** Content hash; a new value means `load()` now resolves to a different module. */
+  version: string;
   load: () => Promise<PageModule>;
 }