seemore 1.8.7 → 1.9.0

package/dist/index.d.ts

@@ -11,6 +11,13 @@ type FeatureMap = Partial<Record<Feature, boolean>>;
 /** @deprecated The array form, where a `!` prefix means off. Write {@link FeatureMap} instead. */
 type FeatureFlag = Feature | `!${Feature}`;
 type ResolvedFeatures = Record<Feature, boolean>;
+/** The payload of `virtual:seemore/config`. */
+/**
+ * The actions a page-actions button can hold, by id. Presence in the `actions` array is
+ * what enables an action; the array order is the menu order.
+ */
+declare const ACTION_IDS: readonly ["export-html", "export-pdf"];
+type ActionId = (typeof ACTION_IDS)[number];
 
 /** The CSS presets fumadocs-ui ships. We do not invent a token system. */
 declare const THEMES: readonly ["neutral", "black", "catppuccin", "dusk", "ocean", "purple", "ruby", "solar", "aspen", "emerald", "vitepress", "shadcn"];
@@ -94,6 +101,10 @@ declare const configSchema: z.ZodObject<{
         apiKey: z.ZodString;
         indexName: z.ZodString;
     }, z.core.$strip>]>>;
+    pageActions: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "export-html": "export-html";
+        "export-pdf": "export-pdf";
+    }>>>;
     exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /** What a user writes in `seemore.config.ts`. */
@@ -139,6 +150,7 @@ interface ResolvedSeemoreConfig {
         text: string;
     };
     search: SearchConfig;
+    pageActions: ActionId[];
     exclude: string[];
     /** Directory the config was resolved from — relative paths in it hang off this. */
     root: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seemore",
-  "version": "1.8.7",
+  "version": "1.9.0",
   "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,10 +1,11 @@
 import { Writable } from 'node:stream';
 import { StrictMode, type ReactNode } from 'react';
 import { renderToPipeableStream } from 'react-dom/server';
