forgebook 0.2.0 → 0.3.0

package/dist/src/vite/docPagesModule.js

@@ -1,5 +1,6 @@
 /**
- * The modules that answer a `?forgebook-docs-pages` import: every page a pattern matches as one module with each page's
+ * The modules that answer a group of docs pages, a `?forgebook-docs-pages` import's pattern or a catalogue's `docs`
+ * list (`DOCS_PAGES_SPECIFIER_PREFIX`): every page the group lists as one module with each page's
  * index, and the loader of the page itself, and each page's own module.
  *
  * @remarks
@@ -15,7 +16,7 @@ import { codeLiteral } from "../codeLiteral.js";
 import { readLinkedFile } from "./docPageLinks.js";
 import { compiledDocPage, compiledHome, docPageIndex } from "./docPageMarkdown.js";
 import { pluginFences } from "./pluginConfig.js";
-import { PAGES_SEARCH_PREFIX, storyFileKeys, storyFilesGroupText } from "./storyFilesModule.js";
+import { EVERY_FILE, PAGES_SEARCH_PREFIX, storyFileKeys, storyFilesGroupText } from "./storyFilesModule.js";
 import { DOCS_PAGE_QUERY } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** Reads a linked page, watching it: its title makes the link's address, so a new title renews the page that links. */
@@ -26,15 +27,16 @@ const watchedRead = (watch) => (file) => {
     return text;
 };
 /**
- * Every page a pattern matches, indexed.
+ * Every page a group's patterns list, indexed.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the patterns, `!` ones included (`listedFiles`).
  * @param watch - adds a file whose edit renews the module that read it.
  * @param fences - the fences the catalogue's plugins draw, which are not code; none by default.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export const indexedDocPages = (root, pattern, watch, fences = []) => {
-    return storyFileKeys(root, [pattern]).map((key) => {
+export const indexedDocPages = (root, patterns, watch, fences = [], isKept = EVERY_FILE) => {
+    return storyFileKeys(root, patterns, isKept).map((key) => {
         const file = resolve(root, key);
         watch(file);
         return { key, file, index: docPageIndex(file, readFileSync(file, "utf8"), watchedRead(watch), fences) };
@@ -43,20 +45,21 @@ export const indexedDocPages = (root, pattern, watch, fences = []) => {
 /** An object literal of a key per page, each value written by `value`. */
 const objectOf = (keys, value) => `{${keys.map((key) => `${codeLiteral(key)}: ${value(key)}`).join(",\n")}}`;
 /**
- * The code of the module for one pattern.
+ * The code of the module for one group.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern before `?forgebook-docs-pages`.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module (each page: its index is in the module).
  * @param isServing - whether a dev server runs, whose tools read a page's Markdown.
  * @param plugins - the catalogue's plugins, whose fences a page may draw; none by default.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export const docPagesModule = (root, pattern, watch, isServing, plugins = []) => {
-    const pages = indexedDocPages(root, pattern, watch, pluginFences(plugins));
+export const docPagesModule = (root, patterns, watch, isServing, plugins = [], isKept = EVERY_FILE) => {
+    const pages = indexedDocPages(root, patterns, watch, pluginFences(plugins), isKept);
     const keys = pages.map((page) => page.key);
     const index = Object.fromEntries(pages.map((page) => [page.key, page.index]));
     const page = (key) => codeLiteral(`${VITE_PATHS.resolve(root, key)}${DOCS_PAGE_QUERY}`);
-    const search = codeLiteral(`${PAGES_SEARCH_PREFIX}${storyFilesGroupText(root, pattern)}`);
+    const search = codeLiteral(`${PAGES_SEARCH_PREFIX}${storyFilesGroupText(root, patterns)}`);
     return [
         "export default {",
         `index: ${codeLiteral(index)},`,

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

@@ -101,6 +101,12 @@ export type DocsExtractorOptions = {
  * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
  */
 export declare const IDLE_MS: number;
