seemore 1.0.0

package/src/app/layout/Sidebar.tsx

@@ -0,0 +1,90 @@
+import { useEffect, type ComponentProps, type ReactNode } from 'react';
+import {
+  SidebarFolder as BaseFolder,
+  SidebarFolderContent as BaseFolderContent,
+  SidebarFolderLink as BaseFolderLink,
+  SidebarFolderTrigger as BaseFolderTrigger,
+  SidebarItem as BaseItem,
+  SidebarSeparator as BaseSeparator,
+  SidebarViewport,
+  useSidebar,
+} from 'fumadocs-ui/components/sidebar/base';
+import { createPageTreeRenderer } from 'fumadocs-ui/components/sidebar/page-tree';
+import { feature } from '../lib/features.js';
+import { useRouteUrl } from '../router.js';
+
+/**
+ * `components/sidebar/base` are behaviour-only primitives: they handle folder state, active
+ * tracking and auto-scroll, and render with no classes at all. Every class is the layout's
+ * to supply, which is what these wrappers do — fumadocs' own layout does the same.
+ */
+type ItemProps = ComponentProps<typeof BaseItem>;
+type FolderLinkProps = ComponentProps<typeof BaseFolderLink>;
+type FolderTriggerProps = ComponentProps<typeof BaseFolderTrigger>;
+type FolderContentProps = ComponentProps<typeof BaseFolderContent>;
+type SeparatorProps = ComponentProps<typeof BaseSeparator>;
+type FolderProps = ComponentProps<typeof BaseFolder>;
+
+const styled = {
+  SidebarItem: (props: ItemProps) => <BaseItem {...props} className="seemore-sidebar-link" />,
+  SidebarFolder: (props: FolderProps) => <BaseFolder {...props} className="seemore-sidebar-folder" />,
+  SidebarFolderLink: (props: FolderLinkProps) => (
+    <BaseFolderLink {...props} className="seemore-sidebar-link seemore-sidebar-folder-label" />
+  ),
+  // Must be a flex row: the chevron the primitive appends positions itself with `ms-auto`.
+  SidebarFolderTrigger: (props: FolderTriggerProps) => (
+    <BaseFolderTrigger {...props} className="seemore-sidebar-link seemore-sidebar-folder-label" />
+  ),
+  SidebarFolderContent: (props: FolderContentProps) => (
+    <BaseFolderContent {...props} className="seemore-sidebar-folder-content" />
+  ),
+  SidebarSeparator: (props: SeparatorProps) => <BaseSeparator {...props} className="seemore-sidebar-separator" />,
+};
+
+const renderPageTree = createPageTreeRenderer(styled);
+
+export function Sidebar({ children }: { children?: ReactNode }) {
+  // Below `md` the sidebar is a drawer, and the header's trigger is what opens it. Without
+  // reading that state the trigger is decorative: the panel is hidden by CSS alone.
+  const { open, setOpen } = useSidebar();
+  const url = useRouteUrl();
+
+  // Following a link should not leave the drawer covering the page you asked for.
+  useEffect(() => {
+    setOpen(false);
+  }, [url, setOpen]);
+
+  // Called during render, never inside `useMemo`: the renderer reads the tree context and
+  // calls hooks of its own.
+  const rendered = renderPageTree({
+    Folder: feature('navigation.sections')
+      ? ({ item, children }) => (
+          // Top-level entries read as headed groups rather than collapsible folders.
+          <BaseFolder collapsible={false} defaultOpen className="seemore-sidebar-folder">
+            <BaseSeparator className="seemore-sidebar-separator">{item.name}</BaseSeparator>
+            <BaseFolderContent className="seemore-sidebar-folder-content">{children}</BaseFolderContent>
+          </BaseFolder>
+        )
+      : undefined,
+  });
+
+  return (
+    <>
+      {open ? (
+        <button
+          type="button"
+          className="seemore-sidebar-backdrop"
+          aria-label="Close navigation"
+          onClick={() => setOpen(false)}
+        />
+      ) : undefined}
+
+      <div className="seemore-sidebar-column" data-open={open}>
+        <aside className="seemore-sidebar" aria-label="Documentation navigation">
+          <SidebarViewport>{rendered}</SidebarViewport>
+        </aside>
+        {children}
+      </div>
+    </>
+  );
+}

