svelte-docsmith 0.10.0 → 0.12.0

package/dist/buildtime/vite/collect.js

@@ -1,9 +1,51 @@
-import fs from 'node:fs';
+/**
+ * The three generated indexes, each a projection of the same page list. Nothing
+ * here reads the filesystem or spawns a process: a build hands these functions
+ * pages read by `./pages.js`, and a test hands them literals. Both go down the
+ * same path, so what the sidebar, search and llms.txt show is decided in one
+ * place and can be checked without a docs root on disk.
+ */
 import path from 'node:path';
-import { listPageFiles } from './pages.js';
-import { parseFrontmatter } from './frontmatter.js';
+import { firstSegmentUnder } from '../../utils/url.js';
+import { docsBaseFrom, urlFor } from '../paths.js';
+import { titleOf } from './pages.js';
 import { extractLlmsContent, extractSearchText, extractToc, readingMinutes } from './extract.js';
-import { lastCommitDate } from './git.js';
+/**
+ * Resolve every titled page against the site's layout. Shared by all three
+ * indexes so they can never disagree about which pages exist or where they live.
+ */
+function indexedPages(pages, options) {
+    const resolved = [];
+    const docsBase = docsBaseFrom(options.routesDir, options.contentDir);
+    for (const page of pages) {
+        const title = titleOf(page);
+        if (title === undefined)
+            continue;
+        const url = urlFor(options.routesDir, path.dirname(page.file));
+        resolved.push({ ...page, url, title, version: versionOf(url) });
+    }
+    // Stable output keeps the generated modules diff-friendly across rebuilds.
+    return resolved.sort((a, b) => a.url.localeCompare(b.url));
+    /**
+     * A page belongs to an archived version when the first segment of its URL below
+     * the docs base is that archive's id; everything else is the current version,
+     * which lives unprefixed at the docs base.
+     *
+     * Decided in URL space, by the same rule `activeVersion` applies to the reader's
+     * pathname at runtime. Deciding it from the directory instead would be a second
+     * rule for the same question, in a second vocabulary, free to drift from the one
+     * the reader is actually served by. No versions ⇒ undefined, which keeps an
+     * unversioned site's index byte-for-byte what it was.
+     */
+    function versionOf(url) {
+        const { versions } = options;
+        if (!versions)
+            return undefined;
+        const segment = firstSegmentUnder(url, docsBase);
+        const archived = versions.archived?.find((v) => v.id === segment);
+        return archived ? archived.id : versions.current.id;
+    }
+}
 /**
  * Read a page's `section` frontmatter: a string is one level, an array is a
  * nested group path. Non-string array members are dropped; anything else is
@@ -33,116 +75,68 @@ function sectionKey(value) {
     return Array.isArray(section) ? section.join(' / ') : section;
 }
 /**
- * Walk every nav-worthy page under `contentDir` once: a page is nav-worthy when
- * its frontmatter has a string `title`. Yields the raw source, parsed
- * frontmatter, derived URL, and title so every index (nav, search, llms) can be
- * built from a single read of each file.
+ * A frontmatter field, when it holds the type the index expects. Frontmatter is
+ * whatever the author typed, so a field of the wrong type is dropped rather than
+ * carried into the index as one.
  */
