seemore 1.0.0

package/src/app/search/client.ts

@@ -0,0 +1,143 @@
+import { staticClient } from 'fumadocs-core/search/client/orama-static';
+import type { SortedResult } from 'fumadocs-core/search';
+import type { ClientSearchConfig } from '../../shared/types.js';
+
+export interface SearchClientLike {
+  search: (query: string) => Promise<SortedResult[]>;
+}
+
+/** Build the client the configured provider calls for. */
+export function createSearchClient(config: ClientSearchConfig): SearchClientLike {
+  if (config.provider === 'static') return createStaticClient(config.from);
+  if (config.provider === 'algolia') return createAlgoliaClient(config);
+  return createOramaCloudClient(config);
+}
+
+/**
+ * The static index is parsed and queried off the main thread, falling back to the main
+ * thread where workers are unavailable.
+ *
+ * On any real corpus, parsing the index on the main thread is a visible stall — MkDocs
+ * Material moved theirs into a worker for the same reason.
+ */
+function createStaticClient(from: string): SearchClientLike {
+  const onMainThread = (): SearchClientLike => {
+    const direct = staticClient({ from });
+    return { search: async (query) => await direct.search(query) };
+  };
+
+  if (typeof Worker === 'undefined') return onMainThread();
+
+  let worker: Worker;
+  try {
+    worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
+  } catch {
+    return onMainThread();
+  }
+
+  const pending = new Map<number, { resolve: (r: SortedResult[]) => void; reject: (e: Error) => void }>();
+  let nextId = 0;
+  let fallback: SearchClientLike | undefined;
+
+  /**
+   * A worker that fails to start must not take search down with it. Anything the worker
+   * cannot do, the main thread does — more slowly, and still correctly.
+   */
+  const degrade = (): SearchClientLike => {
+    fallback ??= onMainThread();
+    for (const [id, handlers] of pending) {
+      pending.delete(id);
+      handlers.reject(new Error('seemore: the search worker stopped; retrying on the main thread.'));
+    }
+    return fallback;
+  };
+
+  worker.addEventListener('error', () => {
+    degrade();
+  });
+
+  worker.addEventListener('message', (event: MessageEvent) => {
+    const data = event.data as { type: string; id?: number; results?: SortedResult[]; message?: string };
+    if (data.id === undefined) return;
+    const handlers = pending.get(data.id);
+    if (handlers === undefined) return;
+    pending.delete(data.id);
+    if (data.type === 'result') handlers.resolve(data.results ?? []);
+    else handlers.reject(new Error(data.message ?? 'Search failed.'));
+  });
+
+  worker.postMessage({ type: 'init', from });
+
+  return {
+    async search(query) {
+      if (fallback !== undefined) return await fallback.search(query);
+
+      try {
+        return await new Promise<SortedResult[]>((resolve, reject) => {
+          const id = nextId++;
+          pending.set(id, { resolve, reject });
+          worker.postMessage({ type: 'query', id, query });
+        });
+      } catch {
+        return await degrade().search(query);
+      }
+    },
+  };
+}
+
+/**
+ * The hosted providers are the escape hatch for a corpus whose static index has grown too
+ * large to download. Their SDKs are optional peers of fumadocs, so they are imported only
+ * when configured — and a missing one raises rather than returning nothing, because a search
+ * box that silently finds no results is the worst of the available failures.
+ */
+function createAlgoliaClient(config: Extract<ClientSearchConfig, { provider: 'algolia' }>): SearchClientLike {
+  const ready = (async () => {
+    const [lite, { algoliaClient }] = await Promise.all([
+      importOrExplain<AlgoliaLite>('algoliasearch/lite', 'algoliasearch'),
+      import('fumadocs-core/search/client/algolia'),
+    ]);
+
+    return algoliaClient({
+      client: lite.liteClient(config.appId, config.apiKey),
+      indexName: config.indexName,
+    });
+  })();
+
+  return { search: async (query) => await (await ready).search(query) };
+}
+
+function createOramaCloudClient(config: Extract<ClientSearchConfig, { provider: 'orama-cloud' }>): SearchClientLike {
+  const ready = (async () => {
+    const [orama, { oramaCloudClient }] = await Promise.all([
+      importOrExplain<OramaCore>('@orama/core', '@orama/core'),
+      import('fumadocs-core/search/client/orama-cloud'),
+    ]);
+
+    return oramaCloudClient({
+      client: new orama.OramaCloud({ projectId: config.endpoint, apiKey: config.apiKey }),
+    });
+  })();
+
+  return { search: async (query) => await (await ready).search(query) };
+}
+
+// Structural shapes for the two optional peers: they are not installed, so their own types
+// are not available to reference.
+interface AlgoliaLite {
+  liteClient: (appId: string, apiKey: string) => never;
+}
+
+interface OramaCore {
+  OramaCloud: new (options: { projectId: string; apiKey: string }) => never;
+}
+
+async function importOrExplain<T>(specifier: string, packageName: string): Promise<T> {
+  try {
+    return (await import(/* @vite-ignore */ specifier)) as T;
+  } catch (cause) {
+    throw new Error(`Search is configured to use ${packageName}, which is not installed. Run \`npm install ${packageName}\`.`, {
+      cause,
+    });
+  }
+}