package/src/app/layout/Toc.tsx

@@ -0,0 +1,59 @@
+import { useEffect, useRef } from 'react';
+import { TOCProvider, TOCScrollArea, useActiveAnchor, useTOCItems } from 'fumadocs-ui/components/toc';
+import { TOCEmpty, TOCItem, TOCItems } from 'fumadocs-ui/components/toc/default';
+import type { TocEntry } from '../../shared/types.js';
+import { feature } from '../lib/features.js';
+
+export function TocProvider({ toc, children }: { toc: TocEntry[]; children: React.ReactNode }) {
+  return <TOCProvider toc={toc}>{children}</TOCProvider>;
+}
+
+export function Toc() {
+  const items = useTOCItems();
+  if (items.length === 0) return <nav className="seemore-toc" aria-label="On this page" />;
+
+  return (
+    <nav className="seemore-toc" aria-label="On this page">
+      <p className="seemore-toc-title">On this page</p>
+      <TOCScrollArea>
+        <TocBody />
+      </TOCScrollArea>
+    </nav>
+  );
+}
+
+/** `toc.integrate`: the same items, rendered inside the sidebar instead of its own rail. */
+export function IntegratedToc() {
+  const items = useTOCItems();
+  if (items.length === 0) return null;
+  return (
+    <div className="seemore-toc-integrated">
+      <TocBody />
+    </div>
+  );
+}
+
+function TocBody() {
+  const items = useTOCItems();
+  const active = useActiveAnchor();
+  const container = useRef<HTMLDivElement>(null);
+
+  // `toc.follow`: keep the active entry visible as the page scrolls.
+  useEffect(() => {
+    if (!feature('toc.follow') || active === undefined || container.current === null) return;
+    const element = container.current.querySelector(`a[href="#${CSS.escape(active)}"]`);
+    element?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+  }, [active]);
+
+  if (items.length === 0) return <TOCEmpty />;
+
+  return (
+    <div ref={container}>
+      <TOCItems>
+        {items.map((item) => (
+          <TOCItem key={item.url} item={item} />
+        ))}
+      </TOCItems>
+    </div>
+  );
+}

package/src/app/lib/features.ts

@@ -0,0 +1,7 @@
+import { config } from 'virtual:seemore/config';
+import type { Feature } from '../../shared/types.js';
+
+/** Feature flags are resolved node-side; the browser only reads them. */
+export function feature(name: Feature): boolean {
+  return config.features[name] === true;
+}

package/src/app/lib/pages.ts

@@ -0,0 +1,81 @@
+import { useSyncExternalStore } from 'react';
+import { getRoutes, subscribeRoutes } from 'virtual:seemore/routes';
+import type { PageModule, RouteEntry } from '../../shared/types.js';
+
+/**
+ * One module cache shared by the router, the hover prefetch and the prerender driver.
+ *
+ * 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.
+ */
+type Tracked = Promise<PageModule> & {
+  status?: 'pending' | 'fulfilled' | 'rejected';
+  value?: PageModule;
+  reason?: unknown;
+};
+
+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(() => {
+  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]));
+}
+
+export function routeEntries(): RouteEntry[] {
+  return getRoutes();
+}
+
+export function findRoute(url: string): RouteEntry | undefined {
+  return index.get(url);
+}
+
+/** Subscribe a component to corpus changes; re-renders on create, rename and delete. */
+export function useRouteEntry(url: string): RouteEntry | undefined {
+  const entries = useSyncExternalStore(subscribeRoutes, getRoutes, getRoutes);
+  return entries.find((entry) => entry.url === url);
+}
+
+export function loadPage(entry: RouteEntry): Tracked {
+  const existing = cache.get(entry.url);
+  if (existing !== undefined) return existing;
+
+  const promise = entry.load() as Tracked;
+  promise.status = 'pending';
+  promise.then(
+    (value) => {
+      promise.status = 'fulfilled';
+      promise.value = value;
+    },
+    (reason: unknown) => {
+      promise.status = 'rejected';
+      promise.reason = reason;
+    },
+  );
+
+  cache.set(entry.url, promise);
+  return promise;
+}
+
+/** Load a page ahead of rendering it. Used by prerender and by the hover prefetch. */
+export async function preloadPage(url: string): Promise<PageModule | undefined> {
+  const entry = findRoute(url);
+  if (entry === undefined) return undefined;
+  return await loadPage(entry);
+}
+
+export function peekPage(url: string): PageModule | undefined {
+  const tracked = cache.get(url);
+  return tracked?.status === 'fulfilled' ? tracked.value : undefined;
+}

