sourcey 3.6.4 → 3.6.6

package/README.md

@@ -22,7 +22,7 @@ npx sourcey init
 ## Features
 
 - **OpenAPI 2.0, 3.0, 3.1, and 3.2**: full spec coverage including `QUERY` operations, response summaries, hierarchical tags, `deviceAuthorization` OAuth, `querystring` parameters, and `$self`-aware refs for multi-document APIs
-- **API reference from OpenAPI**: endpoints, parameters, request/response schemas, auto-generated code samples in 10 languages (cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, C#)
+- **API reference from OpenAPI**: endpoints, parameters, request/response schemas, and auto-generated code samples across 10 supported languages. The default set is cURL, JavaScript, and Python; configure TypeScript, Go, Ruby, Java, PHP, Rust, and C# when you want them
 - **MCP server documentation**: tools, resources, prompts rendered as browsable reference with JSON-RPC, TypeScript, and Python code samples. Color-coded method types, annotation badges, connection config cards
 - **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
 - **MkDocs source import**: point a tab at `mkdocs.yml`; Sourcey reads `docs_dir` and `nav` so existing MkDocs markdown sites can render without hand-copying the sidebar structure
@@ -32,7 +32,7 @@ npx sourcey init
 - **Rust and rustdoc**: native API documentation from nightly rustdoc JSON, with doctests as a first-class extracted view. URL-encoded parametric impl anchors for deep-link parity with doc.rust-lang.org. Snapshot mode lets CI build on stable Rust toolchains. Aggregated doctests index across the workspace
 - **Context exports**: auto-generate llms.txt and llms-full.txt alongside your HTML as alternate views of the same documentation graph
 - **TypeScript config**: `sourcey.config.ts` with `defineConfig()` autocomplete; theme, navbar, CTA buttons, footer
-- **Theme presets**: default (sidebar + TOC), minimal (single column), api-first (Stripe-style three column); colors, fonts, layout dimensions, and custom CSS on top
+- **Themes**: default (sidebar + TOC), minimal (single column), api-first (three column), and reader (editorial specification); colors, fonts, layout dimensions, and custom CSS on top
 - **Vite dev server**: SSR hot reload on every component and CSS change; spec and markdown changes trigger instant refresh
 - **Dark mode**: semantic design tokens, light/dark logo variants, localStorage persistence
 - **Client-side search**: instant fuzzy search across all pages and API operations; Cmd+K
@@ -92,6 +92,39 @@ sourcey build api.yaml -o dist/
 
 In CI, the [`sourcey/build-docs`](https://github.com/sourcey/build-docs) GitHub Action runs the build and deploys to GitHub Pages; see [deploying](https://sourcey.com/docs/deploying).
 
+### Astro integration
+
+Astro sites can mount Sourcey directly instead of running a separate docs CI job. The integration reads the same `sourcey.config.ts`, derives Sourcey's public `siteUrl` and `baseUrl` from Astro's `site`/`base` plus `routeBase`, serves docs in Astro dev, and writes docs into Astro's final build output.
+
+```typescript
+// astro.config.ts
+import { defineConfig } from "astro/config";
+import sourcey from "sourcey/astro";
+
+export default defineConfig({
+  site: "https://sourcey.com",
+  integrations: [
+    sourcey({
+      config: "./sourcey.config.ts",
+      routeBase: "/docs",
+    }),
+  ],
+});
+```
+
+You can also share an imported config object when you want one config module to feed both the CLI and Astro:
+
+```typescript
+import { defineConfig } from "astro/config";
+import sourcey from "sourcey/astro";
+import docs from "./sourcey.config";
+
+export default defineConfig({
+  site: "https://sourcey.com",
+  integrations: [sourcey({ config: docs, configDir: ".", routeBase: "/docs" })],
+});
+```
+
 ## Configuration
 
 Create `sourcey.config.ts` in your project root:
@@ -144,11 +177,11 @@ Guides support rich components in standard markdown:
 
 ### Theme
 
-All visual configuration lives under `theme`. Colors, fonts, layout dimensions, and a preset that controls page structure:
+All visual configuration lives under `theme`. `theme.name` selects the complete renderer; colors, fonts, layout dimensions, and custom CSS apply on top:
 
 ```typescript
 theme: {
-  preset: "api-first",
+  name: "api-first",
   colors: { primary: "#f59e0b", light: "#fbbf24", dark: "#d97706" },
   fonts: { sans: "'Lexend', sans-serif", mono: "'Fira Code', monospace" },
   layout: { sidebar: "16rem", content: "48rem" },
@@ -156,7 +189,7 @@ theme: {
 }
 ```
 
-Presets control layout structure: `"default"` (sidebar + TOC), `"minimal"` (single centered column), `"api-first"` (three-column with persistent code panels). Everything else applies on top.
+Themes control the complete layout structure: `"default"` (sidebar + TOC), `"minimal"` (single centered column), `"api-first"` (three-column with persistent code panels), and `"reader"` (editorial specification reader). Shared brand settings apply on top. Theme-specific options are only interpreted by the selected theme.
 
 ## CLI
 

package/dist/adapters/shared.js

@@ -97,7 +97,7 @@ async function expandGlob(pattern, configDir) {
     }
     catch (err) {
         if (err.code === "ENOENT") {
-            throw new Error(`Glob directory not found: ${dir}`);
+            throw new Error(`Glob directory not found: ${dir}`, { cause: err });
         }
         throw err;
     }

package/dist/astro/index.d.ts

@@ -0,0 +1,89 @@
+import type { Plugin } from "vite";
+import type { PrettyUrls, ResolvedConfig, SourceyConfig } from "../config.js";
+export interface SourceyAstroOptions {
+    /**
+     * A path to `sourcey.config.ts`, a directory containing it, or an already
+     * imported Sourcey config object. Defaults to `sourcey.config.ts` in the
+     * Astro project root.
+     */
+    config?: string | SourceyConfig | ResolvedConfig;
+    /**
+     * Directory used to resolve relative paths when `config` is an object.
+     * Defaults to the Astro project root.
+     */
+    configDir?: string;
+    /**
+     * URL mount point within the Astro site. Defaults to the Sourcey config
+     * `baseUrl` when present, otherwise `/docs`.
+     */
+    routeBase?: string;
+    /** Override the public Sourcey `baseUrl`. Defaults to Astro `base` + `routeBase`. */
+    baseUrl?: string;
+    /** Override the public Sourcey `siteUrl`. Defaults to Astro `site`. */
+    siteUrl?: string | false;
+    /** Override Sourcey pretty URL behavior for the Astro-mounted output. */
+    prettyUrls?: PrettyUrls;
+    /** Treat changelog warnings as build errors. */
+    strictChangelog?: boolean;
+    /** Enable or configure Astro dev-server integration. */
+    dev?: boolean | {
+        enabled?: boolean;
+        generateOgImages?: boolean;
+    };
+    /** Enable or configure Astro build integration. */
+    build?: boolean | {
+        enabled?: boolean;
+        generateOgImages?: boolean;
+    };
+    /**
+     * Allow writing Sourcey at Astro's output root. Off by default because the
+     * standalone renderer prunes its output directory before writing.
+     */
+    allowRootOutput?: boolean;
+}
+interface AstroIntegration {
+    name: string;
+    hooks: {
+        "astro:config:setup"?: (options: AstroConfigSetupOptions) => void | Promise<void>;
+        "astro:build:done"?: (options: AstroBuildDoneOptions) => void | Promise<void>;
+    };
+}
+interface AstroConfigSetupOptions {
+    command: "dev" | "build" | "preview" | "sync" | string;
+    config: AstroResolvedConfig;
+    logger: AstroLogger;
+    addWatchFile: (path: URL | string) => void;
+    createCodegenDir?: () => URL;
+    updateConfig: (config: {
+        vite?: {
+            plugins?: Plugin[];
+        };
+    }) => void;
+}
+interface AstroBuildDoneOptions {
+    dir: URL;
+    logger: AstroLogger;
+}
+interface AstroResolvedConfig {
+    root: URL;
+    site?: string;
+    base?: string;
+}
+interface AstroLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug?(message: string): void;
+}
+interface PreparedAstroSourcey {
+    config: ResolvedConfig;
+    configPath?: string;
+    routeBase: string;
+    outputRoute: string;
+    devOutputDir: string;
+    watchPaths: string[];
+}
+export default function sourceyAstro(options?: SourceyAstroOptions): AstroIntegration;
+export declare function prepareAstroSourcey(options: SourceyAstroOptions, astroConfig: AstroResolvedConfig, codegenDir?: URL): Promise<PreparedAstroSourcey>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/astro/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"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"}

