seemore 1.0.0

package/src/app/entry.client.tsx

@@ -0,0 +1,30 @@
+import { StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { RouterProvider, createBrowserRouter } from 'react-router';
+import { config } from 'virtual:seemore/config';
+import { decodePath, stripBase, toBasename } from '../shared/base.js';
+import { createRouteObjects } from './router.js';
+import { preloadPage } from './lib/pages.js';
+import './styles/globals.css';
+
+const container = document.getElementById('root');
+if (container === null) throw new Error('seemore: #root is missing from the page shell.');
+
+const router = createBrowserRouter(createRouteObjects(), { basename: toBasename(config.base) });
+
+function mount(target: HTMLElement) {
+  hydrateRoot(
+    target,
+    <StrictMode>
+      <RouterProvider router={router} />
+    </StrictMode>,
+  );
+}
+
+// Hydrating against prerendered HTML needs the current page's module in hand, or React would
+// hydrate a Suspense fallback over real markup.
+const current = stripBase(config.base, decodePath(window.location.pathname)).replace(/\/$/, '') || '/';
+void preloadPage(current).then(
+  () => mount(container),
+  () => mount(container),
+);

package/src/app/entry.prerender.tsx

@@ -0,0 +1,67 @@
+import { StrictMode } from 'react';
+import { renderToString } from 'react-dom/server';
+import { RouterProvider, createMemoryRouter } from 'react-router';
+import { config } from 'virtual:seemore/config';
+import { toBasename, withBase } from '../shared/base.js';
+import { ogImagePath } from '../shared/og.js';
+import { createRouteObjects } from './router.js';
+import { findRoute, preloadPage, routeEntries } from './lib/pages.js';
+
+export interface RenderResult {
+  html: string;
+  head: string;
+}
+
+/**
+ * The prerender driver.
+ *
+ * The page's module is loaded first, so `use()` resolves synchronously and `renderToString`
+ * 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.
+ */
+export async function render(url: string): Promise<RenderResult> {
+  await preloadPage(url);
+
+  const router = createMemoryRouter(createRouteObjects(), {
+    basename: toBasename(config.base),
+    initialEntries: [withBase(config.base, url)],
+  });
+
+  const html = renderToString(
+    <StrictMode>
+      <RouterProvider router={router} />
+    </StrictMode>,
+  );
+
+  return { html, head: head(url) };
+}
+
+export function listRoutes(): string[] {
+  return routeEntries().map((entry) => entry.url);
+}
+
+function head(url: string): string {
+  const entry = findRoute(url);
+  const title = entry === undefined || url === '/' ? config.title : `${entry.title} · ${config.title}`;
+  const description = entry?.description ?? config.description;
+
+  const tags = [`<title>${escapeHtml(title)}</title>`];
+  if (description != null) tags.push(`<meta name="description" content="${escapeHtml(description)}" />`);
+  if (config.favicon !== undefined) tags.push(`<link rel="icon" href="${escapeHtml(config.favicon)}" />`);
+
+  tags.push(`<meta property="og:title" content="${escapeHtml(title)}" />`);
+  if (description != null) tags.push(`<meta property="og:description" content="${escapeHtml(description)}" />`);
+
+  if (config.features['social.cards']) {
+    const card = escapeHtml(withBase(config.base, ogImagePath(url)));
+    tags.push(`<meta property="og:image" content="${card}" />`);
+    tags.push(`<meta name="twitter:card" content="summary_large_image" />`);
+    tags.push(`<meta name="twitter:image" content="${card}" />`);
+  }
+
+  return tags.join('\n    ');
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

package/src/app/features/anchors.ts

@@ -0,0 +1,23 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+
+/**
+ * Client-side navigation to `#hash` does not scroll on its own, and the target element only
+ * exists once the page's MDX module has rendered — so scrolling waits a frame.
+ */
+export function useHashScroll(): void {
+  const location = useLocation();
+
+  useEffect(() => {
+    if (location.hash === '') {
+      if (location.key !== 'default') window.scrollTo({ top: 0 });
+      return;
+    }
+
+    const id = decodeURIComponent(location.hash.slice(1));
+    const frame = requestAnimationFrame(() => {
+      document.getElementById(id)?.scrollIntoView({ block: 'start', behavior: 'smooth' });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [location.key, location.hash]);
+}

package/src/app/features/highlight.ts

@@ -0,0 +1,77 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+import { feature } from '../lib/features.js';
+
+/**
+ * `search.highlight`: mark every occurrence of the query on the page you landed on.
+ *
+ * The query rides in `?h=`, so a link copied from the address bar highlights for the next
+ * reader too — which is why there is no separate `search.share` flag.
+ */
+export function useSearchHighlight(): void {
+  const location = useLocation();
+
+  useEffect(() => {
+    if (!feature('search.highlight')) return;
+    const query = new URLSearchParams(location.search).get('h');
+    if (query === null || query.trim() === '') return;
+
+    const article = document.querySelector('article');
+    if (article === null) return;
+
+    const ranges = findRanges(article, query.trim());
+    if (ranges.length === 0) return;
+
+    // CSS Custom Highlight API where available: no DOM mutation, so React never fights it.
+    const highlightApi = (CSS as unknown as { highlights?: Map<string, unknown> }).highlights;
+    const HighlightCtor = (globalThis as unknown as { Highlight?: new (...r: Range[]) => unknown }).Highlight;
+
+    if (highlightApi !== undefined && HighlightCtor !== undefined) {
+      ensureHighlightStyle();
+      highlightApi.set('seemore-search', new HighlightCtor(...ranges));
+      ranges[0]?.startContainer.parentElement?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+      return () => {
+        highlightApi.delete('seemore-search');
+      };
+    }
+
+    ranges[0]?.startContainer.parentElement?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    return undefined;
+  }, [location.key, location.search]);
+}
+
+/**
+ * The `::highlight()` rule is installed here rather than in the stylesheet: CSS optimisers
+ * do not yet recognise the selector and warn about it on every build, and the rule is only
+ * meaningful where the Custom Highlight API exists anyway.
+ */
+function ensureHighlightStyle(): void {
+  const id = 'seemore-highlight-style';
+  if (document.getElementById(id) !== null) return;
+
+  const style = document.createElement('style');
+  style.id = id;
+  style.textContent =
+    '::highlight(seemore-search){background-color:color-mix(in oklab,var(--color-fd-primary) 30%,transparent)}';
+  document.head.append(style);
+}
+
+function findRanges(root: Element, query: string): Range[] {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  const needle = query.toLowerCase();
+  const ranges: Range[] = [];
+
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const text = node.nodeValue?.toLowerCase() ?? '';
+    let from = text.indexOf(needle);
+    while (from !== -1) {
+      const range = document.createRange();
+      range.setStart(node, from);
+      range.setEnd(node, from + needle.length);
+      ranges.push(range);
+      from = text.indexOf(needle, from + needle.length);
+    }
+  }
+
+  return ranges;
+}

package/src/app/features/prefetch.ts

@@ -0,0 +1,55 @@
+import { useEffect } from 'react';
+import { config } from 'virtual:seemore/config';
+import { decodePath, stripBase } from '../../shared/base.js';
+import { findRoute, loadPage } from '../lib/pages.js';
+import { feature } from '../lib/features.js';
+
+/**
+ * `navigation.instant.prefetch`: load the target page's chunk on hover.
+ *
+ * React Router's `<Link prefetch>` is framework-mode only and does nothing in library mode,
+ * so the prefetch is ours. It reads the same import map the router and prerender read, which
+ * is also what makes instant previews possible.
+ */
+export function usePrefetch(): void {
+  useEffect(() => {
+    if (!feature('navigation.instant.prefetch')) return;
+
+    const onPointerOver = (event: PointerEvent) => {
+      const url = routeUrlFromEvent(event);
+      if (url === undefined) return;
+      const entry = findRoute(url);
+      if (entry !== undefined) void loadPage(entry);
+    };
+
+    document.addEventListener('pointerover', onPointerOver, { passive: true });
+    return () => document.removeEventListener('pointerover', onPointerOver);
+  }, []);
+}
+
+/** The route URL a pointer event points at, or `undefined` if it points at nothing of ours. */
+export function routeUrlFromEvent(event: Event): string | undefined {
+  const target = event.target;
+  if (!(target instanceof Element)) return undefined;
+  const anchor = target.closest('a');
+  if (anchor === null) return undefined;
+  return routeUrlFromAnchor(anchor);
+}
+
+export function routeUrlFromAnchor(anchor: HTMLAnchorElement): string | undefined {
+  const href = anchor.getAttribute('href');
+  if (href === null || href === '' || href.startsWith('#')) return undefined;
+  if (anchor.target === '_blank') return undefined;
+
+  let pathname: string;
+  try {
+    const url = new URL(anchor.href, window.location.href);
+    if (url.origin !== window.location.origin) return undefined;
+    pathname = decodePath(url.pathname);
+  } catch {
+    return undefined;
+  }
+
+  const route = stripBase(config.base, pathname).replace(/\/$/, '');
+  return route === '' ? '/' : route;
+}

package/src/app/features/preview.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react';
+import { config } from 'virtual:seemore/config';
+import { findRoute, loadPage, peekPage } from '../lib/pages.js';
+import { feature } from '../lib/features.js';
+import { mdxComponents } from '../mdx/components.js';
+import { routeUrlFromEvent } from './prefetch.js';
+
+interface PreviewState {
+  url: string;
+  x: number;
+  y: number;
+}
+
+/**
+ * `navigation.instant.preview`: a hover popover rendering the target page inline.
+ *
+ * This is the reason the prefetch module exists independently of any router: it needs to
+ * load *and render* the target module, which no router's preload gives you.
+ */
+export function PagePreview() {
+  const [state, setState] = useState<PreviewState>();
+  const enabled = feature('navigation.instant.preview');
+
+  useEffect(() => {
+    if (!enabled) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const onPointerOver = (event: PointerEvent) => {
+      const url = routeUrlFromEvent(event);
+      const entry = url === undefined ? undefined : findRoute(url);
+      if (entry === undefined) return;
+
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        void loadPage(entry).then(() => {
+          setState({ url: entry.url, x: event.clientX, y: event.clientY });
+        });
+      }, 350);
+    };
+
+    const onPointerOut = () => {
+      clearTimeout(timer);
+      setState(undefined);
+    };
+
+    document.addEventListener('pointerover', onPointerOver, { passive: true });
+    document.addEventListener('pointerout', onPointerOut, { passive: true });
+    return () => {
+      clearTimeout(timer);
+      document.removeEventListener('pointerover', onPointerOver);
+      document.removeEventListener('pointerout', onPointerOut);
+    };
+  }, [enabled]);
+
+  if (!enabled || state === undefined) return null;
+
+  const loaded = peekPage(state.url);
+  if (loaded === undefined) return null;
+  const Content = loaded.default;
+
+  return (
+    <div
+      className="seemore-preview"
+      role="tooltip"
+      style={{ left: Math.min(state.x + 16, window.innerWidth - 420), top: state.y + 16 }}
+    >
+      <p className="seemore-preview-title">{findRoute(state.url)?.title ?? config.title}</p>
+      <div className="seemore-preview-body" aria-hidden="true">
+        <Content components={mdxComponents} />
+      </div>
+    </div>
+  );
+}

package/src/app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--seemore-head-->
+  </head>
+  <body>
+    <div id="root"><!--seemore-app--></div>
+    <script type="module" src="./entry.client.tsx"></script>
+  </body>
+</html>

package/src/app/layout/Breadcrumb.tsx

@@ -0,0 +1,29 @@
+import { Fragment } from 'react';
+import { Link } from 'react-router';
+import { useTreePath } from 'fumadocs-ui/contexts/tree';
+
+/** `navigation.path`. */
+export function Breadcrumb() {
+  const path = useTreePath();
+  if (path.length === 0) return null;
+
+  return (
+    <nav className="seemore-breadcrumb" aria-label="Breadcrumb">
+      {path.map((node, index) => {
+        const url = node.type === 'page' ? node.url : node.type === 'folder' ? node.index?.url : undefined;
+        return (
+          <Fragment key={`${String(node.name)}-${index}`}>
+            {index > 0 ? <span aria-hidden="true">/</span> : undefined}
+            {url === undefined ? (
+              <span>{node.name}</span>
+            ) : (
+              <Link to={url} viewTransition>
+                {node.name}
+              </Link>
+            )}
+          </Fragment>
+        );
+      })}
+    </nav>
+  );
+}

package/src/app/layout/DocsLayout.tsx

@@ -0,0 +1,103 @@
+import { use } from 'react';
+import { TreeContextProvider } from 'fumadocs-ui/contexts/tree';
+import { SidebarProvider } from 'fumadocs-ui/components/sidebar/base';
+import { 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 { useRouteUrl } from '../router.js';
+import { feature } from '../lib/features.js';
+import { pruneTree, usePageTree } from '../lib/tree.js';
+import { mdxComponents } from '../mdx/components.js';
+import { usePrefetch } from '../features/prefetch.js';
+import { PagePreview } from '../features/preview.js';
+import { useSearchHighlight } from '../features/highlight.js';
+import { useHashScroll } from '../features/anchors.js';
+import { SeemoreProvider } from './Provider.js';
+import { Header } from './Header.js';
+import { Sidebar } from './Sidebar.js';
+import { Breadcrumb } from './Breadcrumb.js';
+import { BackToTop, PageFooter, SiteFooter } from './Footer.js';
+import { IntegratedToc, Toc, TocProvider } from './Toc.js';
+
+/**
+ * The shell seemore owns. fumadocs-ui supplies the primitives — sidebar,
+ * TOC, search dialog, MDX components — and one layout, tuned by feature flags, arranges them.
+ */
+export function DocsLayout({ children }: { children: React.ReactNode }) {
+  const tree = usePageTree();
+
+  return (
+    <SeemoreProvider>
+      <TreeContextProvider tree={tree}>
+        <SidebarProvider>{children}</SidebarProvider>
+      </TreeContextProvider>
+    </SeemoreProvider>
+  );
+}
+
+export function DocPage({ entry }: { entry: RouteEntry }) {
+  const full = usePageTree();
+  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>);
+  const Content = page.default;
+
+  usePrefetch();
+  useSearchHighlight();
+  useHashScroll();
+
+  const integrated = feature('toc.integrate');
+
+  return (
+    <TocProvider toc={page.toc ?? []}>
+      <div className="seemore-shell">
+        <Header />
+        <div className="seemore-body">
+          <Sidebar>{integrated ? <IntegratedToc /> : undefined}</Sidebar>
+
+          <main className="seemore-main">
+            {feature('navigation.path') ? <Breadcrumb /> : undefined}
+            <article className="seemore-article prose">
+              <Content components={mdxComponents} />
+            </article>
+
+            {config.editLink !== undefined && feature('content.action.edit') ? (
+              <a className="seemore-edit-link" href={joinUrl(config.editLink.base, entry.file)}>
+                <Pencil aria-hidden="true" />
+                {config.editLink.text}
+              </a>
+            ) : undefined}
+
+            {feature('navigation.footer') ? <PageFooter tree={tree} url={url} /> : undefined}
+            <SiteFooter />
+          </main>
+
+          {integrated ? undefined : <Toc />}
+        </div>
+
+        {feature('navigation.top') ? <BackToTop /> : undefined}
+        <PagePreview />
+      </div>
+    </TocProvider>
+  );
+}
+
+export function NotFound() {
+  return (
+    <div className="seemore-shell">
+      <Header />
+      <main className="seemore-main">
+        <h1>Page not found</h1>
+        <p>There is no page at this address.</p>
+      </main>
+    </div>
+  );
+}
+
+function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}

package/src/app/layout/Footer.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router';
+import { ArrowLeft, ArrowRight, ArrowUp } from 'lucide-react';
+import { findNeighbour } from 'fumadocs-core/page-tree';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { config } from 'virtual:seemore/config';
+
+/** `navigation.footer`: previous / next links. */
+export function PageFooter({ tree, url }: { tree: PageTree.Root; url: string }) {
+  const { previous, next } = findNeighbour(tree, url);
+  if (previous === undefined && next === undefined) return null;
+
+  return (
+    <nav className="seemore-page-footer" aria-label="Previous and next page">
+      {previous === undefined ? (
+        <span />
+      ) : (
+        <Link to={previous.url} viewTransition className="seemore-prev">
+          <ArrowLeft aria-hidden="true" />
+          <span>{previous.name}</span>
+        </Link>
+      )}
+      {next === undefined ? (
+        <span />
+      ) : (
+        <Link to={next.url} viewTransition className="seemore-next">
+          <span>{next.name}</span>
+          <ArrowRight aria-hidden="true" />
+        </Link>
+      )}
+    </nav>
+  );
+}
+
+export function SiteFooter() {
+  if (config.footer === undefined) return null;
+  return (
+    <footer className="seemore-site-footer">
+      {config.footer.text === undefined ? undefined : <p>{config.footer.text}</p>}
+      {(config.footer.links ?? []).map((link) => (
+        <a key={link.link} href={link.link}>
+          {link.text}
+        </a>
+      ))}
+    </footer>
+  );
+}
+
+/** `navigation.top`. Hidden until the page has actually been scrolled. */
+export function BackToTop() {
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const onScroll = () => setVisible(window.scrollY > 400);
+    onScroll();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    return () => window.removeEventListener('scroll', onScroll);
+  }, []);
+
+  if (!visible) return null;
+
+  return (
+    <button
+      type="button"
+      className="seemore-back-to-top"
+      onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}
+    >
+      <ArrowUp aria-hidden="true" />
+      <span>Back to top</span>
+    </button>
+  );
+}

