svelte-docsmith 0.12.2 → 0.13.1

package/README.md

@@ -15,8 +15,17 @@ Write a markdown file under `src/routes/docs/` and you get a styled page with
 syntax highlighting, heading anchors, a sidebar derived from your content, and a
 live table of contents. No per-page wiring, no content collection to configure.
 
-> **Status: pre-1.0.** Published to npm and usable today. The public API is still
-> stabilising, so minor releases may include breaking changes until v1.0.
+> **Status: pre-1.0.** Published to npm and usable today. Minor releases may still
+> include breaking changes until v1.0.
+>
+> **What 1.0 will lock.** Authoring components, `DocsShell`, `ErrorPage`,
+> `defineConfig`, the preprocessor, the Vite plugin, the sitemap / llms / feed
+> generators, the search engine, and the theming contract — ordinary semver,
+> breaking changes ride a major.
+>
+> **What stays experimental.** Versioning: `DocsVersions`, `currentOnly`, the
+> archive marker, and the `archive-version` command. They may still change in a
+> minor until authors have used them for real.
 
 ## Install
 
@@ -166,6 +175,20 @@ plugin you already added:
   Graph / Twitter tags for every page from its frontmatter, no per-page wiring.
 - **Error pages.** `ErrorPage` gives a styled 404 that keeps the site chrome;
   drop it into a SvelteKit `+error.svelte`.
+- **Versioned docs.** Declare `versions` on the Vite plugin, freeze a release
+  with `npx svelte-docsmith archive-version <id>`, and pass the generated
+  manifest to `DocsShell`. Scope sitemap / llms endpoints to the current
+  version with `currentOnly`.
+- **Changelog.** Point the plugin at your `CHANGELOG.md`; import the parsed
+  releases from `svelte-docsmith/changelog`, render them with `Changelog`, and
+  wire `generateFeed` into an Atom endpoint.
+- **Mermaid.** A mermaid code fence is rendered client-side (optional `mermaid`
+  peer dependency, loaded only on pages that need it).
+- **Landing sections.** `Hero`, `FeatureGrid`, `Feature`, `CTA`, and `Action`
+  for the marketing page in front of your docs.
+- **Generators.** Framework-agnostic helpers for `sitemap.xml`, `llms.txt` /
+  `llms-full.txt`, and the changelog Atom feed — drop them into `+server.ts`
+  routes over the generated indexes.
 - **Components.** `Callout`, `Tabs`, `Steps`, `Card`, `Accordion`, `Badge`,
   `Kbd`, `FileTree`, `PropsTable`, and more, authored right inside markdown.
 - Heading anchors, a scroll-spy table of contents, and one-click copy on every
@@ -187,15 +210,21 @@ override the tokens yourself.
 
 ## What's exported
 
-| Entry point                    | What it is                                                                                                                               |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `svelte-docsmith`              | All components (`DocsShell`, `ErrorPage`, `LiveExample`, `Callout`, `Tabs`, …), plus `defineConfig`, `createSearchEngine`, and the types |
-| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                              |
-| `svelte-docsmith/vite`         | `docsmith()`, the content index, search index, and `?source` transform (Node, build)                                                     |
-| `svelte-docsmith/content`      | `docs`, the generated sidebar content index                                                                                              |
-| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                              |
-| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                  |
-| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                 |
+| Entry point                    | What it is                                                                                                                                                                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `svelte-docsmith`              | Components (`DocsShell`, `Changelog`, landing sections, `LiveExample`, `Callout`, …), `defineConfig`, `createSearchEngine`, `generateSitemap` / `generateLlmsTxt` / `generateLlmsFullTxt` / `generateFeed`, `currentOnly`, and the types |
+| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                                                                                                                              |
+| `svelte-docsmith/vite`         | `docsmith()`, the content / search / llms / changelog indexes and `?source` transform (Node, build)                                                                                                                                      |
+| `svelte-docsmith/content`      | `docs` and `versions`, the generated sidebar content index and version manifest                                                                                                                                                          |
+| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                                                                                                                              |
+| `svelte-docsmith/llms`         | `docs`, the generated LLM content index (for `llms.txt` / `llms-full.txt` routes)                                                                                                                                                        |
+| `svelte-docsmith/changelog`    | `releases`, the generated changelog index (parsed from `CHANGELOG.md`)                                                                                                                                                                   |
+| `svelte-docsmith/mermaid`      | the Mermaid diagram component (lazy-loaded by the preprocessor when a mermaid fence is present)                                                                                                                                          |
+| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                                                                                                                  |
+| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                                                                                                                 |
+
+The package also ships a CLI binary: `npx svelte-docsmith archive-version <id>`
+freezes the current docs into a versioned archive.
 
 The vendored shadcn primitives and internal helpers (the TOC engine, clipboard
 utility, markdown renderer map) are **not** part of the public API; they can

package/dist/buildtime/archive.d.ts

