poveste 0.19.0 → 0.20.0

package/README.md

@@ -16,17 +16,17 @@ panel.
 Install `poveste` alongside the plugin for your framework:
 
 ```shell
-pnpm i -D poveste @poveste/plugin-vue      # Vue 3
-pnpm i -D poveste @poveste/plugin-svelte   # Svelte 5 and SvelteKit
-pnpm i -D poveste @poveste/plugin-nuxt     # Nuxt 4
-pnpm i -D poveste @poveste/plugin-quasar   # Quasar
-pnpm i -D poveste @poveste/plugin-solid    # Solid, renderer only
-pnpm i -D poveste @poveste/plugin-react    # React 19, renderer only
+pnpm i -D poveste @poveste/plugin-vue                          # Vue 3
+pnpm i -D poveste @poveste/plugin-svelte                       # Svelte 5 and SvelteKit
+pnpm i -D poveste @poveste/plugin-vue @poveste/plugin-nuxt     # Nuxt 4
+pnpm i -D poveste @poveste/plugin-vue @poveste/plugin-quasar   # Quasar
+pnpm i -D poveste @poveste/plugin-solid                        # Solid, renderer only
+pnpm i -D poveste @poveste/plugin-react                        # React 19, renderer only
 ```
 
 > **Installed an older version than you expected?** For about a day after a release, pnpm installs the previous one with no error and no hint, and for a plugin that's new in that release, its empty `0.0.1` placeholder. That's pnpm's release-age cooldown, not a broken publish. `package.json` keeps the old `^x.y.z`, so waiting doesn't fix it: install again with `npm`, with `--config.minimum-release-age=0` (kebab-case: pnpm 12.4 ignores the camelCase spelling), or with exact versions.
 
-Then create a `poveste.config.ts` in your project root:
+Then create a `poveste.config.ts` in your project root. For a Vue project it is this:
 
 ```ts
 import { HstVue } from '@poveste/plugin-vue'
@@ -39,6 +39,8 @@ export default defineConfig({
 })
 ```
 