package/src/app/lib/tree.ts

@@ -0,0 +1,41 @@
+import { useSyncExternalStore } from 'react';
+import { deserializePageTree } from 'fumadocs-core/source/client';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { getTree, subscribeTree } from 'virtual:seemore/tree';
+
+/**
+ * The page tree, kept current across content edits.
+ *
+ * `virtual:seemore/tree` is a self-accepting module, so a create, rename, retitle or delete
+ * replaces its value and notifies here — the sidebar re-renders in place, with no reload and
+ * no lost scroll position.
+ */
+export function usePageTree(): PageTree.Root {
+  const serialized = useSyncExternalStore(subscribeTree, getTree, getTree);
+  return deserializePageTree(serialized);
+}
+
+/**
+ * `navigation.prune`: render only the subtree around the current page.
+ *
+ * Large sites pay for a sidebar that renders every page on every navigation; pruning keeps
+ * the active branch and collapses the rest.
+ */
+export function pruneTree(root: PageTree.Root, url: string): PageTree.Root {
+  return { ...root, children: keep(root.children, url) };
+}
+
+function keep(nodes: PageTree.Node[], url: string): PageTree.Node[] {
+  return nodes.map((node): PageTree.Node => {
+    if (node.type !== 'folder') return node;
+    const children = containsUrl(node, url) ? keep(node.children, url) : [];
+    return { ...node, children };
+  });
+}
+
+function containsUrl(node: PageTree.Node, url: string): boolean {
+  if (node.type === 'page') return node.url === url;
+  if (node.type !== 'folder') return false;
+  if (node.index?.url === url) return true;
+  return node.children.some((child) => containsUrl(child, url));
+}

