poveste 0.15.0 → 0.16.0

package/README.md

@@ -47,7 +47,7 @@ Run `npx poveste --help` for the full list of options.
 
 ## Requirements
 
-Node `^22.22.2 || ^24.15.0 || >=26.0.0` and Vite `^8.0.0`. See
+Node `>=22.22.2` and Vite `^8.0.0`. See
 [supported versions](https://poveste.dev/guide/getting-started#supported-versions) for
 what proves each range.
 

package/bin.mjs

@@ -1,4 +1,22 @@
 #!/usr/bin/env node
 'use strict'
 
-import './dist/node/bin.js'
+import process from 'node:process'
+import { supportedNode } from './node-floor.mjs'
+
+// Before the CLI is imported, not inside it: on a Node below the floor the import
+// itself is one of the things that can fail, and it fails naming neither Node nor
+// Poveste — story collection loads jsdom, which answers `webidl.util
+// .markAsUncloneable is not a function` on Node 20 (#913).
+//
+// Imported dynamically for the same reason. A static import is parsed with this
+// module, before a line of it runs, so syntax `dist/` may carry would win the race
+// against the message explaining it.
+if (supportedNode()) {
+  import('./dist/node/bin.js').catch((error) => {
+    // `exitCode`, not `exit`: the error is the last thing written, and forcing the
+    // process out on the same tick truncates it on a pipe.
+    process.exitCode = 1
+    console.error(error)
+  })
+}

package/dist/node/build-counts.d.ts

@@ -53,4 +53,14 @@ export declare function builtSomething(counts: BuildCounts): boolean;
  * Documents count as content: a book of `.story.md` pages with no variants has
  * something in it, and telling its author nothing was found would be wrong.
  */
-export declare function buildSummary(counts: BuildCounts, seconds: number, storyMatch: string[]): string[];
+export declare function buildSummary(counts: BuildCounts, seconds: number, storyMatch: string[], guideUrl?: string): string[];
+/**
+ * The page that shows a story in the framework this book uses.
+ *
+ * The message used to send everyone to `/guide/`, which explains what a story is
+ * for a second time rather than showing one — two hops of misdirection for a
+ * reader who has just been told they have no stories (#905). Nuxt and Quasar
+ * write Vue stories, SvelteKit writes Svelte ones, so the plugin names map onto
+ * the two pages that exist.
+ */
+export declare function storyGuideUrl(pluginNames: string[]): string;

package/dist/node/build-counts.js

@@ -60,7 +60,7 @@ export function builtSomething(counts) {
  * Documents count as content: a book of `.story.md` pages with no variants has
  * something in it, and telling its author nothing was found would be wrong.
  */
-export function buildSummary(counts, seconds, storyMatch) {
+export function buildSummary(counts, seconds, storyMatch, guideUrl = 'https://poveste.dev/guide/getting-started') {
     const took = `in ${seconds}s`;
     const globs = storyMatch.join(', ');
     if (!builtSomething(counts)) {
@@ -68,12 +68,12 @@ export function buildSummary(counts, seconds, storyMatch) {
             const files = `${counts.empty.length} file${counts.empty.length === 1 ? '' : 's'}`;
             return [
                 `Built 0 stories ${took} — ${files} matched ${globs} and produced no story`,
-                'A story file needs a <Story> in it: https://poveste.dev/guide/',
+                `A story file needs a <Story> in it: ${guideUrl}`,
             ];
         }
         return [
             `Built 0 stories ${took} — nothing matched ${globs}`,
-            'Write a story file and run this again: https://poveste.dev/guide/',
+            `Write a story file and run this again: ${guideUrl}`,
         ];
     }
     const stories = `${counts.stories} stor${counts.stories === 1 ? 'y' : 'ies'}`;
@@ -81,3 +81,24 @@ export function buildSummary(counts, seconds, storyMatch) {
     const docs = counts.docs ? ` and ${counts.docs} document${counts.docs === 1 ? '' : 's'}` : '';
     return [`✅ Built ${stories} (${variants})${docs} ${took}`];
 }
+/**
+ * The page that shows a story in the framework this book uses.
+ *
+ * The message used to send everyone to `/guide/`, which explains what a story is
+ * for a second time rather than showing one — two hops of misdirection for a
+ * reader who has just been told they have no stories (#905). Nuxt and Quasar
+ * write Vue stories, SvelteKit writes Svelte ones, so the plugin names map onto
+ * the two pages that exist.
+ */
+export function storyGuideUrl(pluginNames) {
+    const vue = ['@poveste/plugin-vue', '@poveste/plugin-nuxt', '@poveste/plugin-quasar'];
+    const svelte = ['@poveste/plugin-svelte'];
+    if (pluginNames.some(name => svelte.includes(name))) {
+        return 'https://poveste.dev/guide/svelte/stories';
+    }
+    if (pluginNames.some(name => vue.includes(name))) {
+        return 'https://poveste.dev/guide/vue/stories';
+    }
+    // A book with neither, such as vanilla: the framework list is the next step.
+    return 'https://poveste.dev/guide/getting-started';
+}

package/dist/node/build.js

@@ -5,7 +5,7 @@ import { join } from 'pathe';
 import pc from 'picocolors';
 import { createServer as createViteServer, mergeConfig as mergeViteConfig, build as viteBuild, } from 'vite';
 import { APP_PATH } from './alias.js';
-import { buildCounts, buildSummary, builtSomething } from './build-counts.js';
+import { buildCounts, buildSummary, builtSomething, storyGuideUrl } from './build-counts.js';
 import { getSerializedStoryData } from './build-serialize.js';
 import { useCollectStories } from './collect/index.js';
 import { useModuleLoader } from './load.js';
@@ -286,7 +286,7 @@ export async function build(ctx) {
         // Green only when something was built. A tick over nothing is the claim
         // #624 is about, and it is the first command the guide asks for.
         const paint = builtSomething(counts) ? pc.green : pc.yellow;
-        for (const line of buildSummary(counts, Math.round(duration / 1000 * 100) / 100, ctx.config.storyMatch)) {
+        for (const line of buildSummary(counts, Math.round(duration / 1000 * 100) / 100, ctx.config.storyMatch, storyGuideUrl(ctx.config.plugins.map(plugin => plugin.name)))) {
             console.log(paint(line));
         }
         // Render

package/dist/node/collect/define-globals.js

@@ -1,26 +1,11 @@
-// Story collection runs in a Node worker. Externalised dependencies are loaded by
-// native Node ESM, so Vite never applies `define` to them — and a bare compile-time
-// feature flag is just an undefined identifier there. vue-i18n reading
-// `__VUE_PROD_DEVTOOLS__` was the reported case (#284); anything with build-time
-// flags fails the same way.
-//
-// The fix is to give the collection environment the same values a real build would
-// substitute, taken from Vite's own resolved `define` rather than a list of library
-// names this package would have to keep current.
-// Only `__FLAG__`-shaped keys are seeded. Every flag this exists for follows that
-// convention — `__VUE_OPTIONS_API__`, `__VUE_PROD_DEVTOOLS__`, `__VUE_I18N_LEGACY_API__`,
-// `__INTLIFY_PROD_DEVTOOLS__` — and narrow is the right failure here. A browser-targeted
-// config shimming a Node global (`define: { process: '{"env":{}}' }` is a real shape)
-// would otherwise replace the collection worker's own `process`, surfacing far from the
-// config that caused it. Refusing to evaluate arbitrary expressions while letting
-// arbitrary identifiers overwrite the runtime would be a guard in name only.
-// `process.env.NODE_ENV` and friends fail the same test, being member expressions.
+// Externalised deps load through native Node ESM, which Vite never applies `define`
+// to, so a compile-time flag is an undefined identifier in a collection worker —
+// vue-i18n reading `__VUE_PROD_DEVTOOLS__` was the reported case (#284).
+// Narrow on purpose: a browser-targeted `define: { process: '{"env":{}}' }` would
+// otherwise overwrite the worker's own `process`, far from the config that caused it.
 const FEATURE_FLAG = /^__[A-Z0-9_]+__$/;
-// Vite `define` values are JS expression *source*. A plugin-injected flag arrives
-// already parsed (`false`), while a user's `define: { X: 'false' }` arrives as the
-// string `"false"` — and seeding that string would make the flag *truthy*, silently
-// inverting it. So strings are parsed as literals, and anything that is not a literal
-// is skipped: evaluating arbitrary expressions here is not something this should do.
+// `define` values are expression *source*, so a user's `define: { X: 'false' }` arrives
+// as the string `"false"` and seeding it verbatim would invert the flag.
 export function globalsFromDefine(define) {
     const globals = {};
     for (const [key, value] of Object.entries(define ?? {})) {

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

@@ -0,0 +1,2 @@
+export declare function serializeError(error: unknown, seen?: WeakSet<Error>): unknown;
+export declare function deserializeError(value: unknown): unknown;

package/dist/node/collect/error.js

@@ -0,0 +1,70 @@
+/*
+ * Structured clone keeps an `Error`'s `name`, `message` and `stack` and drops every
+ * own property beyond them, so the code frame a Vite transform error puts on `frame`
+ * never once survived the worker boundary (#1020).
+ */
+const MARK = 'pvt:error';
+function isSerialized(value) {
+    return typeof value === 'object' && value !== null && value.kind === MARK;
+}
+// A property the clone rejects takes the whole message down with it, which is worse
+// than dropping the property.
+function cloneable(value) {
+    try {
+        structuredClone(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/*
+ * `seen` breaks a cause that points back into its own chain. `structuredClone`
+ * carries a cycle happily; this walk is the only thing here that cannot, and it
+ * runs on the path that reports a failure — so overflowing the stack would lose
+ * the error it was called to describe and replace it with its own.
+ */
+export function serializeError(error, seen = new WeakSet()) {
+    if (!(error instanceof Error)) {
+        return cloneable(error) ? error : String(error);
+    }
+    if (seen.has(error)) {
+        // Named and described, without the cause that leads back here.
+        return { kind: MARK, name: error.name, message: error.message, stack: error.stack, props: {} };
+    }
+    seen.add(error);
+    const props = {};
+    for (const key of Object.getOwnPropertyNames(error)) {
+        if (key === 'name' || key === 'message' || key === 'stack') {
+            continue;
+        }
+        const value = error[key];
+        if (key === 'cause') {
+            props[key] = serializeError(value, seen);
+        }
+        else if (cloneable(value)) {
+            props[key] = value;
+        }
+    }
+    return { kind: MARK, name: error.name, message: error.message, stack: error.stack, props };
+}
+export function deserializeError(value) {
+    if (!isSerialized(value)) {
+        return value;
+    }
+    const error = new Error(value.message);
+    error.name = value.name;
+    // Assigning `undefined` would erase the stack `new Error` just gave this one.
+    if (value.stack !== undefined) {
+        error.stack = value.stack;
+    }
+    for (const [key, prop] of Object.entries(value.props)) {
+        Object.defineProperty(error, key, {
+            value: key === 'cause' ? deserializeError(prop) : prop,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return error;
+}

package/dist/node/collect/index.js

@@ -1,6 +1,4 @@
 import { cpus } from 'node:os';
-import { MessageChannel } from 'node:worker_threads';
-import Tinypool from '@akryum/tinypool';
 import { escapeRegExp } from '@poveste/shared';
 import path, { relative } from 'pathe';
 import pc from 'picocolors';
@@ -9,16 +7,14 @@ import { createPath } from '../tree.js';
 import { slash } from '../util/fs.js';
 import { globalsFromDefine } from './define-globals.js';
 import { createModuleServer } from './module-server.js';
-import { serveInvoke } from './rpc.js';
+import { createPool } from './pool.js';
+import { INVALIDATE, INVALIDATE_ALL } from './task.js';
 export function useCollectStories(options, ctx) {
     const { server, mainServer } = options;
     const node = createModuleServer(server, {
         inline: [
-            // Published layout: `poveste` and scoped `@poveste/*` packages. These
-            // MUST be inlined so collection transforms them and resolves their
-            // `virtual:` imports; otherwise they're loaded via native Node ESM,
-            // which throws ERR_UNSUPPORTED_ESM_URL_SCHEME on `virtual:` and breaks
-            // story collection for any fresh npm install.
+            // Must be inlined: loaded through native Node ESM instead, their `virtual:`
+            // imports throw ERR_UNSUPPORTED_ESM_URL_SCHEME on any fresh npm install.
             /\/poveste\/dist/,
             /\/poveste\/client/,
             /@poveste\/[\w-]+\/dist/,
@@ -33,64 +29,44 @@ export function useCollectStories(options, ctx) {
         ],
         transformMode: ctx.config.viteNodeTransformMode,
     });
-    // Same values a real build substitutes, so externalised deps see their flags.
     const defineGlobals = globalsFromDefine(server.config.define);
     const maxThreads = ctx.config.collectMaxThreads ?? cpus().length;
     const threadsCount = ctx.mode === 'dev'
         ? Math.max(Math.min(maxThreads, Math.floor(cpus().length / 2)), 1)
         : Math.max(Math.min(maxThreads, cpus().length - 1), 1);
     console.log(pc.blue(`Using ${threadsCount} thread${threadsCount === 1 ? '' : 's'} for story collection`));
-    const threadPool = new Tinypool({
-        filename: new URL('./worker.js', import.meta.url).href,
-        // WebContainer compatibility (Stackblitz)
-        useAtomics: typeof process.versions['webcontainer'] !== 'string',
-        minThreads: threadsCount,
-        maxThreads: threadsCount,
+    const threadPool = createPool({
+        filename: new URL('./worker.js', import.meta.url),
+        threads: threadsCount,
+        invoke: (name, data) => node.invoke(name, data),
     });
     function clearCache() {
         server.moduleGraph.invalidateAll();
         node.clearCache();
-    }
-    function createChannel() {
-        const channel = new MessageChannel();
-        const port = channel.port2;
-        const workerPort = channel.port1;
-        serveInvoke(port, (name, data) => node.invoke(name, data));
-        return {
-            port,
-            workerPort,
-        };
+        // Both of those make every module read again, and a worker told nothing would
+        // discover that one at a time, dropping each as some story asks for it — which
+        // is how one run ends up holding two instances of a module.
+        threadPool.broadcast({ kind: INVALIDATE_ALL });
     }
     if (mainServer) {
         mainServer.watcher.on('change', (file) => {
             file = slash(file);
-            threadPool.broadcastMessage({
-                kind: 'hst:invalidate',
+            threadPool.broadcast({
+                kind: INVALIDATE,
                 file,
             });
         });
     }
     let destroying = false;
     async function executeStoryFile(storyFile) {
-        // The channel belongs to this execution, and nothing used to close it. On a
-        // build that fails, the executions still in flight are abandoned mid-run and
-        // their main-thread ports stay open and listening — enough live handles to
-        // keep the process alive with nothing left to do (#426).
-        let channel;
         try {
-            channel = createChannel();
             const payload = {
                 root: server.config.root,
                 base: server.config.base,
                 storyFile,
-                port: channel.workerPort,
                 defineGlobals,
             };
-            const { storyData } = await threadPool.run(payload, {
-                transferList: [
-                    channel.workerPort,
-                ],
-            });
+            const { storyData } = await threadPool.run(payload);
             const finalData = storyData[0];
             if (!finalData) {
                 console.warn(pc.yellow(`⚠️  No story found for ${storyFile.path}`));
@@ -99,7 +75,6 @@ export function useCollectStories(options, ctx) {
             else if (storyData.length > 1) {
                 console.warn(pc.yellow(`⚠️  Multiple stories not supported: ${storyFile.path}`));
             }
-            // Default props
             if (ctx.config.defaultStoryProps) {
                 for (const [key, value] of Object.entries(ctx.config.defaultStoryProps)) {
                     if (Reflect.get(finalData, key) == null) {
@@ -132,9 +107,6 @@ export function useCollectStories(options, ctx) {
                 throw e;
             }
         }
-        finally {
-            channel?.port.close();
-        }
     }
     async function destroy() {
         destroying = true;

package/dist/node/collect/module-server.d.ts

@@ -7,6 +7,10 @@ export interface ModuleServerOptions {
         web?: RegExp[];
     } | undefined;
 }
+export declare function isInternalRequest(id: string): boolean;
+/** A request id as the transformed code wrote it, back to a module id. */
+export declare function normalizeRequestId(id: string, base?: string): string;
+export declare function matches(id: string, patterns: (string | RegExp)[] | undefined): boolean;
 export interface ModuleServer {
     invoke: (name: string, data: unknown[]) => Promise<unknown>;
     clearCache: () => void;

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

@@ -37,11 +37,11 @@ function withTrailingSlash(path) {
 function cleanUrl(url) {
     return url.replace(/[?#].*$/, '');
 }
-function isInternalRequest(id) {
+export function isInternalRequest(id) {
     return /^\/?@vite\/(?:client|env)$/.test(id);
 }
 /** A request id as the transformed code wrote it, back to a module id. */
-function normalizeRequestId(id, base) {
+export function normalizeRequestId(id, base) {
     if (base && base !== '/' && id.startsWith(withTrailingSlash(base))) {
         id = `/${id.slice(base.length)}`;
     }
@@ -93,7 +93,7 @@ function toFilePath(id, root) {
         exists,
     };
 }
-function matches(id, patterns) {
+export function matches(id, patterns) {
     return (patterns ?? []).some(pattern => typeof pattern === 'string'
         ? MODULE_DIRECTORIES.some(dir => id.includes(join(dir, pattern)))
         : pattern.test(id));

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

@@ -0,0 +1,14 @@
+import type { Invoke } from './runner.js';
+export interface PoolOptions {
+    filename: string | URL;
+    threads: number;
+    /** Answers the `invoke` calls workers make while they run. */
+    invoke: Invoke;
+}
+export interface Pool<P, R> {
+    run: (payload: P) => Promise<R>;
+    /** Reaches every worker, busy ones included. */
+    broadcast: (message: unknown) => void;
+    destroy: () => Promise<void>;
+}
+export declare function createPool<P, R>(options: PoolOptions): Pool<P, R>;

package/dist/node/collect/pool.js

@@ -0,0 +1,106 @@
+import { Worker } from 'node:worker_threads';
+import { deserializeError } from './error.js';
+import { serveInvoke } from './rpc.js';
+import { DONE, FAILED, TASK } from './task.js';
+export function createPool(options) {
+    const queue = [];
+    const idle = [];
+    const workers = [];
+    let destroyed = false;
+    let nextId = 0;
+    for (let i = 0; i < options.threads; i++) {
+        const worker = new Worker(options.filename, { stdout: false, stderr: false });
+        const handle = { worker, current: undefined };
+        serveInvoke(worker, options.invoke);
+        worker.on('message', (message) => {
+            if (message?.kind !== DONE && message?.kind !== FAILED) {
+                return;
+            }
+            const task = handle.current;
+            // A late or repeated answer is for a task this worker has already finished,
+            // and without the id it would settle whichever one it is running now.
+            if (!task || message.id !== task.id) {
+                return;
+            }
+            handle.current = undefined;
+            if (message.kind === DONE) {
+                task.resolve(message.result);
+            }
+            else {
+                task.reject(deserializeError(message.error));
+            }
+            release(handle);
+        });
+        // A worker that dies takes its task with it. Without this the story's
+        // promise never settles and the build hangs rather than failing.
+        worker.on('error', (error) => {
+            const task = handle.current;
+            handle.current = undefined;
+            task?.reject(error);
+            drop(handle);
+        });
+        worker.on('exit', () => {
+            const task = handle.current;
+            handle.current = undefined;
+            task?.reject(new Error('[poveste] a collection worker exited before its story finished'));
+            drop(handle);
+        });
+        workers.push(handle);
+        idle.push(handle);
+    }
+    function drop(handle) {
+        remove(workers, handle);
+        remove(idle, handle);
+        // Nothing is left to run the queue, so fail it rather than let it wait.
+        if (workers.length === 0) {
+            for (const task of queue.splice(0)) {
+                task.reject(new Error('[poveste] every collection worker is gone'));
+            }
+        }
+    }
+    function remove(list, handle) {
+        const at = list.indexOf(handle);
+        if (at !== -1) {
+            list.splice(at, 1);
+        }
+    }
+    function release(handle) {
+        const next = queue.shift();
+        if (next) {
+            dispatch(handle, next);
+        }
+        else {
+            idle.push(handle);
+        }
+    }
+    function dispatch(handle, task) {
+        handle.current = task;
+        handle.worker.postMessage({ kind: TASK, id: task.id, payload: task.payload });
+    }
+    function run(payload) {
+        return new Promise((resolve, reject) => {
+            if (destroyed) {
+                reject(new Error('[poveste] the collection pool is destroyed'));
+                return;
+            }
+            const task = { id: nextId++, payload, resolve, reject };
+            const handle = idle.shift();
+            if (handle) {
+                dispatch(handle, task);
+            }
+            else {
+                queue.push(task);
+            }
+        });
+    }
+    function broadcast(message) {
+        for (const handle of workers) {
+            handle.worker.postMessage(message);
+        }
+    }
+    async function destroy() {
+        destroyed = true;
+        await Promise.all(workers.slice().map(handle => handle.worker.terminate()));
+    }
+    return { run, broadcast, destroy };
+}

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

@@ -1,6 +1,10 @@
-import type { MessagePort } from 'node:worker_threads';
 import type { Invoke } from './runner.js';
+/** A `MessagePort` or a `Worker` — the two ends this runs over. */
+export interface PortLike {
+    on: (event: 'message', listener: (value: any) => void) => unknown;
+    postMessage: (value: any) => void;
+}
 /** Answers `invoke` requests arriving on `port`. */
-export declare function serveInvoke(port: MessagePort, invoke: Invoke): void;
+export declare function serveInvoke(port: PortLike, invoke: Invoke): void;
 /** An `invoke` that sends its calls over `port`. */
-export declare function invokeOver(port: MessagePort): Invoke;
+export declare function invokeOver(port: PortLike): Invoke;

package/dist/node/collect/rpc.js

@@ -1,21 +1,29 @@
+import { deserializeError, serializeError } from './error.js';
 /*
- * The one call a collection worker makes to the main thread, over the
- * `MessagePort` each task brings. It replaced birpc (#344): after #167 the
- * channel carries a single method, and a dependency that ships in `poveste` was
- * three majors behind to carry it.
+ * The one call a collection worker makes to the main thread. It replaced birpc
+ * (#344): after #167 the channel carries a single method, and a dependency that
+ * ships in `poveste` was three majors behind to carry it.
+ *
+ * Task dispatch shares the channel (#1020), so both sides tag what they send.
  */
 // What birpc waited before rejecting a call, kept so a stuck transform still
 // fails the story rather than holding its worker forever.
 const TIMEOUT_MS = 60_000;
+const REQUEST = 'pvt:invoke';
+const RESPONSE = 'pvt:invoked';
 /** Answers `invoke` requests arriving on `port`. */
 export function serveInvoke(port, invoke) {
-    port.on('message', async ({ id, name, data }) => {
+    port.on('message', async (message) => {
+        if (message?.kind !== REQUEST) {
+            return;
+        }
+        const { id, name, data } = message;
         let response;
         try {
-            response = { id, result: await invoke(name, data) };
+            response = { kind: RESPONSE, id, result: await invoke(name, data) };
         }
         catch (error) {
-            response = { id, error };
+            response = { kind: RESPONSE, id, error: serializeError(error) };
         }
         port.postMessage(response);
     });
@@ -24,15 +32,22 @@ export function serveInvoke(port, invoke) {
 export function invokeOver(port) {
     let nextId = 0;
     const pending = new Map();
-    port.on('message', ({ id, result, error }) => {
+    port.on('message', (message) => {
+        if (message?.kind !== RESPONSE) {
+            return;
+        }
+        const { id, result, error } = message;
         const call = pending.get(id);
         if (!call) {
             return;
         }
         pending.delete(id);
         clearTimeout(call.timeout);
-        if (error) {
-            call.reject(error);
+        // Presence rather than truthiness: `serveInvoke` sets the key only when the
+        // call threw, and a thrown `undefined` or `''` read as no error at all —
+        // resolving the runner with `undefined` where it expects a module.
+        if ('error' in message) {
+            call.reject(deserializeError(error));
         }
         else {
             call.resolve(result);
@@ -46,6 +61,6 @@ export function invokeOver(port) {
         }, TIMEOUT_MS);
         timeout.unref();
         pending.set(id, { resolve, reject, timeout });
-        port.postMessage({ id, name, data });
+        port.postMessage({ kind: REQUEST, id, name, data });
     });
 }

package/dist/node/collect/runner.js

@@ -19,22 +19,13 @@ function exportAll(exports, source) {
         }
     }
 }
-/**
- * Loads an externalised dependency the way vite-node did, which collection has
- * always relied on: a CommonJS package's named exports are read through its
- * default export, so `import { x } from 'cjs-package'` works whether or not Node's
- * lexer found `x`.
- */
+/** As vite-node did: a CJS package's named exports are read through its default. */
 class InteropEvaluator {
     // The runner offsets source maps by the lines a wrapper adds, which match Vite's own.
     startOffset = new ESModulesEvaluator().startOffset;
     /**
-     * Runs a transformed module with `require`, `exports`, `module`, `__filename`
-     * and `__dirname` in scope, as vite-node did. Vite's own evaluator passes only
-     * its import bindings, so a CommonJS dependency a book inlines through
-     * `viteNodeInlineDeps` threw `exports is not defined` (#167). What a module
-     * assigns to `exports` or `module.exports` becomes its default export and its
-     * named exports.
+     * Vite's own evaluator passes only import bindings, so a CJS dependency inlined
+     * through `viteNodeInlineDeps` threw `exports is not defined` (#167).
      */
     async runInlinedModule(context, code, module) {
         const exports = context[ssrModuleExportsKey];
@@ -102,8 +93,7 @@ class InteropEvaluator {
         });
     }
 }
-// `import.meta.env` as vite-node gave it: `process.env`, with the three flags as
-// booleans. The runner's default throws on any key the transform did not replace.
+// The runner's own default throws on any key the transform did not replace.
 const env = new Proxy(process.env, {
     get: (target, key) => typeof key !== 'string'
         ? undefined

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

@@ -0,0 +1,14 @@
+import type { PortLike } from './rpc.js';
+import type { Payload, ReturnData } from './types.js';
+export declare const TASK = "pvt:task";
+export declare const DONE = "pvt:done";
+export declare const FAILED = "pvt:failed";
+export declare const INVALIDATE = "hst:invalidate";
+export declare const INVALIDATE_ALL = "pvt:invalidate-all";
+export interface TaskHandlers {
+    invalidate: (file: string) => void;
+    invalidateAll: () => void;
+    collect: (payload: Payload) => Promise<ReturnData>;
+}
+/** Answers task dispatch and invalidation arriving on `port`. */
+export declare function serveTasks(port: PortLike, handlers: TaskHandlers): void;

package/dist/node/collect/task.js

@@ -0,0 +1,81 @@
+import { serializeError } from './error.js';
+/*
+ * The task half of what a collection worker answers on its port (#1020). Split
+ * from `worker.ts` because that module throws outside a worker thread, which
+ * leaves this — where a mis-routed message loses a story — unreachable from a test.
+ */
+export const TASK = 'pvt:task';
+export const DONE = 'pvt:done';
+export const FAILED = 'pvt:failed';
+/* The watcher's, and older than the rest — the wire value is what `index.ts`
+   has always sent. Shared so a rename cannot land on one end only: an unknown
+   kind is dropped in silence by design, so a typo here stops invalidation
+   without failing anything. */
+export const INVALIDATE = 'hst:invalidate';
+export const INVALIDATE_ALL = 'pvt:invalidate-all';
+/** Answers task dispatch and invalidation arriving on `port`. */
+export function serveTasks(port, handlers) {
+    // Invalidations that arrived while a story was running, held until none is.
+    const deferred = new Set();
+    let dropEverything = false;
+    // A count rather than a flag: nothing here stops a second task arriving before
+    // the first settles — the pool sends one at a time, and the spec beside this
+    // one drives two deliberately — and under a flag the second task's own drain
+    // would invalidate modules the first is still holding, which is the thing this
+    // whole file is arranging not to do.
+    let running = 0;
+    port.on('message', (message) => {
+        // Sent once per collection pass, when the server clears its own cache. Every
+        // module is read again either way; applying it here rather than one module at
+        // a time as each is next asked for is what stops a run straddling the two.
+        if (message?.kind === INVALIDATE_ALL) {
+            if (running > 0) {
+                dropEverything = true;
+                return;
+            }
+            handlers.invalidateAll();
+            return;
+        }
+        if (message?.kind === INVALIDATE) {
+            // Applied mid-story it re-evaluates modules that story is already using,
+            // and the two halves of a framework then disagree about which instance is
+            // current: Vue injects a key its provider never used, Svelte reads a
+            // component context outside any component. The invalidation is for the
+            // *next* run of the file anyway, so it waits for one.
+            if (running > 0) {
+                deferred.add(message.file);
+                return;
+            }
+            handlers.invalidate(message.file);
+            return;
+        }
+        if (message?.kind !== TASK) {
+            return;
+        }
+        const { id } = message;
+        // Only with the graph to itself: a task starting beside another cannot take
+        // modules out from under it.
+        if (running === 0) {
+            if (dropEverything) {
+                dropEverything = false;
+                deferred.clear();
+                handlers.invalidateAll();
+            }
+            for (const file of deferred) {
+                handlers.invalidate(file);
+            }
+            deferred.clear();
+        }
+        running++;
+        const settle = () => {
+            running--;
+        };
+        handlers.collect(message.payload).then((result) => {
+            settle();
+            port.postMessage({ kind: DONE, id, result });
+        }, (error) => {
+            settle();
+            port.postMessage({ kind: FAILED, id, error: serializeError(error) });
+        });
+    });
+}

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

@@ -0,0 +1,10 @@
+import type { ServerStory, ServerStoryFile } from '@poveste/shared';
+export interface Payload {
+    root: string;
+    base: string;
+    storyFile: ServerStoryFile;
+    defineGlobals?: Record<string, unknown>;
+}
+export interface ReturnData {
+    storyData: ServerStory[];
+}

package/dist/node/collect/types.js

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

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

@@ -1,14 +1 @@
-import type { ServerStory, ServerStoryFile } from '@poveste/shared';
-import type { MessagePort } from 'node:worker_threads';
-export interface Payload {
-    root: string;
-    base: string;
-    port: MessagePort;
-    storyFile: ServerStoryFile;
-    defineGlobals?: Record<string, unknown>;
-}
-export interface ReturnData {
-    storyData: ServerStory[];
-}
-declare const _default: (payload: Payload) => Promise<ReturnData>;
-export default _default;
+export {};

package/dist/node/collect/worker.js

@@ -7,13 +7,13 @@ import { EvaluatedModules } from 'vite/module-runner';
 import { createDomEnv, resetDomEnv } from '../dom/env.js';
 import { invokeOver } from './rpc.js';
 import { createRunner } from './runner.js';
+import { serveTasks } from './task.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _evaluatedModules = new EvaluatedModules();
 let _runner;
 // Worker-lifetime: externalised runtimes cache the DOM they first saw, so one
 // per story broke re-collection.
 let _domEnv;
-let _invoke;
 // A virtual module is cached under the id the plugin resolved it to, not the one
 // it was asked for, so both forms have to go.
 function invalidate(file) {
@@ -27,28 +27,38 @@ function invalidate(file) {
         _evaluatedModules.invalidateModule(node);
     }
 }
-// Cleanup module cache
-parentPort?.on('message', (message) => {
-    if (message?.kind === 'hst:invalidate') {
-        invalidate(message.file);
+// The whole graph, dropped at a task boundary. The server clears its own cache
+// once per pass, so this is re-read in that pass anyway — what changes is whether
+// a story can be halfway through when its turn comes.
+//
+// Everything, with nothing held back. Vitest skips its own `dist` from the reset
+// it does between test files, and the same shape here re-broke Svelte: keeping a
+// module while dropping what it imports leaves it holding the dropped instances.
+// Vitest's skipped set imports only itself; the plugin runtime imports the
+// framework, which is in this graph.
+function invalidateAll() {
+    for (const node of _evaluatedModules.idToModuleMap.values()) {
+        _evaluatedModules.invalidateModule(node);
     }
-});
-export default async (payload) => {
+}
+if (!parentPort) {
+    throw new Error('[poveste] the collection worker was started outside a worker thread');
+}
+// The port it answers over is the one tasks arrive on, so nothing is handed over
+// per story.
+const _invoke = invokeOver(parentPort);
+serveTasks(parentPort, { invalidate, invalidateAll, collect });
+async function collect(payload) {
     const startTime = performance.now();
     process.env['HST_COLLECT'] = 'true';
-    // Here rather than broadcast from the main thread: the pool dispatches tasks
-    // on a different port from `broadcastMessage`, and nothing orders the two, so
-    // a busy worker could start the task first and read its own stale cache. A
-    // story being re-executed is being re-read by definition (#557).
+    // A story being re-executed is being re-read by definition (#557), and one
+    // re-collected without an intervening watcher event gets no broadcast at all.
     invalidate(payload.storyFile.moduleId);
     // Before any module runs: an externalised dep reads these at import time.
     for (const [key, value] of Object.entries(payload.defineGlobals ?? {})) {
         ;
         globalThis[key] = value;
     }
-    _invoke = invokeOver(payload.port);
-    // One runner for the worker's lifetime, reaching the server through whichever
-    // port the current task brought.
     const runner = _runner ?? (_runner = createRunner((name, data) => _invoke(name, data), _evaluatedModules));
     if (_domEnv) {
         resetDomEnv(_domEnv);
@@ -58,7 +68,6 @@ export default async (payload) => {
     }
     const el = window.document.createElement('div');
     const beforeExecuteTime = performance.now();
-    // Mount app to collect stories/variants
     const { run } = (await runner.import(resolve(__dirname, './run.js')));
     const afterExecuteTime = performance.now();
     const storyData = [];
@@ -81,4 +90,4 @@ export default async (payload) => {
     return {
         storyData,
     };
-};
+}

package/dist/node/colors.js

@@ -280,7 +280,14 @@ export const defaultColors = {
     },
 };
 const HEX = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i;
-const SHORT_HEX = /^#([a-f\d]){3,4}$/i;
+/*
+ * Four groups, not one group repeated. `([a-f\d]){3,4}` captures only the last
+ * character it matched, so the expansion below received `#0f0` as one group and
+ * built `#00undefinedundefined` — which `HEX` then rejected, and every shorthand
+ * colour a config used came back unreadable (#955).
+ */
+// eslint-disable-next-line regexp/optimal-quantifier-concatenation -- `{1,2}` here is the bug above
+const SHORT_HEX = /^#([a-f\d])([a-f\d])([a-f\d])([a-f\d])?$/i;
 const VALUE = `(?:\\d+|\\d*\\.\\d+)%?`;
 const SEP = `(?:\\s*,\\s*|\\s+)`;
 const ALPHA_SEP = `\\s*[,/]\\s*`;

package/dist/node/plugin.d.ts

@@ -11,7 +11,7 @@ export declare class BasePluginApi implements PluginApiBase {
     colors: import("picocolors/types.js").Colors & {
         createColors: (enabled?: boolean) => import("picocolors/types.js").Colors;
     };
-    path: import("path").PlatformPath;
+    path: typeof import("node:path");
     fs: typeof fs;
     constructor(ctx: Context, plugin: Plugin, moduleLoader: ModuleLoader, 
     /** Absent where nothing should watch, which is a build. */

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

@@ -5,11 +5,17 @@ export function resolvedTheme(ctx) {
     const colors = ctx.config.theme?.colors ?? {};
     for (const color in colors) {
         for (const key in colors[color]) {
-            const parsed = parseColor(colors[color][key]);
-            if (!parsed) {
-                throw new Error(`[poveste] theme.colors.${color}.${key} is not a colour poveste can read: ${JSON.stringify(colors[color][key])}`);
+            const value = colors[color][key];
+            // Parsed to be rejected, not to be rebuilt. What goes into the variable is
+            // what the config wrote: `parseColor` splits a colour into channels and
+            // drops both the alpha and the space it was written in, so rebuilding from
+            // its parts silently turned `#10b98180` opaque and `hsl(160 84% 39%)` into
+            // `rgb(160 84% 39%)` — which is not a colour, so the declaration was thrown
+            // away and the token fell back (#955).
+            if (!parseColor(value)) {
+                throw new Error(`[poveste] theme.colors.${color}.${key} is not a colour poveste can read: ${JSON.stringify(value)}`);
             }
-            css += `--_poveste-color-${color}-${key}: ${parsed.color.join(' ')};`;
+            css += `--_poveste-color-${color}-${key}: ${value};`;
         }
     }
     css += '}';

package/dist/node/vite.js

@@ -113,16 +113,18 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
     // published book is Poveste's own stores, so the 200 KB buys them nothing
     // (#791).
     //
-    // Two copies reach a book. A consumer's stories resolve their own pinia, which
-    // imports `@vue/devtools-api` by name; Poveste's own stores use
-    // `@poveste/vendors`, which keeps the real module as `devtools-api.js` so that
-    // `poveste dev` still registers them. Both are stubbed here.
+    // One rule reaches both copies now. A consumer's stories resolve their own
+    // pinia and Poveste's stores resolve its own, and since #347 both import
+    // `@vue/devtools-api` by name rather than one of them carrying it inside a
+    // prebundled chunk — so the name is the whole of it.
     //
-    // `apply: 'build'` is what keeps dev registering — the vendored chunk is the
-    // real module until a book is built.
+    // `apply: 'build'` keeps dev registering. Note that it is not what makes the
+    // real module reach a dev browser: Vite's dep optimiser bakes it into a chunk
+    // before this plugin sees the id, and flipping this to `'serve'` leaves dev
+    // serving it regardless. Measured while rewriting the spec that used to claim
+    // otherwise.
     if (!isServer) {
         const STUB = '\0poveste:devtools-api';
-        const VENDORED = /[\\/](?:poveste-vendors|@poveste[\\/]vendors)[\\/]dist[\\/]client[\\/]devtools-api\.js(?:\?.*)?$/;
         plugins.push({
             name: 'poveste-devtools-api-stub',
             apply: 'build',
@@ -133,9 +135,9 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
             load(id) {
                 // Not an empty module: pinia and vue-router *call* this, so the export
                 // has to exist or the book throws where it used to register nothing.
-                // Both spellings, because `b-pinia` and `b-vue-router` import different
-                // ones of the two the package exports.
-                return id === STUB || VENDORED.test(id)
+                // Both spellings, because pinia and vue-router import different ones of
+                // the two the package exports.
+                return id === STUB
                     ? 'export function setupDevtoolsPlugin() {}\nexport { setupDevtoolsPlugin as setupDevToolsPlugin }\n'
                     : undefined;
             },
@@ -389,11 +391,8 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
                     resolve: {
                         alias: [
                             ...[
-                                ['floating-vue/dist/style.css', 'node_modules/floating-vue/dist/style.css'],
-                                ['floating-vue', 'floating-vue'],
                                 ['@iconify/vue', 'iconify'],
                                 ['pinia', 'pinia'],
-                                ['scroll-into-view-if-needed', 'scroll'],
                                 ['vue-router', 'vue-router'],
                                 ['@vueuse/core', 'vue-use'],
                                 ['vue', 'vue'],

package/node-floor.mjs

@@ -0,0 +1,87 @@
+// The Node check the CLI makes before it loads anything.
+//
+// `engines.node` is an install-time signal, and #901 is where it works against
+// us: npm answers a Node its range rejects by resolving *backwards*, and the
+// seventeen versions published before this package declared the field (0.1.0 to
+// 0.6.1) accept every Node, so that is where it lands. #907 made the range
+// contiguous, which removes the realistic case; it cannot remove the class,
+// because nothing can be added to a version already published and deprecation
+// does not stop npm choosing one.
+//
+// So the run-time signal is the one that is ours. Vite has carried this for
+// years and its wording is the model (#913).
+//
+// Its own file, in plain ES2015, imported by `bin.mjs` before the CLI: the
+// failure it exists for can be the import of `dist/`, and syntax this file
+// cannot parse on an old Node would be the same defect wearing a different hat.
+
+import { readFileSync, writeSync } from 'node:fs'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * The floor of a `>=x.y.z` range, or `null` for any other shape.
+ *
+ * One `>=` floor is the only shape `engines.node` may take — `scripts/checks/
+ * versions.ts` holds every published package to it — so anything else means the
+ * manifest has drifted, and the CLI says nothing rather than turning our own
+ * drift into a reader's failed command.
+ */
+export function floorOf(range) {
+  const match = /^>=(\d+)\.(\d+)\.(\d+)$/.exec(String(range ?? '').trim())
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null
+}
+
+export function isBelow(version, floor) {
+  const parts = String(version).split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const part = parts[i] ?? 0
+    if (part !== floor[i]) {
+      return part < floor[i]
+    }
+  }
+  return false
+}
+
+/** Vite's wording, because a reader may well have seen it already. */
+export function unsupportedNodeMessage(version, range) {
+  return `You are using Node.js ${version}. Poveste requires Node.js version ${range}. Please upgrade your Node.js version.`
+}
+
+export function nodeProblem(version, range) {
+  const floor = floorOf(range)
+  return floor && isBelow(version, floor) ? unsupportedNodeMessage(version, range) : null
+}
+
+/**
+ * Whether this Node may run the CLI, saying so on stderr when it may not.
+ *
+ * `writeSync` and `process.exitCode`, not `console.error` and `process.exit`: a
+ * write to a piped stderr is asynchronous and `process.exit` does not wait for it.
+ * `src/node/bin.ts` delays its own forced exit 500ms for that hazard, after a
+ * framed compiler error came out cut in half.
+ *
+ * Measured here, this message survived both shapes — 112 bytes is small enough to
+ * land in one write. So this is the shape that cannot lose it rather than a fix for
+ * an observed loss, and it costs nothing: there is nothing to flush and nothing
+ * left to do but exit.
+ */
+export function supportedNode(manifestUrl = new URL('./package.json', import.meta.url)) {
+  let range
+  try {
+    range = JSON.parse(readFileSync(fileURLToPath(manifestUrl), 'utf8')).engines?.node
+  }
+  catch {
+    // A manifest this cannot read is not the reader's problem to be told about.
+    return true
+  }
+
+  const problem = nodeProblem(process.versions.node, range)
+  if (!problem) {
+    return true
+  }
+
+  writeSync(2, `${problem}\n`)
+  process.exitCode = 1
+  return false
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Interactive component playgrounds for Vue, Nuxt, Svelte, SvelteKit and Quasar — a drop-in fork of histoire, with Quasar support histoire does not ship.",
   "author": {
     "name": "Sorin Gitlan",
@@ -62,29 +62,29 @@
     "client.js",
     "dist",
     "index.d.ts",
+    "node-floor.mjs",
     "plugin.d.ts",
     "plugin.js"
   ],
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": ">=22.22.2"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
   },
   "dependencies": {
     "@11ty/gray-matter": "^3.0.0",
-    "@akryum/tinypool": "^0.3.1",
-    "@poveste/app": "^0.15.0",
-    "@poveste/controls": "^0.15.0",
-    "@poveste/shared": "^0.15.0",
-    "@poveste/vendors": "^0.15.0",
+    "@poveste/app": "^0.16.0",
+    "@poveste/controls": "^0.16.0",
+    "@poveste/shared": "^0.16.0",
+    "@poveste/vendors": "^0.16.0",
     "change-case": "^5.4.4",
     "chokidar": "^5.0.0",
     "defu": "^6.1.4",
     "diacritics": "^1.3.0",
     "es-module-lexer": "^3.0.2",
-    "fs-extra": "^11.2.0",
-    "jsdom": "^30.0.1",
+    "fs-extra": "^11.4.1",
+    "jsdom": "^30.1.1",
     "lightningcss": "^1.32.0",
     "markdown-it": "^15.0.2",
     "markdown-it-anchor": "^10.0.0",
@@ -97,22 +97,23 @@
     "sade": "^1.8.1",
     "shiki": "^4.4.3",
     "tinyglobby": "^0.2.17",
-    "unhead": "^3.1.0"
+    "unhead": "^3.4.1"
   },
   "devDependencies": {
     "@types/diacritics": "^1.3.3",
     "@types/fs-extra": "^11.0.4",
     "@types/jsdom": "^30.0.0",
-    "@types/node": "^22.10.1",
+    "@types/node": "^26.6.3",
     "@types/picomatch": "^4.0.3",
     "typescript": "6.0.3",
-    "vite": "^8.2.0",
-    "vitest": "^5.0.0"
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
   },
   "scripts": {
     "build": "rimraf dist && tsc",
     "watch": "tsc -w --sourceMap",
     "test": "vitest run",
-    "test:dev": "vitest"
+    "test:dev": "vitest",
+    "typecheck:server": "tsc -p tsconfig.server.json --noEmit"
   }
 }

package/dist/node/__tests__/dev-cleanup/poveste.config.d.ts

@@ -1,7 +0,0 @@
-declare const _default: {
-    plugins: {
-        name: string;
-        defaultConfig(): void;
-    }[];
-};
-export default _default;

package/dist/node/__tests__/dev-cleanup/poveste.config.js

@@ -1,15 +0,0 @@
-import { appendFileSync } from 'node:fs';
-import { onPovesteCleanup } from 'poveste';
-const marker = process.env['POVESTE_CLEANUP_MARKER'] ?? '';
-// Registers the way @poveste/plugin-nuxt does, while the config resolves, and
-// leaves a line behind each time the cleanup runs.
-// `.ts`, not `.js`: the restart specs edit this file, and a `.js` config can be
-// served from Node's module cache, so the edit would never be read.
-export default {
-    plugins: [{
-            name: 'cleanup-marker',
-            defaultConfig() {
-                onPovesteCleanup(() => appendFileSync(marker, 'ran\n'));
-            },
-        }],
-};