-function* eachTitledPage(contentDir, routesDir, versions) {
-    for (const file of listPageFiles(contentDir)) {
-        const source = fs.readFileSync(file, 'utf-8');
-        const front = parseFrontmatter(source, file);
-        if (typeof front.title !== 'string')
-            continue;
-        const dir = path.dirname(file);
-        const url = '/' + path.relative(routesDir, dir).split(path.sep).join('/');
-        yield { source, front, url, title: front.title, file, version: versionOf(dir) };
-    }
-    /**
-     * A page belongs to an archived version when its first directory segment under
-     * the content dir is that archive's id; everything else is the current
-     * version, which lives unprefixed at the docs root. No versions ⇒ undefined,
-     * which keeps an unversioned site's index byte-for-byte what it was.
-     */
-    function versionOf(dir) {
-        if (!versions)
-            return undefined;
-        const firstSegment = path.relative(contentDir, dir).split(path.sep)[0];
-        const archived = versions.archived?.find((v) => v.id === firstSegment);
-        return archived ? archived.id : versions.current.id;
-    }
+function stringField(front, key) {
+    return typeof front[key] === 'string' ? front[key] : undefined;
+}
+/** As {@link stringField}, for the numeric fields. */
+function numberField(front, key) {
+    return typeof front[key] === 'number' ? front[key] : undefined;
 }
 /**
- * Scan `contentDir` for `+page.md`/`+page.svx` files and read the frontmatter
- * fields the sidebar needs (plus the heading list for a server-rendered TOC and
- * an estimated reading time), deriving each page's URL from its directory
- * relative to `routesDir`. Pure and synchronous so it can be unit-tested.
+ * The sidebar's index: the frontmatter fields navigation needs, plus the heading
+ * list for a server-rendered TOC and an estimated reading time. Served as the
+ * eagerly-imported `svelte-docsmith/content` virtual module.
+ *
+ * `lastUpdated` is read off the page rather than looked up here, so pass pages
+ * that have been through `withCommitDates` or the column comes out blank.
  */
-export function collectDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir)) {
-        console.warn(`[svelte-docsmith] content directory not found: ${contentDir}\n` +
-            `  The sidebar will be empty. Create your doc pages there, or point docsmith() at the right place with \`content\`.`);
-        return [];
-    }
-    const items = [];
-    for (const { source, front, url, title, file, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        items.push({
-            title,
-            path: url,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            section: readSection(front.section),
-            order: typeof front.order === 'number' ? front.order : undefined,
-            sourcePath: path.relative(process.cwd(), file).split(path.sep).join('/'),
-            // Frontmatter wins over git so an archived page keeps the date it last
-            // really changed: archiving copies every page in one commit, which would
-            // otherwise stamp the whole archive with the day it was created.
-            lastUpdated: typeof front.lastUpdated === 'string' ? front.lastUpdated : lastCommitDate(file),
-            readingTime: readingMinutes(extractSearchText(source)),
-            toc: extractToc(source),
-            version
-        });
-    }
-    if (items.length === 0) {
-        console.warn(`[svelte-docsmith] no doc pages found under ${contentDir}\n` +
-            `  Add \`+page.md\` files with at least a \`title:\` in their frontmatter to populate the sidebar.`);
-    }
-    // Stable output keeps the generated module diff-friendly across rebuilds.
-    return items.sort((a, b) => a.path.localeCompare(b.path));
+export function contentIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        title: page.title,
+        path: page.url,
+        description: stringField(page.frontmatter, 'description'),
+        section: readSection(page.frontmatter.section),
+        order: numberField(page.frontmatter, 'order'),
+        sourcePath: path.relative(process.cwd(), page.file).split(path.sep).join('/'),
+        lastUpdated: page.lastUpdated,
+        readingTime: readingMinutes(extractSearchText(page.source)),
+        toc: extractToc(page.source),
+        version: page.version
+    }));
 }
 /**
- * Build the search records for every page under `contentDir`: title, section,
- * description, heading list, and plain-text body. Served as the lazy-loaded
- * `svelte-docsmith/search` virtual module so search can index bodies without
- * bloating the eagerly-imported nav index. The missing-directory case is
- * already reported by {@link collectDocs}, so this stays quiet.
+ * The search index: title, section, description, heading list, and plain-text
+ * body. Served as the lazy-loaded `svelte-docsmith/search` virtual module so
+ * search can index bodies without bloating the eagerly-imported content index.
  */
-export function collectSearchDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        docs.push({
-            path: url,
-            title,
-            section: sectionLabel(front.section),
-            description: typeof front.description === 'string' ? front.description : undefined,
-            headings: extractToc(source).map((entry) => entry.title),
-            text: extractSearchText(source),
-            version
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
+export function searchIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        path: page.url,
+        title: page.title,
+        section: sectionLabel(page.frontmatter.section),
+        description: stringField(page.frontmatter, 'description'),
+        headings: extractToc(page.source).map((entry) => entry.title),
+        text: extractSearchText(page.source),
+        version: page.version
+    }));
 }
 /**
- * Build the LLM records for every page: title, section, description, and the
- * full markdown content. Served as the `svelte-docsmith/llms` virtual module and
- * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
- * to the client.
+ * The LLM index: title, section, description, and the full markdown content.
+ * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
+ * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
  */