package/src/app/mdx/Mermaid.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useId, useRef, useState } from 'react';
+
+/**
+ * Mermaid runs in the browser.
+ *
+ * Rendering diagrams at build time would mean `rehype-mermaid`, which means Playwright and a
+ * downloaded browser as an install dependency of a documentation CLI. The stated consequence
+ * is that diagrams are absent from the prerendered HTML; page *text*, which is what the SEO
+ * guarantee protects, is not.
+ */
+export function Mermaid({ chart }: { chart: string }) {
+  const id = useId().replace(/[^a-zA-Z0-9]/g, '');
+  const container = useRef<HTMLDivElement>(null);
+  const [svg, setSvg] = useState<string>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    let cancelled = false;
+
+    void (async () => {
+      try {
+        const { default: mermaid } = await import('mermaid');
+        const dark = document.documentElement.classList.contains('dark');
+        mermaid.initialize({ startOnLoad: false, theme: dark ? 'dark' : 'default', securityLevel: 'strict' });
+        const { svg: rendered } = await mermaid.render(`seemore-mermaid-${id}`, chart);
+        if (!cancelled) setSvg(rendered);
+      } catch (cause) {
+        if (!cancelled) setError(cause instanceof Error ? cause.message : String(cause));
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [chart, id]);
+
+  if (error !== undefined) {
+    return (
+      <pre className="seemore-mermaid-error" role="note">
+        {`Could not render this diagram: ${error}`}
+      </pre>
+    );
+  }
+
+  return (
+    <div
+      ref={container}
+      className="seemore-mermaid"
+      // The diagram is generated by mermaid from the page's own source, not from user input.
+      dangerouslySetInnerHTML={svg === undefined ? undefined : { __html: svg }}
+    >
+      {svg === undefined ? <pre className="seemore-mermaid-source">{chart}</pre> : undefined}
+    </div>
+  );
+}
+
+export default Mermaid;

package/src/app/mdx/Pdf.tsx

@@ -0,0 +1,25 @@
+import type { ComponentProps } from 'react';
+
+/**
+ * Sibling PDFs render in the browser's own viewer.
+ *
+ * Every element here is inline-level. Markdown puts an image in a paragraph, and a `<figure>`
+ * or any other block element inside a `<p>` makes the HTML parser close the paragraph early —
+ * so the prerendered markup and React's tree disagree, and hydration throws. `display: block`
+ * on a `<span>` gets the same layout with none of that.
+ *
+ * `pdfjs-dist` is roughly a megabyte, which is a poor trade for a docs site. The accepted
+ * cost is that most mobile browsers degrade `<embed>` to a download link.
+ */
+export function Pdf({ src, title, ...props }: ComponentProps<'embed'> & { src: string }) {
+  return (
+    <span className="seemore-pdf">
+      <embed src={src} type="application/pdf" title={title} {...props} />
+      <a href={src} download>
+        Download {title ?? 'PDF'}
+      </a>
+    </span>
+  );
+}
+
+export default Pdf;

package/src/app/mdx/components.tsx

@@ -0,0 +1,57 @@
+import type { AnchorHTMLAttributes, ComponentProps } from 'react';
+import { Link } from 'react-router';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { config } from 'virtual:seemore/config';
+import { isExternalHref, stripBase } from '../../shared/base.js';
+import { Mermaid } from './Mermaid.js';
+import { Pdf } from './Pdf.js';
+
+/**
+ * Internal links go through React Router so navigation stays client-side.
+ *
+ * remark rewrote content links to *based* hrefs, and React Router re-applies the
+ * basename itself, so the base is stripped here to keep it from appearing twice.
+ */
+function MdxLink({ href = '', children, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) {
+  if (isExternalHref(href)) {
+    const external = /^[a-z][a-z0-9+.-]*:|^\/\//i.test(href);
+    return (
+      <a href={href} {...(external ? { target: '_blank', rel: 'noreferrer noopener' } : {})} {...props}>
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <Link to={stripBase(config.base, href)} viewTransition {...props}>
+      {children}
+    </Link>
+  );
+}
+
+function isPdf(src: string | undefined): src is string {
+  if (typeof src !== 'string') return false;
+  // A small PDF is inlined by the bundler, so the extension is gone and the mime type is
+  // the only thing left to go on.
+  return /\.pdf(?:[?#].*)?$/i.test(src) || src.startsWith('data:application/pdf');
+}
+
+/** Sibling assets: images inline, PDFs in a viewer. */
+function MdxImage({ src, alt, ...props }: ComponentProps<'img'>) {
+  const source = typeof src === 'string' ? src : undefined;
+  if (isPdf(source)) {
+    return <Pdf src={source} title={alt} />;
+  }
+  const Image = defaultMdxComponents.img;
+  return <Image src={src} alt={alt} {...props} />;
+}
+
+export const mdxComponents = {
+  ...defaultMdxComponents,
+  a: MdxLink,
+  img: MdxImage,
+  // `remark-mdx-mermaid` rewrites ```mermaid fences to <Mermaid chart="…" />, but supplies no
+  // component of its own — this is ours.
+  Mermaid,
+  Pdf,
+};

package/src/app/router.tsx

@@ -0,0 +1,43 @@
+import { Suspense } from 'react';
+import { useLocation, type RouteObject } from 'react-router';
+import { decodePath } from '../shared/base.js';
+import { DocPage, DocsLayout, NotFound } from './layout/DocsLayout.js';
+import { useRouteEntry } from './lib/pages.js';
+
+/** The current route URL: React Router has already removed the basename. */
+export function useRouteUrl(): string {
+  const { pathname } = useLocation();
+  const trimmed = decodePath(pathname).replace(/\/+$/, '');
+  return trimmed === '' ? '/' : trimmed;
+}
+
+function Page() {
+  const entry = useRouteEntry(useRouteUrl());
+  return entry === undefined ? <NotFound /> : <DocPage entry={entry} />;
+}
+
+/**
+ * One catch-all route, matched against `virtual:seemore/routes` at render time.
+ *
+ * Our URLs are exact strings, so there is no pattern matching for a router to do — and a
+ * route table that never changes shape means creating or deleting a page needs no new
+ * router, which is what keeps the dev-mode sidebar refresh a re-render rather than a reload.
+ *
+ * A data router, because fumadocs' React Router integration uses its hooks — but **no route
+ * carries a loader**, which is the actual guarantee. With nothing to fetch,
+ * there is no code path in which server-side data can fail to prerender.
+ */
+export function createRouteObjects(): RouteObject[] {
+  return [
+    {
+      path: '*',
+      element: (
+        <DocsLayout>
+          <Suspense fallback={<div className="seemore-loading" aria-busy="true" />}>
+            <Page />
+          </Suspense>
+        </DocsLayout>
+      ),
+    },
+  ];
+}

package/src/app/search/SearchDialog.tsx

@@ -0,0 +1,103 @@
+import { useMemo } from 'react';
+import { useNavigate } from 'react-router';
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import {
+  SearchDialog as Dialog,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+} from 'fumadocs-ui/components/dialog/search';
+import type { SharedProps } from 'fumadocs-ui/contexts/search';
+import { config } from 'virtual:seemore/config';
+import { stripBase } from '../../shared/base.js';
+import { feature } from '../lib/features.js';
+import { createSearchClient } from './client.js';
+
+/**
+ * Our own dialog rather than fumadocs' `DefaultSearchDialog`, because the default one talks
+ * to a search *route*; seemore has no server, so the client is a static index read in a
+ * worker.
+ */
+/**
+ * Add the highlight query to a result URL.
+ *
+ * A content match points at a heading, so the URL already has a fragment — and a query
+ * appended after one is part of the fragment, not a search param.
+ */
+function withHighlight(url: string, query: string): string {
+  if (!feature('search.highlight') || query === '') return url;
+
+  const hashAt = url.indexOf('#');
+  const path = hashAt === -1 ? url : url.slice(0, hashAt);
+  const hash = hashAt === -1 ? '' : url.slice(hashAt);
+  return `${path}?h=${encodeURIComponent(query)}${hash}`;
+}
+
+export function SearchDialog(props: SharedProps) {
+  const navigate = useNavigate();
+
+  const client = useMemo(() => createSearchClient(config.search), []);
+  const { search, setSearch, query } = useDocsSearch({ client });
+  const results = query.data === 'empty' || query.data === undefined ? [] : query.data;
+
+  // `search.suggest`: complete the last word inline from the best result's title.
+  const completion = useMemo(() => {
+    if (!feature('search.suggest') || search === '' || results.length === 0) return '';
+    const title = results[0]?.content ?? '';
+    return title.toLowerCase().startsWith(search.toLowerCase()) ? title.slice(search.length) : '';
+  }, [results, search]);
+
+  const items = results.map((result) => ({ ...result, external: false }));
+
+  return (
+    <Dialog
+      {...props}
+      search={search}
+      onSearchChange={setSearch}
+      isLoading={query.isLoading}
+      onSelect={(item) => {
+        if (item.type === 'action') return;
+        props.onOpenChange(false);
+        // `search.highlight`: the query travels with the link, so a shared result highlights
+        // too — which is why there is no separate `search.share`.
+        void navigate(withHighlight(stripBase(config.base, item.url), search), { viewTransition: true });
+      }}
+    >
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput
+            placeholder="Search documentation…"
+            onKeyDown={(event) => {
+              if (event.key !== 'ArrowRight' || completion === '') return;
+              event.preventDefault();
+              setSearch(search + completion);
+            }}
+          />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        {completion === '' ? undefined : (
+          <p className="seemore-search-suggestion" aria-hidden="true">
+            {search}
+            <span>{completion}</span>
+          </p>
+        )}
+        {query.error === undefined ? (
+          <SearchDialogList items={items} />
+        ) : (
+          // A search box that silently finds nothing is worse than one that says why.
+          <p className="seemore-search-error" role="alert">
+            {query.error.message}
+          </p>
+        )}
+      </SearchDialogContent>
+    </Dialog>
+  );
+}
+
+export default SearchDialog;