package/dist/astro/index.js

@@ -0,0 +1,299 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, resolveConfigFromRaw } from "../config.js";
+import { contentTypeForPath, outputPathCandidatesForRequest, requestPathMatchesBase, } from "../renderer/static-files.js";
+import { buildSourceySite, collectSourceyWatchPaths, writeSourceySite } from "../site.js";
+import { normalizeBaseUrl, normalizeSiteUrl } from "../site-url.js";
+export default function sourceyAstro(options = {}) {
+    let prepared = null;
+    const prepareOnce = (astroConfig, codegenDir) => {
+        prepared ??= prepareAstroSourcey(options, astroConfig, codegenDir);
+        return prepared;
+    };
+    return {
+        name: "sourcey",
+        hooks: {
+            async "astro:config:setup"({ command, config, logger, addWatchFile, createCodegenDir, updateConfig, }) {
+                const codegenDir = createCodegenDir?.() ?? new URL("./.sourcey/", config.root);
+                const preparedSourcey = await prepareOnce(config, codegenDir);
+                for (const path of preparedSourcey.watchPaths) {
+                    addWatchFile(path);
+                }
+                if (command === "dev" && phaseEnabled(options.dev, true)) {
+                    updateConfig({
+                        vite: {
+                            plugins: [
+                                sourceyAstroDevPlugin({
+                                    prepared: preparedSourcey,
+                                    logger,
+                                    strictChangelog: options.strictChangelog,
+                                    generateOgImages: phaseGenerateOgImages(options.dev, false),
+                                }),
+                            ],
+                        },
+                    });
+                }
+            },
+            async "astro:build:done"({ dir, logger }) {
+                if (!phaseEnabled(options.build, true))
+                    return;
+                const fallbackConfig = {
+                    root: new URL("./", dir),
+                };
+                const preparedSourcey = await (prepared ?? prepareOnce(fallbackConfig));
+                if (preparedSourcey.outputRoute === "" && !options.allowRootOutput) {
+                    throw new Error(`sourcey/astro routeBase "/" would prune Astro's full output directory. ` +
+                        `Use routeBase: "/docs" or set allowRootOutput: true intentionally.`);
+                }
+                const outputDir = fileURLToPath(new URL(`./${preparedSourcey.outputRoute}`, dir));
+                logger.info(`Sourcey: building docs at ${displayRoute(preparedSourcey.routeBase)}`);
+                const sourceySite = await buildSourceySite({
+                    config: preparedSourcey.config,
+                    outputDir,
+                    strictChangelog: options.strictChangelog,
+                    generateOgImages: phaseGenerateOgImages(options.build, true),
+                });
+                await writeSourceySite(sourceySite);
+                await writeAstroRouteAlias({
+                    outputRoot: fileURLToPath(dir),
+                    outputDir,
+                    routeBase: preparedSourcey.routeBase,
+                    publicBase: preparedSourcey.config.baseUrl,
+                });
+                logger.info(`Sourcey: wrote ${sourceySite.pageCount} page${sourceySite.pageCount === 1 ? "" : "s"}`);
+            },
+        },
+    };
+}
+export async function prepareAstroSourcey(options, astroConfig, codegenDir = new URL("./.sourcey/", astroConfig.root)) {
+    const rootDir = fileURLToPath(astroConfig.root);
+    const { config, configPath } = await loadSourceyConfigForAstro(options, rootDir);
+    const routeBase = normalizeRouteBase(options.routeBase ?? (config.baseUrl || "/docs"));
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? joinBasePaths(astroConfig.base, routeBase));
+    const siteUrl = options.siteUrl === false
+        ? undefined
+        : normalizeSiteUrl(options.siteUrl ?? astroConfig.site ?? config.siteUrl);
+    const mergedConfig = {
+        ...config,
+        baseUrl,
+        siteUrl,
+        prettyUrls: options.prettyUrls ?? config.prettyUrls,
+    };
+    const outputRoute = routeBase === "/" ? "" : `${routeBase.replace(/^\/+|\/+$/g, "")}/`;
+    const devOutputDir = fileURLToPath(new URL("./sourcey-output/", codegenDir));
+    const watchPaths = collectSourceyWatchPaths(mergedConfig, configPath);
+    return {
+        config: mergedConfig,
+        configPath,
+        routeBase,
+        outputRoute,
+        devOutputDir,
+        watchPaths,
+    };
+}
+async function loadSourceyConfigForAstro(options, rootDir) {
+    if (typeof options.config === "string") {
+        const configPath = resolveConfigPath(rootDir, options.config);
+        return { config: await loadConfig(configPath), configPath };
+    }
+    if (!options.config) {
+        const configPath = resolve(rootDir, "sourcey.config.ts");
+        return { config: await loadConfig(configPath), configPath };
+    }
+    if (isResolvedConfig(options.config)) {
+        return { config: options.config };
+    }
+    const configDir = resolve(rootDir, options.configDir ?? ".");
+    return { config: await resolveConfigFromRaw(options.config, configDir) };
+}
+function sourceyAstroDevPlugin(options) {
+    const { prepared, logger } = options;
+    let buildPromise = null;
+    let built = false;
+    async function rebuild() {
+        buildPromise ??= (async () => {
+            const sourceySite = await buildSourceySite({
+                config: prepared.config,
+                outputDir: prepared.devOutputDir,
+                strictChangelog: options.strictChangelog,
+                generateOgImages: options.generateOgImages,
+            });
+            await writeSourceySite(sourceySite);
+            built = true;
+            logger.info(`Sourcey: ready at ${displayRoute(prepared.routeBase)} (${sourceySite.pageCount} pages)`);
+        })().finally(() => {
+            buildPromise = null;
+        });
+        return buildPromise;
+    }
+    async function ensureBuilt() {
+        if (built)
+            return;
+        await rebuild();
+    }
+    return {
+        name: "sourcey:astro-dev",
+        configureServer(server) {
+            for (const path of prepared.watchPaths) {
+                server.watcher.add(path);
+            }
+            server.watcher.on("change", (file) => {
+                if (!shouldRebuildForChange(file, prepared.watchPaths))
+                    return;
+                built = false;
+                rebuild()
+                    .then(() => {
+                    server.ws.send({ type: "full-reload" });
+                })
+                    .catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    server.ssrFixStacktrace(err);
+                    logger.error(`Sourcey: ${err.message}`);
+                    server.ws.send({
+                        type: "error",
+                        err: { message: err.message, stack: err.stack ?? "" },
+                    });
+                });
+            });
+            server.middlewares.use(async (req, res, next) => {
+                const url = req.url ?? "/";
+                const pathname = url.split("?", 1)[0] ?? "/";
+                if (url.startsWith("/@") || url.startsWith("/__vite") || url.startsWith("/node_modules/")) {
+                    return next();
+                }
+                if (!requestPathMatchesBase(pathname, prepared.config.baseUrl)) {
+                    return next();
+                }
+                try {
+                    await ensureBuilt();
+                    const file = await readGeneratedFile(prepared.devOutputDir, pathname, prepared.config.baseUrl, prepared.config.prettyUrls);
+                    if (!file)
+                        return next();
+                    res.writeHead(200, {
+                        "Content-Type": contentTypeForPath(file.outputPath),
+                        "Cache-Control": "no-cache",
+                    });
+                    res.end(file.data);
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    server.ssrFixStacktrace(err);
+                    logger.error(`Sourcey: ${err.message}`);
+                    server.ws.send({ type: "error", err: { message: err.message, stack: err.stack ?? "" } });
+                    res.writeHead(500, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Cache-Control": "no-cache",
+                    });
+                    res.end(`<!DOCTYPE html><html><head><script type="module" src="/@vite/client"></script></head><body></body></html>`);
+                }
+            });
+        },
+    };
+}
+async function readGeneratedFile(outputDir, pathname, baseUrl, prettyUrls) {
+    for (const outputPath of outputPathCandidatesForRequest(pathname, baseUrl, prettyUrls)) {
+        const path = resolve(outputDir, outputPath);
+        if (!(await exists(path)))
+            continue;
+        const data = await readFile(path);
+        return {
+            outputPath,
+            data: shouldReadAsText(outputPath) ? data.toString("utf-8") : data,
+        };
+    }
+    return null;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveConfigPath(rootDir, config) {
+    const candidate = resolve(rootDir, config);
+    return candidate.endsWith(".ts") ? candidate : resolve(candidate, "sourcey.config.ts");
+}
+function normalizeRouteBase(value) {
+    const normalized = normalizeBaseUrl(value);
+    return normalized || "/";
+}
+function joinBasePaths(...paths) {
+    const joined = paths
+        .map((path) => path?.trim())
+        .filter((path) => Boolean(path))
+        .flatMap((path) => path.split("/"))
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .join("/");
+    return joined ? `/${joined}/` : "";
+}
+function displayRoute(routeBase) {
+    return routeBase === "/" ? "/" : routeBase.slice(0, -1);
+}
+async function writeAstroRouteAlias(options) {
+    if (options.routeBase === "/")
+        return;
+    const route = options.routeBase.replace(/^\/+|\/+$/g, "");
+    if (!route)
+        return;
+    const indexPath = resolve(options.outputDir, "index.html");
+    if (!(await exists(indexPath)))
+        return;
+    const aliasPath = resolve(options.outputRoot, `${route}.html`);
+    const html = await readFile(indexPath, "utf-8");
+    await mkdir(dirname(aliasPath), { recursive: true });
+    await writeFile(aliasPath, renderAstroRouteAlias(html, options.publicBase));
+}
+function renderAstroRouteAlias(html, routeBase) {
+    const basePath = routeBase.endsWith("/") ? routeBase : `${routeBase}/`;
+    return html
+        .replace(/\b(href|src)="([^"]+)"/g, (match, attr, value) => {
+        if (!shouldPrefixAliasUrl(value))
+            return match;
+        return `${attr}="${basePath}${value.replace(/^\.\//, "")}"`;
+    })
+        .replace(/(<meta\s+name="sourcey-search"\s+content=")([^"]+)(")/g, (match, prefix, value, suffix) => {
+        if (!shouldPrefixAliasUrl(value))
+            return match;
+        return `${prefix}${basePath}${value.replace(/^\.\//, "")}${suffix}`;
+    });
+}
+function shouldPrefixAliasUrl(value) {
+    return !/^(?:#|\/|[a-z][a-z0-9+.-]*:)/i.test(value);
+}
+function isResolvedConfig(config) {
+    return Array.isArray(config.tabs);
+}
+function phaseEnabled(phase, defaultEnabled) {
+    if (typeof phase === "boolean")
+        return phase;
+    return phase?.enabled ?? defaultEnabled;
+}
+function phaseGenerateOgImages(phase, defaultEnabled) {
+    return typeof phase === "object" ? (phase.generateOgImages ?? defaultEnabled) : defaultEnabled;
+}
+function shouldRebuildForChange(file, watchPaths) {
+    if (watchPaths.includes(file))
+        return true;
+    const ext = extname(file);
+    return ext === ".md" || ext === ".mdx" || ext === ".json" || ext === ".yml" || ext === ".yaml";
+}
+function shouldReadAsText(outputPath) {
+    switch (extname(outputPath).toLowerCase()) {
+        case ".html":
+        case ".css":
+        case ".js":
+        case ".mjs":
+        case ".json":
+        case ".svg":
+        case ".txt":
+        case ".xml":
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { runIntrospector, GodocIntrospectorError } from "./core/godoc-introspect
 import { GODOC_SCHEMA_VERSION } from "./core/godoc-types.js";
 import { init } from "./init.js";
 import { formatChangelogDiagnostic, formatGodocDiagnostic, formatRustdocDiagnostic, } from "./site-assembly.js";
+import { findPlaceholderServerUrls } from "./utils/server-warnings.js";
 import pkg from "../package.json" with { type: "json" };
 const build = defineCommand({
     meta: {
@@ -63,6 +64,7 @@ const build = defineCommand({
                     strictChangelog: args.strictChangelog,
                 });
                 if (!args.quiet) {
+                    logQuickBuildServerWarnings(result.spec);
                     logChangelogDiagnostics(result.changelogDiagnostics);
                     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
                     console.log(`  Spec:       ${result.spec.info.title} v${result.spec.info.version}`);
@@ -308,6 +310,12 @@ function logRustdocDiagnostics(diagnostics) {
         writer(`  ${formatRustdocDiagnostic(diagnostic)}`);
     }
 }
+function logQuickBuildServerWarnings(spec) {
+    const placeholderUrls = findPlaceholderServerUrls(spec);
+    for (const url of placeholderUrls) {
+        console.warn(`  Warning: quick build is using placeholder server URL "${url}". Generated code samples will target that host. Use sourcey.config.ts or correct the source document before publishing.`);
+    }
+}
 function parsePort(value) {
     if (!/^\d+$/.test(value)) {
         throw new Error(`Invalid port "${value}". Expected an integer from 1 to 65535.`);

package/dist/client/reader-controls.js

@@ -0,0 +1,81 @@
+(function () {
+  var root = document.querySelector(".sourcey-reader");
+  if (!root) return;
+  root.querySelectorAll("[data-reader-enhancement]").forEach(function (el) {
+    el.hidden = false;
+  });
+  root.querySelectorAll("[data-reader-fallback]").forEach(function (el) {
+    el.hidden = true;
+  });
+  var toggle = root.querySelector(".menu-toggle");
+  var menu = root.querySelector("#reader-mobile-nav");
+  function closeMenu() {
+    menu.hidden = true;
+    toggle.setAttribute("aria-expanded", "false");
+    toggle.setAttribute("aria-label", "Open navigation");
+  }
+  toggle.addEventListener("click", function () {
+    var open = toggle.getAttribute("aria-expanded") !== "true";
+    menu.hidden = !open;
+    toggle.setAttribute("aria-expanded", String(open));
+    toggle.setAttribute("aria-label", open ? "Close navigation" : "Open navigation");
+  });
+  window.matchMedia("(min-width: 901px)").addEventListener("change", function (event) {
+    if (event.matches) closeMenu();
+  });
+  document.addEventListener("keydown", function (event) {
+    if (event.key === "Escape" && !menu.hidden) {
+      closeMenu();
+      toggle.focus();
+    }
+    var search = root.querySelector("a.search-link");
+    if (
+      search &&
+      event.key === "/" &&
+      !event.metaKey &&
+      !event.ctrlKey &&
+      !event.altKey &&
+      !event.target.closest("input, textarea, select, [contenteditable]")
+    ) {
+      event.preventDefault();
+      window.location.href = search.href;
+    }
+  });
+  var select = root.querySelector("#chapter-select");
+  select.addEventListener("change", function () {
+    window.location.href = select.value;
+  });
+  var copy = root.querySelector("[data-copy-page]");
+  if (copy)
+    copy.addEventListener("click", async function () {
+      var label = copy.querySelector("span");
+      try {
+        await navigator.clipboard.writeText(window.location.href);
+        label.textContent = "Copied";
+      } catch {
+        label.textContent = "Copy the address bar URL";
+      }
+      setTimeout(function () {
+        label.textContent = "Copy link";
+      }, 2500);
+    });
+  var links = Array.from(root.querySelectorAll(".docs-toc nav a"));
+  if ("IntersectionObserver" in window) {
+    var observer = new window.IntersectionObserver(
+      function (entries) {
+        var active = entries.find(function (entry) {
+          return entry.isIntersecting;
+        });
+        if (!active) return;
+        links.forEach(function (link) {
+          if (link.hash === "#" + active.target.id) link.setAttribute("aria-current", "location");
+          else link.removeAttribute("aria-current");
+        });
+      },
+      { rootMargin: "-100px 0px -65% 0px" },
+    );
+    root.querySelectorAll(".reader-prose h2, .reader-prose h3").forEach(function (heading) {
+      observer.observe(heading);
+    });
+  }
+})();

package/dist/client/reader.d.ts

@@ -0,0 +1,5 @@
+import "../themes/default/main.css";
+import "./tabs.js";
+import "./search.js";
+import "./reader-controls.js";
+//# sourceMappingURL=reader.d.ts.map

package/dist/client/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/client/reader.ts"],"names":[],"mappings":"AACA,OAAO,4BAA4B,CAAC;AACpC,OAAO,WAAW,CAAC;AACnB,OAAO,aAAa,CAAC;AACrB,OAAO,sBAAsB,CAAC"}

package/dist/client/reader.js

@@ -0,0 +1,5 @@
+// Shared content primitives, with the reader's own progressive enhancements.
+import "../themes/default/main.css";
+import "./tabs.js";
+import "./search.js";
+import "./reader-controls.js";