package/src/app/search/worker.ts

@@ -0,0 +1,42 @@
+/// <reference lib="webworker" />
+import { staticClient } from 'fumadocs-core/search/client/orama-static';
+import type { SortedResult } from 'fumadocs-core/search';
+
+/**
+ * The static index is parsed and queried off the main thread.
+ *
+ * On any real corpus, parsing the index on the main thread is a visible stall — MkDocs
+ * Material moved theirs into a worker for the same reason.
+ */
+type Incoming = { type: 'init'; from: string } | { type: 'query'; id: number; query: string };
+type Outgoing =
+  | { type: 'ready' }
+  | { type: 'result'; id: number; results: SortedResult[] }
+  | { type: 'error'; id: number; message: string };
+
+let client: ReturnType<typeof staticClient> | undefined;
+
+const post = (message: Outgoing) => {
+  (self as unknown as DedicatedWorkerGlobalScope).postMessage(message);
+};
+
+self.onmessage = async (event: MessageEvent<Incoming>) => {
+  const data = event.data;
+
+  if (data.type === 'init') {
+    client = staticClient({ from: data.from });
+    post({ type: 'ready' });
+    return;
+  }
+
+  if (client === undefined) {
+    post({ type: 'error', id: data.id, message: 'Search worker received a query before it was initialised.' });
+    return;
+  }
+
+  try {
+    post({ type: 'result', id: data.id, results: await client.search(data.query) });
+  } catch (error) {
+    post({ type: 'error', id: data.id, message: error instanceof Error ? error.message : String(error) });
+  }
+};

package/src/app/styles/globals.css