-export function collectLlmsDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        docs.push({
-            path: url,
-            title,
-            section: sectionKey(front.section),
-            order: typeof front.order === 'number' ? front.order : undefined,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            content: extractLlmsContent(source, title),
-            version
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
+export function llmsIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        path: page.url,
+        title: page.title,
+        section: sectionKey(page.frontmatter.section),
+        order: numberField(page.frontmatter, 'order'),
+        description: stringField(page.frontmatter, 'description'),
+        content: extractLlmsContent(page.source, page.title),
+        version: page.version
+    }));
 }

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

@@ -3,8 +3,6 @@ export type TocEntry = {
     title: string;
     depth: 2 | 3;
 };
-/** Strip inline markdown so a heading's TOC label is plain text. */
-export declare function stripInlineMarkdown(text: string): string;
 /**
  * Reduce a markdown page to plain, searchable body text: prose and heading text
  * with frontmatter, `<script>`/`<style>` blocks, fenced code, HTML/Svelte tags,

package/dist/buildtime/vite/extract.js

@@ -5,7 +5,7 @@ function withoutSetupBlocks(body) {
     return body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
 }
 /** Strip inline markdown so a heading's TOC label is plain text. */
-export function stripInlineMarkdown(text) {
+function stripInlineMarkdown(text) {
     return text
         .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
         .replace(/`([^`]+)`/g, '$1')

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

@@ -1,7 +1,5 @@
 import type { Plugin } from 'vite';
 import { type DocsVersions } from '../../core/version.js';
-export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
-export { collectReleases } from './releases.js';
 export interface DocsmithViteOptions {
     /** Directory scanned for doc pages. Default: `'src/routes/docs'`. */
     content?: string;

package/dist/buildtime/vite/index.js

@@ -13,18 +13,19 @@
  *  3. The **`?source` transform** powering `LiveExample`: importing
  *     `Component.svelte?source` yields that file's Shiki-highlighted source.
  *
- * The per-index scanning lives in `./collect.js`; this file owns the two Vite
- * plugins and re-exports the collectors for consumers and tests.
+ * Reading the docs root lives in `./pages.js` and building each index from what
+ * it read lives in `./collect.js`; this file owns the two Vite plugins, and is
+ * the only layer that reports to the console.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
-import { resolveVersions } from '../../core/version.js';
-import { isPageFile, listPageFiles } from './pages.js';
-import { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
+import { checkVersions, resolveVersions } from '../../core/version.js';
+import { ARCHIVE_MARKER, discoverArchives } from '../archives.js';
+import { docsBaseFrom } from '../paths.js';
+import { isPageFile, readSourcePages, withCommitDates } from './pages.js';
+import { contentIndex, llmsIndex, searchIndex } from './collect.js';
 import { collectReleases } from './releases.js';
-export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
-export { collectReleases } from './releases.js';
 /**
  * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:
  *
@@ -45,16 +46,30 @@ const LLMS_SPECIFIER = 'svelte-docsmith/llms';
 const VIRTUAL_LLMS_ID = '\0svelte-docsmith:llms';
 const CHANGELOG_SPECIFIER = 'svelte-docsmith/changelog';
 const VIRTUAL_CHANGELOG_ID = '\0svelte-docsmith:changelog';
+/**
+ * Tell the author when their docs root produced nothing, and why. An empty
+ * sidebar is otherwise silent: the build succeeds and the site renders, so
+ * without this the first sign of a misconfigured `content` is a missing nav.
+ */
+function warnAboutDocsRoot(contentDir, exists, indexed) {
+    if (!exists) {
+        console.warn(`[svelte-docsmith] content directory not found: ${contentDir}\n` +
+            `  The sidebar will be empty. Create your doc pages there, or point docsmith() at the right place with \`content\`.`);
+    }
+    else if (indexed === 0) {
+        console.warn(`[svelte-docsmith] no doc pages found under ${contentDir}\n` +
+            `  Add \`+page.md\` files with at least a \`title:\` in their frontmatter to populate the sidebar.`);
+    }
+}
 function contentIndexPlugin(options) {
     const contentDir = path.resolve(options.content ?? 'src/routes/docs');
     const routesDir = path.resolve(options.routes ?? 'src/routes');
     const versions = options.versions;
-    // The docs URL base, e.g. `/docs`, derived from the content dir's location
-    // under the routes dir — the same mapping `collect.ts` uses for page URLs.
-    const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+    const docsBase = docsBaseFrom(routesDir, contentDir);
     const changelogFile = options.changelog === false ? undefined : path.resolve(options.changelog ?? 'CHANGELOG.md');
     const changelogRoute = options.changelogPath ?? '/changelog';
-    const changelogOverrides = path.join(routesDir, changelogRoute.replace(/^\//, ''));
+    const changelogOverrides = path.join(routesDir, changelogRoute);
+    const indexOptions = { contentDir, routesDir, versions };
     return {
         name: 'docsmith-content',
         enforce: 'pre',
@@ -73,25 +88,34 @@ function contentIndexPlugin(options) {
             // body re-runs this load. A directory here is treated as an
             // unresolvable import by vite:import-analysis; new/removed pages are
             // handled by the watcher in configureServer.
+            const watch = (pages) => {
+                for (const page of pages)
+                    this.addWatchFile(page.file);
+            };
             if (id === VIRTUAL_CONTENT_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectDocs(contentDir, routesDir, versions);
+                // Before anything is read: a config that disagrees with the docs root
+                // produces an index that is wrong rather than empty, so it has to fail
+                // here rather than render. Re-runs on invalidation, so archiving during
+                // `dev` reports immediately.
+                checkVersions(versions, discoverArchives(contentDir), ARCHIVE_MARKER);
+                const { pages, exists } = readSourcePages(contentDir);
+                watch(pages);
+                // Only this index has a date field, so only this one pays for git.
+                const docs = contentIndex(withCommitDates(pages), indexOptions);
+                warnAboutDocsRoot(contentDir, exists, docs.length);
                 const resolved = resolveVersions(versions, docsBase, docs);
                 return (`export const docs = ${JSON.stringify(docs, null, 2)};\n` +
                     `export const versions = ${JSON.stringify(resolved, null, 2)};\n`);
             }
             if (id === VIRTUAL_SEARCH_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectSearchDocs(contentDir, routesDir, versions);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
+                const { pages } = readSourcePages(contentDir);
+                watch(pages);
+                return `export const docs = ${JSON.stringify(searchIndex(pages, indexOptions))};\n`;
             }
             if (id === VIRTUAL_LLMS_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectLlmsDocs(contentDir, routesDir, versions);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
+                const { pages } = readSourcePages(contentDir);
+                watch(pages);
+                return `export const docs = ${JSON.stringify(llmsIndex(pages, indexOptions))};\n`;
             }
             if (id === VIRTUAL_CHANGELOG_ID) {
                 if (!changelogFile)

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

@@ -1,5 +1,56 @@
+/**
+ * One doc page as authored on disk, before any index-specific derivation. Its
+ * URL, version, headings and search text are all derived from these fields, so
+ * everything downstream of the read is pure.
+ */
+export type SourcePage = {
+    /** Absolute path to the page file. */
+    file: string;
+    /** The page's raw markdown, frontmatter included. */
+    source: string;
+    /** The page's parsed frontmatter, `{}` when it has none. */
+    frontmatter: Record<string, unknown>;
+    /**
+     * The day (`YYYY-MM-DD`) the page last changed. Only {@link withCommitDates}
+     * fills this in, so it is absent on a page list that never went through it.
+     */
+    lastUpdated?: string;
+};
 /** Whether a filename is a doc page the plugin should index. */
 export declare function isPageFile(file: string): boolean;
+/**
+ * Turn a page's path and raw markdown into a {@link SourcePage}. Pure, and
+ * shared with tests so an in-memory page is built exactly the way a read one is.
+ */
+export declare function toPage(file: string, source: string): SourcePage;
+/**
+ * Read every doc page under `contentDir`. `exists` distinguishes a missing docs
+ * root from an empty one, which the page list alone cannot: both give no pages,
+ * but only one of them is a misconfiguration worth reporting.
+ */
+export declare function readSourcePages(contentDir: string): {
+    pages: SourcePage[];
+    exists: boolean;
+};
+/**
+ * A page's title, when it has one. A page whose frontmatter has no string
+ * `title` is a stub: no index carries it, so nothing is derived for it and
+ * nothing is looked up about it.
+ */
+export declare function titleOf(page: SourcePage): string | undefined;
+/**
+ * Date each page from the commit that last touched it, skipping the lookup for
+ * pages that carry their own `lastUpdated`. Archiving copies every page in one
+ * commit, so an archive's pages are written with the date they last really
+ * changed and must keep it.
+ *
+ * Deliberately a second pass rather than part of {@link readSourcePages}: it
+ * spawns a git process per page, and only the content index has a date field.
+ * Folding it into the read would make the search and llms indexes pay for a
+ * value neither of them has anywhere to put. For the same reason it skips
+ * untitled pages, which no index carries.
+ */
+export declare function withCommitDates(pages: SourcePage[]): SourcePage[];
 /**
  * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
  */

package/dist/buildtime/vite/pages.js

@@ -1,10 +1,68 @@
+/**
+ * The docs root, and what a page is before any index has looked at it. Reading
+ * stops at a {@link SourcePage} list, which is the only value the index builders
+ * in `./collect.js` see — so the same builders run against a real docs root in
+ * the plugin and against an array of literals in tests.
+ */
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { lastCommitDate } from '../git.js';
 const PAGE_NAMES = ['+page.md', '+page.svx'];
 /** Whether a filename is a doc page the plugin should index. */
 export function isPageFile(file) {
     return PAGE_NAMES.some((name) => file.endsWith(name));
 }
+/**
+ * Turn a page's path and raw markdown into a {@link SourcePage}. Pure, and
+ * shared with tests so an in-memory page is built exactly the way a read one is.
+ */
+export function toPage(file, source) {
+    return { file, source, frontmatter: parseFrontmatter(source, file) };
+}
+/**
+ * Read every doc page under `contentDir`. `exists` distinguishes a missing docs
+ * root from an empty one, which the page list alone cannot: both give no pages,
+ * but only one of them is a misconfiguration worth reporting.
+ */
+export function readSourcePages(contentDir) {
+    if (!fs.existsSync(contentDir))
+        return { pages: [], exists: false };
+    const pages = listPageFiles(contentDir).map((file) => toPage(file, fs.readFileSync(file, 'utf-8')));
+    return { pages, exists: true };
+}
+/**
+ * A page's title, when it has one. A page whose frontmatter has no string
+ * `title` is a stub: no index carries it, so nothing is derived for it and
+ * nothing is looked up about it.
+ */
+export function titleOf(page) {
+    return typeof page.frontmatter.title === 'string' ? page.frontmatter.title : undefined;
+}
+/**
+ * Date each page from the commit that last touched it, skipping the lookup for
+ * pages that carry their own `lastUpdated`. Archiving copies every page in one
+ * commit, so an archive's pages are written with the date they last really
+ * changed and must keep it.
+ *
+ * Deliberately a second pass rather than part of {@link readSourcePages}: it
+ * spawns a git process per page, and only the content index has a date field.
+ * Folding it into the read would make the search and llms indexes pay for a
+ * value neither of them has anywhere to put. For the same reason it skips
+ * untitled pages, which no index carries.
+ */
+export function withCommitDates(pages) {
+    return pages.map((page) => {
+        if (titleOf(page) === undefined)
+            return page;
+        return {
+            ...page,
+            lastUpdated: typeof page.frontmatter.lastUpdated === 'string'
+                ? page.frontmatter.lastUpdated
+                : lastCommitDate(page.file)
+        };
+    });
+}
 /**
  * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
  */

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

@@ -8,5 +8,3 @@ import type { ChangelogRelease } from '../../core/changelog.js';
  * have one while the rest stay generated.
  */
 export declare function collectReleases(changelogFile: string, overridesDir?: string, routePath?: string): ChangelogRelease[];
-/** Default location of a monorepo package's changelog, relative to the app. */
-export declare function defaultChangelogPath(cwd?: string): string;

package/dist/buildtime/vite/releases.js

@@ -1,8 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { marked } from 'marked';
 import { parseChangelog } from '../changelog.js';
-import { changelogDates } from './git.js';
+import { changelogDates } from '../git.js';
 /**
  * Render an entry's markdown to HTML at build time. Changesets entries use
  * inline code, emphasis, links and nested lists, so shipping the raw markdown
@@ -51,7 +50,3 @@ export function collectReleases(changelogFile, overridesDir, routePath = '/chang
         };
     });
 }
-/** Default location of a monorepo package's changelog, relative to the app. */
-export function defaultChangelogPath(cwd = process.cwd()) {
-    return path.resolve(cwd, 'CHANGELOG.md');
-}

package/dist/components/changelog/changelog-entry.svelte

@@ -3,12 +3,17 @@
 
 	const { release }: { release: ChangelogRelease } = $props();
 
+	// `timeZone: 'UTC'` is not cosmetic. `release.date` is a calendar day, which
+	// parses to UTC midnight, so formatting in the ambient zone shifts it a day
+	// west of UTC — and shifts it on the client but not on the server, so the
+	// rendered date changes under hydration.
 	const formatted = $derived(
 		release.date
 			? new Date(release.date).toLocaleDateString('en-US', {
 					year: 'numeric',
 					month: 'long',
-					day: 'numeric'
+					day: 'numeric',
+					timeZone: 'UTC'
 				})
 			: undefined
 	);

package/dist/components/chrome/search.svelte

@@ -2,6 +2,7 @@
 	import { goto } from '$app/navigation';
 	import * as Command from '../shadcn/command/index.js';
 	import { useSearch } from '../../search/context.svelte.js';
+	import { useDocsPage } from '../docs-page-context.js';
 	import type { SearchDoc } from '../../core/index.js';
 	import type { SearchEngine } from '../../search/create-search.js';
 	import CornerDownLeft from '@lucide/svelte/icons/corner-down-left';
@@ -26,6 +27,10 @@
 	} = $props();
 
 	const search = useSearch();
+	// The version being read, straight off the shell's resolved page view, so
+	// results and the cached engine follow the reader across a version switch.
+	const docsPage = useDocsPage();
+	const activeVersion = $derived(docsPage.view.activeVersionId);
 
 	let query = $state('');
 	let engine = $state<SearchEngine | null>(null);
@@ -36,14 +41,12 @@
 	let engineVersion: string | undefined;
 
 	const trimmed = $derived(query.trim());
-	// Scope to the active version when the shell set one (versioned sites).
-	const results = $derived(
-		engine && trimmed ? engine.search(query, undefined, search?.version) : []
-	);
+	// Scope to the active version on a versioned site; `undefined` otherwise.
+	const results = $derived(engine && trimmed ? engine.search(query, undefined, activeVersion) : []);
 
 	// Build the index the first time the palette opens; keep it for later opens.
 	async function ensureEngine() {
-		const version = search?.version;
+		const version = activeVersion;
 		if ((engine && engineVersion === version) || status === 'loading') return;
 		status = 'loading';
 		try {

package/dist/components/chrome/version-banner.svelte

@@ -1,12 +1,7 @@
 <script lang="ts">
 	import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
 	import ArrowRight from '@lucide/svelte/icons/arrow-right';
-	import {
-		mapPathToVersion,
-		scopeContent,
-		type ResolvedVersion,
-		type DocsContentItem
-	} from '../../core/index.js';
+	import type { ResolvedVersion } from '../../core/index.js';
 
 	// Rendered by DocsShell only on an archived version, to warn a reader who
 	// landed there (usually from a search engine) and give them a one-click path
@@ -15,23 +10,13 @@
 	const {
 		active,
 		current,
-		pathname,
-		content
+		href
 	}: {
 		active: ResolvedVersion;
 		current: ResolvedVersion;
-		pathname: string;
-		content: DocsContentItem[];
+		/** This page under the current version, from the resolved page view. */
+		href: string;
 	} = $props();
-
-	const currentHref = $derived(
-		mapPathToVersion(
-			pathname,
-			active,
-			current,
-			scopeContent(content, current.id).map((c) => c.path)
-		)
-	);
 </script>
 
 <div class="docsmith-version-banner" role="note">
@@ -39,7 +24,7 @@
 	<p>
 		You're reading the <strong>{active.label}</strong> docs. The current version is
 		<strong>{current.label}</strong>.
-		<a href={currentHref}>View this page in {current.label} <ArrowRight size={14} /></a>
+		<a {href}>View this page in {current.label} <ArrowRight size={14} /></a>
 	</p>
 </div>
 

package/dist/components/chrome/version-banner.svelte.d.ts

@@ -1,9 +1,9 @@
-import { type ResolvedVersion, type DocsContentItem } from '../../core/index.js';
+import type { ResolvedVersion } from '../../core/index.js';
 type $$ComponentProps = {
     active: ResolvedVersion;
     current: ResolvedVersion;
-    pathname: string;
-    content: DocsContentItem[];
+    /** This page under the current version, from the resolved page view. */
+    href: string;
 };
 declare const VersionBanner: import("svelte").Component<$$ComponentProps, {}, "">;
 type VersionBanner = ReturnType<typeof VersionBanner>;