forgebook 0.3.0 → 0.3.2

package/dist/src/storyMocks.js

@@ -0,0 +1,208 @@
+/**
+ * A story's mock handlers (`parameters.msw.handlers`) read from its parameters, and run on a server in place of the
+ * network. Exported as `forgebook/story-mocks`, for `@forgebook/plugin-msw` and the adapters that render on a server.
+ *
+ * @remarks
+ * A server render (the generated server tests) has no service worker, and whatever answers on the test machine must
+ * not decide what a page draws. So the handlers the frame's worker serves are run here through MSW's `getResponse`, a
+ * plain call with no interception, so concurrent renders never see each other's handlers. A request no handler answers,
+ * one a handler answers with `passthrough()`, or one made with `bypass()`, fails with the error the adapter writes, which
+ * knows what its stories can give instead. A handler's `HttpResponse.error()` rejects the fetch and its redirect is
+ * followed, as in the frame.
+ *
+ * Imports nothing, MSW included: `msw` is an optional peer of each adapter that uses this, so it is resolved from that
+ * package and passed in. A strict package manager would not find it from here.
+ *
+ * @module
+ */
+/** How many redirects a fetch follows, as browsers and Node's `fetch` do. */
+const MOST_REDIRECTS = 20;
+/**
+ * How many requests of a render wait at once. A handler that fetches the address it answers comes back to itself for
+ * ever, in promises alone, so no timer of the render's ever fires: only this stops it.
+ */
+const MOST_WAITING = 1000;
+/** The headers a redirect to another origin does not carry. */
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/** Whether a value is an object with named fields. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The handlers a story's parameters declare, flat: a list, or a record of lists as MSW's Storybook addon writes them.
+ *
+ * @param parameters - the story's parameters.
+ * @returns the handlers; none when the story has no mocks.
+ */
+export const mockHandlersOf = (parameters) => {
+    const msw = parameters["msw"];
+    const handlers = isRecord(msw) ? msw["handlers"] : undefined;
+    if (Array.isArray(handlers))
+        return handlers;
+    return isRecord(handlers) ? Object.values(handlers).flat() : [];
+};
+/** The addresses of this machine that are not a range: every interface's, which connecting to reaches this machine. */
+const OWN_ADDRESSES = new Set(["[::1]", "0.0.0.0", "[::]"]);
+/**
+ * Whether a host name is this machine's own, as `URL` writes it: `localhost` and its subdomains, with or without the
+ * final dot, `127.0.0.0/8`, the same range mapped into IPv6, and the addresses that reach every interface.
+ *
+ * @param hostname - the host name, from a `URL`.
+ */
+const isLoopback = (hostname) => {
+    const name = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+    return (name === "localhost" ||
+        name.endsWith(".localhost") ||
+        OWN_ADDRESSES.has(name) ||
+        /^127\.\d+\.\d+\.\d+$/.test(name) ||
+        /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(name));
+};
+/**
+ * Whether an address reaches the same server as a page: its origin, or another name of this machine on the same scheme
+ * and port (`127.0.0.1` or `[::1]` beside a `localhost` page), which a real machine answers the same.
+ *
+ * @param address - the address.
+ * @param page - the page's address.
+ */
+export const isOnPageOrigin = (address, page) => {
+    if (address.origin === page.origin)
+        return true;
+    return (address.protocol === page.protocol &&
+        address.port === page.port &&
+        isLoopback(address.hostname) &&
+        isLoopback(page.hostname));
+};
+/**
+ * Makes a story's `{ once: true }` handlers answer again, as MSW's `restoreHandlers` does: each render on a server is a
+ * page of its own, as each frame is, while the handler objects outlive it in the test process.
+ *
+ * @param handlers - the story's handlers.
+ */
+const restoreHandlers = (handlers) => {
+    for (const handler of handlers)
+        if (isRecord(handler) && typeof handler["isUsed"] === "boolean")
+            Reflect.set(handler, "isUsed", false);
+};
+/**
+ * Whether a module is MSW's, as much as a server render uses.
+ *
+ * @param module - the module, as `import()` gave it.
+ */
+const isMswCore = (module) => typeof module === "object" &&
+    module !== null &&
+    "getResponse" in module &&
+    typeof module.getResponse === "function";
+/**
+ * Loads MSW, which only a story with handlers needs on a server.
+ *
+ * @param loadMsw - imports it.
+ * @throws when MSW is not installed, or is older than its `getResponse`.
+ */
+const mswCore = async (loadMsw) => {
+    let module;
+    try {
+        module = await loadMsw();
+    }
+    catch (error) {
+        throw new Error("Answering a fetch with the story's mocks on a server needs MSW: npm install --save-dev msw", { cause: error });
+    }
+    if (!isMswCore(module))
+        throw new Error("The installed MSW has no getResponse: MSW 2.11 or later is needed");
+    return module;
+};
+/**
+ * Whether a request asks to skip the mocks and reach the network: MSW's `bypass()` adds this to its `accept` header. A
+ * handler's `fetch(bypass(request))` would otherwise come back to the same handler for ever.
+ *
+ * @param request - the request.
+ */
+const isBypass = (request) => request.headers.get("accept")?.includes("msw/passthrough") === true;
+/**
+ * Whether an answer is MSW's `passthrough()`: MSW marks it with this status and header, which its own
+ * `isPassthroughResponse` reads (exported from MSW 3 only).
+ *
+ * @param answer - a handler's answer.
+ */
+const isPassthrough = (answer) => answer.status === 302 && answer.headers.get("x-msw-intention") === "passthrough";
+/**
+ * What the story's handlers answer: none when they do not, or when the one that does sends the request on to the
+ * network, which a server render never reaches.
+ *
+ * @param mocks - the story's mocks.
+ * @param request - the request.
+ */
+const mockAnswer = async (mocks, request) => {
+    if (mocks.handlers.length === 0 || isBypass(request))
+        return undefined;
+    const { getResponse } = await mswCore(mocks.loadMsw);
+    const address = new URL(request.url);
+    // an address on this machine, whichever name or port, is the app's own: `/api/users` answers it as in the app
+    const baseUrl = isLoopback(address.hostname) ? address.origin : mocks.origin;
+    const answer = await getResponse([...mocks.handlers], request, { baseUrl });
+    return answer === undefined || isPassthrough(answer) ? undefined : answer;
+};
+/**
+ * The request a mocked redirect leads to, as `fetch` follows it: the same method and body for a 307 or a 308, a GET
+ * for a 303 and for a POST's 301 or 302; none when the answer is no redirect or the request does not follow one.
+ *
+ * @param answer - a handler's answer.
+ * @param request - the request it answered, its body unread.
+ * @throws a `TypeError` for a redirect a request with `redirect: "error"` gets, as `fetch` does.
+ */
+const redirectOf = (answer, request) => {
+    const location = answer.headers.get("location");
+    if (![301, 302, 303, 307, 308].includes(answer.status) || location === null)
+        return undefined;
+    if (request.redirect === "manual")
+        return undefined;
+    if (request.redirect === "error")
+        throw new TypeError(`Redirected to ${location}, which the request refuses`);
+    const target = new URL(location, request.url);
+    const isGet = answer.status === 303 || (request.method === "POST" && answer.status !== 307 && answer.status !== 308);
+    const next = isGet
+        ? new Request(target, { method: request.method === "HEAD" ? "HEAD" : "GET", headers: request.headers })
+        : new Request(target, request);
+    // an adapter may send this one to the network: another origin never gets the first one's credentials, as with `fetch`
+    if (target.origin !== new URL(request.url).origin)
+        for (const name of CREDENTIAL_HEADERS)
+            next.headers.delete(name);
+    return next;
+};
+/**
+ * A `fetch` of one render, its requests answered by the story's mocks. Make one per render: its `{ once: true }` handlers
+ * answer again from here.
+ *
+ * @param mocks - the story's mocks.
+ * @returns what sends a request; an address the mocks do not take goes to the global `fetch`.
+ */
+export const mockedFetch = (mocks) => {
+    restoreHandlers(mocks.handlers);
+    const send = async (request, redirects) => {
+        if (mocks.isMocked?.(new URL(request.url)) === false)
+            return globalThis.fetch(request);
+        // kept for a redirect that sends the request again, body included, after a handler read it
+        const kept = request.clone();
+        const answer = await mockAnswer(mocks, request);
+        if (answer === undefined)
+            throw mocks.onUnanswered(request);
+        // MSW's mocked network error: `fetch` rejects, as it does in the frame
+        if (answer.type === "error")
+            throw new TypeError("Failed to fetch", { cause: answer });
+        const next = redirectOf(answer, kept);
+        if (next === undefined)
+            return answer;
+        if (redirects >= MOST_REDIRECTS)
+            throw new TypeError(`Too many redirects, the last to ${next.url}`);
+        return send(next, redirects + 1);
+    };
+    let waiting = 0;
+    return async (request) => {
+        if (waiting >= MOST_WAITING)
+            throw new TypeError(`${request.method} ${request.url}: a handler keeps fetching what it answers`);
+        waiting += 1;
+        try {
+            return await send(request, 0);
+        }
+        finally {
+            waiting -= 1;
+        }
+    };
+};