@@ -0,0 +1,224 @@
+@import 'tailwindcss';
+
+/* seemore:imports — the configured fumadocs theme preset and the paths Tailwind must scan
+   are inserted here by the seemore Vite plugin. They belong above `preset.css`, and above
+   every rule, because `@import` is only valid before the first style rule. */
+
+@import 'fumadocs-ui/css/preset.css';
+
+@layer base {
+  body {
+    @apply flex min-h-screen flex-col bg-fd-background text-fd-foreground;
+  }
+}
+
+@layer components {
+  .seemore-shell {
+    @apply flex min-h-screen flex-col;
+  }
+
+  .seemore-header {
+    @apply sticky top-0 z-50 flex items-center gap-2 border-b border-fd-border bg-fd-background/80 px-4 py-3 backdrop-blur md:gap-4;
+  }
+
+  .seemore-brand {
+    @apply truncate;
+  }
+
+  .seemore-sidebar-trigger {
+    @apply shrink-0 md:hidden;
+  }
+
+  .seemore-brand {
+    @apply text-base font-semibold;
+  }
+
+  .seemore-nav {
+    @apply flex items-center gap-3 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-search-trigger {
+    @apply ms-auto inline-flex shrink-0 items-center gap-2 rounded-lg border border-fd-border p-2 text-sm text-fd-muted-foreground sm:px-3 sm:py-1.5;
+  }
+
+  /* Icon only where there is no room for the label. */
+  .seemore-search-trigger span,
+  .seemore-search-trigger kbd {
+    @apply hidden sm:inline;
+  }
+
+  .seemore-search-trigger kbd {
+    @apply rounded border border-fd-border px-1 text-xs;
+  }
+
+  .seemore-theme-toggle {
+    @apply shrink-0;
+  }
+
+  .seemore-search-error {
+    @apply px-4 py-6 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-search-suggestion {
+    @apply px-4 pb-2 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-search-suggestion span {
+    @apply opacity-60;
+  }
+
+  .seemore-theme-toggle {
+    @apply rounded-lg border border-fd-border p-2;
+  }
+
+  .seemore-icon-dark {
+    @apply hidden dark:block;
+  }
+
+  .seemore-icon-light {
+    @apply block dark:hidden;
+  }
+
+  .seemore-body {
+    @apply mx-auto flex w-full max-w-7xl flex-1 gap-8 px-4;
+  }
+
+  .seemore-sidebar {
+    @apply h-full;
+  }
+
+  .seemore-sidebar-link {
+    @apply flex w-full items-center gap-2 rounded-lg px-3 py-1.5 text-sm text-fd-muted-foreground transition-colors;
+  }
+
+  .seemore-sidebar-link:hover {
+    @apply bg-fd-accent text-fd-accent-foreground;
+  }
+
+  .seemore-sidebar-link[data-active='true'] {
+    @apply bg-fd-primary/10 font-medium text-fd-primary;
+  }
+
+  .seemore-sidebar-folder-label {
+    @apply text-fd-foreground;
+  }
+
+  /* The rule the nesting reads from: one guide line per level, indented from its parent. */
+  .seemore-sidebar-folder-content {
+    @apply ms-4 flex flex-col border-s border-fd-border ps-1;
+  }
+
+  .seemore-sidebar-folder {
+    @apply flex flex-col;
+  }
+
+  .seemore-sidebar-separator {
+    @apply mt-4 mb-1 px-3 text-xs font-medium text-fd-muted-foreground uppercase;
+  }
+
+  /* A sticky column on wide screens; a drawer below `md`, driven by the sidebar state. */
+  .seemore-sidebar-column {
+    /* `pt-20` clears the sticky header, which sits above the drawer. */
+    @apply fixed inset-y-0 start-0 z-40 w-72 -translate-x-full overflow-y-auto border-e border-fd-border bg-fd-background px-4 pt-20 pb-4 transition-transform rtl:translate-x-full;
+    @apply md:sticky md:top-16 md:z-auto md:h-[calc(100vh-4rem)] md:w-64 md:translate-x-0 md:border-0 md:bg-transparent md:px-0 md:py-6 rtl:md:translate-x-0;
+  }
+
+  .seemore-sidebar-column[data-open='true'] {
+    @apply translate-x-0 rtl:translate-x-0;
+  }
+
+  .seemore-sidebar-backdrop {
+    @apply fixed inset-0 z-30 bg-black/40 md:hidden;
+  }
+
+  .seemore-main {
+    @apply min-w-0 flex-1 py-8;
+  }
+
+  .seemore-toc {
+    @apply sticky top-16 hidden h-[calc(100vh-4rem)] w-56 shrink-0 py-8 text-sm lg:block;
+  }
+
+  .seemore-toc-title {
+    @apply mb-2 font-medium text-fd-muted-foreground;
+  }
+
+  .seemore-toc-integrated {
+    @apply mt-6 border-t border-fd-border pt-4 text-sm;
+  }
+
+  .seemore-breadcrumb {
+    @apply mb-4 flex flex-wrap items-center gap-2 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-page-footer {
+    @apply mt-10 grid grid-cols-2 gap-4 border-t border-fd-border pt-6 text-sm;
+  }
+
+  .seemore-next {
+    @apply flex items-center justify-end gap-2 text-end;
+  }
+
+  .seemore-prev {
+    @apply flex items-center gap-2;
+  }
+
+  .seemore-edit-link {
+    @apply mt-8 inline-flex items-center gap-2 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-site-footer {
+    @apply mt-10 flex flex-wrap gap-4 border-t border-fd-border pt-6 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-back-to-top {
+    @apply fixed bottom-6 end-6 inline-flex items-center gap-2 rounded-full border border-fd-border bg-fd-background px-4 py-2 text-sm shadow;
+  }
+
+  .seemore-preview {
+    @apply pointer-events-none fixed z-50 max-h-80 w-[400px] overflow-hidden rounded-xl border border-fd-border bg-fd-popover p-4 text-sm shadow-lg;
+  }
+
+  .seemore-preview-title {
+    @apply mb-2 font-medium;
+  }
+
+  .seemore-preview-body {
+    @apply line-clamp-6 opacity-80;
+  }
+
+  .seemore-loading {
+    @apply min-h-[50vh];
+  }
+
+  .seemore-broken-wikilink {
+    @apply cursor-help border-b border-dotted border-fd-muted-foreground text-fd-muted-foreground;
+  }
+
+  .seemore-mermaid {
+    @apply my-6 flex justify-center;
+  }
+
+  .seemore-mermaid-source {
+    @apply w-full overflow-x-auto text-xs opacity-60;
+  }
+
+  .seemore-mermaid-error {
+    @apply my-6 rounded-lg border border-fd-border p-4 text-sm text-fd-muted-foreground;
+  }
+
+  .seemore-pdf {
+    @apply my-6 block;
+  }
+
+  .seemore-pdf embed {
+    @apply block h-[70vh] w-full rounded-lg border border-fd-border;
+  }
+
+  .seemore-pdf a {
+    @apply mt-2 block text-sm text-fd-muted-foreground;
+  }
+}
+
+/* seemore:user-css — the stylesheet named by `css` in seemore.config.ts is inlined here, at
+   the very end, so that it wins against everything above it. */

package/src/app/virtual.d.ts

@@ -0,0 +1,17 @@
+// Ambient declarations for the modules the seemore Vite plugin generates.
+// Types are referenced with `import(...)` because relative imports are not allowed inside an
+// ambient module declaration.
+
+declare module 'virtual:seemore/tree' {
+  export function getTree(): import('fumadocs-core/source/client').SerializedPageTree;
+  export function subscribeTree(listener: () => void): () => void;
+}
+
+declare module 'virtual:seemore/routes' {
+  export function getRoutes(): import('../shared/types.js').RouteEntry[];
+  export function subscribeRoutes(listener: () => void): () => void;
+}
+
+declare module 'virtual:seemore/config' {
+  export const config: import('../shared/types.js').ClientConfig;
+}

package/src/shared/base.ts

@@ -0,0 +1,67 @@
+/**
+ * Base-path handling.
+ *
+ * Internally a base is always normalised to leading + trailing slash (`/sub/`), because a
+ * single canonical shape is what makes the "no absolute-root URL leaks" test possible. The
+ * trailing slash is stripped again only at the point of output.
+ */
+
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/** `undefined` | `sub` | `/sub` | `/sub/` → `/sub/`. The root base is `/`. */
+export function normaliseBase(base: string | undefined): string {
+  if (base === undefined || base === '') return '/';
+  if (EXTERNAL.test(base)) {
+    throw new Error(
+      `Invalid \`base\`: ${JSON.stringify(base)}. \`base\` is a path on the host, not a URL — use "/${base.replace(/^.*?:\/\/[^/]*/, '').replace(/^\/+/, '')}".`,
+    );
+  }
+  const trimmed = base.replace(/^\/+/, '').replace(/\/+$/, '');
+  return trimmed === '' ? '/' : `/${trimmed}/`;
+}
+
+/** True for hrefs that a base must never touch: external, protocol-relative, hash, or relative. */
+export function isExternalHref(href: string): boolean {
+  return EXTERNAL.test(href) || href.startsWith('#') || !href.startsWith('/');
+}
+
+/** Prefix a root-relative path with the base. Idempotent; leaves external hrefs alone. */
+export function withBase(base: string, href: string): string {
+  const b = normaliseBase(base);
+  if (b === '/' || isExternalHref(href)) return href;
+  if (href === '/') return b;
+  if (href === b.slice(0, -1) || href.startsWith(b)) return href;
+  return b + href.replace(/^\/+/, '');
+}
+
+/** Inverse of {@link withBase}: turn a browser pathname back into an internal route URL. */
+export function stripBase(base: string, pathname: string): string {
+  const b = normaliseBase(base);
+  if (b === '/') return pathname;
+  if (pathname === b || pathname === b.slice(0, -1)) return '/';
+  if (!pathname.startsWith(b)) return pathname;
+  return `/${pathname.slice(b.length)}`;
+}
+
+/** The form React Router wants for `basename`: leading slash, no trailing slash, `/` at root. */
+export function toBasename(base: string): string {
+  const b = normaliseBase(base);
+  return b === '/' ? '/' : b.slice(0, -1);
+}
+
+/**
+ * Browser pathnames are percent-encoded; route URLs are not.
+ *
+ * `/guía/página-uno` arrives from `location.pathname` as `/gu%C3%ADa/p%C3%A1gina-uno`, and a
+ * lookup against the route map misses — so a correctly prerendered page hydrates into "Page
+ * not found". `decodeURI`, not `decodeURIComponent`: a literal `%2F` in a filename must stay
+ * encoded or it would split into two path segments.
+ */
+export function decodePath(pathname: string): string {
+  try {
+    return decodeURI(pathname);
+  } catch {
+    // Malformed escapes are the browser's problem, not ours; match on what we were given.
+    return pathname;
+  }
+}

package/src/shared/og.ts

@@ -0,0 +1,12 @@
+/**
+ * Where a page's social card lives.
+ *
+ * Shared, because the build writes the file and the prerendered `<head>` points at it — and
+ * a card nothing references is a card nobody sees.
+ */
+export function ogImagePath(url: string): string {
+  const clean = url.replace(/^\/+|\/+$/g, '');
+  // A path per route, rather than a flattened filename: `/a/b` and `/a-b` are different
+  // routes and must not write to the same file.
+  return clean === '' ? '/api/og/card.png' : `/api/og/${clean}/card.png`;
+}

package/src/shared/types.ts

@@ -0,0 +1,77 @@
+import type { ComponentType, ReactNode } from 'react';
+
+/**
+ * Types shared by the node pipeline and the browser app. This file ships as source, next to
+ * `src/app`, so both halves agree on the shape of the virtual modules.
+ */
+
+export const FEATURES = [
+  'navigation.instant.prefetch',
+  'navigation.instant.preview',
+  'navigation.footer',
+  'navigation.top',
+  'navigation.path',
+  'navigation.sections',
+  'navigation.prune',
+  'toc.follow',
+  'toc.integrate',
+  'content.code.copy',
+  'content.action.edit',
+  'search.suggest',
+  'search.highlight',
+  'social.cards',
+] as const;
+
+export type Feature = (typeof FEATURES)[number];
+/** What a user may write in `features`: a flag, or `!flag` to switch a default-on flag off. */
+export type FeatureFlag = Feature | `!${Feature}`;
+export type ResolvedFeatures = Record<Feature, boolean>;
+
+export interface NavItem {
+  text: string;
+  link?: string;
+  items?: NavItem[];
+}
+
+export type ClientSearchConfig =
+  | { provider: 'static'; from: string }
+  | { provider: 'orama-cloud'; endpoint: string; apiKey: string }
+  | { provider: 'algolia'; appId: string; apiKey: string; indexName: string };
+
+/** The payload of `virtual:seemore/config`. */
+export interface ClientConfig {
+  title: string;
+  description?: string;
+  base: string;
+  theme: string;
+  features: ResolvedFeatures;
+  nav?: NavItem[];
+  footer?: { text?: string; links?: { text: string; link: string }[] };
+  editLink?: { base: string; text: string };
+  favicon?: string;
+  search: ClientSearchConfig;
+  contentRoot: string;
+}
+
+/** One entry of `virtual:seemore/routes`. */
+export interface RouteEntry {
+  url: string;
+  /** Virtual path relative to the content root — what an edit link points at. */
+  file: string;
+  absPath: string;
+  title: string;
+  description: string | null;
+  load: () => Promise<PageModule>;
+}
+
+export interface TocEntry {
+  title: ReactNode;
+  url: string;
+  depth: number;
+}
+
+export interface PageModule {
+  default: ComponentType<{ components?: Record<string, unknown> }>;
+  /** Exported by fumadocs' `rehype-toc`. */
+  toc?: TocEntry[];
+}