+/**
+ * The extractor of a catalogue that reads no component docs (`componentDocs: false`): it starts no worker and builds no
+ * TypeScript program, answers every story file as one whose meta names no component, and every group's usage with why
+ * there is none.
+ */
+export declare const NO_DOCS_EXTRACTOR: DocsExtractor;
 /**
  * A docs extractor with its worker, started on its first request.
  *

package/dist/src/vite/docsExtractor.js

@@ -62,6 +62,19 @@ const codeStampOf = (docsModule) => {
         return undefined;
     }
 };
+/**
+ * The extractor of a catalogue that reads no component docs (`componentDocs: false`): it starts no worker and builds no
+ * TypeScript program, answers every story file as one whose meta names no component, and every group's usage with why
+ * there is none.
+ */
+export const NO_DOCS_EXTRACTOR = {
+    extract: () => Promise.resolve({ docs: { name: null } }),
+    usage: () => Promise.resolve("The catalogue reads no component docs (componentDocs: false)"),
+    warm: () => undefined,
+    changed: () => undefined,
+    listed: () => undefined,
+    close: () => Promise.resolve()
+};
 /**
  * A docs extractor with its worker, started on its first request.
  *

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

@@ -0,0 +1,51 @@
+import { type ResolvedConfig, type ViteDevServer } from "vite";
+import type { IsFileKept } from "./storyFilesModule.ts";
+/**
+ * Whether Vite refuses a listed file whatever `server.fs.allow` says: `deny`, or a path it will not trust (a `:` in it).
+ * Vite offers no check of this step alone, so this asks its whole check with an `allow` that covers the file.
+ *
+ * @param config - the dev server's configuration.
+ * @param file - the file, absolute in Vite's form.
+ */
+export declare const isFileRefused: (config: ResolvedConfig, file: string) => boolean;
+/**
+ * Whether a dev server may read the file a query's id names. An id Vite resolved is normalised; one with a `..` came
+ * from an address unresolved, and Vite's check reads a path as written, so `/project/../secret` would pass for a file
+ * of `/project`.
+ *
+ * @param config - the dev server's configuration.
+ * @param id - the module's id, the file and then its query.
+ */
+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;
+    /**
+     * Whether a resolver's importer is a module, not the stand-in Vite gives an address asked for directly.
+     *
+     * @param importer - the importer the resolver was given.
+     */
+    readonly isModule: (importer: string | undefined) => importer is string;
+    /**
+     * Notes that a module imports a group, whose id is now served.
+     *
+     * @param id - the group module's id.
+     */
+    readonly noteImported: (id: string) => void;
+    /** 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`.
+     *
+     * @param id - the module's id.
+     */
+    readonly isRefused: (id: string) => boolean;
+};
+/**
+ * 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.
+ */
+export declare const devServerAccess: (renew: (server: ViteDevServer, ids: Iterable<string>) => void) => DevServerAccess;

package/dist/src/vite/fileAccess.js

@@ -0,0 +1,109 @@
+/**
+ * What a dev server's plugin may read for a client, by Vite's own `server.fs` and by what the project imports: a
+ * plugin's answer never passes through Vite's check, so each read an address can name asks here first.
+ *
+ * @remarks
+ * Vite's rule is two steps. The first refuses a file whatever else holds (`server.fs.deny`, a path it will not trust).
+ * Past it, a file is served when `allow` covers it or a module of the project imports it. A group of story files or
+ * docs pages is what a module of the project imports, so it keeps to the first step alone: a catalogue's `../src` may be
+ * outside `allow`, and Vite serves its files all the same. A query names one file in the address, so it asks both steps:
+ * Vite has recorded the file by then if a module imports it.
+ *
+ * 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`.
+ *
+ * @module
+ */
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { isFileLoadingAllowed } from "vite";
+import { isGroupId } 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. */
+const FILE_QUERIES = [
+    DOCS_QUERY,
+    CODE_QUERY,
+    PAGE_QUERY,
+    MARKDOWN_QUERY,
+    DOCS_PAGE_QUERY,
+    HOME_QUERY
+];
+/**
+ * A listed file's real path, in Vite's form. Vite refuses a Windows short name (`RUNNER~1`), which could dodge `deny`,
+ * and a system's temporary folder is often written with one: the long name lets the file be judged by what it is. So
+ * does a link's target, which is the file that would be read.
+ *
+ * @param file - the file, absolute.
+ */
+const realFile = (file) => {
+    try {
+        return VITE_PATHS.normalize(realpathSync.native(file));
+    }
+    catch {
+        return file;
+    }
+};
+/**
+ * Whether Vite refuses a listed file whatever `server.fs.allow` says: `deny`, or a path it will not trust (a `:` in it).
+ * Vite offers no check of this step alone, so this asks its whole check with an `allow` that covers the file.
+ *
+ * @param config - the dev server's configuration.
+ * @param file - the file, absolute in Vite's form.
+ */
+export const isFileRefused = (config, file) => {
+    const real = realFile(file);
+    const fs = { ...config.server.fs, allow: [VITE_PATHS.dirname(real)] };
+    return !isFileLoadingAllowed({ ...config, server: { ...config.server, fs } }, real);
+};
+/**
+ * Whether a dev server may read the file a query's id names. An id Vite resolved is normalised; one with a `..` came
+ * from an address unresolved, and Vite's check reads a path as written, so `/project/../secret` would pass for a file
+ * of `/project`.
+ *
+ * @param config - the dev server's configuration.
+ * @param id - the module's id, the file and then its query.
+ */
+export const isQueriedFileReadable = (config, id) => {
+    const file = id.slice(0, id.lastIndexOf("?"));
+    return VITE_PATHS.normalize(file) === file && isFileLoadingAllowed(config, file);
+};
+/**
+ * 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.
+ */
+export const devServerAccess = (renew) => {
+    let devServer;
+    let addressImporter;
+    const imported = new Set();
+    const refused = new Set();
+    return {
+        serve: (server) => {
+            devServer = server;
+            addressImporter = join(server.config.root, "index.html");
+        },
+        isModule: (importer) => importer !== undefined && importer !== addressImporter,
+        noteImported: (id) => {
+            imported.add(id);
+            if (refused.delete(id) && devServer !== undefined)
+                renew(devServer, [id]);
+        },
+        isKept: (file) => {
+            if (devServer === undefined || !isFileRefused(devServer.config, file))
+                return true;
+            devServer.config.logger.warnOnce(`Forgebook leaves out ${file}: Vite's server.fs refuses it`);
+            return false;
+        },
+        isRefused: (id) => {
+            if (devServer === undefined)
+                return false;
+            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;
+        }
+    };
+};

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