package/src/app/layout/Header.tsx

@@ -0,0 +1,59 @@
+import { Link, useLocation } from 'react-router';
+import { Moon, PanelLeft, Search, Sun } from 'lucide-react';
+import { useSearchContext } from 'fumadocs-ui/contexts/search';
+import { SidebarTrigger } from 'fumadocs-ui/components/sidebar/base';
+import { useTheme } from 'fumadocs-ui/provider/base';
+import { config } from 'virtual:seemore/config';
+
+export function Header() {
+  const search = useSearchContext();
+  const { resolvedTheme, setTheme } = useTheme();
+  const location = useLocation();
+
+  return (
+    <header className="seemore-header">
+      <SidebarTrigger className="seemore-sidebar-trigger" aria-label="Toggle navigation">
+        <PanelLeft />
+      </SidebarTrigger>
+
+      <Link to="/" className="seemore-brand" viewTransition>
+        {config.title}
+      </Link>
+
+      <nav className="seemore-nav" aria-label="Site">
+        {(config.nav ?? []).map((item) =>
+          item.link === undefined ? (
+            <span key={item.text}>{item.text}</span>
+          ) : (
+            <Link
+              key={item.text}
+              to={item.link}
+              viewTransition
+              aria-current={location.pathname === item.link ? 'page' : undefined}
+            >
+              {item.text}
+            </Link>
+          ),
+        )}
+      </nav>
+
+      {search.enabled ? (
+        <button type="button" className="seemore-search-trigger" onClick={() => search.setOpenSearch(true)}>
+          <Search aria-hidden="true" />
+          <span>Search</span>
+          <kbd>{'⌘K'}</kbd>
+        </button>
+      ) : undefined}
+
+      <button
+        type="button"
+        className="seemore-theme-toggle"
+        aria-label="Toggle dark mode"
+        onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
+      >
+        <Sun className="seemore-icon-light" aria-hidden="true" />
+        <Moon className="seemore-icon-dark" aria-hidden="true" />
+      </button>
+    </header>
+  );
+}