+Every other framework uses its own plugin, and Quasar also needs a setup file, so take the config from its guide: [Svelte](https://poveste.dev/guide/svelte/getting-started), [SvelteKit](https://poveste.dev/guide/sveltekit/getting-started), [Nuxt](https://poveste.dev/guide/nuxt/getting-started), [Quasar](https://poveste.dev/guide/quasar/getting-started), [Solid](https://poveste.dev/guide/solid/getting-started) or [React](https://poveste.dev/guide/react/getting-started).
+
 ## Commands
 
 | | |

package/dist/node/build.js

@@ -8,13 +8,14 @@ import { APP_PATH } from './alias.js';
 import { buildCounts, buildSummary, builtSomething, storyGuideUrl } from './build-counts.js';
 import { getSerializedStoryData } from './build-serialize.js';
 import { useCollectStories } from './collect/index.js';
+import { extractComponentDocs } from './docgen/build.js';
 import { useModuleLoader } from './load.js';
 import { createMarkdownFilesWatcher } from './markdown.js';
 import { BuildPluginApi } from './plugin.js';
 import { startPreview } from './preview.js';
 import { findAllStories } from './stories.js';
 import { chromeCssScopePlugin, entryCssMergerPlugin, userCssScopePlugin, } from './style-isolation/index.js';
-import { applyHeadTransform } from './util/head.js';
+import { applyHeadTransform, defaultDescription } from './util/head.js';
 import { wrapLogError } from './util/log.js';
 import { viteMode } from './util/vite-mode.js';
 import { getViteConfigWithPlugins } from './vite.js';
@@ -38,6 +39,12 @@ const APP_ONLY_VENDORS = [
     /[\\/]node_modules[\\/]shiki[\\/]/,
     /[\\/]node_modules[\\/]@shikijs[\\/]/,
 ];
+// Left to the bundler wherever they are installed, rather than sent to `vendor`.
+// `@poveste/controls` loads three controls lazily, and in a book installed from
+// npm `vendor` took them in, so every reader downloaded them before anything
+// rendered. The workspace book never showed it: linked source has no
+// `node_modules` in its path (#1343).
+const LEFT_TO_BUNDLER = ['@poveste/app', '@poveste/controls'];
 const PREFETCHED_MODULES = [
     'StoryView',
     'reactivity',
@@ -117,6 +124,7 @@ export async function build(ctx) {
             // Same wrapper the dev path uses for these exact calls (server.ts).
             await wrapLogError('destroyCollectStories', () => destroyCollectStories());
         }
+        ctx.componentDocs = await extractComponentDocs(ctx, server.moduleGraph);
         const counts = buildCounts(ctx.storyFiles);
         const { viteConfig: buildViteConfigRaw } = await getViteConfigWithPlugins(false, ctx);
         const buildViteConfig = mergeViteConfig(buildViteConfigRaw, {
@@ -198,7 +206,7 @@ export async function build(ctx) {
                         if (id.replace(/^\0/, '').startsWith('vite/')) {
                             return 'app-runtime';
                         }
-                        if (!id.includes('@poveste/app') && id.includes('node_modules')) {
+                        if (!LEFT_TO_BUNDLER.some(name => id.includes(name)) && id.includes('node_modules')) {
                             if (APP_ONLY_VENDORS.some(test => test.test(id))) {
                                 return 'highlighter';
                             }
@@ -271,13 +279,19 @@ export async function build(ctx) {
         let indexHtml = generateEntryHtml(indexOutput.fileName, mainStyleOutput.fileName, {
             HEAD: `${preloadHtml}${prefetchHtml}`,
         }, ctx);
-        indexHtml = await applyHeadTransform(indexHtml, ctx.config.head);
+        indexHtml = await applyHeadTransform(indexHtml, ctx.config.head, defaultDescription(ctx.config.theme.title ?? 'Poveste'));
         await writeFile('index.html', indexHtml, ctx);
         // Sandbox
         let sandboxHtml = generateEntryHtml(sandboxOutput.fileName, sandboxStyleOutput.fileName, {}, ctx);
         sandboxHtml = await applyHeadTransform(sandboxHtml, ctx.config.head);
         await writeFile('__sandbox.html', sandboxHtml, ctx);
         await writeFile('poveste.json', JSON.stringify(getSerializedStoryData(ctx), null, 2), ctx);
+        // A host's SPA fallback answers a missing /robots.txt with index.html, which a
+        // crawler reads as a malformed robots file rather than as none (#316). One in
+        // the public directory is the book's own, and was copied here already.
+        if (!await fs.pathExists(join(ctx.config.outDir, 'robots.txt'))) {
+            await writeFile('robots.txt', 'User-agent: *\nAllow: /\n', ctx);
+        }
         const duration = performance.now() - startTime;
         const { empty } = counts;
         if (empty.length) {

package/dist/node/collect/index.js

@@ -5,6 +5,7 @@ import { TEMP_PATH } from '../alias.js';
 import { createPath } from '../tree.js';
 import { escapeRegExp } from '../util/escape-regexp.js';
 import { slash } from '../util/fs.js';
+import { NOOP_ID, SETUP_ID } from '../virtual/index.js';
 import { globalsFromDefine } from './define-globals.js';
 import { strayLayoutKeys } from './layout-keys.js';
 import { createModuleServer } from './module-server.js';
@@ -41,7 +42,16 @@ export function useCollectStories(options, ctx) {
         threads: threadsCount,
         invoke: (name, data) => node.invoke(name, data),
     });
+    // Resolved once: a change to the config restarts the server.
+    let setupFile;
+    function resolveSetupFile() {
+        return setupFile ??= server.pluginContainer.resolveId(SETUP_ID, undefined, { ssr: true })
+            .then(resolved => resolved && resolved.id !== NOOP_ID ? resolved.id : undefined);
+    }
+    // Every story the setup file reaches fails with it, so it is reported once a pass.
+    let setupFailureReported = false;
     function clearCache() {
+        setupFailureReported = false;
         server.moduleGraph.invalidateAll();
         node.clearCache();
         // Both of those make every module read again, and a worker told nothing would
@@ -66,6 +76,7 @@ export function useCollectStories(options, ctx) {
                 base: server.config.base,
                 storyFile,
                 defineGlobals,
+                setupFile: await resolveSetupFile(),
             };
             const { storyData } = await threadPool.run(payload);
             const finalData = storyData[0];
@@ -101,12 +112,20 @@ export function useCollectStories(options, ctx) {
         catch (e) {
             // Work `destroy` cut short fails with whatever the pool or a closing server
             // throws. That is the shutdown, not the story, so it is not reported (#878).
-            if (destroying && !options.throws) {
+            // A build destroys only once a story has failed, which already threw.
+            if (destroying) {
                 return;
             }
             // A Vite transform error carries the code frame on `frame`.
             const error = (e instanceof Error ? e : new Error(String(e)));
-            console.error(pc.red(`Error while collecting story ${storyFile.path}:\n${error.frame ? `${pc.bold(error.message)}\n${error.frame}` : error.stack}`));
+            const detail = error.frame ? `${pc.bold(error.message)}\n${error.frame}` : error.stack;
+            if (!error.setupFile) {
+                console.error(pc.red(`Error while collecting story ${storyFile.path}:\n${detail}`));
+            }
+            else if (!setupFailureReported) {
+                setupFailureReported = true;
+                console.error(pc.red(`Error while loading the setup file ${error.setupFile}, so no story that needs it was collected:\n${detail}`));
+            }
             if (options.throws) {
                 throw e;
             }

package/dist/node/collect/module-server.js

@@ -152,6 +152,13 @@ export function createModuleServer(server, options) {
         ? true
         : [...options.inline, ...(Array.isArray(noExternal) ? noExternal : noExternal ? [noExternal] : [])];
     const externalizeCache = new Map();
+    // Each entry keeps the module's invalidation time it was transformed under, in
+    // Vite's clock rather than `Date.now()`. That clock adds a millisecond for every
+    // call within one, so a burst of transforms runs it ahead of the wall clock, and
+    // `invalidateAll` then stamps every module seconds in the future. Against
+    // `Date.now()` the whole cache read as stale until real time caught up, each
+    // re-transform pushed the clock further ahead, and one reload re-collected a
+    // large book a hundred times over (#1352).
     const fetchCache = new Map();
     function getTransformMode(id) {
         const path = cleanUrl(id);
@@ -227,12 +234,11 @@ export function createModuleServer(server, options) {
         const moduleNode = server.moduleGraph.getModuleById(id) ?? [...server.moduleGraph.getModulesByFile(path) ?? []][0];
         const invalidatedAt = moduleNode ? Math.max(moduleNode.lastHMRTimestamp, moduleNode.lastInvalidationTimestamp) : 0;
         const cached = fetchCache.get(path);
-        if (cached && (invalidatedAt === 0 || cached.timestamp >= invalidatedAt)) {
+        if (cached && invalidatedAt <= cached.invalidatedAt) {
             // Unchanged since the runner last read it: it keeps what it has. A runner
             // that never had it gets the code, with nothing of its own to invalidate.
             return cachedByRunner ? { cache: true } : { ...cached.result, invalidate: false };
         }
-        const timestamp = Date.now();
         const result = await transform(id, getTransformMode(id));
         if (!result) {
             throw new Error(`[poveste] could not transform ${id}${importer ? `, imported from ${importer}` : ''}`);
@@ -244,7 +250,7 @@ export function createModuleServer(server, options) {
             url: id,
             invalidate: true,
         };
-        fetchCache.set(path, { timestamp, result: fetched });
+        fetchCache.set(path, { invalidatedAt, result: fetched });
         return fetched;
     }
     /** The two calls a `ModuleRunner` makes, as its transport's `invoke` carries them. */

package/dist/node/collect/runner.d.ts

@@ -30,5 +30,12 @@ export type Invoke = (name: string, data: unknown[]) => Promise<unknown>;
  * that branch, and no id or file in either book carried the prefix.
  */
 export declare function filenameOf(module: Readonly<EvaluatedModuleNode>, root: string): string;
+/**
+ * The keys an externalised module added to `globalThis` when Node ran it. Node
+ * caches that module, so once a worker's reset deletes them nothing installs them
+ * again. Vue's development build sets `__VUE_HMR_RUNTIME__` this way, and a story
+ * compiled with HMR code reads it at its top level (#1320).
+ */
+export declare const globalsFromExternals: Set<string>;
 /** A runner over a module server, reached through `invoke`. `root` is the Vite root. */
 export declare function createRunner(invoke: Invoke, root: string, evaluatedModules?: EvaluatedModules): ModuleRunner;

package/dist/node/collect/runner.js

@@ -67,6 +67,25 @@ export function filenameOf(module, root) {
     }
     return join(root, 'virtual-module');
 }
+/**
+ * The keys an externalised module added to `globalThis` when Node ran it. Node
+ * caches that module, so once a worker's reset deletes them nothing installs them
+ * again. Vue's development build sets `__VUE_HMR_RUNTIME__` this way, and a story
+ * compiled with HMR code reads it at its top level (#1320).
+ */
+export const globalsFromExternals = new Set();
+const ranExternals = new Set();
+async function importRecordingGlobals(file) {
+    const before = new Set(Object.keys(globalThis));
+    const imported = await import(file);
+    ranExternals.add(file);
+    for (const key of Object.keys(globalThis)) {
+        if (!before.has(key)) {
+            globalsFromExternals.add(key);
+        }
+    }
+    return imported;
+}
 /** As vite-node did: a CJS package's named exports are read through its default. */
 class InteropEvaluator {
     root;
@@ -130,7 +149,7 @@ class InteropEvaluator {
         await run(context[ssrModuleExportsKey], context[ssrImportMetaKey], context[ssrImportKey], context[ssrDynamicImportKey], context[ssrExportAllKey], context[ssrExportNameKey], createRequire(filename), cjsExports, moduleProxy, filename, dirname(filename));
     }
     async runExternalModule(file) {
-        const imported = await import(file);
+        const imported = ranExternals.has(file) ? await import(file) : await importRecordingGlobals(file);
         if (file.endsWith('.mjs') || !('default' in imported)) {
             return imported;
         }

package/dist/node/collect/types.d.ts

@@ -4,6 +4,8 @@ export interface Payload {
     base: string;
     storyFile: ServerStoryFile;
     defineGlobals?: Record<string, unknown>;
+    /** The book's setup file as the collect server resolved it, when it has one. */
+    setupFile?: string | undefined;
 }
 export interface ReturnData {
     storyData: ServerStory[];

package/dist/node/collect/worker.js

@@ -6,7 +6,7 @@ import pc from 'picocolors';
 import { EvaluatedModules } from 'vite/module-runner';
 import { createDomEnv, resetDomEnv } from '../dom/env.js';
 import { invokeOver } from './rpc.js';
-import { createRunner } from './runner.js';
+import { createRunner, globalsFromExternals } from './runner.js';
 import { serveTasks } from './task.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _evaluatedModules = new EvaluatedModules();
@@ -41,6 +41,22 @@ function invalidateAll() {
         _evaluatedModules.invalidateModule(node);
     }
 }
+// A framework's collect module imports the setup file, so a setup file that fails
+// to load fails every story with an error that names neither of them (#1324). The
+// runner keeps a module that failed as its rejected promise, which is how it is told
+// apart from a story that failed on its own. Matched on the fetched file, because
+// the module's id is however its importer wrote it, root-relative inside the root.
+async function blameSetupFile(error, setupFile) {
+    const nodes = setupFile
+        ? [..._evaluatedModules.idToModuleMap.values()].filter(node => node.meta && 'file' in node.meta && node.meta.file === setupFile)
+        : [];
+    const failed = await Promise.all(nodes.map(node => node.promise?.then(() => false, () => true)));
+    if (!failed.includes(true)) {
+        return error;
+    }
+    const blamed = typeof error === 'object' && error !== null ? error : new Error(String(error));
+    return Object.assign(blamed, { setupFile });
+}
 if (!parentPort) {
     throw new Error('[poveste] the collection worker was started outside a worker thread');
 }
@@ -63,7 +79,7 @@ async function collect(payload) {
     // belongs to one server, so every task it is sent carries that server's root.
     const runner = _runner ?? (_runner = createRunner((name, data) => _invoke(name, data), payload.root, _evaluatedModules));
     if (_domEnv) {
-        resetDomEnv(_domEnv);
+        resetDomEnv(_domEnv, globalsFromExternals);
     }
     else {
         _domEnv = createDomEnv();
@@ -73,11 +89,16 @@ async function collect(payload) {
     const { run } = (await runner.import(resolve(__dirname, './run.js')));
     const afterExecuteTime = performance.now();
     const storyData = [];
-    await run({
-        file: payload.storyFile,
-        storyData,
-        el,
-    });
+    try {
+        await run({
+            file: payload.storyFile,
+            storyData,
+            el,
+        });
+    }
+    catch (error) {
+        throw await blameSetupFile(error, payload.setupFile);
+    }
     const afterRunTime = performance.now();
     if (payload.storyFile.markdownFile) {
         const el = document.createElement('div');

package/dist/node/config-validation.js

@@ -7,6 +7,9 @@ const RULES = [
     { path: 'setupCode', kind: 'string[]' },
     { path: 'globalStyles', kind: 'string[]' },
     { path: 'isolateStyles', kind: 'boolean' },
+    { path: 'autoDocs', kind: ['boolean', 'object'] },
+    { path: 'autoDocs.allow', kind: 'string[]' },
+    { path: 'autoDocs.exclude', kind: 'string[]' },
     { path: 'autoApplyContrastColor', kind: 'boolean' },
     { path: 'defaultBackgroundColor', kind: 'string' },
     { path: 'sandboxDarkClass', kind: 'string' },

package/dist/node/context.d.ts

@@ -1,5 +1,6 @@
 import type { ConfigMode, FinalSupportPlugin, PluginCommand, PovesteConfig, ServerMarkdownFile, ServerStoryFile } from '@poveste/shared';
 import type { ResolvedConfig } from 'vite';
+import type { StoryDocsResult } from './docgen/protocol.js';
 export interface Context {
     root: string;
     config: PovesteConfig;
@@ -9,6 +10,8 @@ export interface Context {
     supportPlugins: FinalSupportPlugin[];
     markdownFiles: ServerMarkdownFile[];
     registeredCommands: PluginCommand[];
+    /** What `poveste build` extracted for auto-docs, by story id (#1159). */
+    componentDocs?: Record<string, StoryDocsResult['components']>;
 }
 export interface CreateContextOptions {
     mode: Context['mode'];

package/dist/node/docgen/build.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleGraph } from 'vite';
+import type { Context } from '../context.js';
+import type { StoryDocsResult } from './protocol.js';
+/**
+ * The build's pass (#1159): with no reader to wait for, every story's named
+ * components are extracted once, after collection, into what the book ships.
+ */
+export declare function extractComponentDocs(ctx: Context, moduleGraph: ModuleGraph): Promise<Record<string, StoryDocsResult['components']>>;

package/dist/node/docgen/build.js

@@ -0,0 +1,49 @@
+import { componentsOfStory } from './components-of.js';
+import { createDocgenService } from './service.js';
+/**
+ * The build's pass (#1159): with no reader to wait for, every story's named
+ * components are extracted once, after collection, into what the book ships.
+ */
+export async function extractComponentDocs(ctx, moduleGraph) {
+    const docgen = createDocgenService({
+        root: ctx.root,
+        plugins: ctx.config.plugins,
+        enabled: ctx.config.autoDocs !== false,
+        bookOptions: typeof ctx.config.autoDocs === 'object' ? ctx.config.autoDocs : undefined,
+        collected: Promise.resolve(),
+        componentsOf: storyId => componentsOfStory(ctx.storyFiles, moduleGraph, storyId),
+    });
+    if (!docgen.enabled) {
+        return {};
+    }
+    const docs = {};
+    const failed = new Map();
+    try {
+        for (const storyFile of ctx.storyFiles) {
+            const storyId = storyFile.story?.id;
+            if (!storyId) {
+                continue;
+            }
+            const { components } = await docgen.request(storyId);
+            // A built book is published, so an extractor's error stays on the build
+            // machine: the component keeps its runtime props, as with auto-docs off (#1382).
+            const read = Object.entries(components).filter(([file, result]) => {
+                if (!result.doc) {
+                    failed.set(file, result.error);
+                }
+                return result.doc;
+            });
+            if (read.length) {
+                docs[storyId] = Object.fromEntries(read);
+            }
+        }
+    }
+    finally {
+        await docgen.dispose();
+    }
+    if (failed.size) {
+        const [file, error] = [...failed][0];
+        console.warn(`[poveste] auto-docs could not read ${failed.size} component${failed.size === 1 ? '' : 's'}, which show their runtime props instead. The first, ${file}: ${error}`);
+    }
+    return docs;
+}

package/dist/node/docgen/components-of.d.ts

@@ -0,0 +1,7 @@
+import type { ServerStoryFile } from '@poveste/shared';
+import type { ModuleGraph } from 'vite';
+/**
+ * The files a story's own module imports, as collection resolved them: the
+ * components that story names. Other story files are left out.
+ */
+export declare function componentsOfStory(storyFiles: ServerStoryFile[], moduleGraph: ModuleGraph, storyId: string): string[];

package/dist/node/docgen/components-of.js

@@ -0,0 +1,17 @@
+/**
+ * The files a story's own module imports, as collection resolved them: the
+ * components that story names. Other story files are left out.
+ */
+export function componentsOfStory(storyFiles, moduleGraph, storyId) {
+    const storyFile = storyFiles.find(file => file.story?.id === storyId);
+    const storyPaths = new Set(storyFiles.map(file => file.path));
+    const files = new Set();
+    for (const mod of moduleGraph.getModulesByFile(storyFile?.path ?? '') ?? []) {
+        for (const imported of mod.importedModules) {
+            if (imported.file && !storyPaths.has(imported.file)) {
+                files.add(imported.file);
+            }
+        }
+    }
+    return [...files];
+}

package/dist/node/docgen/engine.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentDoc, DocgenExtractorModule } from '@poveste/shared';
+export interface EngineExtractorSpec {
+    /** The plugin's name, which keys its extractor. */
+    name: string;
+    module: string;
+    options?: unknown;
+}
+export type ExtractResult = {
+    doc: ComponentDoc;
+} | {
+    doc?: undefined;
+    error: string;
+};
+export interface DocgenEngineOptions {
+    root: string;
+    extractors: EngineExtractorSpec[];
+    /**
+     * Dispose every extractor once the heap passes this share of its limit, and
+     * build afresh on the next request. Storybook recycles at 0.7, and laziness
+     * alone did not cap its memory (storybookjs/storybook#35260).
+     */
+    heapRatio?: number;
+    heapLimit?: number;
+    heapUsed?: () => number;
+    load?: (module: string) => Promise<DocgenExtractorModule>;
+}
+/**
+ * What a reader is shown of an extractor's failure: its first line, with the
+ * book's root made relative and any other absolute path cut to its file name.
+ * Node's `MODULE_NOT_FOUND` message carries a require stack of absolute paths,
+ * which a built book published under every component (#1382).
+ */
+export declare function describeError(error: unknown, root: string): string;
+/** The extraction loop that runs inside the docgen worker, kept free of the thread. */
+/** `import()` takes a URL, and an absolute Windows path is not one: `D:` reads as its scheme. */
+export declare function importable(module: string): string;
+export declare function createDocgenEngine(options: DocgenEngineOptions): {
+    stats: {
+        created: number;
+        recycled: number;
+    };
+    extract(requests: {
+        name: string;
+        file: string;
+    }[]): Promise<Record<string, ExtractResult>>;
+    /** Every live extractor's sources, for the dev server to watch. */
+    sources(): Promise<string[]>;
+    update(file: string): Promise<void>;
+    dispose: () => Promise<void>;
+};

package/dist/node/docgen/engine.js

@@ -0,0 +1,90 @@
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getHeapStatistics } from 'node:v8';
+// An absolute path, POSIX or Windows, of two segments or more; its last segment is kept.
+const ABSOLUTE_PATH = /(?:(?<![\w.])\/|\b[A-Z]:[\\/])(?:[^\s'"`/\\]+[\\/])+([^\s'"`/\\]+)/gi;
+/**
+ * What a reader is shown of an extractor's failure: its first line, with the
+ * book's root made relative and any other absolute path cut to its file name.
+ * Node's `MODULE_NOT_FOUND` message carries a require stack of absolute paths,
+ * which a built book published under every component (#1382).
+ */
+export function describeError(error, root) {
+    const firstLine = (error instanceof Error ? error.message : String(error)).split('\n')[0].trim();
+    return firstLine.replaceAll(`${root}/`, '').replaceAll(root, '.').replace(ABSOLUTE_PATH, '$1');
+}
+/** The extraction loop that runs inside the docgen worker, kept free of the thread. */
+/** `import()` takes a URL, and an absolute Windows path is not one: `D:` reads as its scheme. */
+export function importable(module) {
+    return isAbsolute(module) ? pathToFileURL(module).href : module;
+}
+export function createDocgenEngine(options) {
+    const heapRatio = options.heapRatio ?? 0.7;
+    const heapLimit = options.heapLimit ?? getHeapStatistics().heap_size_limit;
+    const heapUsed = options.heapUsed ?? (() => process.memoryUsage().heapUsed);
+    const load = options.load ?? (module => import(importable(module)));
+    const live = new Map();
+    const stats = { created: 0, recycled: 0 };
+    function extractorFor(name) {
+        let extractor = live.get(name);
+        if (!extractor) {
+            const spec = options.extractors.find(e => e.name === name);
+            if (!spec) {
+                throw new Error(`no docgen extractor named "${name}"`);
+            }
+            extractor = load(spec.module).then((module) => {
+                stats.created++;
+                return module.createExtractor({ root: options.root, options: spec.options });
+            });
+            // A failed start is not cached: the next request tries again.
+            extractor.catch(() => live.delete(name));
+            live.set(name, extractor);
+        }
+        return extractor;
+    }
+    async function disposeAll() {
+        const extractors = [...live.values()];
+        live.clear();
+        await Promise.all(extractors.map(async (extractor) => (await extractor.catch(() => undefined))?.dispose()));
+    }
+    async function recycleIfNeeded() {
+        if (live.size > 0 && heapUsed() > heapLimit * heapRatio) {
+            await disposeAll();
+            stats.recycled++;
+        }
+    }
+    return {
+        stats,
+        async extract(requests) {
+            const results = {};
+            for (const { name, file } of requests) {
+                try {
+                    const extractor = await extractorFor(name);
+                    const doc = await extractor.extract(file);
+                    results[file] = doc ? { doc } : { error: 'no component found' };
+                }
+                catch (error) {
+                    results[file] = { error: describeError(error, options.root) };
+                }
+                await recycleIfNeeded();
+            }
+            return results;
+        },
+        /** Every live extractor's sources, for the dev server to watch. */
+        async sources() {
+            const files = new Set();
+            for (const extractor of live.values()) {
+                for (const file of await (await extractor.catch(() => undefined))?.sources?.() ?? []) {
+                    files.add(file);
+                }
+            }
+            return [...files];
+        },
+        async update(file) {
+            for (const extractor of live.values()) {
+                await (await extractor.catch(() => undefined))?.update?.(file);
+            }
+        },
+        dispose: disposeAll,
+    };
+}

package/dist/node/docgen/protocol.d.ts

@@ -0,0 +1,32 @@
+import type { ExtractResult } from './engine.js';
+export type DocgenRequest = {
+    id: number;
+    type: 'extract';
+    requests: {
+        name: string;
+        file: string;
+    }[];
+} | {
+    id: number;
+    type: 'update';
+    file: string;
+} | {
+    id: number;
+    type: 'dispose';
+};
+export interface DocgenResponse {
+    id: number;
+    results?: Record<string, ExtractResult>;
+    stats?: {
+        created: number;
+        recycled: number;
+    };
+    /** What the extractors read, sent with each extraction. */
+    sources?: string[];
+}
+/** What the dev server sends a client that asked for a story's docs. */
+export interface StoryDocsResult {
+    storyId: string;
+    /** Keyed by component file, relative to the book's root. */
+    components: Record<string, ExtractResult>;
+}

package/dist/node/docgen/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/node/docgen/service.d.ts

@@ -0,0 +1,52 @@
+import type { AutoDocsOptions, Plugin } from '@poveste/shared';
+import type { EngineExtractorSpec } from './engine.js';
+import type { DocgenRequest, DocgenResponse, StoryDocsResult } from './protocol.js';
+type Outgoing = DocgenRequest extends infer R ? R extends {
+    id: number;
+} ? Omit<R, 'id'> : never : never;
+export interface DocgenRunner {
+    send: (request: Outgoing) => Promise<DocgenResponse>;
+    terminate: () => Promise<void>;
+}
+export interface DocgenWorkerData {
+    root: string;
+    extractors: EngineExtractorSpec[];
+}
+export declare function createWorkerRunner(data: DocgenWorkerData): DocgenRunner;
+export interface DocgenServiceOptions {
+    root: string;
+    plugins: Plugin[];
+    /** The config's off-switch. */
+    enabled: boolean;
+    /** `autoDocs` when the config gives an object: merged into every extractor's options. */
+    bookOptions?: AutoDocsOptions | undefined;
+    /** Settles once the first full collection has finished. */
+    collected: Promise<void>;
+    /** The component files a story imports, resolved to absolute paths. */
+    componentsOf: (storyId: string) => string[] | Promise<string[]>;
+    createRunner?: (data: DocgenWorkerData) => DocgenRunner;
+    /** Called with files the extractors read that nothing was watching yet. */
+    watch?: (files: string[]) => void;
+    /** Where a plugin's reason for being unavailable is said. */
+    warn?: (message: string) => void;
+}
+/**
+ * When extraction runs, for every framework (#159). Nothing starts until a reader
+ * first asks for a story's docs: no worker, no checker. Then only the components
+ * that story imports are extracted, after collection has finished, and a change
+ * on disk drops what was extracted rather than re-extracting it unasked.
+ */
+export declare function createDocgenService(options: DocgenServiceOptions): {
+    enabled: boolean;
+    /** Whether a worker exists, and so whether a checker could. */
+    readonly started: boolean;
+    request(storyId: string): Promise<StoryDocsResult>;
+    /**
+     * A file changed. Returns whether anything extracted went stale, so the
+     * caller can tell an open panel to ask again. Before the first request there
+     * is nothing to drop and nothing is started.
+     */
+    fileChanged(file: string): Promise<boolean>;
+    dispose(): Promise<void>;
+};
+export {};

package/dist/node/docgen/service.js

@@ -0,0 +1,128 @@
+import { Worker } from 'node:worker_threads';
+import { relative } from 'pathe';
+export function createWorkerRunner(data) {
+    const worker = new Worker(new URL('./worker.js', import.meta.url), { workerData: data });
+    const pending = new Map();
+    let nextId = 0;
+    worker.on('message', (response) => {
+        pending.get(response.id)?.(response);
+        pending.delete(response.id);
+    });
+    // The engine already answers a failed extraction; this is the thread dying.
+    worker.on('error', (error) => {
+        for (const resolve of pending.values()) {
+            resolve({ id: -1, results: {} });
+        }
+        pending.clear();
+        console.error('[poveste] the docgen worker stopped:', error);
+    });
+    return {
+        send: request => new Promise((resolve) => {
+            const id = nextId++;
+            pending.set(id, resolve);
+            worker.postMessage({ ...request, id });
+        }),
+        terminate: async () => {
+            await worker.terminate();
+        },
+    };
+}
+/**
+ * When extraction runs, for every framework (#159). Nothing starts until a reader
+ * first asks for a story's docs: no worker, no checker. Then only the components
+ * that story imports are extracted, after collection has finished, and a change
+ * on disk drops what was extracted rather than re-extracting it unasked.
+ */
+export function createDocgenService(options) {
+    const warn = options.warn ?? (message => console.warn(message));
+    const plugins = options.plugins.filter((plugin) => {
+        if (!plugin.docgen) {
+            return false;
+        }
+        const reason = options.enabled ? plugin.docgen.unavailable?.(options.root) : undefined;
+        if (reason) {
+            warn(`[poveste] ${reason}`);
+        }
+        return !reason;
+    });
+    const enabled = options.enabled && plugins.length > 0;
+    const createRunner = options.createRunner ?? createWorkerRunner;
+    let runner;
+    const cache = new Map();
+    const watched = new Set();
+    const exclude = options.bookOptions?.exclude ?? [];
+    function pluginFor(file) {
+        if (exclude.some(pattern => file.includes(pattern))) {
+            return undefined;
+        }
+        return plugins.find(plugin => plugin.docgen.match(file));
+    }
+    function start() {
+        runner ??= createRunner({
+            root: options.root,
+            extractors: plugins.map(plugin => ({
+                name: plugin.name,
+                module: plugin.docgen.module,
+                options: { ...plugin.docgen.options, ...options.bookOptions },
+            })),
+        });
+        return runner;
+    }
+    function extract(files) {
+        const missing = files.filter(file => !cache.has(file));
+        if (missing.length) {
+            const response = start().send({
+                type: 'extract',
+                requests: missing.map(file => ({ name: pluginFor(file).name, file })),
+            });
+            for (const file of missing) {
+                cache.set(file, response.then(({ results }) => results?.[file] ?? { error: 'the docgen worker gave no answer' }));
+            }
+            void response.then(({ sources }) => {
+                const unseen = (sources ?? []).filter(file => !watched.has(file));
+                if (unseen.length && options.watch) {
+                    unseen.forEach(file => watched.add(file));
+                    options.watch(unseen);
+                }
+            });
+        }
+        return Promise.all(files.map(async (file) => [relative(options.root, file), await cache.get(file)]));
+    }
+    return {
+        enabled,
+        /** Whether a worker exists, and so whether a checker could. */
+        get started() {
+            return runner !== undefined;
+        },
+        async request(storyId) {
+            if (!enabled) {
+                return { storyId, components: {} };
+            }
+            await options.collected;
+            const files = (await options.componentsOf(storyId)).filter(file => pluginFor(file));
+            return { storyId, components: Object.fromEntries(await extract(files)) };
+        },
+        /**
+         * A file changed. Returns whether anything extracted went stale, so the
+         * caller can tell an open panel to ask again. Before the first request there
+         * is nothing to drop and nothing is started.
+         */
+        async fileChanged(file) {
+            if (!runner || cache.size === 0 || file.includes('/node_modules/')) {
+                return false;
+            }
+            await runner.send({ type: 'update', file });
+            cache.clear();
+            return true;
+        },
+        async dispose() {
+            const current = runner;
+            runner = undefined;
+            cache.clear();
+            if (current) {
+                await current.send({ type: 'dispose' });
+                await current.terminate();
+            }
+        },
+    };
+}

package/dist/node/docgen/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node/docgen/worker.js

@@ -0,0 +1,20 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { createDocgenEngine } from './engine.js';
+const engine = createDocgenEngine(workerData);
+parentPort.on('message', async (message) => {
+    let response;
+    switch (message.type) {
+        case 'extract':
+            response = { id: message.id, results: await engine.extract(message.requests), stats: { ...engine.stats }, sources: await engine.sources() };
+            break;
+        case 'update':
+            await engine.update(message.file);
+            response = { id: message.id };
+            break;
+        case 'dispose':
+            await engine.dispose();
+            response = { id: message.id };
+            break;
+    }
+    parentPort.postMessage(response);
+});

package/dist/node/dom/env.d.ts

@@ -6,4 +6,4 @@ export declare function createDomEnv(): {
     storages: Storage[];
 };
 /** Returns a reused environment to the state a fresh one would have been in. */
-export declare function resetDomEnv(env: Pick<ReturnType<typeof createDomEnv>, 'window' | 'pristineKeys' | 'storages'>): void;
+export declare function resetDomEnv(env: Pick<ReturnType<typeof createDomEnv>, 'window' | 'pristineKeys' | 'storages'>, kept?: ReadonlySet<string>): void;

package/dist/node/dom/env.js

@@ -134,7 +134,7 @@ export function createDomEnv() {
     };
 }
 /** Returns a reused environment to the state a fresh one would have been in. */
-export function resetDomEnv(env) {
+export function resetDomEnv(env, kept = new Set()) {
     const doc = env.window.document;
     for (const el of [doc.documentElement, doc.head, doc.body]) {
         if (!el)
@@ -149,8 +149,9 @@ export function resetDomEnv(env) {
         storage.clear();
     }
     // Additions only: the modules that installed the rest are cached, not re-run.
+    // So are the ones that installed `kept`, after this environment was made.
     for (const key of Object.keys(globalThis)) {
-        if (!env.pristineKeys.has(key)) {
+        if (!env.pristineKeys.has(key) && !kept.has(key)) {
             delete globalThis[key];
         }
     }

package/dist/node/server.js

@@ -4,6 +4,8 @@ import { createServer as createViteServer, mergeConfig as mergeViteConfig } from
 import { useCollectStories } from './collect/index.js';
 import { socketOnBookPort } from './commands/port.js';
 import { answerDevEvent } from './dev-event.js';
+import { componentsOfStory } from './docgen/components-of.js';
+import { createDocgenService } from './docgen/service.js';
 import { useModuleLoader } from './load.js';
 import { createMarkdownFilesWatcher, onMarkdownFileChange, onMarkdownListChange } from './markdown.js';
 import { DevEventPluginApi, DevPluginApi } from './plugin.js';
@@ -143,6 +145,31 @@ async function startServer(ctx, options, onOpen, close) {
             },
         ],
     });
+    // Auto-docs (#1159). Nothing here starts a worker: the first request does.
+    let markCollected;
+    const collected = new Promise((resolve) => {
+        markCollected = resolve;
+    });
+    const docgen = createDocgenService({
+        root: ctx.root,
+        plugins: ctx.config.plugins,
+        enabled: ctx.config.autoDocs !== false,
+        bookOptions: typeof ctx.config.autoDocs === 'object' ? ctx.config.autoDocs : undefined,
+        collected,
+        componentsOf: storyId => componentsOfStory(ctx.storyFiles, nodeServer.moduleGraph, storyId),
+        watch: files => server.watcher.add(files),
+    });
+    onOpen('docgen', () => docgen.dispose());
+    if (docgen.enabled) {
+        server.ws.on('poveste:docgen-request', async ({ storyId }) => {
+            server.ws.send('poveste:docgen-result', await docgen.request(storyId));
+        });
+        server.watcher.on('change', async (file) => {
+            if (await docgen.fileChanged(file)) {
+                server.ws.send('poveste:docgen-stale', {});
+            }
+        });
+    }
     // Invalidate modules
     const invalidateModule = (id) => {
         const mod = server.moduleGraph.getModuleById(id);
@@ -248,6 +275,7 @@ async function startServer(ctx, options, onOpen, close) {
                 return;
             }
             didAllStoriesYet = true;
+            markCollected();
             server.ws.send('poveste:all-stories-loaded', {});
         }
         if (closed) {

package/dist/node/stories.d.ts

@@ -1,4 +1,4 @@
-import type { ServerStoryFile } from '@poveste/shared';
+import type { ServerStoryFile, SupportMatchPattern } from '@poveste/shared';
 import type { Context } from './context.js';
 type StoryChangeHandler = (file?: ServerStoryFile) => unknown;
 /**
@@ -16,6 +16,7 @@ type StoryListChangeHandler = () => unknown;
 export declare function onStoryListChange(handler: StoryListChangeHandler): () => void;
 export declare function notifyStoryListChange(): void;
 export declare function watchStories(newContext: Context): Promise<import("chokidar").FSWatcher>;
+export declare function noSupportPluginMessage(file: string, supportMatch: SupportMatchPattern[]): string;
 export declare function addStory(relativeFilePath: string, virtualModuleCode?: string): ServerStoryFile;
 export declare function removeStory(relativeFilePath: string): void;
 export declare function findAllStories(newContext: Context): Promise<void>;

package/dist/node/stories.js

@@ -1,6 +1,6 @@
 import { kebabCase } from 'change-case';
 import chokidar from 'chokidar';
-import { basename, resolve } from 'pathe';
+import { basename, extname, relative, resolve } from 'pathe';
 import picomatch from 'picomatch';
 import { glob } from 'tinyglobby';
 import { unregister } from './util/unregister.js';
@@ -65,6 +65,23 @@ export async function watchStories(newContext) {
 function getAbsoluteFilePath(relativeFilePath) {
     return resolve(context.root, relativeFilePath);
 }
+// The plugin a story's extension needs, where one plugin alone collects it. A
+// Quasar book without `HstVue()` was told only that nothing claimed its story,
+// which named neither the file's plugin nor which ones had looked (#1337).
+const PLUGIN_FOR_EXTENSION = {
+    '.vue': '`HstVue()` from `@poveste/plugin-vue`',
+    '.svelte': '`HstSvelte()` from `@poveste/plugin-svelte`',
+};
+export function noSupportPluginMessage(file, supportMatch) {
+    const claimed = supportMatch.map(p => `${p.id} (${p.patterns.join(', ')})`).join(', ');
+    const extension = extname(file);
+    const needed = PLUGIN_FOR_EXTENSION[extension];
+    return [
+        `No support plugin found for file ${file}.`,
+        `What this book's plugins collect: ${claimed || 'nothing'}.`,
+        ...needed ? [`A \`${extension}\` story needs ${needed} in the config's \`plugins\`.`] : [],
+    ].join(' ');
+}
 export function addStory(relativeFilePath, virtualModuleCode) {
     const absoluteFilePath = getAbsoluteFilePath(relativeFilePath);
     for (const file of context.storyFiles) {
@@ -87,14 +104,17 @@ export function addStory(relativeFilePath, virtualModuleCode) {
         }
     }
     if (!supportPluginId) {
-        throw new Error(`No support plugin found for file ${absoluteFilePath}`);
+        throw new Error(noSupportPluginMessage(absoluteFilePath, context.config.supportMatch));
     }
+    // A plugin adds its story by absolute path, and `relativePath` and a virtual
+    // module's id are published in a built book (#1383).
+    const relativePath = relative(context.root, absoluteFilePath);
     const file = {
         id: fileId, // The file id will be changed by the story id after it is collected
         path: absoluteFilePath,
-        relativePath: relativeFilePath,
+        relativePath,
         fileName,
-        moduleId: virtualModuleCode ? `virtual:story:${absoluteFilePath}` : absoluteFilePath,
+        moduleId: virtualModuleCode ? `virtual:story:${relativePath}` : absoluteFilePath,
         supportPluginId,
         virtual: !!virtualModuleCode,
         moduleCode: virtualModuleCode,

package/dist/node/util/head.d.ts

@@ -1,2 +1,9 @@
 import type { UseHeadInput } from 'unhead/types';
-export declare function applyHeadTransform(html: string, head: UseHeadInput | undefined): Promise<string>;
+/**
+ * The description a book's index page gets when its `head` sets none. Without
+ * one, a search result and Lighthouse's SEO audit have nothing to read (#316).
+ * Unhead keeps one `description` per page and a later entry wins, so a book's own
+ * replaces this.
+ */
+export declare function defaultDescription(title: string): UseHeadInput;
+export declare function applyHeadTransform(html: string, head: UseHeadInput | undefined, defaults?: UseHeadInput): Promise<string>;

package/dist/node/util/head.js

@@ -1,10 +1,20 @@
 import { createHead, transformHtmlTemplate } from 'unhead/server';
-export async function applyHeadTransform(html, head) {
-    if (!head) {
+/**
+ * The description a book's index page gets when its `head` sets none. Without
+ * one, a search result and Lighthouse's SEO audit have nothing to read (#316).
+ * Unhead keeps one `description` per page and a later entry wins, so a book's own
+ * replaces this.
+ */
+export function defaultDescription(title) {
+    return { meta: [{ name: 'description', content: `${title}, a book of component stories.` }] };
+}
+export async function applyHeadTransform(html, head, defaults) {
+    const init = [defaults, head].filter((entry) => entry !== undefined);
+    if (init.length === 0) {
         return html;
     }
     // disableDefaults: don't inject unhead's `lang="en"` / viewport tags — Poveste's
     // own HTML template already provides viewport, and we shouldn't override it.
-    const instance = createHead({ init: [head], disableDefaults: true });
+    const instance = createHead({ init, disableDefaults: true });
     return await transformHtmlTemplate(instance, html);
 }

package/dist/node/util/vendors.d.ts

@@ -1,2 +1,7 @@
 export declare const __dirname: string;
+/**
+ * Source as a reader is shown it: an import `getInjectedImport` wrote as a file
+ * URL on this machine reads as the package it stands for (#1383).
+ */
+export declare function withPackageImports(source: string): string;
 export declare function getInjectedImport(request: string): string;

package/dist/node/util/vendors.js

@@ -8,6 +8,17 @@ const alias = {
     '@poveste/vendors/vue': path.resolve(__dirname, '../vendors/vue.js'),
     '@poveste/controls': path.resolve(__dirname, '../vendors/controls.js'),
 };
+/**
+ * Source as a reader is shown it: an import `getInjectedImport` wrote as a file
+ * URL on this machine reads as the package it stands for (#1383).
+ */
+export function withPackageImports(source) {
+    let result = source;
+    for (const [request, file] of Object.entries(alias)) {
+        result = result.replaceAll(JSON.stringify(pathToFileURL(file).href), JSON.stringify(request));
+    }
+    return result;
+}
 export function getInjectedImport(request) {
     let id = request;
     id = alias[id] ?? id;

package/dist/node/virtual/index.d.ts

@@ -10,6 +10,8 @@ export declare const SEARCH_TITLE_DATA_ID = "virtual:$poveste-search-title-data"
 export declare const RESOLVED_SEARCH_TITLE_DATA_ID = "\0virtual:$poveste-search-title-data";
 export declare const SEARCH_DOCS_DATA_ID = "virtual:$poveste-search-docs-data";
 export declare const RESOLVED_SEARCH_DOCS_DATA_ID = "\0virtual:$poveste-search-docs-data";
+export declare const COMPONENT_DOCS_ID = "virtual:$poveste-component-docs";
+export declare const RESOLVED_COMPONENT_DOCS_ID = "\0virtual:$poveste-component-docs";
 export declare const GENERATED_GLOBAL_SETUP = "virtual:$poveste-generated-global-setup";
 export declare const RESOLVED_GENERATED_GLOBAL_SETUP = "\0virtual:$poveste-generated-global-setup";
 export declare const GENERATED_SETUP_CODE = "virtual:$poveste-generated-setup-code";

package/dist/node/virtual/index.js

@@ -17,6 +17,8 @@ export const RESOLVED_SEARCH_TITLE_DATA_ID = `\0${SEARCH_TITLE_DATA_ID}`;
 export const SEARCH_DOCS_DATA_ID = 'virtual:$poveste-search-docs-data';
 // export const RESOLVED_SEARCH_DOCS_DATA_ID = `/__resolved__${SEARCH_DOCS_DATA_ID}`
 export const RESOLVED_SEARCH_DOCS_DATA_ID = `\0${SEARCH_DOCS_DATA_ID}`;
+export const COMPONENT_DOCS_ID = 'virtual:$poveste-component-docs';
+export const RESOLVED_COMPONENT_DOCS_ID = `\0${COMPONENT_DOCS_ID}`;
 export const GENERATED_GLOBAL_SETUP = 'virtual:$poveste-generated-global-setup';
 // export const RESOLVED_GENERATED_GLOBAL_SETUP = `/__resolved__${GENERATED_GLOBAL_SETUP}`
 export const RESOLVED_GENERATED_GLOBAL_SETUP = `\0${GENERATED_GLOBAL_SETUP}`;

package/dist/node/virtual/resolved-config.d.ts

@@ -1,2 +1,26 @@
 import type { Context } from '../context.js';
+/**
+ * The config as the browser gets it: the fields `@poveste/app` reads, and no
+ * others. The rest is build-side, and holds paths on the machine that built the
+ * book (`outDir`, each plugin's modules, the logo files), which a built book
+ * published in full (#1383). The logos reach the browser as `logos`, below.
+ */
+export declare function clientConfig(config: Context['config']): {
+    theme: {
+        title: string | undefined;
+        logoHref: string | undefined;
+        defaultColorScheme: "auto" | "light" | "dark" | undefined;
+        hideColorSchemeSwitch: boolean | undefined;
+        storeColorScheme: boolean | undefined;
+        darkClass: string | undefined;
+    };
+    routerMode: "hash" | "history" | undefined;
+    autoApplyContrastColor: boolean | undefined;
+    responsivePresets: import("@poveste/shared").ResponsivePreset[] | undefined;
+    backgroundPresets: import("@poveste/shared").BackgroundPreset[] | undefined;
+    defaultBackgroundColor: string | undefined;
+    preview: import("@poveste/shared").PreviewConfig | undefined;
+    isolateStyles: boolean | undefined;
+    sandboxDarkClass: string | undefined;
+};
 export declare function resolvedConfig(ctx: Context): string;

package/dist/node/virtual/resolved-config.js

@@ -1,6 +1,35 @@
 import { jsIdentifier, jsString } from './codegen.js';
+/**
+ * The config as the browser gets it: the fields `@poveste/app` reads, and no
+ * others. The rest is build-side, and holds paths on the machine that built the
+ * book (`outDir`, each plugin's modules, the logo files), which a built book
+ * published in full (#1383). The logos reach the browser as `logos`, below.
+ */
+export function clientConfig(config) {
+    const theme = config.theme ?? {};
+    return {
+        theme: {
+            title: theme.title,
+            logoHref: theme.logoHref,
+            defaultColorScheme: theme.defaultColorScheme,
+            hideColorSchemeSwitch: theme.hideColorSchemeSwitch,
+            storeColorScheme: theme.storeColorScheme,
+            darkClass: theme.darkClass,
+        },
+        routerMode: config.routerMode,
+        autoApplyContrastColor: config.autoApplyContrastColor,
+        responsivePresets: config.responsivePresets,
+        backgroundPresets: config.backgroundPresets,
+        // eslint-disable-next-line ts/no-deprecated -- the app still reads it as a fallback
+        defaultBackgroundColor: config.defaultBackgroundColor,
+        preview: config.preview,
+        isolateStyles: config.isolateStyles,
+        // eslint-disable-next-line ts/no-deprecated -- the app still reads it as a fallback
+        sandboxDarkClass: config.sandboxDarkClass,
+    };
+}
 export function resolvedConfig(ctx) {
-    let js = `export const config = ${JSON.stringify(ctx.config)}\n`;
+    let js = `export const config = ${JSON.stringify(clientConfig(ctx.config))}\n`;
     const logos = Object.entries(ctx.config.theme?.logo ?? {}).flatMap(([key, file]) => file === undefined ? [] : [[key, file]]);
     for (const [key, file] of logos) {
         js += `import Logo_${jsIdentifier(key, `theme.logo key '${key}'`)} from ${jsString(file)}\n`;

package/dist/node/virtual/story-source.js

@@ -1,5 +1,6 @@
 import fs from 'fs-extra';
 import { resolve } from 'pathe';
+import { withPackageImports } from '../util/vendors.js';
 export async function storySource(ctx, id) {
     const storyId = id.slice('/__resolved__virtual:story-source:'.length);
     const storyFile = ctx.storyFiles.find(f => f.story?.id === storyId);
@@ -11,7 +12,7 @@ export async function storySource(ctx, id) {
         else {
             source = await fs.readFile(resolve(ctx.root, storyFile.relativePath), 'utf-8');
         }
-        return `export default ${JSON.stringify(source)}`;
+        return `export default ${JSON.stringify(withPackageImports(source))}`;
     }
     return undefined;
 }

package/dist/node/virtual/vite-plugin.js

@@ -42,6 +42,9 @@ export function createVirtualFilesPlugin(ctx, isServer) {
             if (id.startsWith(VirtualFiles.SEARCH_DOCS_DATA_ID)) {
                 return VirtualFiles.RESOLVED_SEARCH_DOCS_DATA_ID;
             }
+            if (id === VirtualFiles.COMPONENT_DOCS_ID) {
+                return VirtualFiles.RESOLVED_COMPONENT_DOCS_ID;
+            }
             if (id.startsWith(VirtualFiles.GENERATED_GLOBAL_SETUP)) {
                 return VirtualFiles.RESOLVED_GENERATED_GLOBAL_SETUP;
             }
@@ -95,6 +98,10 @@ export function createVirtualFilesPlugin(ctx, isServer) {
             if (id === VirtualFiles.RESOLVED_SEARCH_DOCS_DATA_ID) {
                 return getSearchDataJS(await generateDocSearchData(ctx));
             }
+            // Filled by `poveste build`; in dev the docs come over the dev socket instead.
+            if (id === VirtualFiles.RESOLVED_COMPONENT_DOCS_ID) {
+                return `export const componentDocs = ${JSON.stringify(ctx.componentDocs ?? {})}\n`;
+            }
             if (id === VirtualFiles.RESOLVED_GENERATED_GLOBAL_SETUP) {
                 return VirtualFiles.resolvedGeneratedGlobalSetup(ctx);
             }

package/dist/node/vite.js

@@ -11,7 +11,7 @@ import { optimizeEntries } from './optimize-entries.js';
 import { notifyStoryChange } from './stories.js';
 import { chromeCssScopePlugin, globalStylesPlugin, userCssScopePlugin, } from './style-isolation/index.js';
 import { escapeRegExp } from './util/escape-regexp.js';
-import { applyHeadTransform } from './util/head.js';
+import { applyHeadTransform, defaultDescription } from './util/head.js';
 import { viteCommand, viteMode } from './util/vite-mode.js';
 import { chromePrebundles, collapseVendoredVue, vendorsFromPoveste } from './vendors.js';
 import { createVirtualFilesPlugin } from './virtual/vite-plugin.js';
@@ -330,7 +330,7 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
     <script type="module" src="/@fs/${APP_PATH}/bundle-main${process.env['POVESTE_DEV'] ? '-dev' : ''}.js"></script>
   </body>
 </html>`;
-                        html = await applyHeadTransform(html, ctx.config.head);
+                        html = await applyHeadTransform(html, ctx.config.head, defaultDescription(ctx.config.theme?.title ?? 'Poveste'));
                         // Apply Vite HTML transforms. This injects the Vite HMR client, and
                         // also applies HTML transforms from Vite plugins
                         html = await server.transformIndexHtml(req.url ?? '/', html);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Interactive component playgrounds for Vue, Nuxt, Svelte, SvelteKit and Quasar, plus Solid and React (renderer only) — a drop-in fork of histoire, with Quasar support histoire does not ship.",
   "author": {
     "name": "Sorin Gitlan",
@@ -78,19 +78,19 @@
   },
   "dependencies": {
     "@11ty/gray-matter": "^3.0.0",
-    "@poveste/app": "^0.19.0",
-    "@poveste/controls": "^0.19.0",
-    "@poveste/shared": "^0.19.0",
-    "@poveste/vendors": "^0.19.0",
+    "@poveste/app": "^0.20.0",
+    "@poveste/controls": "^0.20.0",
+    "@poveste/shared": "^0.20.0",
+    "@poveste/vendors": "^0.20.0",
     "change-case": "^5.4.4",
     "chokidar": "^5.0.0",
     "defu": "^6.1.4",
     "diacritics": "^1.3.0",
-    "es-module-lexer": "^3.0.2",
+    "es-module-lexer": "^3.0.3",
     "fs-extra": "^11.4.1",
-    "jsdom": "^30.1.1",
+    "jsdom": "^30.1.2",
     "lightningcss": "^1.32.0",
-    "markdown-it": "^15.0.2",
+    "markdown-it": "^15.0.3",
     "markdown-it-anchor": "^10.0.0",
     "markdown-it-attrs": "^5.0.1",
     "markdown-it-emoji": "^3.1.0",
@@ -99,19 +99,19 @@
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.7",
     "sade": "^1.8.1",
-    "shiki": "^4.4.3",
+    "shiki": "^4.5.0",
     "tinyglobby": "^0.2.17",
-    "unhead": "^3.4.1"
+    "unhead": "^3.4.3"
   },
   "devDependencies": {
     "@types/diacritics": "^1.3.3",
     "@types/fs-extra": "^11.0.4",
     "@types/jsdom": "^30.0.0",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "@types/picomatch": "^4.0.3",
     "typescript": "6.0.3",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4"
   },
   "scripts": {
     "build": "rimraf dist && tsc",