@@ -1,4 +1,4 @@
-import { type Plugin } from "vite";
+import type { Plugin } from "vite";
 import type { FrameworkAdapter } from "./adapter.ts";
 import { type ResolvedConfig } from "./configFile.ts";
 /** The plugin's options. */

package/dist/src/vite/forgebookPlugin.js

@@ -13,38 +13,40 @@
  * come the same way, with `?forgebook-docs-pages` (`docPagesModule.ts`), and the written home with `?forgebook-home`. It also sets Lightning CSS as the CSS transformer with the forced-states visitor (`forcedStates.ts`) and lets Sass resolve
  * `pkg:` URLs, which the library's style sheets use.
  *
- * A pattern's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
+ * A group's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
  * sources' story files live in other packages: `watch` names their folders, and a story file added or removed there
- * renews every pattern's module and reloads the page, so the sidebar lists it at once.
+ * renews the modules of the groups whose list it changes and reloads the page, so the sidebar lists it at once; one no
+ * group lists (a `!` pattern leaves it out) reloads nothing.
  *
  * @module
  */
-import { existsSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
-import { isFileLoadingAllowed } from "vite";
+import { checksA11y, offersUsedIn, readsComponentDocs } from "../catalogue.js";
 import { SAME_ORIGIN } from "../frameOrigins.js";
 import { createLiveErrors, isLiveErrorReport, LIVE_ERROR_EVENT } from "../liveErrors.js";
 import { agentMiddleware, FRAMED_AGENT_PAGES } from "./agentRoutes.js";
 import { STORY_FILE } from "./autoTitle.js";
-import { axeAddress, axeBuildAsset } from "./axeScript.js";
+import { axeBuildAsset } from "./axeScript.js";
 import { groupTexts } from "./builtTexts.js";
 import { catalogueConfig } from "./catalogueConfig.js";
 import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
 import { codeStamp, diskCache } from "./diskCache.js";
-import { createDocsExtractor } from "./docsExtractor.js";
+import { createDocsExtractor, NO_DOCS_EXTRACTOR } from "./docsExtractor.js";
+import { devServerAccess } from "./fileAccess.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
 import { builtPlacement } from "./framesConfig.js";
 import { serveFrames } from "./framesServer.js";
+import { generatedId, generatedModule } from "./generatedModules.js";
 import { missingHeightsMiddleware } from "./heightsRoute.js";
 import { FILES_MODULE_HOT, renewedModule, servedPatterns, storyFileHotHooks } from "./hotSnippets.js";
 import { inlineJson, packedJsonOf } from "./packedModule.js";
-import { AGENT_SOURCES_FILE, agentSourcesModule, configModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, shellEntry, storiesSourceModule } from "./pages.js";
+import { AGENT_SOURCES_FILE, configModule, PAGE_FILES, pageHtml, pageModulePath } from "./pages.js";
 import { CONFIG_ID, DOCS_PAGES_PREFIX, patternId, TOKENS_ID, virtualId } from "./pluginIds.js";
-import { docsModule, docsValue, FILES_PREFIX, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
+import { docsModule, docsValue, FILES_PREFIX, listingRenewals, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
 import { isKeptIndex, storyFilesGroupOf } from "./storyFilesModule.js";
 import { tokensModule } from "./storylessRoutes.js";
-import { CODE_QUERY, DOCS_PAGE_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
+import { DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, RENEWED_QUERIES, TEXT_QUERIES } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** This module's folder, in the core's package: the core's own dependencies resolve from here, not the project's. */
 const PACKAGE_DIR = import.meta.dirname;
@@ -62,31 +64,6 @@ const sassOptions = async () => {
 const DOCS_PAGE_FILE = /\.md$/;
 /** A TypeScript source file, whose edit may change a component's docs. */
 const SOURCE_FILE = /\.tsx?$/;
-/** The query that asks for a story file's component docs. */
-const DOCS_QUERY = "?forgebook-docs";
-/** The queries `textModules.ts` answers. */
-const TEXT_QUERIES = [CODE_QUERY, PAGE_QUERY, MARKDOWN_QUERY];
-/** The queries of a story file's modules the shell reads, which hand an edit to it in place on a dev server. */
-const RENEWED_QUERIES = [DOCS_QUERY, CODE_QUERY, PAGE_QUERY];
-/** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
-const FILE_QUERIES = [
-    DOCS_QUERY,
-    CODE_QUERY,
-    PAGE_QUERY,
-    MARKDOWN_QUERY,
-    DOCS_PAGE_QUERY,
-    HOME_QUERY
-];
-/**
- * Whether a dev server may read the file a query names: a plugin's answer never passes Vite's own check of
- * `server.fs`, so without this any file could be asked for by adding a query to its address.
- *
- * @param id - the module's id.
- * @param server - the dev server; none in a build, which reads only what the sources import.
- */
-const isReadable = (id, server) => server === undefined ||
-    !FILE_QUERIES.some((query) => id.endsWith(query)) ||
-    isFileLoadingAllowed(server.config, id.slice(0, id.lastIndexOf("?")));
 /**
  * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
  *
@@ -120,8 +97,9 @@ const requestedPage = (url) => {
  * @param watch - adds a file whose edit renews the module.
  * @param isServing - whether a dev server runs.
  * @param plugins - the catalogue's plugins, whose fences a page may draw.
+ * @param isKept - whether a page its group lists may be read.
  */
-const docsModuleOf = async (id, watch, isServing, plugins) => {
+const docsModuleOf = async (id, watch, isServing, plugins, isKept) => {
     const isHome = id.endsWith(HOME_QUERY);
     const isPage = id.endsWith(DOCS_PAGE_QUERY);
     if (!isHome && !isPage && !id.startsWith(DOCS_PAGES_PREFIX))
@@ -133,47 +111,8 @@ const docsModuleOf = async (id, watch, isServing, plugins) => {
         const file = id.slice(0, -DOCS_PAGE_QUERY.length);
         return { code: docPageModule(file, watch, isServing, plugins), moduleType: "js" };
     }
-    const { root, pattern } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
-    return { code: docPagesModule(root, pattern, watch, isServing, plugins), moduleType: "js" };
-};
-/**
- * A module the plugin generates for a catalogue's pages, when the id names one: an entry, the project's own stories'
- * source, or a page's HTML (unless the folder has one of its own). The configuration's data waits for the frames'
- * placement, so the plugin's `load` makes it.
- *
- * @param id - the module's id.
- * @param config - the catalogue's configuration.
- * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
- */
-const generatedModule = (id, config, command) => {
-    const named = pageModuleOf(id, config.dir);
-    if (named === undefined)
-        return undefined;
-    if (named.kind === "entry") {
-        const code = named.page === "index.html" ? shellEntry(config) : frameEntry(config, axeAddress(command, PACKAGE_DIR));
-        return { code, moduleType: "js" };
-    }
-    if (named.kind === "stories-source")
-        return { code: storiesSourceModule(config), moduleType: "js" };
-    if (named.kind === "agent-sources")
-        return { code: agentSourcesModule(config), moduleType: "js" };
-    return existsSync(id) ? undefined : pageHtml(named.page, config, builtPlacement(config.frames));
-};
-/**
- * The id of a module the plugin generates for a catalogue's pages, when an import names one: a page or an entry by
- * its address (`/index.html`, `/.forgebook-shell.ts`) or by its path, a source by its path.
- *
- * @param source - the import's specifier.
- * @param dir - the configuration's folder.
- */
-const generatedId = (source, dir) => {
-    const byAddress = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}`);
-    if (byAddress !== undefined)
-        return pageModulePath(dir, PAGE_ENTRIES[byAddress]);
-    const pageByAddress = PAGE_FILES.find((page) => source === `/${page}`);
-    if (pageByAddress !== undefined)
-        return pageModulePath(dir, pageByAddress);
-    return pageModuleOf(source, dir) === undefined ? undefined : VITE_PATHS.normalize(source);
+    const { root, patterns } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
+    return { code: docPagesModule(root, patterns, watch, isServing, plugins, isKept), moduleType: "js" };
 };
 /**
  * The catalogue's Vite plugin: the story index, the docs, the code and the Markdown of the stories, the forced-states
@@ -184,8 +123,11 @@ const generatedId = (source, dir) => {
  * @returns the plugin, for the app's `plugins`.
  */
 export const forgebookPlugin = (options = {}) => {
-    /** The modules of the patterns, renewed when a story file is added or removed. */
-    const filesModules = new Set();
+    /**
+     * The modules of the groups of story files, with the files each listed when served (none while it could not be
+     * made), renewed when a story file is added to or removed from what one lists.
+     */
+    const filesModules = new Map();
     // what each pattern's module was served with: an edit of a story file that changes its list reloads the pages
     const served = servedPatterns();
     /** The groups' "Used in" modules, renewed when a source file changes: any edit may change what reaches what. */
@@ -194,6 +136,8 @@ export const forgebookPlugin = (options = {}) => {
     const docsModules = new Set();
     /** 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);
     /** 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. */
@@ -212,8 +156,6 @@ export const forgebookPlugin = (options = {}) => {
             return { code: configModule(config, await framesPlacement()), moduleType: "js" };
         return generatedModule(id, config, command);
     };
-    /** The dev server; none in a build. */
-    let devServer;
     /** The files followed one by one, so an edit reaches the dev server at once. */
     const watching = currentCloseWatch();
     /** Whether a dev server runs, or a build: tools ask only the former. */
@@ -223,7 +165,8 @@ export const forgebookPlugin = (options = {}) => {
     const search = searchIndexes({
         extract: (storyFile) => extractor().extract(storyFile),
         isServing,
-        track: (id, isPages) => (isPages ? docsModules : searchModules).add(id)
+        track: (id, isPages) => (isPages ? docsModules : searchModules).add(id),
+        isKept: access.isKept
     });
     // a build's docs, code and pages of each group's story files, read while the build loads the stories
     const texts = groupTexts();
@@ -258,6 +201,9 @@ export const forgebookPlugin = (options = {}) => {
     // build and would hold every other answer of the dev server meanwhile
     let docs;
     const extractor = () => {
+        // a catalogue that reads no component docs never starts the worker: its programs are most of the server's memory
+        if (config !== undefined && !readsComponentDocs(config.lists))
+            return NO_DOCS_EXTRACTOR;
         const framework = config?.framework ?? options.framework;
         if (framework === undefined)
             throw new Error("Forgebook has no framework: add forgebook.config.ts, or give the plugin `framework`");
@@ -294,21 +240,23 @@ export const forgebookPlugin = (options = {}) => {
     const storiesModule = async (id, watch, pack, startTexts) => {
         if (id.startsWith(USAGE_ID_PREFIX)) {
             usageModules.add(id);
-            return usageModule(id, watch, extractor().usage, indexCache(), pack);
+            return usageModule(id, watch, extractor().usage, indexCache(), pack, access.isKept);
         }
         // what each story reaches is for the dev server's tools only: a build ships none of it
         if (id.startsWith(REACH_ID_PREFIX)) {
             usageModules.add(id);
             return isServing()
-                ? reachModule(id, watch, extractor().usage, indexCache())
+                ? reachModule(id, watch, extractor().usage, indexCache(), access.isKept)
                 : { code: "export default [];", moduleType: "js" };
         }
         if (!id.startsWith(FILES_PREFIX))
             return undefined;
-        filesModules.add(id);
-        const hasUsage = config?.lists.usedIn !== false;
+        filesModules.set(id, undefined);
+        const lists = config?.lists ?? {};
+        const hasUsage = offersUsedIn(lists);
         // the worker starts while Vite loads the pages, unless the disk keeps the docs; a test run asks for no page
-        const { files, code } = patternModule(id, watch, { hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts);
+        const { files, code } = patternModule(id, watch, { hasDocs: readsComponentDocs(lists), hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts, access.isKept);
+        filesModules.set(id, new Set(files.map((file) => file.file)));
         if (!isRedrawing())
             return { code, moduleType: "js" };
         served.keep(id, files);
@@ -333,9 +281,9 @@ export const forgebookPlugin = (options = {}) => {
      * @param file - the file.
      */
     const modulesListing = (file) => {
-        // the patterns' modules list the story files; the groups' "Used in" read them
+        // the groups' modules list the story files, their "Used in" and search indexes read them
         if (STORY_FILE.test(file))
-            return [...filesModules, ...usageModules, ...searchModules];
+            return listingRenewals(filesModules, file, [...usageModules, ...searchModules], access.isKept);
         return DOCS_PAGE_FILE.test(file) && docsModules.size > 0 ? [...docsModules] : undefined;
     };
     /**
@@ -356,7 +304,7 @@ export const forgebookPlugin = (options = {}) => {
         }
         if (id.startsWith(DOCS_PAGES_PREFIX))
             docsModules.add(id);
-        const docsPages = await docsModuleOf(id, watch, isServing(), config?.plugins ?? []);
+        const docsPages = await docsModuleOf(id, watch, isServing(), config?.plugins ?? [], access.isKept);
         if (docsPages !== undefined)
             return docsPages;
         if (!TEXT_QUERIES.some((query) => id.endsWith(query)))
@@ -380,7 +328,13 @@ export const forgebookPlugin = (options = {}) => {
         const pack = emit === undefined ? inlineJson : packedJsonOf(emit);
         const componentFiles = (config?.framework ?? options.framework)?.componentFiles;
         const docsOf = async (storyFile) => docsValue(await search.docsOf(storyFile), watch);
-        const sources = { docsOf, watch, resolveImport, componentFiles };
+        const hasDocs = config === undefined || readsComponentDocs(config.lists);
+        const sources = {
+            docsOf: hasDocs ? docsOf : undefined,
+            watch,
+            resolveImport,
+            componentFiles
+        };
         // a build's browser files only: a dev server answers each text from its query, and no texts module
         const startTexts = emit === undefined ? undefined : texts.starter(id, sources);
         return ((emit === undefined ? undefined : await texts.moduleOf(id, sources, emit)) ??
@@ -410,13 +364,23 @@ export const forgebookPlugin = (options = {}) => {
             };
         },
         resolveId(source, importer) {
+            const isModule = access.isModule(importer);
             const virtual = virtualId(source);
-            if (virtual !== undefined)
+            if (virtual !== undefined) {
+                if (isModule)
+                    access.noteImported(virtual);
                 return virtual;
+            }
             const generated = config === undefined ? undefined : generatedId(source, config.dir);
             if (generated !== undefined)
                 return generated;
-            return importer === undefined ? null : patternId(source, VITE_PATHS.dirname(importer));
+            if (!access.isModule(importer))
+                return null;
+            // the importer's file: its id may carry whatever query an address gave it
+            const pattern = patternId(source, VITE_PATHS.dirname(importer.split("?")[0] ?? importer));
+            if (pattern !== null)
+                access.noteImported(pattern);
+            return pattern;
         },
         // a warning and not a failure: a theme a reader can still use must not stop a catalogue from building
         configResolved: (resolved) => {
@@ -428,7 +392,7 @@ export const forgebookPlugin = (options = {}) => {
                 resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
         },
         configureServer: (server) => {
-            devServer = server;
+            access.serve(server);
             // no person waits for a page in a test run
             watching.serve(isTestRun ? undefined : server);
             server.httpServer?.on("close", () => void docs?.close());
@@ -469,7 +433,7 @@ export const forgebookPlugin = (options = {}) => {
                     .catch(next);
             });
             // folders outside the configuration's are watched only when named; a story file added or removed anywhere the
-            // server watches (its own folder, a story file it loaded) renews the lists either way
+            // server watches (its own folder, a story file it loaded) renews the lists that change either way
             const watched = [...(config?.watch ?? []), ...(options.watch ?? [])];
             if (watched.length > 0)
                 server.watcher.add(watched);
@@ -488,7 +452,8 @@ export const forgebookPlugin = (options = {}) => {
             // axe's script, for the frames' Accessibility card: loaded by the frame, never imported; the browser's build only
             if (this.environment.name !== "client")
                 return;
-            const axe = config === undefined ? undefined : axeBuildAsset(PACKAGE_DIR);
+            // a catalogue that checks no accessibility ships none of it
+            const axe = config === undefined || !checksA11y(config.lists) ? undefined : axeBuildAsset(PACKAGE_DIR);
             if (axe !== undefined)
                 this.emitFile({ type: "asset", fileName: axe.fileName, source: axe.source });
         },
@@ -506,7 +471,7 @@ export const forgebookPlugin = (options = {}) => {
             if (generated !== undefined)
                 return generated;
             // an answer, not an error: an error would raise Vite's overlay on every reader's open page
-            if (!isReadable(id, devServer))
+            if (access.isRefused(id))
                 return { code: "export default null;", moduleType: "js" };
             // 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));

package/dist/src/vite/framesServer.js

@@ -45,6 +45,20 @@ export const hostOf = (request) => headerOf(request, "host") ?? headerOf(request
  * @param url - the request's address.
  */
 const isProxied = (proxy, url) => Object.keys(proxy ?? {}).some((key) => key.startsWith("^") ? new RegExp(key).test(url) : url.startsWith(key));
+/**
+ * A request's path as an address parser reads it, which is how the routes behind the guards read it: a guard that read
+ * `//x/__forgebook/api/stories` as written would pass what the route answers as `/__forgebook/api/stories`.
+ *
+ * @param url - the request's address, as it was sent.
+ */
+const parsedPath = (url) => {
+    try {
+        return new URL(url, "http://parsed.invalid").pathname;
+    }
+    catch {
+        return (url.split("?")[0] ?? url).split("#")[0] ?? "/";
+    }
+};
 /**
  * What the browser says of a request.
  *
@@ -54,7 +68,7 @@ const factsOf = (request) => {
     const url = request.url ?? "/";
     const queryAt = url.indexOf("?");
     return {
-        path: (queryAt === -1 ? url : url.slice(0, queryAt)).split("#")[0] ?? "/",
+        path: parsedPath(url),
         query: queryAt === -1 ? "" : (url.slice(queryAt).split("#")[0] ?? ""),
         site: headerOf(request, "sec-fetch-site"),
         mode: headerOf(request, "sec-fetch-mode"),
@@ -83,14 +97,16 @@ const isPublicFile = (publicDir, path) => {
     return file.startsWith(`${publicDir}${sep}`) && existsSync(file) && statSync(file).isFile();
 };
 /**
- * Whether a module's code, as Vite served it, names an address: how a worker's file (`?worker_file`) is started.
+ * Whether a module the catalogue imports names an address in its code, as a whole string: how a worker's file
+ * (`?worker_file`) is started. Only an imported module counts, and only a whole string: an address asked for directly
+ * writes its own query into its module's code (its HMR context), and a story's script could plant any address there.
  *
  * @param modules - the graph's modules.
  * @param url - the address, as the graph reads it; its `t=` left out.
  */
 const isNamedInCode = (modules, url) => {
-    const named = url.replace(/[?&]t=\d+/, "");
-    return modules.some((module) => module.transformResult?.code.includes(named) === true);
+    const named = JSON.stringify(url.replace(/[?&]t=\d+/, ""));
+    return modules.some((module) => module.importers.size > 0 && module.transformResult?.code.includes(named) === true);
 };
 /**
  * Ends a request the guards turned down, with its status and nothing a page could use.
@@ -204,7 +220,7 @@ export const framesServing = (server, frames, frameHtml, framedPages) => {
             next();
             return;
         }
-        const answer = catalogueAnswer(factsOf(request), framedPages);
+        const answer = catalogueAnswer(factsOf(request), framedPages, (path) => isPublicFile(server.config.publicDir, path));
         if (answer === "refuse") {
             turnDown(response, 403);
             return;