-import { RouterProvider, createMemoryRouter } from 'react-router';
+import { MemoryRouter, 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 { mdxComponents } from './mdx/components.js';
 import { createRouteObjects } from './router.js';
 import { findRoute, preloadPage, routeEntries } from './lib/pages.js';
 
@@ -108,6 +109,43 @@ export function listRoutes(): string[] {
   return routeEntries().map((entry) => entry.url);
 }
 
+/** What `renderArticle` hands back: the content and the metadata a title bar needs. */
+export interface ExportedArticle {
+  html: string;
+  title: string;
+  description?: string;
+}
+
+/**
+ * The article alone — the MDX content, no layout, no sidebar, no chrome — for the
+ * single-page export. Rendering the component directly, rather than extracting the
+ * article from a full-page render, means no HTML parsing anywhere in the export path.
+ *
+ * Diagrams are absent here, as in every prerendered page (see `Mermaid.tsx`); the CLI
+ * export inlines a runtime that renders them when the file is opened.
+ */
+export async function renderArticle(url: string): Promise<ExportedArticle> {
+  const entry = findRoute(url);
+  if (entry === undefined) throw new Error(`No page at ${url}.`);
+
+  const page = await preloadPage(url);
+  if (page === undefined) throw new Error(`No page at ${url}.`);
+
+  const Content = page.default;
+  // A router is still required: content links go through react-router's `Link`, which
+  // reads the routing context. A memory router with just this page is the smallest one.
+  const { html, failures } = await renderToHtml(
+    <StrictMode>
+      <MemoryRouter initialEntries={[withBase(config.base, url)]} basename={toBasename(config.base)}>
+        <Content components={mdxComponents} />
+      </MemoryRouter>
+    </StrictMode>,
+  );
+  if (failures.length > 0) throw prerenderError(url, failures[0]);
+
+  return { html, title: entry.title, description: entry.description ?? undefined };
+}
+
 function head(url: string): string {
   const entry = findRoute(url);
   const title = entry === undefined || url === '/' ? config.title : `${entry.title} · ${config.title}`;

package/src/app/export/exportPage.ts

@@ -0,0 +1,416 @@
+import { config } from 'virtual:seemore/config';
+import { THEME_TOGGLE } from './themeToggle.js';
+
+/**
+ * The single-page export: the article you are reading, in one HTML file that renders
+ * offline.
+ *
+ * Everything happens client-side against the live DOM, which is what makes the same code
+ * work in the dev server, on a hosted static build, and inside an editor webview — none of
+ * the three owe the export a server. The page gives up three things in exchange: it runs
+ * after hydration (diagrams must already be rendered or renderable), it needs the network
+ * only for assets that are themselves remote, and it serialises the DOM as it is — site
+ * chrome never enters the file because only the article is taken.
+ *
+ * The same preparation drives the PDF path: print is the browser's own renderer, so the
+ * feature contributes a print stylesheet (see `globals.css`) and a light theme, not a PDF
+ * library.
+ */
+
+/** Mermaid and D2 render on scroll-into-view; the export needs every diagram as SVG. */
+async function prepareDiagrams(): Promise<void> {
+  const pending = Array.from(document.querySelectorAll<HTMLElement>('.seemore-mermaid, .seemore-d2')).filter(
+    (el) => el.querySelector('svg') === null && el.querySelector('.seemore-mermaid-error, .seemore-d2-error') === null,
+  );
+  if (pending.length === 0) return;
+
+  // Walking the page to wake each diagram moves the reader; put them back afterwards.
+  const scrollX = window.scrollX;
+  const scrollY = window.scrollY;
+
+  for (const el of pending) {
+    el.scrollIntoView({ behavior: 'instant', block: 'center' });
+    // A settled diagram shows either its SVG or the component's own error note. A timeout
+    // gives up on that one diagram rather than on the export: the site itself renders
+    // nothing better on a failed diagram, and the Markdown source `pre` it leaves behind
+    // is still honest content.
+    await waitFor(
+      () => el.querySelector('svg, .seemore-mermaid-error, .seemore-d2-error') !== null,
+      15_000,
+    );
+  }
+
+  window.scrollTo(scrollX, scrollY);
+}
+
+function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const tick = () => {
+      if (predicate() || Date.now() - started > timeoutMs) return resolve();
+      window.setTimeout(tick, 120);
+    };
+    tick();
+  });
+}
+
+/**
+ * Every rule the page is styled by, as one string.
+ *
+ * Dev injects `<style>` tags (one per module, sometimes several identical ones across
+ * reloads); the build ships a single hashed stylesheet link. Same-origin sheets are inlined
+ * — a `file://` page cannot fetch them — and a sheet that is genuinely remote stays linked,
+ * the same treaty as remote images.
+ */
+async function collectCss(): Promise<{ css: string; remoteLinks: string }> {
+  const seen = new Set<string>();
+  const parts: string[] = [];
+  const remote: string[] = [];
+
+  for (const style of document.querySelectorAll('style')) {
+    // The highlight rule is installed per-navigation and means nothing in a static file.
+    if (style.id === 'seemore-highlight-style') continue;
+    const text = style.textContent ?? '';
+    if (text.trim() === '' || seen.has(text)) continue;
+    seen.add(text);
+    parts.push(text);
+  }
+
+  for (const link of document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')) {
+    let url: URL;
+    try {
+      url = new URL(link.href, document.baseURI);
+    } catch {
+      continue;
+    }
+    if (url.origin !== location.origin) {
+      remote.push(link.outerHTML);
+      continue;
+    }
+    const text = await fetch(url.href)
+      .then((response) => response.text())
+      .catch(() => undefined);
+    if (text === undefined || seen.has(text)) continue;
+    seen.add(text);
+    parts.push(text);
+  }
+
+  return { css: parts.join('\n'), remoteLinks: remote.join('\n') };
+}
+
+/** Rewrite same-origin `url(...)` references to data URIs; remote and broken ones stay. */
+async function inlineCssUrls(css: string): Promise<string> {
+  const pattern = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+  const replacements = new Map<string, string>();
+
+  for (const match of css.matchAll(pattern)) {
+    const raw = match[2] ?? '';
+    if (/^(?:data:|https?:)/i.test(raw) === false && !raw.startsWith('#')) {
+      try {
+        const url = new URL(raw, document.baseURI);
+        if (url.origin === location.origin) {
+          const blob = await fetch(url.href).then((response) => response.blob());
+          replacements.set(raw, await blobToDataUri(blob));
+        }
+      } catch {
+        // Left as written: it did not resolve here, and a data URI we cannot build
+        // is no worse than the reference the live page already carries.
+      }
+    }
+  }
+
+  return css.replace(pattern, (whole, _quote: string, raw: string) => {
+    const data = replacements.get(raw);
+    return data === undefined ? whole : `url("${data}")`;
+  });
+}
+
+/** Same-origin images become data URIs; remote images keep their URLs, as decided. */
+async function inlineImages(scope: Element): Promise<void> {
+  for (const img of scope.querySelectorAll('img')) {
+    const src = img.getAttribute('src');
+    if (src === null || src === '' || /^(?:data:|https?:)/i.test(src)) continue;
+    try {
+      const url = new URL(src, document.baseURI);
+      if (url.origin !== location.origin) continue;
+      const blob = await fetch(url.href).then((response) => {
+        if (!response.ok) throw new Error(String(response.status));
+        return response.blob();
+      });
+      img.setAttribute('src', await blobToDataUri(blob));
+      img.removeAttribute('srcset');
+    } catch {
+      // Left as written: the reference was already broken on the live page, or points
+      // somewhere we agreed not to inline.
+    }
+  }
+}
+
+/**
+ * Favicons, inlined under the same treaty as everything else: data URIs ride along,
+ * same-origin files are fetched and turned into one, remote ones stay linked.
+ */
+async function collectFavicons(): Promise<string> {
+  const links: string[] = [];
+  for (const link of document.querySelectorAll<HTMLLinkElement>('link[rel="icon"]')) {
+    try {
+      const url = new URL(link.href, document.baseURI);
+      if (url.protocol === 'data:' || url.origin !== location.origin) {
+        links.push(link.outerHTML);
+        continue;
+      }
+      const blob = await fetch(url.href).then((response) => response.blob());
+      links.push(link.outerHTML.replace(/href="[^"]*"/i, `href="${await blobToDataUri(blob)}"`));
+    } catch {
+      // One unreachable icon is no reason to skip the export.
+    }
+  }
+  return links.join('\n');
+}
+
+function blobToDataUri(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error('Could not read the asset.'));
+    reader.readAsDataURL(blob);
+  });
+}
+
+/**
+ * "On this page" for a file whose only navigation is itself: built from the headings the
+ * article already has (remark gave them ids), two levels deep, inserted after the title.
+ * Styled by `.seemore-export-toc`, which lives in the site stylesheet the file inlines.
+ */
+function buildExportToc(article: Element): Element | undefined {
+  const headings = Array.from(article.querySelectorAll('h2[id], h3[id]'));
+  if (headings.length === 0) return undefined;
+
+  const nav = document.createElement('nav');
+  nav.className = 'seemore-export-toc';
+
+  // A collapsible, not a heading pair: on narrow screens the block starts collapsed under
+  // the title, and the runtime opens it when the viewport is wide enough for the rail.
+  const details = document.createElement('details');
+  const summary = document.createElement('summary');
+  summary.textContent = 'On this page';
+  details.append(summary);
+
+  const top = document.createElement('ul');
+  details.append(top);
+  nav.append(details);
+  let nested: HTMLUListElement | undefined;
+
+  for (const heading of headings) {
+    const li = document.createElement('li');
+    const a = document.createElement('a');
+    a.href = `#${heading.id}`;
+    a.textContent = heading.textContent ?? '';
+    li.append(a);
+
+    if (heading.tagName === 'H2') {
+      top.append(li);
+      nested = document.createElement('ul');
+      li.append(nested);
+    } else {
+      (nested ?? top).append(li);
+    }
+  }
+
+  return nav;
+}
+
+/** The article is the only thing taken, but dev leaves editor affordances inside it. */
+function cleanArticleForExport(article: Element): Element {
+  const clone = article.cloneNode(true) as Element;
+  for (const el of clone.querySelectorAll('.seemore-editor-layer, .seemore-editor, .seemore-editor-error')) {
+    el.remove();
+  }
+  for (const el of clone.querySelectorAll('[data-seemore-pos]')) {
+    el.removeAttribute('data-seemore-pos');
+  }
+  return clone;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+/**
+ * The exported file's runtime: theme toggle, code copy, click-to-zoom — the three behaviors
+ * kept, at roughly a kilobyte instead of the site bundle. Handed to React in hydration on
+ * the live page; here each is three lines against the static DOM.
+ *
+ * Kept free of `</script>`-shaped sequences by construction: it is inlined verbatim.
+ */
+const RUNTIME = `(function () {
+  var root = document.documentElement;
+  var toggle = document.querySelector('.seemore-export-theme-toggle');
+  if (toggle) toggle.addEventListener('click', function () { root.classList.toggle('dark'); });
+
+  document.querySelectorAll('figure').forEach(function (figure) {
+    var button = figure.querySelector('button[aria-label]');
+    if (!button || !/copy/i.test(button.getAttribute('aria-label') || '')) return;
+    button.addEventListener('click', function () {
+      var code = figure.querySelector('pre, code');
+      if (code && navigator.clipboard) navigator.clipboard.writeText(code.textContent || '');
+    });
+  });
+
+  // The live site's TOC follows the reader with fumadocs' own scroll tracking; in the file,
+  // the plainest version of the same behaviour — last heading above the fold wins.
+  var tocLinks = [].slice.call(document.querySelectorAll('.seemore-export-toc a'));
+  if (tocLinks.length > 0) {
+    var byId = {};
+    tocLinks.forEach(function (a) { byId[(a.getAttribute('href') || '').slice(1)] = a; });
+    var points = Object.keys(byId).map(function (id) { return document.getElementById(id); }).filter(Boolean);
+    var sync = function () {
+      var current;
+      for (var i = 0; i < points.length; i++) {
+        // Headings carry scroll-margin-top (room for the live site's fixed header), and an
+        // anchor jump parks them exactly there — so "reached" means at or above their own
+        // margin line, not the raw viewport top.
+        var margin = parseFloat(getComputedStyle(points[i]).scrollMarginTop) || 0;
+        if (points[i].getBoundingClientRect().top - margin <= 48) current = points[i]; else break;
+      }
+      tocLinks.forEach(function (a) { a.removeAttribute('data-active'); });
+      if (current) byId[current.id].setAttribute('data-active', 'true');
+    };
+    window.addEventListener('scroll', sync, { passive: true });
+    sync();
+  }
+
+  // Wide enough for the rail: open the collapsible so it reads as a list, not a disclosure.
+  var tocDetails = document.querySelector('.seemore-export-toc details');
+  if (tocDetails && window.matchMedia('(min-width: 1280px)').matches) tocDetails.open = true;
+
+  var main = document.querySelector('main');
+  var overlay = document.createElement('div');
+  overlay.className = 'seemore-export-overlay';
+  overlay.hidden = true;
+  var zoomed = document.createElement('img');
+  overlay.appendChild(zoomed);
+  document.body.appendChild(overlay);
+  function close() { overlay.hidden = true; zoomed.removeAttribute('src'); }
+  overlay.addEventListener('click', close);
+  document.addEventListener('keydown', function (event) { if (event.key === 'Escape') close(); });
+  if (main) main.querySelectorAll('img').forEach(function (img) {
+    if (img.closest('a')) return;
+    img.addEventListener('click', function () {
+      zoomed.setAttribute('src', img.currentSrc || img.src);
+      overlay.hidden = false;
+    });
+  });
+})();`;
+
+function buildExportHtml(article: Element, css: string, remoteLinks: string, favicons: string): string {
+  const attrs = Array.from(document.documentElement.attributes)
+    .map((attr) => ` ${attr.name}="${escapeHtml(attr.value)}"`)
+    .join('');
+
+  const description = config.description === undefined ? '' : `<meta name="description" content="${escapeHtml(config.description)}">`;
+
+  return [
+    '<!doctype html>',
+    `<html${attrs}>`,
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(document.title)}</title>`,
+    description,
+    '<meta name="generator" content="seemore">',
+    favicons,
+    remoteLinks,
+    // The guard is belt-and-braces: a stylesheet containing `</style>` would already be
+    // breaking the live page's own inline styles the same way.
+    `<style>\n${css.replaceAll('</style', '<\\/style')}</style>`,
+    '</head>',
+    '<body>',
+    `<main class="seemore-export-main">${article.outerHTML}</main>`,
+    THEME_TOGGLE,
+    `<script>${RUNTIME}</script>`,
+    '</body>',
+    '</html>',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+/** The downloaded file's name: the page's own path segment, sanitised for a filename. */
+function exportFilename(): string {
+  let path = location.pathname;
+  if (config.base !== '/') path = path.replace(config.base, '/');
+  const last = decodeURIComponent(path.replace(/\/+$/, '').split('/').at(-1) ?? '');
+  const slug = last === '' || last === '/' ? 'index' : last;
+  return `${slug.replace(/[^a-zA-Z0-9._-]+/g, '-')}.html`;
+}
+
+function download(filename: string, html: string): void {
+  const url = URL.createObjectURL(new Blob([html], { type: 'text/html' }));
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.append(a);
+  a.click();
+  a.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}
+
+/** Export the page you are reading as one self-contained HTML file. */
+export async function exportPageAsHtml(): Promise<void> {
+  const article = document.querySelector('main.seemore-main article');
+  if (article === null) throw new Error('There is nothing to export on this page.');
+
+  await prepareDiagrams();
+
+  const clone = cleanArticleForExport(article);
+  await inlineImages(clone);
+
+  const toc = buildExportToc(clone);
+  const heading = clone.querySelector('h1');
+  if (toc !== undefined) {
+    if (heading !== null && heading.nextElementSibling !== null) {
+      heading.nextElementSibling.before(toc);
+    } else if (heading !== null) {
+      heading.after(toc);
+    } else {
+      clone.prepend(toc);
+    }
+  }
+
+  const { css, remoteLinks } = await collectCss();
+  const favicons = await collectFavicons();
+  download(exportFilename(), buildExportHtml(clone, await inlineCssUrls(css), remoteLinks, favicons));
+}
+
+/**
+ * Print the page you are reading — the browser's Save-as-PDF makes it a PDF.
+ *
+ * Print is always light, whatever the screen was showing: code blocks and diagrams are
+ * themed by CSS variables that flip with `dark`, and ink follows the light values.
+ */
+export async function printPageAsPdf(): Promise<void> {
+  await prepareDiagrams();
+
+  const root = document.documentElement;
+  const wasDark = root.classList.contains('dark');
+  if (!wasDark) {
+    window.print();
+    return;
+  }
+
+  root.classList.remove('dark');
+  const restore = () => {
+    root.classList.add('dark');
+    window.removeEventListener('afterprint', restore);
+  };
+  window.addEventListener('afterprint', restore);
+  window.print();
+  // Safari's dialog does not always fire `afterprint` when it is dismissed; a page left
+  // dark-less forever is worse than a late restore.
+  window.setTimeout(restore, 60_000);
+}

package/src/app/export/standalone.ts

@@ -0,0 +1,137 @@
+/**
+ * The runtime inside a CLI-exported page.
+ *
+ * `seemore export` renders the article in node, where diagrams cannot render — that would
+ * mean a headless browser as an install dependency, which SPEC §16 rules out. This entry,
+ * bundled to an IIFE and inlined into the file, finishes the job when the page is opened:
+ * each diagram is rendered from the source `pre` the site's own components leave in
+ * prerendered output. It also binds the behaviors the export keeps — theme toggle, code
+ * copy, click-to-zoom — so the file behaves like the browser-exported one.
+ *
+ * The browser export ships a hand-written twin of the behavior half (the `RUNTIME` string
+ * in `exportPage.ts`): it needs no diagram half, because its diagrams are already SVG when
+ * the export runs. Keep the two in sync.
+ */
+
+const isDark = (): boolean => document.documentElement.classList.contains('dark');
+
+async function renderMermaid(container: HTMLElement, chart: string, index: number): Promise<void> {
+  const { default: mermaid } = await import('mermaid');
+  mermaid.initialize({ startOnLoad: false, theme: isDark() ? 'dark' : 'default', securityLevel: 'strict' });
+  const { svg } = await mermaid.render(`seemore-export-mermaid-${index}`, chart);
+  container.innerHTML = svg;
+}
+
+async function renderD2(container: HTMLElement, chart: string, index: number): Promise<void> {
+  const { D2: D2Compiler } = await import('@terrastruct/d2');
+  const compiler = new D2Compiler();
+  const { diagram, renderOptions } = await compiler.compile(chart, {
+    options: { themeID: isDark() ? 300 : 0 },
+  });
+  container.innerHTML = await compiler.render(diagram, { ...renderOptions, salt: String(index) });
+}
+
+/** The site's own failure UI for a diagram that will not render. */
+function fail(container: HTMLElement, className: string, cause: unknown): void {
+  const pre = document.createElement('pre');
+  pre.className = className;
+  pre.setAttribute('role', 'note');
+  pre.textContent = `Could not render this diagram: ${cause instanceof Error ? cause.message : String(cause)}`;
+  container.replaceChildren(pre);
+}
+
+async function renderDiagrams(): Promise<void> {
+  const kinds = [
+    { selector: '.seemore-mermaid', source: '.seemore-mermaid-source', error: 'seemore-mermaid-error', render: renderMermaid },
+    { selector: '.seemore-d2', source: '.seemore-d2-source', error: 'seemore-d2-error', render: renderD2 },
+  ] as const;
+
+  for (const kind of kinds) {
+    const containers = Array.from(document.querySelectorAll<HTMLElement>(kind.selector));
+    for (const [index, container] of containers.entries()) {
+      if (container.querySelector('svg') !== null) continue;
+      const chart = container.querySelector(kind.source)?.textContent ?? '';
+      if (chart === '') continue;
+      try {
+        await kind.render(container, chart, index);
+      } catch (cause) {
+        fail(container, kind.error, cause);
+      }
+    }
+  }
+}
+
+function bindBehaviors(): void {
+  const root = document.documentElement;
+  document.querySelector('.seemore-export-theme-toggle')?.addEventListener('click', () => {
+    root.classList.toggle('dark');
+  });
+
+  for (const figure of document.querySelectorAll('figure')) {
+    const button = figure.querySelector('button[aria-label]');
+    if (button === null || !/copy/i.test(button.getAttribute('aria-label') ?? '')) continue;
+    button.addEventListener('click', () => {
+      const code = figure.querySelector('pre, code');
+      if (code !== null) void navigator.clipboard?.writeText(code.textContent ?? '');
+    });
+  }
+
+  // The live site's TOC follows the reader with fumadocs' own scroll tracking; in the file,
+  // the plainest version of the same behaviour — last heading above the fold wins.
+  const tocLinks = Array.from(document.querySelectorAll<HTMLAnchorElement>('.seemore-export-toc a'));
+  if (tocLinks.length > 0) {
+    const byId = new Map<string, HTMLAnchorElement>();
+    for (const a of tocLinks) byId.set((a.getAttribute('href') ?? '').slice(1), a);
+    const points = Array.from(byId.keys())
+      .map((id) => document.getElementById(id))
+      .filter((el): el is HTMLElement => el !== null);
+    const sync = (): void => {
+      let current: HTMLElement | undefined;
+      for (const point of points) {
+        // Headings carry `scroll-margin-top` (room for the live site's fixed header), and an
+        // anchor jump parks them exactly there — so "reached" means at or above their own
+        // margin line, not the raw viewport top.
+        const margin = Number.parseFloat(getComputedStyle(point).scrollMarginTop) || 0;
+        if (point.getBoundingClientRect().top - margin <= 48) current = point;
+        else break;
+      }
+      for (const a of tocLinks) a.removeAttribute('data-active');
+      if (current !== undefined) byId.get(current.id)?.setAttribute('data-active', 'true');
+    };
+    window.addEventListener('scroll', sync, { passive: true });
+    sync();
+  }
+
+  // Wide enough for the rail: open the collapsible so it reads as a list, not a disclosure.
+  const tocDetails = document.querySelector<HTMLDetailsElement>('.seemore-export-toc details');
+  if (tocDetails && window.matchMedia('(min-width: 1280px)').matches) tocDetails.open = true;
+
+  const overlay = document.createElement('div');
+  overlay.className = 'seemore-export-overlay';
+  overlay.hidden = true;
+  const zoomed = document.createElement('img');
+  overlay.append(zoomed);
+  document.body.append(overlay);
+  const close = (): void => {
+    overlay.hidden = true;
+    zoomed.removeAttribute('src');
+  };
+  overlay.addEventListener('click', close);
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') close();
+  });
+  for (const img of document.querySelectorAll<HTMLImageElement>('main img')) {
+    if (img.closest('a') !== null) continue;
+    img.addEventListener('click', () => {
+      zoomed.setAttribute('src', img.currentSrc || img.src);
+      overlay.hidden = false;
+    });
+  }
+}
+
+function main(): void {
+  bindBehaviors();
+  void renderDiagrams();
+}
+
+main();

package/src/app/export/themeToggle.ts

@@ -0,0 +1,12 @@
+/**
+ * The export's only chrome: a floating theme toggle, since the header is gone by design.
+ *
+ * The two glyphs ride as inline SVG with the site's own show/hide classes, so whichever
+ * runtime flips `dark` also flips the icon for free. Shared as a string because both
+ * export paths inline it verbatim — the browser export at run time, the CLI export at
+ * build time — and the two files must ship the same button.
+ */
+export const THEME_TOGGLE = `<button type="button" class="seemore-export-theme-toggle" aria-label="Toggle dark mode">
+<svg class="seemore-icon-light" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>
+<svg class="seemore-icon-dark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>
+</button>`;

package/src/app/layout/DocsLayout.tsx

@@ -19,6 +19,7 @@ import { useExternalLinkBridge } from './ExternalLinkBridge.js';
 import { Header } from './Header.js';
 import { Sidebar } from './Sidebar.js';
 import { Breadcrumb } from './Breadcrumb.js';
+import { PageActions } from './PageActions.js';
 import { BackToTop, PageFooter, SiteFooter } from './Footer.js';
 import { SelectionCopyButton } from './SelectionCopyButton.js';
 import { IntegratedToc, Toc, TocProvider } from './Toc.js';
@@ -68,6 +69,7 @@ export function DocPage({ entry }: { entry: RouteEntry }) {
 
           <main className="seemore-main">
             {feature('navigation.path') ? <Breadcrumb /> : undefined}
+            <PageActions />
             <article className={editable ? 'seemore-article prose seemore-editable' : 'seemore-article prose'}>
               <Content components={mdxComponents} />
               {editable ? <InlineEditor key={entry.url} entry={entry} /> : undefined}