package/dist/src/vite/docsExtractor.d.ts

@@ -83,6 +83,11 @@ export type DocsWorkerData = {
     /** Whether its answers are kept on disk, so it stamps what each was read from; a build's are not. */
     readonly keepsAnswers: boolean;
 };
+/** What the worker says of its own, unasked: that its modules, the framework's docs module's included, are loaded. */
+export type DocsWorkerLoaded = {
+    /** The message's kind. */
+    readonly kind: "loaded";
+};
 /** How an extractor reads. */
 export type DocsExtractorOptions = {
     /** Whether every story's docs will be read, as in a build; a dev server's reads by default. */
@@ -94,6 +99,8 @@ export type DocsExtractorOptions = {
      * never ends before the build does.
      */
     readonly idleMs?: number;
+    /** How long ending the worker waits for its modules to load, in milliseconds; `LOAD_WAIT_MS` by default. */
+    readonly loadWaitMs?: number;
 };
 /**
  * How long a dev server's worker stays with nothing to do, in milliseconds, before it ends. Its programs are the
@@ -114,4 +121,4 @@ export declare const NO_DOCS_EXTRACTOR: DocsExtractor;
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs }?: DocsExtractorOptions) => DocsExtractor;
+export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs, loadWaitMs }?: DocsExtractorOptions) => DocsExtractor;

package/dist/src/vite/docsExtractor.js

@@ -10,7 +10,7 @@
  * the disk keeps no docs at all (a first start, a build), one warm-up at a time and only while nothing waits. For the
  * same reason a dev server's worker left with nothing to do ends (`IDLE_MS`), so the memory a first start took does
  * not stay with the server until it stops. Requests are answered in order. The worker never keeps the process alive
- * (`unref`), and `close` ends it when the build or the server ends.
+ * (`unref`), and `close` ends it when the build or the server ends, once its modules are loaded (`endOnceLoaded`).
  *
  * @module
  */
@@ -40,6 +40,11 @@ const YOUNG_GENERATION_MB = 8;
  * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
  */
 export const IDLE_MS = 5 * 60_000;
+/**
+ * How long ending a worker waits for its modules to load, in milliseconds: well past a slow machine's load of the
+ * compiler, and a limit so that a docs module whose loading never ends cannot keep a server from closing.
+ */
+const LOAD_WAIT_MS = 30_000;
 /**
  * The worker's young generation in a build, in MB: a build reads every story's docs in one go, and with the dev
  * server's small one it would spend much of that time collecting garbage.
@@ -75,6 +80,28 @@ export const NO_DOCS_EXTRACTOR = {
     listed: () => undefined,
     close: () => Promise.resolve()
 };
+/**
+ * Ends a worker once its modules are loaded.
+ *
+ * @remarks
+ * Node 24 aborts the whole process when a worker is terminated while it reads the exports of a CommonJS module it
+ * imports, and the compiler is one: a command answered before the warm-up's worker had loaded would die with nothing
+ * printed. Past the loading, terminating is safe and stops a program being built at once, which a request to the worker
+ * to end by itself would have to wait for.
+ *
+ * @param worker - the worker.
+ * @param loaded - settled once its modules are loaded, or it has ended.
+ * @param waitMs - how long to wait for that, in milliseconds.
+ */
+const endOnceLoaded = async (worker, loaded, waitMs) => {
+    let limit;
+    const overLimit = new Promise((resolve) => {
+        limit = setTimeout(resolve, waitMs);
+    });
+    await Promise.race([loaded, overLimit]);
+    clearTimeout(limit);
+    await worker.terminate();
+};
 /**
  * A docs extractor with its worker, started on its first request.
  *
@@ -82,7 +109,7 @@ export const NO_DOCS_EXTRACTOR = {
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS } = {}) => {
+export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS, loadWaitMs = LOAD_WAIT_MS } = {}) => {
     // the code that writes the answers: this package's and the framework's docs, whose edit or new version is a miss
     const code = cacheFolder === undefined ? undefined : codeStampOf(docsModule);
     const cacheOf = (kind, isValue) => cacheFolder === undefined || code === undefined
@@ -91,6 +118,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     const docsCache = cacheOf("docs", isKeptDocs);
     const usageCache = cacheOf("usage", isKeptUsage);
     let worker;
+    // settled once the current worker's modules are loaded, or it has ended
+    let workerLoaded = Promise.resolve();
     let nextId = 0;
     // the changes the watcher reported: an answer read across one may have read a file before it changed, so it is not kept
     let changes = 0;
@@ -103,17 +132,23 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     // the warm-ups not sent yet: one goes out only when nothing is pending, so a read never waits behind them all
     const warmUps = [];
     let idle;
+    // every ending under way: a second close must wait for the first's too, as a process may exit once it resolves
+    let ending = Promise.resolve();
+    // lets the current worker go, so the next request starts another, and ends it
+    const endWorker = async () => {
+        const running = worker;
+        worker = undefined;
+        if (running !== undefined)
+            ending = Promise.all([ending, endOnceLoaded(running, workerLoaded, loadWaitMs)]);
+        await ending;
+    };
     // ends the worker once nothing is asked of it for a while; a request in the meantime keeps it
     const stopWhenIdle = () => {
         clearTimeout(idle);
         // a build reads every story, and a quiet stretch in it would build every program again
         if (readsEverything || pending.size > 0 || warmUps.length > 0)
             return;
-        idle = setTimeout(() => {
-            const running = worker;
-            worker = undefined;
-            void running?.terminate();
-        }, idleMs);
+        idle = setTimeout(() => void endWorker(), idleMs);
         idle.unref();
     };
     const sendWarmUp = () => {
@@ -135,7 +170,16 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
             }
         });
         created.unref();
+        workerLoaded = new Promise((resolve) => {
+            created.on("message", (message) => {
+                if (message.kind === "loaded")
+                    resolve();
+            });
+            created.once("exit", () => resolve());
+        });
         created.on("message", (response) => {
+            if (response.kind === "loaded")
+                return;
             pending.get(response.id)?.(response);
             pending.delete(response.id);
             sendWarmUp();
@@ -229,10 +273,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
         },
         close: async () => {
             clearTimeout(idle);
-            const running = worker;
-            worker = undefined;
             warmUps.length = 0;
-            await running?.terminate();
+            await endWorker();
         }
     };
 };

package/dist/src/vite/docsWorker.js

@@ -17,7 +17,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * read builds one, and a changed source file (`{ kind: "changed" }`) renews them on their next read. A usage request
  * (`{ kind: "usage", id, files }`) is answered from the same programs (`usageGraph.ts`). A request is `{ id, storyFile }`, the answer `{ id, result }`, `extractStoryComponent`'s result as
  * it is (plain data), with the files it can change with (`docsDependencies.ts`), which the dev server keeps it on disk
- * with.
+ * with. Unasked, it says `{ kind: "loaded" }` once its modules are loaded.
  *
  * @module
  */
@@ -55,6 +55,11 @@ if (isWorkerData(workerData) && !workerData.readsEverything)
     readAskedFilesOnly();
 /** The framework's docs module, loaded once, before the first answer. */
 const docsModule = loadDocsModule();
+// the extractor waits for this before it ends the thread: `endOnceLoaded` says why
+void docsModule.then(() => {
+    const loaded = { kind: "loaded" };
+    parentPort?.postMessage(loaded);
+});
 /** The extractor's result, or why it threw: a throw would end the worker and every request waiting on it. */
 const extracted = async (storyFile) => {
     const module = await docsModule;

package/dist/src/vite/fileAccess.d.ts

@@ -19,8 +19,13 @@ export declare const isFileRefused: (config: ResolvedConfig, file: string) => bo
 export declare const isQueriedFileReadable: (config: ResolvedConfig, id: string) => boolean;
 /** What a plugin's dev server lets a client read: `devServerAccess` makes it. */
 export type DevServerAccess = {
-    /** Starts on a dev server; until then (and in a build, which has none) nothing is refused. */
-    readonly serve: (server: ViteDevServer) => void;
+    /**
+     * Starts on a dev server; until then (and in a build, which has none) nothing is refused.
+     *
+     * @param server - the dev server.
+     * @param sources - the module that imports the configuration's sources; none without a configuration.
+     */
+    readonly serve: (server: ViteDevServer, sources: string | undefined) => void;
     /**
      * Whether a resolver's importer is a module, not the stand-in Vite gives an address asked for directly.
      *
@@ -36,16 +41,35 @@ export type DevServerAccess = {
     /** Whether a file a group lists may be read; says so once when not, as nothing else would tell why it is missing. */
     readonly isKept: IsFileKept;
     /**
-     * Whether a module is answered with nothing: a group no module imported, or a file `server.fs` refuses. Asked of every
-     * id, since an address can name an id directly, past the plugin's `resolveId`.
+     * Holds a request for a group no import has named until the configuration's sources have been read.
+     *
+     * @param url - the request's address.
+     */
+    readonly settle: (url: string) => Promise<void>;
+    /**
+     * What the plugin's load answers for a file's query `server.fs` refuses: an empty module and not Vite's 404, as Vite
+     * would then read a path with a `..` as written, past the check that refused it. Asked of every id, since an address
+     * can name an id directly, past the plugin's `resolveId`.
      *
      * @param id - the module's id.
+     * @returns the module, or none when the client may read the id.
+     * @throws for a group no module of the project imports, with Vite's code for a missing file.
      */
-    readonly isRefused: (id: string) => boolean;
+    readonly refusal: (id: string) => {
+        readonly code: string;
+        readonly moduleType: "js";
+    } | undefined;
 };
+/** What a plugin's dev server lets a client read. */
+export declare const devServerAccess: () => DevServerAccess;
 /**
- * What a plugin's dev server lets a client read.
- *
- * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ * The plugin's hook for Vitest (`configureVitest`), whose module cache keeps each module's transform on disk between
+ * runs: a module read from it resolves no import, so a group it names would stay refused from the second run on.
  */
-export declare const devServerAccess: (renew: (server: ViteDevServer, ids: Iterable<string>) => void) => DevServerAccess;
+export declare const VITEST_HOOKS: {
+    configureVitest: (context: {
+        readonly defineCacheKeyGenerator?: (generator: (module: {
+            readonly sourceCode: string;
+        }) => false | undefined) => void;
+    }) => void;
+};

package/dist/src/vite/fileAccess.js

@@ -12,12 +12,23 @@
  * A group's id holds its patterns, so an id alone must never choose what is read: any address could name a folder to
  * list and read, and the imports the group's module writes would make Vite serve every file listed, past `allow`.
  *
+ * A group is named by a module's import, which the plugin sees when Vite transforms that module. A client may ask before
+ * that: a tab left open across a restart holds its modules and asks for a search index first. So a request for a group
+ * no import has named waits, before Vite starts on it, for the server to read what the configuration's sources import,
+ * the same modules a page would load: inside the group's load the reading could wait for a request that waits for it. A
+ * cache of transforms would hide the import for good, and Vitest keeps one on disk between runs: a module that names a
+ * group stays out of it.
+ *
+ * A group no module names answers as a missing file does: Vite answers 404, keeps no module to renew and raises no
+ * overlay on the pages open. A module's `export default null` would read as a group, and fail far from here in whatever
+ * reads it.
+ *
  * @module
  */
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
-import { isFileLoadingAllowed } from "vite";
-import { isGroupId } from "./pluginIds.js";
+import { isCSSRequest, isFileLoadingAllowed } from "vite";
+import { isGroupId, namesGroup, namingGroupOf } from "./pluginIds.js";
 import { CODE_QUERY, DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
@@ -69,25 +80,81 @@ export const isQueriedFileReadable = (config, id) => {
     return VITE_PATHS.normalize(file) === file && isFileLoadingAllowed(config, file);
 };
 /**
- * What a plugin's dev server lets a client read.
+ * Whether reading a module can show an import of a group: not a group (reading one waits for this reading) nor a file's
+ * query, which reads no import; not a style sheet or a pre-bundled dependency, which import none.
+ *
+ * @param environment - the environment the module is read in.
+ * @param module - the module.
+ */
+const mayNameGroup = (environment, module) => {
+    const { id, url } = module;
+    return (id !== null &&
+        !isCSSRequest(url) &&
+        !isGroupId(id) &&
+        !FILE_QUERIES.some((query) => id.endsWith(query)) &&
+        environment.depsOptimizer?.isOptimizedDepUrl(url) !== true);
+};
+/**
+ * Reads a module and what it imports, for the imports the plugin sees on the way.
+ *
+ * @param environment - the environment to read them in.
+ * @param entry - the module's address.
+ * @returns whether each could be read: one that could not may name a group once it is fixed.
+ */
+const readImports = async (environment, entry) => {
+    const seen = new Set([entry]);
+    const read = async (url) => {
+        try {
+            await environment.transformRequest(url);
+        }
+        catch {
+            return false;
+        }
+        const module = await environment.moduleGraph.getModuleByUrl(url);
+        const next = [...(module?.importedModules ?? [])].filter((imported) => !seen.has(imported.url) && mayNameGroup(environment, imported));
+        for (const imported of next)
+            seen.add(imported.url);
+        const reads = await Promise.all(next.map((imported) => read(imported.url)));
+        return reads.every(Boolean);
+    };
+    return read(entry);
+};
+/**
+ * The id of the group a request's address names, when it names one: any spelling this misses reaches the plugin's load,
+ * which refuses it all the same.
  *
- * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ * @param url - the request's address.
  */
-export const devServerAccess = (renew) => {
+const groupIdOf = (url) => {
+    try {
+        const path = decodeURI(url.split("?")[0] ?? "");
+        const at = path.indexOf("virtual:forgebook-");
+        return at === -1 ? undefined : `\0${path.slice(at)}`;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Vite's code for a file it could not load: its server answers 404, with no overlay, and a runner fails with the text. */
+const MISSING_MODULE = "ERR_LOAD_URL";
+/** What a plugin's dev server lets a client read. */
+export const devServerAccess = () => {
     let devServer;
     let addressImporter;
+    let sourcesEntry;
+    /** The reading of the sources: once, as an edit that names a new group is seen when Vite transforms it. */
+    let sourcesRead;
     const imported = new Set();
-    const refused = new Set();
     return {
-        serve: (server) => {
+        serve: (server, sources) => {
             devServer = server;
             addressImporter = join(server.config.root, "index.html");
+            sourcesEntry = sources;
+            sourcesRead = undefined;
         },
         isModule: (importer) => importer !== undefined && importer !== addressImporter,
         noteImported: (id) => {
-            imported.add(id);
-            if (refused.delete(id) && devServer !== undefined)
-                renew(devServer, [id]);
+            imported.add(namingGroupOf(id));
         },
         isKept: (file) => {
             if (devServer === undefined || !isFileRefused(devServer.config, file))
@@ -95,15 +162,38 @@ export const devServerAccess = (renew) => {
             devServer.config.logger.warnOnce(`Forgebook leaves out ${file}: Vite's server.fs refuses it`);
             return false;
         },
-        isRefused: (id) => {
+        settle: async (url) => {
+            const id = groupIdOf(url);
+            if (id === undefined || devServer === undefined || sourcesEntry === undefined)
+                return;
+            if (imported.has(namingGroupOf(id)))
+                return;
+            sourcesRead ??= readImports(devServer.environments.client, sourcesEntry).then((isRead) => {
+                if (!isRead)
+                    sourcesRead = undefined;
+            });
+            await sourcesRead;
+        },
+        refusal: (id) => {
             if (devServer === undefined)
-                return false;
+                return undefined;
             if (!isGroupId(id))
-                return (FILE_QUERIES.some((query) => id.endsWith(query)) && !isQueriedFileReadable(devServer.config, id));
-            if (imported.has(id))
-                return false;
-            refused.add(id);
-            return true;
+                return FILE_QUERIES.some((query) => id.endsWith(query)) &&
+                    !isQueriedFileReadable(devServer.config, id)
+                    ? { code: "export default null;", moduleType: "js" }
+                    : undefined;
+            if (imported.has(namingGroupOf(id)))
+                return undefined;
+            throw Object.assign(new Error(`Forgebook serves a group of files only when a module imports it: no module of the project imports ${id.slice(1)}`), { code: MISSING_MODULE });
         }
     };
 };
+/**
+ * The plugin's hook for Vitest (`configureVitest`), whose module cache keeps each module's transform on disk between
+ * runs: a module read from it resolves no import, so a group it names would stay refused from the second run on.
+ */
+export const VITEST_HOOKS = {
+    configureVitest: (context) => {
+        context.defineCacheKeyGenerator?.(({ sourceCode }) => (namesGroup(sourceCode) ? false : undefined));
+    }
+};

package/dist/src/vite/forgebookPlugin.js

@@ -33,7 +33,7 @@ import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
 import { codeStamp, diskCache } from "./diskCache.js";
 import { createDocsExtractor, NO_DOCS_EXTRACTOR } from "./docsExtractor.js";
-import { devServerAccess } from "./fileAccess.js";
+import { devServerAccess, VITEST_HOOKS } from "./fileAccess.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
 import { builtPlacement } from "./framesConfig.js";
 import { serveFrames } from "./framesServer.js";
@@ -137,7 +137,7 @@ export const forgebookPlugin = (options = {}) => {
     /** The groups' search indexes: any edit may change what a component's docs say. */
     const searchModules = new Set();
     /** What a client may read of a dev server. */
-    const access = devServerAccess(invalidateEverywhere);
+    const access = devServerAccess();
     /** The errors the open frames report, for `forgebook errors` and the agents. */
     const live = createLiveErrors();
     /** Where the frames run: the dev server's second port once it listens, the configuration's choice in a build. */
@@ -392,7 +392,10 @@ export const forgebookPlugin = (options = {}) => {
                 resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
         },
         configureServer: (server) => {
-            access.serve(server);
+            access.serve(server, config === undefined ? undefined : pageModulePath(config.dir, AGENT_SOURCES_FILE));
+            server.middlewares.use((request, _response, next) => {
+                access.settle(request.url ?? "/").then(() => next(), next);
+            });
             // no person waits for a page in a test run
             watching.serve(isTestRun ? undefined : server);
             server.httpServer?.on("close", () => void docs?.close());
@@ -466,13 +469,14 @@ export const forgebookPlugin = (options = {}) => {
             await docs?.close();
         },
         ...storyFileHotHooks(isRedrawing, served.changedBy, watching),
+        ...VITEST_HOOKS,
         async load(id) {
             const generated = await pagesModule(id);
             if (generated !== undefined)
                 return generated;
-            // an answer, not an error: an error would raise Vite's overlay on every reader's open page
-            if (access.isRefused(id))
-                return { code: "export default null;", moduleType: "js" };
+            const refusal = access.refusal(id);
+            if (refusal !== undefined)
+                return refusal;
             // in Vite's form, the text Vite's module graph knows a file by: a Node path on Windows (`C:\app\x.md`) is another
             const watch = (file) => this.addWatchFile(VITE_PATHS.normalize(file));
             const resolveImport = async (specifier, importer) => {