package/src/app/layout/Provider.tsx

@@ -0,0 +1,60 @@
+import { useMemo, type ComponentProps, type ReactNode } from 'react';
+import { Link as RouterLink, useLocation, useNavigate, useParams, useRevalidator } from 'react-router';
+import { FrameworkProvider } from 'fumadocs-core/framework';
+import { RootProvider } from 'fumadocs-ui/provider/base';
+import { decodePath } from '../../shared/base.js';
+import { SearchDialog } from '../search/SearchDialog.js';
+
+/**
+ * fumadocs' React Router bindings, with one change.
+ *
+ * Its `usePathname` returns `useLocation().pathname` verbatim, which the browser reports
+ * percent-encoded. Every active-state comparison in fumadocs — the highlighted sidebar link,
+ * whether a folder starts open — then measures `/gu%C3%ADa/…` against a page tree holding
+ * `/guía/…` and finds no match. Prerendering runs against a memory router, where the
+ * pathname is *not* encoded, so the two disagree and hydration fails on any page with a
+ * non-ASCII route. Decoding here makes both sides read the same URL.
+ */
+function usePathname(): string {
+  return decodePath(useLocation().pathname);
+}
+
+function useRouter() {
+  const navigate = useNavigate();
+  const revalidator = useRevalidator();
+
+  return useMemo(
+    () => ({
+      push(url: string) {
+        void navigate(url);
+      },
+      refresh() {
+        void revalidator.revalidate();
+      },
+    }),
+    [navigate, revalidator],
+  );
+}
+
+/** fumadocs' own Link binding, plus the view transition that gives navigation the SPA feel. */
+function Link({ href, prefetch: _prefetch, ...props }: ComponentProps<'a'> & { prefetch?: boolean }) {
+  return <RouterLink to={href ?? ''} viewTransition {...props} />;
+}
+
+export function SeemoreProvider({ children }: { children: ReactNode }) {
+  return (
+    <FrameworkProvider
+      usePathname={usePathname}
+      useParams={() => useParams() as Record<string, string | string[]>}
+      useRouter={useRouter}
+      Link={Link}
+    >
+      <RootProvider
+        search={{ enabled: true, SearchDialog }}
+        theme={{ attribute: 'class', defaultTheme: 'system', enableSystem: true }}
+      >
+        {children}
+      </RootProvider>
+    </FrameworkProvider>
+  );
+}