poveste 0.15.0 → 0.16.1

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.d.ts

@@ -1,4 +1,34 @@
+import type { EvaluatedModuleNode } from 'vite/module-runner';
 import { EvaluatedModules, ModuleRunner } from 'vite/module-runner';
 export type Invoke = (name: string, data: unknown[]) => Promise<unknown>;
-/** A runner over a module server, reached through `invoke`. */
-export declare function createRunner(invoke: Invoke, evaluatedModules?: EvaluatedModules): ModuleRunner;
+/**
+ * The file a CJS module should believe it is, for `require`, `__filename` and
+ * `__dirname`.
+ *
+ * A Vite id is root-relative, so `/node_modules/vue/index.js` is an id and not a
+ * path that exists. `isAbsolute()` answers "does this start with a separator",
+ * which that satisfies, so an id used to become a `filename` and the module's own
+ * `require('./dist/…')` resolved against a directory under the filesystem root.
+ * Quasar's config pulls `vue` through here, and a Quasar book could not collect a
+ * story at all (#1048).
+ *
+ * `file` is no better a source: measured over two books, it was `cleanUrl(id)` on
+ * every one of 1360 calls and a resolved path on none, so it differs from the id
+ * only in having the query stripped. It is read first because when the two ever do
+ * disagree Vite means `file`, not because being set makes it a path.
+ *
+ * So an absolute-looking candidate is accepted only if it names something — one
+ * `existsSync` against evaluating a module, and it is the question the old
+ * predicate meant to ask. `root` is the Vite root and not `process.cwd()`: they
+ * coincide only when the consumer runs poveste from the directory Vite is rooted
+ * at, and this branch is taken on most modules in a book.
+ *
+ * Vite's `/@fs/` ids — its escape hatch for a file outside the root — never reach
+ * here: `normalizeModuleId` strips the prefix server-side, so such a module arrives
+ * as a plain absolute path and is found by the first `existsSync`. Measured, not
+ * assumed: 81 of the Quasar book's modules resolve outside its root, all through
+ * that branch, and no id or file in either book carried the prefix.
+ */
+export declare function filenameOf(module: Readonly<EvaluatedModuleNode>, root: string): 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;