@@ -29,3 +29,21 @@ export declare function rewriteDocsLinks(text: string, options: {
  * existing `lastUpdated` and any page without frontmatter alone.
  */
 export declare function freezeLastUpdated(text: string, date: string | undefined): string;
+/**
+ * The specifiers a page's `<script>` imports from outside the freeze boundary,
+ * deduplicated in source order. `pageDir` is the page's directory relative to
+ * the docs root, which is what its relative imports resolve against.
+ *
+ * Archiving copies the docs root and nothing else, so anything reached from
+ * outside it keeps resolving to current code: a live example on an archived
+ * page demonstrates the current library rather than the version the page
+ * documents, with a green build and nothing said. Hence `$lib`, bare npm
+ * specifiers and relative paths that climb out all count, while a relative
+ * import landing inside the docs root is frozen along with the page.
+ *
+ * `svelte-docsmith` itself is never reported. An archived page importing the
+ * authoring components is the expected shape, and those are covered by the
+ * stability promise rather than by this notice. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ */
+export declare function boundaryCrossings(source: string, pageDir: string): string[];

package/dist/buildtime/archive.js

@@ -8,7 +8,7 @@
  * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
  */
 import { atBoundary, firstSegmentUnder } from '../utils/url.js';
-import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
+import { outsideCodeFences, scriptBlocks, withFrontmatter } from './markdown-source.js';
 /** Route files at the docs root that an archive nested inside it already inherits. */
 export function isInheritedRouteFile(name) {
     return /^\+(layout|error)\./.test(name);
@@ -50,3 +50,63 @@ export function freezeLastUpdated(text, date) {
         return text;
     return withFrontmatter(text, (front) => /^lastUpdated:/m.test(front) ? front : `${front}\nlastUpdated: '${date}'`);
 }
+/**
+ * An import's specifier, static or dynamic. The clause between `import` and
+ * `from` may not hold a quote or a paren, so the scan cannot run past a
+ * side-effect import to borrow a later `from`, and `import.meta.glob('./x')`
+ * matches nothing.
+ */
+const IMPORT = /\bimport\s*\(?\s*(?:[^'"()]*?\bfrom\s*)?['"]([^'"]+)['"]/g;
+/** The package an archived page is expected to import, and its subpaths. */
+const LIBRARY = 'svelte-docsmith';
+/**
+ * Whether a relative specifier climbs out of the docs root when resolved from a
+ * page `depth` directories inside it. Counting segments rather than resolving
+ * real paths keeps the rule pure, and the docs root is the only boundary that
+ * matters: where under it a surviving import lands is the archive's business.
+ */
+function escapesRoot(specifier, depth) {
+    let level = depth;
+    for (const segment of specifier.split('/')) {
+        if (segment === '..')
+            level--;
+        else if (segment !== '.' && segment !== '')
+            level++;
+        if (level < 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * The specifiers a page's `<script>` imports from outside the freeze boundary,
+ * deduplicated in source order. `pageDir` is the page's directory relative to
+ * the docs root, which is what its relative imports resolve against.
+ *
+ * Archiving copies the docs root and nothing else, so anything reached from
+ * outside it keeps resolving to current code: a live example on an archived
+ * page demonstrates the current library rather than the version the page
+ * documents, with a green build and nothing said. Hence `$lib`, bare npm
+ * specifiers and relative paths that climb out all count, while a relative
+ * import landing inside the docs root is frozen along with the page.
+ *
+ * `svelte-docsmith` itself is never reported. An archived page importing the
+ * authoring components is the expected shape, and those are covered by the
+ * stability promise rather than by this notice. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ */
+export function boundaryCrossings(source, pageDir) {
+    const depth = pageDir.split('/').filter(Boolean).length;
+    const found = new Set();
+    for (const block of scriptBlocks(source)) {
+        for (const [, specifier] of block.matchAll(IMPORT)) {
+            if (specifier === LIBRARY || specifier.startsWith(`${LIBRARY}/`))
+                continue;
+            // Only a package name can start with something other than a dot, and no
+            // package name starts with one, so this is the whole relative/bare split.
+            if (specifier.startsWith('.') && !escapesRoot(specifier, depth))
+                continue;
+            found.add(specifier);
+        }
+    }
+    return [...found];
+}

package/dist/buildtime/archives.d.ts

@@ -6,6 +6,9 @@ import type { ArchivesOnDisk } from '../core/version.js';
  * are otherwise indistinguishable, since a page is assigned to a version by its
  * first directory segment. See
  * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Name and role may change in
+ * a minor until authors have used versioning for real.
  */
 export declare const ARCHIVE_MARKER = ".docsmith-archive";
 /** The text written into a new archive's marker file. */

package/dist/buildtime/archives.js

@@ -16,6 +16,9 @@ import path from 'node:path';
  * are otherwise indistinguishable, since a page is assigned to a version by its
  * first directory segment. See
  * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Name and role may change in
+ * a minor until authors have used versioning for real.
  */
 export const ARCHIVE_MARKER = '.docsmith-archive';
 /** The text written into a new archive's marker file. */

package/dist/buildtime/cli/archive-version.d.ts

@@ -14,5 +14,8 @@ export type ArchiveVersionOptions = {
  * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
  * each copied page so it stays inside the archive and keeps its real
  * last-updated date. Returns the number of pages archived.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export declare function archiveVersion(options: ArchiveVersionOptions, log: (line: string) => void): number;

package/dist/buildtime/cli/archive-version.js

@@ -3,15 +3,23 @@
  * archived version folder so they keep serving the release they document while
  * the docs root goes on being edited.
  *
+ * Freezes content, not dependencies: the prose, samples and URLs are that
+ * version's, while anything a page imports keeps resolving to whatever the app
+ * currently has installed. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ *
  * The pure text transforms live in `../archive.js`; this is the filesystem work
  * around them. It takes its working directory and its output sink rather than
  * reading `process.cwd()` and calling `console.log`, so the whole command runs
  * in-process under test. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Flags and behaviour may
+ * change in a minor until authors have used versioning for real.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { assertValidVersionId } from '../../core/version.js';
-import { freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
+import { boundaryCrossings, freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
 import { ARCHIVE_MARKER, discoverArchives, markerContents } from '../archives.js';
 import { commitDates } from '../git.js';
 import { docsBaseFrom } from '../paths.js';
@@ -21,6 +29,9 @@ import { CliError } from './error.js';
  * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
  * each copied page so it stays inside the archive and keeps its real
  * last-updated date. Returns the number of pages archived.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export function archiveVersion(options, log) {
     const cwd = options.cwd ?? process.cwd();
@@ -84,17 +95,23 @@ export function archiveVersion(options, log) {
     // be read: an archive is written once and never edited again, so a page that
     // misses its date here keeps the wrong one for good.
     const dates = commitDates(contentDir, (reason) => {
-        log(`\n! Could not read commit dates: ${reason}`);
+        log(`\n! Skipping git-derived page dates: ${reason}`);
         log('  Archived pages will keep no last-updated date.\n');
     });
     copyCurrent(contentDir, toDir);
     fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
     let pages = 0;
+    /** One `path: specifiers` line per page that imports across the freeze boundary. */
+    const crossings = [];
     for (const { file, source } of eachCopiedFile()) {
         if (!isPageFile(path.basename(file)))
             continue;
         pages++;
         const text = fs.readFileSync(file, 'utf-8');
+        const pageDir = path.relative(toDir, path.dirname(file)).split(path.sep).join('/');
+        const crossed = boundaryCrossings(text, pageDir);
+        if (crossed.length)
+            crossings.push(`    ${rel(file)}: ${crossed.join(', ')}`);
         fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), dates.get(source)));
     }
     log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
@@ -102,6 +119,17 @@ export function archiveVersion(options, log) {
     // Only claim the dates were kept when the walk actually produced some.
     if (dates.size)
         log('Each page kept its real last-updated date.');
+    // Informational: the archive is correct as content, and there is nothing to
+    // fix here. Said out loud because the alternative is a green build hiding a
+    // v1 page that demos v2, which nothing downstream can notice.
+    if (crossings.length) {
+        const count = crossings.length === 1 ? '1 page' : `${crossings.length} pages`;
+        log(`\n! ${count} import across the freeze boundary:`);
+        crossings.sort().forEach(log);
+        log('  Archiving copies the docs root, not what it imports, so these keep');
+        log('  resolving to current code. Their examples will demonstrate the');
+        log('  current library rather than the version this archive documents.\n');
+    }
     log('Review the diff, then update docsmith({ versions }) so the archive');
     log('is served:\n');
     log('  versions: {');

package/dist/buildtime/cli/run.js

@@ -7,6 +7,9 @@
  * message and an exit code. Keeping the process boundary out here means the
  * command is typechecked, and testable in-process against a temporary directory
  * rather than by spawning node and parsing stdout.
+ *
+ * @experimental `archive-version` sits outside the 1.0 stability promise and
+ * may change in a minor until authors have used versioning for real.
  */
 import { archiveVersion } from './archive-version.js';
 import { CliError } from './error.js';

package/dist/buildtime/git.d.ts

@@ -14,12 +14,19 @@
  * all-or-nothing: a truncated read would date some pages and not others, which
  * looks like real data and is not.
  *
- * Only a truncated read calls `onFail`, because it is the one failure that would
- * otherwise date some pages and not others. A directory outside a repository, a
- * missing directory, or a machine without git all yield no dates, which every
- * caller already handles and which the plugin already reports where it matters.
- * Reporting is the caller's to do, which is why this takes a callback rather
- * than writing to the console itself.
+ * A shallow clone also yields no dates. Its single commit introduces every
+ * tracked file, so a walk would stamp every page with the same day — silent,
+ * plausible, and wrong for both page footers and sitemap `<lastmod>`. Omitting
+ * the date is legitimate; a uniform wrong date is not. Callers that need real
+ * dates should build from a full clone (`fetch-depth: 0` in CI, unshallow on
+ * the host).
+ *
+ * `onFail` fires for a truncated read or a shallow repository: those are the
+ * cases that would otherwise produce dates that look real and are not. A
+ * directory outside a repository, a missing directory, or a machine without git
+ * all yield no dates quietly, which every caller already handles. Reporting is
+ * the caller's to do, which is why this takes a callback rather than writing to
+ * the console itself.
  */
 export declare function commitDates(dir: string, onFail?: (reason: string) => void, 
 /**

package/dist/buildtime/git.js

@@ -28,12 +28,19 @@ import path from 'node:path';
  * all-or-nothing: a truncated read would date some pages and not others, which
  * looks like real data and is not.
  *
- * Only a truncated read calls `onFail`, because it is the one failure that would
- * otherwise date some pages and not others. A directory outside a repository, a
- * missing directory, or a machine without git all yield no dates, which every
- * caller already handles and which the plugin already reports where it matters.
- * Reporting is the caller's to do, which is why this takes a callback rather
- * than writing to the console itself.
+ * A shallow clone also yields no dates. Its single commit introduces every
+ * tracked file, so a walk would stamp every page with the same day — silent,
+ * plausible, and wrong for both page footers and sitemap `<lastmod>`. Omitting
+ * the date is legitimate; a uniform wrong date is not. Callers that need real
+ * dates should build from a full clone (`fetch-depth: 0` in CI, unshallow on
+ * the host).
+ *
+ * `onFail` fires for a truncated read or a shallow repository: those are the
+ * cases that would otherwise produce dates that look real and are not. A
+ * directory outside a repository, a missing directory, or a machine without git
+ * all yield no dates quietly, which every caller already handles. Reporting is
+ * the caller's to do, which is why this takes a callback rather than writing to
+ * the console itself.
  */
 export function commitDates(dir, onFail, 
 /**
@@ -43,6 +50,13 @@ export function commitDates(dir, onFail,
  */
 maxBuffer = 256 * 1024 * 1024) {
     const dates = new Map();
+    // One cheap probe before the walk. On a shallow clone the walk would "work"
+    // and return one day for every file — worse than failing, so refuse first.
+    if (isShallowRepository(dir)) {
+        onFail?.('shallow clone: git history is incomplete, so commit dates would be wrong. ' +
+            'Build from a full clone (e.g. actions/checkout fetch-depth: 0), or set lastUpdated in frontmatter.');
+        return dates;
+    }
     const res = spawnSync('git', ['log', '--format=%cs', '--name-only', '--relative', '--no-renames', '--', '.'], 
     // The 1 MB default would truncate rather than throw on a large history,
     // which is why the cap is raised and the result checked below.
@@ -71,6 +85,17 @@ maxBuffer = 256 * 1024 * 1024) {
     }
     return dates;
 }
+/**
+ * Whether `dir` sits in a shallow clone. Outside a repository, or when git is
+ * missing, returns false so the walk's own failure path still owns that case.
+ */
+function isShallowRepository(dir) {
+    const res = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
+        cwd: dir,
+        encoding: 'utf-8'
+    });
+    return res.status === 0 && res.stdout.trim() === 'true';
+}
 /**
  * Release dates keyed by version, read from the commit that introduced each
  * `## <version>` heading in a changelog. Changesets does not write dates, and a

package/dist/buildtime/markdown-layout.svelte

@@ -23,7 +23,9 @@
 	}: { title?: string; description?: string; children: Snippet } = $props();
 </script>
 
-<article class="prose prose-base dark:prose-invert max-w-none pb-16">
+<!-- max-w-prose (~65ch) keeps body measure in the DESIGN.md 65–75ch band on
+     ultrawide screens; code blocks and not-prose widgets still overflow locally. -->
+<article class="prose prose-base dark:prose-invert max-w-prose pb-16">
 	{#if title}
 		<h1>{title}</h1>
 	{/if}

package/dist/buildtime/markdown-source.d.ts

@@ -29,3 +29,12 @@ export declare function withFrontmatter(source: string, transform: (frontmatter:
 export declare function outsideCodeFences(text: string, transform: (line: string) => string): string;
 /** A page's prose lines, in order, with fenced code and its markers dropped. */
 export declare function proseLines(text: string): Generator<string>;
+/**
+ * The code inside each `<script>` block a page actually runs, in order.
+ *
+ * Fenced blocks are skipped, which is the whole reason this reads the page
+ * through {@link proseLines} rather than scanning the raw text: a docs page
+ * about authoring is mostly ```svelte samples that open with a `<script>`, and
+ * those are code being displayed, not code the page runs.
+ */
+export declare function scriptBlocks(text: string): Generator<string>;

package/dist/buildtime/markdown-source.js

@@ -88,3 +88,25 @@ export function* proseLines(text) {
             yield line;
     }
 }
+/**
+ * A `<script>` element with any attributes, through its closing tag. The open
+ * tag has to start a line, indented no further than CommonMark lets HTML be:
+ * four spaces make an indented code block, and mid-line means a sentence about
+ * a script tag rather than one. Authoring prose writes `` `<script>` `` in
+ * inline code constantly, and a page that only talks about a script block has
+ * no script block.
+ */
+const SCRIPT_BLOCK = /^ {0,3}<script\b[^>]*>([\s\S]*?)<\/script>/gim;
+/**
+ * The code inside each `<script>` block a page actually runs, in order.
+ *
+ * Fenced blocks are skipped, which is the whole reason this reads the page
+ * through {@link proseLines} rather than scanning the raw text: a docs page
+ * about authoring is mostly ```svelte samples that open with a `<script>`, and
+ * those are code being displayed, not code the page runs.
+ */
+export function* scriptBlocks(text) {
+    const prose = [...proseLines(splitFrontmatter(text).body)].join('\n');
+    for (const match of prose.matchAll(SCRIPT_BLOCK))
+        yield match[1];
+}

package/dist/buildtime/vite/index.d.ts

@@ -31,6 +31,10 @@ export interface DocsmithViteOptions {
      * keep their unprefixed URLs. Each archived version's pages live under
      * `<content>/<id>/` and are served at `/docs/<id>/…`. Omit for a single,
      * unversioned docs tree (the default).
+     *
+     * @experimental Outside the 1.0 stability promise. May change in a minor
+     * until authors have used versioning for real. An archive freezes content,
+     * not dependencies.
      */
     versions?: DocsVersions;
 }

package/dist/buildtime/vite/index.js

@@ -78,7 +78,10 @@ function contentIndexPlugin(options) {
     // `dev` leaves the dates as they were until the server restarts.
     let dates;
     const trackedDates = () => (dates ??= commitDates(contentDir, (reason) => {
-        console.warn(`[svelte-docsmith] could not read commit dates under ${contentDir}\n` +
+        // Truncation and shallow clones both refuse dates deliberately; the
+        // reason line says which. "Could not read" would misframe a shallow
+        // skip as a hard failure.
+        console.warn(`[svelte-docsmith] skipping git-derived page dates under ${contentDir}\n` +
             `  ${reason}\n` +
             `  Pages will render without a last-updated date, and sitemap entries without \`lastmod\`.`);
     }));

package/dist/components/chrome/background-pattern.svelte

@@ -1,12 +1,11 @@
 <!-- Decorative page background: a faint grid fading out from the top, with two
-soft primary/accent glows. Render it inside a `relative isolate` container. -->
+soft primary/accent glows. Grid lines use --border so they track every theme
+preset; render inside a `relative isolate` container. -->
 <div
 	class="pointer-events-none absolute inset-0 -z-10 h-full w-full overflow-hidden"
 	aria-hidden="true"
 >
-	<div
-		class="fixed inset-0 bg-[linear-gradient(to_right,#80808012_1px,transparent_1px),linear-gradient(to_bottom,#80808012_1px,transparent_1px)] bg-size-[24px_24px] mask-[radial-gradient(ellipse_80%_80%_at_50%_0%,#000_70%,transparent_100%)]"
-	></div>
+	<div class="pattern-grid fixed inset-0"></div>
 
 	<div
 		class="bg-primary/20 pointer-events-none fixed top-0 left-1/2 h-[500px] w-[800px] -translate-x-1/2 rounded-full opacity-40 mix-blend-screen blur-[120px] dark:opacity-20 dark:mix-blend-normal"
@@ -15,3 +14,22 @@ soft primary/accent glows. Render it inside a `relative isolate` container. -->
 		class="bg-accent/25 pointer-events-none fixed top-28 left-1/2 h-[400px] w-[600px] -translate-x-1/2 rounded-full opacity-30 mix-blend-screen blur-[100px] dark:opacity-20 dark:mix-blend-normal"
 	></div>
 </div>
+
+<style>
+	.pattern-grid {
+		/* 24px cell; line colour follows the theme border token at low opacity. */
+		background-image:
+			linear-gradient(
+				to right,
+				color-mix(in oklch, var(--border) 70%, transparent) 1px,
+				transparent 1px
+			),
+			linear-gradient(
+				to bottom,
+				color-mix(in oklch, var(--border) 70%, transparent) 1px,
+				transparent 1px
+			);
+		background-size: 24px 24px;
+		mask-image: radial-gradient(ellipse 80% 80% at 50% 0%, #000 70%, transparent 100%);
+	}
+</style>

package/dist/components/chrome/search.svelte

@@ -34,6 +34,7 @@
 
 	let query = $state('');
 	let engine = $state<SearchEngine | null>(null);
+	let indexDocs = $state<SearchDoc[]>([]);
 	let status = $state<'idle' | 'loading' | 'error'>('idle');
 	// The version the cached engine was built for, so a loader that returns only
 	// one version's records is rebuilt when the reader switches versions. Stays
@@ -44,6 +45,27 @@
 	// Scope to the active version on a versioned site; `undefined` otherwise.
 	const results = $derived(engine && trimmed ? engine.search(query, undefined, activeVersion) : []);
 
+	// Empty-state starters: prefer common first pages when present, then fill
+	// from the rest of the index so a custom site still has something useful.
+	const suggestions = $derived.by(() => {
+		const scoped = activeVersion ? indexDocs.filter((d) => d.version === activeVersion) : indexDocs;
+		if (!scoped.length) return [];
+		const preferred = [/introduction/i, /quick[- ]?start/i, /install/i, /getting started/i];
+		const picked: SearchDoc[] = [];
+		for (const re of preferred) {
+			const hit = scoped.find(
+				(d) =>
+					!picked.includes(d) && (re.test(d.title) || re.test(d.path) || re.test(d.section ?? ''))
+			);
+			if (hit) picked.push(hit);
+		}
+		for (const d of scoped) {
+			if (picked.length >= 4) break;
+			if (!picked.includes(d)) picked.push(d);
+		}
+		return picked.slice(0, 4);
+	});
+
 	// Build the index the first time the palette opens; keep it for later opens.
 	async function ensureEngine() {
 		const version = activeVersion;
@@ -54,6 +76,7 @@
 				import('../../search/create-search.js'),
 				load(version)
 			]);
+			indexDocs = docs;
 			engine = createSearchEngine(docs);
 			engineVersion = version;
 			status = 'idle';
@@ -106,16 +129,48 @@
 					Search is unavailable right now.
 				</div>
 			{:else if !trimmed}
-				<div
-					class="text-muted-foreground flex flex-col items-center gap-3 px-4 py-10 text-center text-sm"
-				>
-					<span
-						class="bg-muted/60 text-muted-foreground flex size-11 items-center justify-center rounded-full"
+				{#if suggestions.length}
+					<p class="text-muted-foreground px-2.5 pb-1.5 text-xs font-medium tracking-wide">
+						Suggested
+					</p>
+					{#each suggestions as doc (doc.path)}
+						<Command.LinkItem
+							href={doc.path}
+							onSelect={() => select(doc.path)}
+							class="group/result mb-0.5 flex items-center gap-3 rounded-lg px-2.5 py-2 aria-selected:bg-accent aria-selected:text-accent-foreground"
+						>
+							<span
+								class="border-border/60 bg-muted/40 text-muted-foreground group-aria-selected/result:border-accent-foreground/20 group-aria-selected/result:text-accent-foreground flex size-8 shrink-0 items-center justify-center rounded-md border"
+							>
+								<FileText class="size-4" />
+							</span>
+							<span class="flex min-w-0 flex-1 flex-col gap-0.5">
+								<span class="truncate font-medium">{doc.title}</span>
+								{#if doc.section}
+									<span
+										class="text-muted-foreground group-aria-selected/result:text-accent-foreground/80 text-xs"
+									>
+										{doc.section}
+									</span>
+								{/if}
+							</span>
+							<CornerDownLeft
+								class="text-muted-foreground group-aria-selected/result:text-accent-foreground size-4 shrink-0 opacity-0 group-aria-selected/result:opacity-100"
+							/>
+						</Command.LinkItem>
+					{/each}
+				{:else}
+					<div
+						class="text-muted-foreground flex flex-col items-center gap-3 px-4 py-10 text-center text-sm"
 					>
-						<SearchIcon class="size-5" />
-					</span>
-					<span>Search across every page of the documentation.</span>
-				</div>
+						<span
+							class="bg-muted/60 text-muted-foreground flex size-11 items-center justify-center rounded-full"
+						>
+							<SearchIcon class="size-5" />
+						</span>
+						<span>Search across every page of the documentation.</span>
+					</div>
+				{/if}
 			{:else if results.length === 0}
 				<div class="text-muted-foreground px-4 py-10 text-center text-sm">
 					No results for <span class="text-foreground font-medium">“{trimmed}”</span>.

package/dist/components/chrome/theme-toggle.svelte

@@ -5,12 +5,17 @@
 	import { mode, toggleMode } from 'mode-watcher';
 
 	const { class: className }: { class?: string } = $props();
+
+	// Label names the destination mode so the control is self-describing for
+	// assistive tech and matches what the icon shows (sun = go light, moon = go dark).
+	const label = $derived(mode.current === 'dark' ? 'Switch to light mode' : 'Switch to dark mode');
 </script>
 
 <Button
 	size="icon"
 	variant="ghost"
 	onclick={toggleMode}
+	aria-label={label}
 	class="text-muted-foreground hover:text-foreground size-8 {className ?? ''}"
 >
 	{#if mode.current === 'dark'}
@@ -18,5 +23,4 @@
 	{:else}
 		<Moon class="size-4" />
 	{/if}
-	<span class="sr-only">Toggle theme</span>
 </Button>

package/dist/components/landing/cta.svelte

@@ -5,6 +5,7 @@
 		title,
 		description,
 		actions,
+		before,
 		children
 	}: {
 		title: string;
@@ -12,7 +13,12 @@
 		description?: string;
 		/** Call-to-action buttons. */
 		actions?: Snippet;
-		/** Anything to sit below the actions, e.g. a note or a callout. */
+		/**
+		 * Optional content above the heading (e.g. a pre-release note). Placed
+		 * before the title so the section can still *end* on the actions.
+		 */
+		before?: Snippet;
+		/** Anything to sit below the actions, e.g. a secondary note. */
 		children?: Snippet;
 	} = $props();
 </script>
@@ -29,12 +35,18 @@
 			></div>
 		</div>
 
-		<h2 class="mx-auto max-w-2xl text-3xl font-semibold tracking-tight text-balance sm:text-4xl">
+		{#if before}
+			<div class="mx-auto mb-8 max-w-xl text-left">{@render before()}</div>
+		{/if}
+
+		<h2
+			class="font-serif mx-auto max-w-2xl text-3xl font-semibold tracking-tight text-balance sm:text-4xl"
+		>
 			{title}
 		</h2>
 
 		{#if description}
-			<p class="text-muted-foreground mx-auto mt-4 max-w-xl text-lg leading-relaxed text-pretty">
+			<p class="text-foreground mx-auto mt-4 max-w-xl text-lg leading-relaxed text-pretty">
 				{description}
 			</p>
 		{/if}

package/dist/components/landing/cta.svelte.d.ts

@@ -5,7 +5,12 @@ type $$ComponentProps = {
     description?: string;
     /** Call-to-action buttons. */
     actions?: Snippet;
-    /** Anything to sit below the actions, e.g. a note or a callout. */
+    /**
+     * Optional content above the heading (e.g. a pre-release note). Placed
+     * before the title so the section can still *end* on the actions.
+     */
+    before?: Snippet;
+    /** Anything to sit below the actions, e.g. a secondary note. */
     children?: Snippet;
 };
 declare const Cta: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/landing/feature-grid.svelte

@@ -29,10 +29,12 @@
 		{#if title || description}
 			<div class="mx-auto max-w-2xl text-center">
 				{#if title}
-					<h2 class="text-3xl font-semibold tracking-tight text-balance sm:text-4xl">{title}</h2>
+					<h2 class="font-serif text-3xl font-semibold tracking-tight text-balance sm:text-4xl">
+						{title}
+					</h2>
 				{/if}
 				{#if description}
-					<p class="text-muted-foreground mt-4 text-lg leading-relaxed text-pretty">
+					<p class="text-foreground mt-4 text-lg leading-relaxed text-pretty">
 						{description}
 					</p>
 				{/if}

package/dist/components/landing/feature.svelte

@@ -27,7 +27,7 @@
 	<div class="min-w-0">
 		<h3 class="font-semibold">{title}</h3>
 		{#if children}
-			<p class="text-muted-foreground mt-1 text-sm leading-relaxed">{@render children()}</p>
+			<p class="text-foreground/80 mt-1 text-sm leading-relaxed">{@render children()}</p>
 		{/if}
 	</div>
 </div>

package/dist/components/landing/hero.svelte

@@ -40,7 +40,7 @@
 		{/if}
 
 		<h1
-			class="text-5xl font-semibold tracking-[-0.03em] text-balance sm:text-6xl lg:text-[4.25rem] lg:leading-[1.02] {eyebrow
+			class="font-serif text-5xl font-semibold tracking-[-0.03em] text-balance sm:text-6xl lg:text-[4.25rem] lg:leading-[1.02] {eyebrow
 				? 'mt-6'
 				: ''}"
 		>
@@ -49,7 +49,7 @@
 
 		{#if description}
 			<p
-				class="text-muted-foreground mt-6 max-w-xl text-lg leading-relaxed text-pretty {media
+				class="text-foreground mt-6 max-w-xl text-lg leading-relaxed text-pretty {media
 					? ''
 					: 'mx-auto'}"
 			>

package/dist/components/layouts/docs-mobile-header.svelte

@@ -13,9 +13,10 @@
 	import * as Sheet from '../shadcn/sheet/index.js';
 	import { useSearch } from '../../search/context.svelte.js';
 	import { useDocsPage } from '../docs-page-context.js';
+	import GithubIcon from '../icons/github.svelte';
 	import BookOpenText from '@lucide/svelte/icons/book-open-text';
+	import List from '@lucide/svelte/icons/list';
 	import Menu from '@lucide/svelte/icons/menu';
-	import PanelRight from '@lucide/svelte/icons/panel-right';
 	import SearchIcon from '@lucide/svelte/icons/search';
 	import type { Snippet } from 'svelte';
 
@@ -124,15 +125,32 @@
 				</Button>
 			{/if}
 
+			{#if config.github}
+				<Button
+					size="icon"
+					variant="ghost"
+					target="_blank"
+					rel="noopener noreferrer"
+					href={config.github}
+					class="text-muted-foreground hover:text-foreground size-8"
+				>
+					<GithubIcon class="size-4" />
+					<span class="sr-only">GitHub</span>
+				</Button>
+			{/if}
+
 			<ThemeToggle />
 
 			{#if tocItems.length > 0}
 				<Popover.Root bind:open={isTocOpen}>
 					<Popover.Trigger>
 						{#snippet child({ props })}
-							<Button variant="ghost" size="icon" class="size-8" {...props}>
-								<PanelRight class="size-4" />
-								<span class="sr-only">Table of contents</span>
+							<!-- Labeled (not icon-only) so first-timers find "on this page"
+							     without guessing PanelRight. Label collapses on the narrowest
+							     phones so the title still has room. -->
+							<Button variant="ghost" size="sm" class="h-8 gap-1.5 px-2" {...props}>
+								<List class="size-4 shrink-0" />
+								<span class="text-xs font-medium max-[22rem]:sr-only">On this page</span>
 							</Button>
 						{/snippet}
 					</Popover.Trigger>

package/dist/components/layouts/docs-shell.svelte

@@ -151,7 +151,7 @@
 		readingTime && view.readingMinutes ? `${view.readingMinutes} min read` : undefined
 	);
 
-	const breadcrumbs = $derived(view.breadcrumbs.map((title) => ({ title })));
+	const breadcrumbs = $derived(view.breadcrumbs);
 
 	// The archived-version banner, or nothing. Its "view this page in <current>"
 	// link is the current version's entry in the same list the switcher renders,
@@ -286,6 +286,10 @@
 							<PageFeedback
 								path={view.pathname}
 								onfeedback={typeof feedback === 'function' ? feedback : undefined}
+								editHref={view.editHref}
+								issueHref={config.github
+									? `${config.github}/issues/new?title=${encodeURIComponent(`Feedback: ${view.title}`)}&body=${encodeURIComponent(`Page: ${view.pathname}\n\n<!-- What was unclear or missing? -->\n`)}`
+									: undefined}
 							/>
 						</div>
 					{/key}

package/dist/components/layouts/docs-sidebar.svelte

@@ -43,7 +43,7 @@
 						href={node.url}
 						aria-current={current === node.url ? 'page' : undefined}
 						class={cn(
-							'hover:text-primary hover:bg-primary/20 block rounded-md px-2 py-1.5 text-sm transition-colors',
+							'hover:text-primary hover:bg-primary/10 block rounded-md px-2 py-1.5 text-sm transition-colors',
 							current === node.url
 								? 'text-primary bg-primary/20 font-medium'
 								: 'text-muted-foreground'

package/dist/components/layouts/page-feedback.svelte

@@ -2,19 +2,29 @@
 	import { Button } from '../shadcn/button/index.js';
 	import ThumbsUp from '@lucide/svelte/icons/thumbs-up';
 	import ThumbsDown from '@lucide/svelte/icons/thumbs-down';
+	import SquarePen from '@lucide/svelte/icons/square-pen';
+	import ExternalLink from '@lucide/svelte/icons/external-link';
 
 	const {
 		path,
-		onfeedback
+		onfeedback,
+		editHref,
+		issueHref
 	}: {
 		/** The current page path, passed to the callback so it can attribute votes. */
 		path: string;
 		/** Called once per page when the reader votes; wire it to your analytics. */
 		onfeedback?: (vote: 'up' | 'down', path: string) => void;
+		/** "Edit this page" target — offered after a "No" vote when present. */
+		editHref?: string;
+		/** "Open an issue" target — offered after a "No" vote when present. */
+		issueHref?: string;
 	} = $props();
 
 	let vote = $state<'up' | 'down' | null>(null);
 
+	const hasRecovery = $derived(Boolean(editHref || issueHref));
+
 	function cast(value: 'up' | 'down') {
 		if (vote) return;
 		vote = value;
@@ -23,8 +33,40 @@
 </script>
 
 <div class="flex flex-col items-center gap-2.5 text-center">
-	{#if vote}
+	{#if vote === 'up'}
 		<p class="text-muted-foreground text-sm">Thanks for your feedback!</p>
+	{:else if vote === 'down'}
+		<p class="text-muted-foreground text-sm">
+			{hasRecovery ? 'Thanks — want to help improve this page?' : 'Thanks for your feedback!'}
+		</p>
+		{#if hasRecovery}
+			<div class="flex flex-wrap items-center justify-center gap-2">
+				{#if editHref}
+					<Button
+						variant="outline"
+						size="sm"
+						href={editHref}
+						target="_blank"
+						rel="noopener noreferrer"
+					>
+						<SquarePen />
+						Edit this page
+					</Button>
+				{/if}
+				{#if issueHref}
+					<Button
+						variant="outline"
+						size="sm"
+						href={issueHref}
+						target="_blank"
+						rel="noopener noreferrer"
+					>
+						<ExternalLink />
+						Open an issue
+					</Button>
+				{/if}
+			</div>
+		{/if}
 	{:else}
 		<p class="text-muted-foreground text-sm">Was this page helpful?</p>
 		<div class="flex items-center gap-2">

package/dist/components/layouts/page-feedback.svelte.d.ts

@@ -3,6 +3,10 @@ type $$ComponentProps = {
     path: string;
     /** Called once per page when the reader votes; wire it to your analytics. */
     onfeedback?: (vote: 'up' | 'down', path: string) => void;
+    /** "Edit this page" target — offered after a "No" vote when present. */
+    editHref?: string;
+    /** "Open an issue" target — offered after a "No" vote when present. */
+    issueHref?: string;
 };
 declare const PageFeedback: import("svelte").Component<$$ComponentProps, {}, "">;
 type PageFeedback = ReturnType<typeof PageFeedback>;

package/dist/components/layouts/prev-next-nav.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
 	import type { NavItem } from '../../core/index.js';
+	import ChevronLeft from '@lucide/svelte/icons/chevron-left';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
 
 	const {
 		prev,
@@ -16,9 +18,14 @@
 		{#if prev}
 			<a
 				href={prev.url}
-				class="border-border hover:border-primary flex min-w-0 flex-1 flex-col gap-1 rounded-lg border p-4 transition-colors"
+				class="border-border hover:border-primary/60 hover:bg-primary/5 group flex min-w-0 flex-1 flex-col gap-1 rounded-lg border p-4 transition-colors"
 			>
-				<span class="text-muted-foreground text-xs">Previous</span>
+				<span
+					class="text-muted-foreground group-hover:text-primary flex items-center gap-1 text-xs"
+				>
+					<ChevronLeft class="size-3.5" aria-hidden="true" />
+					Previous
+				</span>
 				<span class="text-foreground truncate font-medium">{prev.title}</span>
 			</a>
 		{:else}
@@ -27,9 +34,14 @@
 		{#if next}
 			<a
 				href={next.url}
-				class="border-border hover:border-primary ml-auto flex min-w-0 flex-1 flex-col gap-1 rounded-lg border p-4 text-right transition-colors"
+				class="border-border hover:border-primary/60 hover:bg-primary/5 group ml-auto flex min-w-0 flex-1 flex-col items-end gap-1 rounded-lg border p-4 text-right transition-colors"
 			>
-				<span class="text-muted-foreground text-xs">Next</span>
+				<span
+					class="text-muted-foreground group-hover:text-primary flex items-center gap-1 text-xs"
+				>
+					Next
+					<ChevronRight class="size-3.5" aria-hidden="true" />
+				</span>
 				<span class="text-foreground truncate font-medium">{next.title}</span>
 			</a>
 		{:else}

package/dist/core/content.d.ts

@@ -25,9 +25,11 @@ export type DocsContentItem = {
     sourcePath?: string;
     /**
      * The day (`YYYY-MM-DD`) the page's source file last changed, from git, or
-     * from the page's own `lastUpdated` frontmatter when it has one. A calendar
-     * day rather than a timestamp: it is rendered as a UTC day, so it reads the
-     * same for every reader and matches on the server and the client.
+     * from the page's own `lastUpdated` frontmatter when it has one. Absent when
+     * neither source supplies a day — including on a shallow clone, where git
+     * dates would be wrong. A calendar day rather than a timestamp: it is
+     * rendered as a UTC day, so it reads the same for every reader and matches
+     * on the server and the client.
      */
     lastUpdated?: string;
     /** Estimated reading time in whole minutes (at ~200 wpm), min 1. */

package/dist/core/docs-page.d.ts

@@ -9,7 +9,7 @@
  * component that renders them.
  */
 import type { DocsContentItem } from './content.js';
-import { type NavGroup, type NavItem } from './nav.js';
+import { type Breadcrumb, type NavGroup, type NavItem } from './nav.js';
 import { type ResolvedVersion } from './version.js';
 /** The page's build-time headings, as extracted into the content index. */
 type PageToc = NonNullable<DocsContentItem['toc']>;
@@ -56,10 +56,11 @@ export type DocsPageView = {
     /** The page's nav title, falling back to the site title off the nav tree. */
     title: string;
     /**
-     * Breadcrumb titles: the page's group trail, then the page itself. Titles
-     * only, so this layer never depends on a component's `Crumb` type.
+     * Breadcrumb trail: group steps (with a jump URL to the group's first page),
+     * then the current page as a title-only final crumb. No component types
+     * here — the shell maps this onto its `Crumb` shape.
      */
-    breadcrumbs: string[];
+    breadcrumbs: Breadcrumb[];
     /** The page's server-rendered TOC, from {@link entry}. */
     toc: PageToc;
     /**

package/dist/core/docs-page.js

@@ -24,7 +24,7 @@ export function resolveDocsPage(input) {
     const title = pageIndex >= 0 ? flatNav[pageIndex].title : siteTitle;
     const breadcrumbs = navTrail(nav, pathname) ?? [];
     if (pageIndex >= 0)
-        breadcrumbs.push(title);
+        breadcrumbs.push({ title });
     return {
         pathname,
         activeVersion: active,

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
 export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn, type DocsmithAnnouncement } from './config.js';
 export type { DocsContentItem, SearchDoc, LlmsDoc } from './content.js';
 export { resolveVersions, activeVersion, currentVersion, currentOnly, scopeContent, mapPathToVersion, type DocsVersion, type DocsVersions, type ResolvedVersion } from './version.js';
-export { navFromContent, flattenNav, navTrail, isNavGroup, type NavItem, type NavGroup, type NavNode } from './nav.js';
+export { navFromContent, flattenNav, navTrail, type Breadcrumb, isNavGroup, type NavItem, type NavGroup, type NavNode } from './nav.js';
 export { resolveDocsPage, type DocsPageView, type VersionLink } from './docs-page.js';

package/dist/core/nav.d.ts

@@ -26,9 +26,14 @@ export declare function navFromContent(content: DocsContentItem[]): NavGroup[];
  * for the prev/next pager.
  */
 export declare function flattenNav(nodes: NavNode[]): NavItem[];
+/** One step in a breadcrumb trail: a label, and an optional jump target. */
+export type Breadcrumb = {
+    title: string;
+    url?: string;
+};
 /**
- * The trail of group titles leading to the page at `url` (top group first,
- * excluding the page itself), or `undefined` if the page is not in the tree.
- * Drives the breadcrumb trail.
+ * The trail of groups leading to the page at `url` (top group first, excluding
+ * the page itself), or `undefined` if the page is not in the tree. Each group
+ * step carries a `url` to its first leaf so breadcrumbs are navigable.
  */
-export declare function navTrail(nodes: NavNode[], url: string): string[] | undefined;
+export declare function navTrail(nodes: NavNode[], url: string): Breadcrumb[] | undefined;

package/dist/core/nav.js

@@ -82,16 +82,35 @@ export function flattenNav(nodes) {
     return out;
 }
 /**
- * The trail of group titles leading to the page at `url` (top group first,
- * excluding the page itself), or `undefined` if the page is not in the tree.
- * Drives the breadcrumb trail.
+ * First leaf URL under a group, depth-first. Groups have no page of their own,
+ * so breadcrumbs that name a group link to its earliest page (the place a
+ * reader lands if they "go up" into that section).
+ */
+function firstLeafUrl(group) {
+    for (const child of group.items) {
+        if (isNavGroup(child)) {
+            const url = firstLeafUrl(child);
+            if (url)
+                return url;
+        }
+        else {
+            return child.url;
+        }
+    }
+    return undefined;
+}
+/**
+ * The trail of groups leading to the page at `url` (top group first, excluding
+ * the page itself), or `undefined` if the page is not in the tree. Each group
+ * step carries a `url` to its first leaf so breadcrumbs are navigable.
  */
 export function navTrail(nodes, url) {
     for (const node of nodes) {
         if (isNavGroup(node)) {
             const inner = navTrail(node.items, url);
-            if (inner)
-                return [node.title, ...inner];
+            if (inner) {
+                return [{ title: node.title, url: firstLeafUrl(node) }, ...inner];
+            }
         }
         else if (node.url === url) {
             return [];

package/dist/core/version.d.ts

@@ -7,9 +7,18 @@
  * anyone edits; superseded releases are frozen copies under their own prefix.
  * See `docs/adr/0001-unprefixed-current-docs.md`. All of it is a no-op when a
  * site declares no versions.
+ *
+ * **Experimental.** The versioning API sits outside the 1.0 stability promise
+ * and may change in a minor until authors have used it for real. An archive
+ * freezes content, not dependencies — see
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
  */
 import type { DocsContentItem } from './content.js';
-/** One documentation version, declared in the `docsmith()` vite plugin. */
+/**
+ * One documentation version, declared in the `docsmith()` vite plugin.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor.
+ */
 export type DocsVersion = {
     /** Stable id. Also the URL/directory segment for an archived version. */
     id: string;
@@ -23,12 +32,22 @@ export type DocsVersion = {
  * the docs root, is served unprefixed, and is the folder you edit. `archived`
  * holds frozen copies of superseded releases, each in `<docs root>/<id>/`, in
  * the order they should appear in the switcher (newest first).
+ *
+ * Freezes content, not dependencies: prose, samples and URLs stay that
+ * version's, while imports keep resolving to whatever the app has installed.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export type DocsVersions = {
     current: DocsVersion;
     archived?: DocsVersion[];
 };
-/** A {@link DocsVersion} with the URL fields the runtime needs, computed at build time. */
+/**
+ * A {@link DocsVersion} with the URL fields the runtime needs, computed at build time.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor.
+ */
 export type ResolvedVersion = DocsVersion & {
     /** Absolute URL base: the docs root for `current`, `/docs/<id>` for an archive. */
     basePath: string;
@@ -98,6 +117,9 @@ export declare function currentVersion(versions: ResolvedVersion[]): ResolvedVer
  * Keep only the current version's pages, for `sitemap.xml` and `llms.txt`, so
  * search engines and LLMs index one canonical set. A no-op when the site
  * declares no versions. Works over any record carrying `version`.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export declare function currentOnly<T extends {
     version?: string;

package/dist/core/version.js

@@ -153,6 +153,9 @@ export function currentVersion(versions) {
  * Keep only the current version's pages, for `sitemap.xml` and `llms.txt`, so
  * search engines and LLMs index one canonical set. A no-op when the site
  * declares no versions. Works over any record carrying `version`.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export function currentOnly(items, versions) {
     const current = currentVersion(versions);

package/dist/index.js

@@ -31,10 +31,12 @@ export { default as CTA } from './components/landing/cta.svelte';
 export { default as Action } from './components/landing/action.svelte';
 // Config
 export { defineConfig } from './core/index.js';
-// Versioned docs. Declare `versions` in the `docsmith()` vite plugin; the
-// resolved manifest is exported from `svelte-docsmith/content` and passed to
-// `DocsShell`. `currentOnly` scopes sitemap.xml / llms.txt to the current
-// version, so archived releases don't compete with it in search results.
+// Versioned docs (experimental — outside the 1.0 stability promise). Declare
+// `versions` in the `docsmith()` vite plugin; the resolved manifest is exported
+// from `svelte-docsmith/content` and passed to `DocsShell`. `currentOnly`
+// scopes sitemap.xml / llms.txt to the current version, so archived releases
+// don't compete with it in search results. An archive freezes content, not
+// dependencies.
 export { currentOnly } from './core/index.js';
 // Search engine (framework-agnostic; for building a custom search UI over the
 // generated `svelte-docsmith/search` index)

package/dist/theme.css

@@ -16,6 +16,8 @@
 @import 'tw-animate-css';
 @import 'tailwindcss';
 @import '@fontsource-variable/inter';
+@import '@fontsource-variable/source-serif-4';
+@import '@fontsource/jetbrains-mono';
 
 /* Generate utilities for the classes used inside this package. */
 @source './';
@@ -139,9 +141,12 @@
 		--sidebar-accent-foreground: oklch(0.2101 0.0318 264.6645);
 		--sidebar-border: oklch(0.9276 0.0058 264.5313);
 		--sidebar-ring: oklch(0.6716 0.1368 48.513);
-		--font-sans: Inter, sans-serif;
-		--font-serif: Source Serif 4, serif;
-		--font-mono: JetBrains Mono, monospace;
+		/* Fontsource variable packages register as "… Variable"; keep the
+		 * static family names as fallbacks for consumers who load Google Fonts
+		 * or system stacks instead. */
+		--font-sans: 'Inter Variable', Inter, sans-serif;
+		--font-serif: 'Source Serif 4 Variable', 'Source Serif 4', serif;
+		--font-mono: 'JetBrains Mono', ui-monospace, monospace;
 		--radius: 0.75rem;
 		--shadow-2xs: 0px 1px 3px 0px hsl(0 0% 0% / 0.05);
 		--shadow-xs: 0px 1px 3px 0px hsl(0 0% 0% / 0.05);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docsmith",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "A framework for building beautiful documentation sites with Svelte.",
   "author": {
     "name": "George Daskalakis",
@@ -66,7 +66,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/geodask/svelte-docsmith.git"
+    "url": "git+https://github.com/geodask/svelte-docsmith.git"
   },
   "license": "MIT",
   "peerDependencies": {
@@ -107,6 +107,8 @@
   },
   "dependencies": {
     "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource-variable/source-serif-4": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@hbsnow/rehype-sectionize": "^1.0.7",
     "@lucide/svelte": "^1.24.0",
     "@shikijs/transformers": "^3.3.0",