forgebook 0.2.0 → 0.3.0

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

@@ -0,0 +1,23 @@
+import type { ConfigEnv } from "vite";
+import type { ResolvedConfig } from "./configFile.ts";
+/**
+ * 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.
+ */
+export declare const generatedModule: (id: string, config: ResolvedConfig, command: ConfigEnv["command"]) => {
+    code: string;
+    moduleType: "js";
+} | string | undefined;
+/**
+ * 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.
+ */
+export declare const generatedId: (source: string, dir: string) => string | undefined;

package/dist/src/vite/generatedModules.js

@@ -0,0 +1,58 @@
+/**
+ * The modules the plugin generates for a catalogue's pages: the shell's and the frame's entries, the project's own
+ * stories' source, the agents' sources and the pages' HTML, and the ids imports name them by.
+ *
+ * @remarks
+ * The configuration's data is not among them: it waits for the frames' placement, which only the plugin knows.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { checksA11y } from "../catalogue.js";
+import { axeAddress } from "./axeScript.js";
+import { builtPlacement } from "./framesConfig.js";
+import { agentSourcesModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, shellEntry, storiesSourceModule } from "./pages.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The core's folder, where axe's script is found from. */
+const PACKAGE_DIR = import.meta.dirname;
+/**
+ * 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.
+ */
+export 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, checksA11y(config.lists) ? axeAddress(command, PACKAGE_DIR) : undefined);
+        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.
+ */
+export 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);
+};

package/dist/src/vite/hotSnippets.js

@@ -105,10 +105,14 @@ const readIndex = (root, pattern, key) => {
 };
 /** The patterns' modules a dev server serves, kept to tell an edit that changes a list. */
 export const servedPatterns = () => {
+    // by group, each story file as served: its key, the pattern that lists it, its index
     const served = new Map();
     return {
         keep: (id, files) => {
-            served.set(id, new Map(files.map((file) => [file.file, { key: file.key, index: JSON.stringify(file.index) }])));
+            served.set(id, new Map(files.map((file) => [
+                file.file,
+                { key: file.key, pattern: file.pattern, index: JSON.stringify(file.index) }
+            ])));
         },
         changedBy: (file) => [...served]
             .filter(([id, files]) => {
@@ -116,8 +120,8 @@ export const servedPatterns = () => {
             const kept = files.get(VITE_PATHS.normalize(file));
             if (kept === undefined)
                 return false;
-            const { root, pattern } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
-            const index = readIndex(root, pattern, kept.key);
+            const { root } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
+            const index = readIndex(root, kept.pattern, kept.key);
             return typeof index !== "string" && JSON.stringify(index) !== kept.index;
         })
             .map(([id]) => id)

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

@@ -17,8 +17,8 @@
  *
  * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
  * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
- * the story loads. `touch`, `logic`, `device`, `design.figma` and the meta's `propGroups` are read by the index only
- * (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
+ * the story loads. `touch`, `logic`, `device`, `requiredFirst`, `design.figma` and the meta's `propGroups` are read by
+ * the index only (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
  * A `design.figma` is checked here too, so the pages never carry the checker: one that is not a link to a Figma file is
  * noted and left out, and the file keeps its stories. A title written by code, or none, is the file's path
  * (`autoTitle`, as Storybook's auto-title); one written by code is also noted, since the author meant another. A value written plainly but wrongly

package/dist/src/vite/indexStoryFile.js

@@ -17,8 +17,8 @@
  *
  * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
  * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
- * the story loads. `touch`, `logic`, `device`, `design.figma` and the meta's `propGroups` are read by the index only
- * (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
+ * the story loads. `touch`, `logic`, `device`, `requiredFirst`, `design.figma` and the meta's `propGroups` are read by
+ * the index only (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
  * A `design.figma` is checked here too, so the pages never carry the checker: one that is not a link to a Figma file is
  * noted and left out, and the file keeps its stories. A title written by code, or none, is the file's path
  * (`autoTitle`, as Storybook's auto-title); one written by code is also noted, since the author meant another. A value written plainly but wrongly

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

@@ -1,7 +1,7 @@
 import type { StoryIndexEntry } from "@forgebook/story-format/source";
 import { type Fields } from "./indexFields.ts";
 /** What the index keeps of these parameters: each only when written. */
-export type IndexedParameters = Pick<StoryIndexEntry, "isTouch" | "isLogic" | "device">;
+export type IndexedParameters = Pick<StoryIndexEntry, "isTouch" | "isLogic" | "device" | "requiredFirst">;
 /**
  * The parameters only the index reads, each only when written, or the first problem.
  *

package/dist/src/vite/indexedParameters.js

@@ -1,4 +1,5 @@
 import { deviceSettingProblem, isDeviceOrientation } from "../deviceView.js";
+import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
 import { keyName, parameter, unwrapped } from "./indexFields.js";
 /** Why `parameters.device` cannot be read as it is written. */
 const DEVICE_PROBLEM = '`parameters.device` must be written as a plain object (`{ frame: true, model: "iphone-16" }`)';
@@ -87,6 +88,21 @@ const deviceOf = (value) => {
     const problem = deviceSettingProblem(setting);
     return problem === undefined ? setting : new Error(`\`parameters.device\`: ${problem}`);
 };
+/**
+ * `parameters.requiredFirst`: `undefined` when none, `"in-groups"`, `"section"` or `false` written plainly, or a
+ * problem otherwise.
+ *
+ * @param value - the parameter's value.
+ */
+const requiredFirstOf = (value) => {
+    if (value === undefined)
+        return undefined;
+    const written = value.type === "Literal" ? value.value : undefined;
+    const layout = REQUIRED_FIRST_LAYOUTS.find((each) => each === written);
+    if (layout !== undefined)
+        return layout;
+    return new Error('`parameters.requiredFirst` must be written as a plain `"in-groups"`, `"section"` or `false`');
+};
 /**
  * The parameters only the index reads, each only when written, or the first problem.
  *
@@ -102,9 +118,13 @@ export const indexedParameters = (fields) => {
     const device = deviceOf(parameter(fields, "device"));
     if (device instanceof Error)
         return device;
+    const requiredFirst = requiredFirstOf(parameter(fields, "requiredFirst"));
+    if (requiredFirst instanceof Error)
+        return requiredFirst;
     return {
         ...(touch === undefined ? {} : { isTouch: touch }),
         ...(logic === undefined ? {} : { isLogic: logic }),
-        ...(device === undefined ? {} : { device })
+        ...(device === undefined ? {} : { device }),
+        ...(requiredFirst === undefined ? {} : { requiredFirst })
     };
 };

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

@@ -6,7 +6,13 @@
  * @remarks
  * Vite's CORS lets any page on `localhost` or `127.0.0.1` read the dev server, whatever its port: a frame on a second
  * port would read the catalogue's agent API and files as before. So the catalogue refuses a request another origin
- * sends, unless it is a navigation (a link, an embed), which shows a page but lets nobody read it.
+ * sends, unless it opens one of its pages (a link, an embed) or a public file, which shows it but lets nobody read it.
+ * No other address is opened for another origin's page: a server's route acts when opened (`/__open-in-editor` opens a
+ * file), and a module or a source file has no use as a page.
+ *
+ * Vite checks `Host` first, on both ports, against `server.allowedHosts`: a page that reaches `127.0.0.1` through its
+ * own domain (DNS rebinding) is not told apart here, since it is same-origin for its browser, and over plain HTTP on
+ * that domain its browser sends no `Sec-Fetch-*`.
  *
  * The frames' origin would otherwise serve everything the catalogue's does, and a story's script would read the
  * project from there. It serves a script or a `fetch` (whose body a script reads) only for a module that another
@@ -23,7 +29,10 @@
  */
 /** What a browser says of a request, from its headers. */
 export type RequestFacts = {
-    /** Its path, without the query (`/frame.html`). */
+    /**
+     * Its path as an address parser reads it, without the query (`/frame.html`): the routes behind the guards read the
+     * same, so `//x/__forgebook/api/stories` or `/./__forgebook/api/stories` is the route it would reach.
+     */
     readonly path: string;
     /** Its query, with its `?` (`?raw`); empty without one. */
     readonly query: string;
@@ -44,13 +53,14 @@ export declare const FRAME_PAGE_PATH = "/frame.html";
 export type CatalogueAnswer = "serve" | "refuse" | "to-frames";
 /**
  * What the catalogue's origin does with a request: the frame page goes to the frames' origin, another origin's
- * request is refused, the rest is served.
+ * request is refused unless it opens a page or a public file, the rest is served.
  *
  * @param request - what the browser says of it.
  * @param framedPages - the server's routes that are pages made to be framed by another origin's page (a client's
  *   inline preview), which only show a story and act on nothing.
+ * @param isPublic - whether a path names a file of the public folder; asked only of another origin's navigation.
  */
-export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>) => CatalogueAnswer;
+export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>, isPublic?: (path: string) => boolean) => CatalogueAnswer;
 /** What the frames' origin does with a request: `ask-graph` serves it when another module imports it. */
 export type FramesAnswer = "serve" | "refuse" | "not-found" | "ask-graph";
 /** What the frames' origin knows of a request's path. */

package/dist/src/vite/originGuard.js

@@ -6,7 +6,13 @@
  * @remarks
  * Vite's CORS lets any page on `localhost` or `127.0.0.1` read the dev server, whatever its port: a frame on a second
  * port would read the catalogue's agent API and files as before. So the catalogue refuses a request another origin
- * sends, unless it is a navigation (a link, an embed), which shows a page but lets nobody read it.
+ * sends, unless it opens one of its pages (a link, an embed) or a public file, which shows it but lets nobody read it.
+ * No other address is opened for another origin's page: a server's route acts when opened (`/__open-in-editor` opens a
+ * file), and a module or a source file has no use as a page.
+ *
+ * Vite checks `Host` first, on both ports, against `server.allowedHosts`: a page that reaches `127.0.0.1` through its
+ * own domain (DNS rebinding) is not told apart here, since it is same-origin for its browser, and over plain HTTP on
+ * that domain its browser sends no `Sec-Fetch-*`.
  *
  * The frames' origin would otherwise serve everything the catalogue's does, and a story's script would read the
  * project from there. It serves a script or a `fetch` (whose body a script reads) only for a module that another
@@ -41,6 +47,8 @@ const OPAQUE_DESTS = new Set([
 ]);
 /** The queries that ask Vite for a module made from a file (its text, its address…), never a file as it is. */
 const TRANSFORM_QUERY = /[?&](?:raw|import|inline|url|worker|worker_file|sharedworker)(?:[&=]|$)/;
+/** The catalogue's pages, by their addresses: what another origin's page may open, with public files and framed routes. */
+const CATALOGUE_PAGES = new Set(["/", "/index.html", FRAME_PAGE_PATH]);
 /** The dev server's own routes (`/__forgebook/api/`, `/__open-in-editor`): never a story's. */
 const SERVER_ROUTE_PREFIX = "/__";
 /**
@@ -88,18 +96,19 @@ const isAnyFromAnotherOrigin = (request) => request.site === undefined
 const isDocumentRequest = (request) => request.mode === "navigate" || DOCUMENT_DESTS.has(request.dest ?? "");
 /**
  * What the catalogue's origin does with a request: the frame page goes to the frames' origin, another origin's
- * request is refused, the rest is served.
+ * request is refused unless it opens a page or a public file, the rest is served.
  *
  * @param request - what the browser says of it.
  * @param framedPages - the server's routes that are pages made to be framed by another origin's page (a client's
  *   inline preview), which only show a story and act on nothing.
+ * @param isPublic - whether a path names a file of the public folder; asked only of another origin's navigation.
  */
-export const catalogueAnswer = (request, framedPages) => {
+export const catalogueAnswer = (request, framedPages, isPublic = () => false) => {
     if (isFromAnotherOrigin(request))
         return "refuse";
-    const isFramedPage = framedPages.has(request.path) && isDocumentRequest(request);
-    // a route of the server acts when it is opened (`/__open-in-editor` opens a file): not on another page's say
-    if (request.path.startsWith(SERVER_ROUTE_PREFIX) && !isFramedPage && isAnyFromAnotherOrigin(request))
+    const isOpenable = () => CATALOGUE_PAGES.has(request.path) ||
+        (isDocumentRequest(request) && (framedPages.has(request.path) || isPublic(request.path)));
+    if (isAnyFromAnotherOrigin(request) && !isOpenable())
         return "refuse";
     return request.path === FRAME_PAGE_PATH ? "to-frames" : "serve";
 };

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

@@ -106,8 +106,9 @@ export declare const frameEntry: (config: ResolvedConfig, axe?: AxeAddress) => s
  */
 export declare const agentSourcesModule: (config: ResolvedConfig) => string;
 /**
- * The source of the project's own stories and docs pages: one `?forgebook-files` or `?forgebook-docs-pages` import per
- * glob, named after the catalogue.
+ * The source of the project's own stories and docs pages: its `stories` as one group of story files and its `docs` as
+ * one group of docs pages, each imported by its patterns (`FILES_SPECIFIER_PREFIX`), so a `!` pattern leaves files out
+ * of what all the others list and a file two patterns list comes once; named after the catalogue.
  *
  * @param config - the configuration.
  */

package/dist/src/vite/pages.js

@@ -18,6 +18,7 @@ import { LOAD_RELOADS_KEY } from "../frame/staleModule.js";
 import { PREVIEWS_EVENT } from "../hotModules.js";
 import { PLAY_TOOLS_PACKAGES } from "./configFile.js";
 import { pluginFrameModule } from "./pluginConfig.js";
+import { DOCS_PAGES_SPECIFIER_PREFIX, FILES_SPECIFIER_PREFIX, storyFilesGroupText } from "./storyFilesModule.js";
 import { HOME_QUERY } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** The pages, by their file name. */
@@ -402,22 +403,28 @@ export const agentSourcesModule = (config) => {
     return [...sources.imports, `export const sources = ${sources.list};`, ""].join("\n");
 };
 /**
- * The source of the project's own stories and docs pages: one `?forgebook-files` or `?forgebook-docs-pages` import per
- * glob, named after the catalogue.
+ * The source of the project's own stories and docs pages: its `stories` as one group of story files and its `docs` as
+ * one group of docs pages, each imported by its patterns (`FILES_SPECIFIER_PREFIX`), so a `!` pattern leaves files out
+ * of what all the others list and a file two patterns list comes once; named after the catalogue.
  *
  * @param config - the configuration.
  */
-export const storiesSourceModule = (config) => [
-    ...config.stories.map((pattern, index) => `import files${index} from ${codeLiteral(`./${pattern.replace(/^\.\//, "")}?forgebook-files`)};`),
-    ...config.docs.map((pattern, index) => `import docs${index} from ${codeLiteral(`./${pattern.replace(/^\.\//, "")}?forgebook-docs-pages`)};`),
-    "export const source = {",
-    `  id: ${codeLiteral(OWN_SOURCE_ID)},`,
-    `  name: ${codeLiteral(config.title)},`,
-    `  files: [${config.stories.map((_pattern, index) => `files${index}`).join(", ")}],`,
-    ...(config.docs.length === 0
-        ? []
-        : [`  docs: [${config.docs.map((_pattern, index) => `docs${index}`).join(", ")}],`]),
-    "  sheets: { required: [], theme: [], restyled: [] }",
-    "};",
-    ""
-].join("\n");
+export const storiesSourceModule = (config) => {
+    // the configuration's folder in Vite's form, as the plugin names an importer's: the patterns are relative to it
+    const folder = VITE_PATHS.normalize(config.dir);
+    const group = (prefix, patterns) => codeLiteral(`${prefix}${storyFilesGroupText(folder, patterns)}`);
+    const hasStories = config.stories.length > 0;
+    const hasDocs = config.docs.length > 0;
+    return [
+        ...(hasStories ? [`import files from ${group(FILES_SPECIFIER_PREFIX, config.stories)};`] : []),
+        ...(hasDocs ? [`import docs from ${group(DOCS_PAGES_SPECIFIER_PREFIX, config.docs)};`] : []),
+        "export const source = {",
+        `  id: ${codeLiteral(OWN_SOURCE_ID)},`,
+        `  name: ${codeLiteral(config.title)},`,
+        `  files: [${hasStories ? "files" : ""}],`,
+        ...(hasDocs ? ["  docs: [docs],"] : []),
+        "  sheets: { required: [], theme: [], restyled: [] }",
+        "};",
+        ""
+    ].join("\n");
+};

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

@@ -1,5 +1,5 @@
-/** The id of a pattern's docs pages: virtual, with the declaring module's folder and the pattern after it. */
-export declare const DOCS_PAGES_PREFIX = "\0forgebook-docs-pages:";
+/** The id of a group of docs pages: virtual, with the declaring module's folder and the patterns after it. */
+export declare const DOCS_PAGES_PREFIX = "\0virtual:forgebook-docs-pages:";
 /**
  * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
  *
@@ -14,6 +14,13 @@ export declare const patternId: (source: string, folder: string) => string | nul
  * @param source - the import's specifier.
  */
 export declare const virtualId: (source: string) => string | undefined;
+/**
+ * Whether an id names a group's module: one whose patterns are written in the id itself, so that whoever writes the id
+ * chooses what the plugin reads.
+ *
+ * @param id - the module's id.
+ */
+export declare const isGroupId: (id: string) => boolean;
 /** The resolved id of the configuration's data module. */
 export declare const CONFIG_ID = "\0virtual:forgebook/config";
 /** The resolved id of the design tokens' module. */

package/dist/src/vite/pluginIds.js

@@ -6,20 +6,20 @@
  */
 import { CONFIG_MODULE, TOKENS_MODULE } from "./pages.js";
 import { FILES_PREFIX } from "./pluginModules.js";
-import { PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFilesGroupText, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
+import { DOCS_PAGES_SPECIFIER_PREFIX, FILES_SPECIFIER_PREFIX, GROUP_SEPARATOR, PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFilesGroupText, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
 /** The query that asks for the story files a pattern matches (`../src/**\/*.stories.tsx?forgebook-files`). */
 const FILES_QUERY = "?forgebook-files";
 /** The query that asks for the docs pages a pattern matches (`./docs/*.md?forgebook-docs-pages`). */
 const DOCS_PAGES_QUERY = "?forgebook-docs-pages";
-/** The id of a pattern's docs pages: virtual, with the declaring module's folder and the pattern after it. */
-export const DOCS_PAGES_PREFIX = "\0forgebook-docs-pages:";
+/** The id of a group of docs pages: virtual, with the declaring module's folder and the patterns after it. */
+export const DOCS_PAGES_PREFIX = `\0${DOCS_PAGES_SPECIFIER_PREFIX}`;
 /**
  * The id of a `?forgebook-files` module: its prefix, then its group (`storyFilesGroupText`), which holds no `..`.
  *
  * @param folder - the importing module's folder.
  * @param pattern - the pattern as the import writes it.
  */
-const filesId = (folder, pattern) => `${FILES_PREFIX}${storyFilesGroupText(folder, pattern)}`;
+const filesId = (folder, pattern) => `${FILES_PREFIX}${storyFilesGroupText(folder, [pattern])}`;
 /**
  * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
  *
@@ -27,15 +27,23 @@ const filesId = (folder, pattern) => `${FILES_PREFIX}${storyFilesGroupText(folde
  * @param folder - the importing module's folder.
  */
 export const patternId = (source, folder) => {
+    // the separator of a group's id: a folder that holds it would read back as patterns of its own
+    if (folder.includes(GROUP_SEPARATOR))
+        return null;
     if (source.endsWith(FILES_QUERY))
         return filesId(folder, source.slice(0, -FILES_QUERY.length));
     if (!source.endsWith(DOCS_PAGES_QUERY))
         return null;
     const pattern = source.slice(0, -DOCS_PAGES_QUERY.length);
-    return `${DOCS_PAGES_PREFIX}${storyFilesGroupText(folder, pattern)}`;
+    return `${DOCS_PAGES_PREFIX}${storyFilesGroupText(folder, [pattern])}`;
 };
-/** The specifiers' prefixes of a group's virtual modules: its "Used in", its reach, its search indexes, its texts. */
+/**
+ * The specifiers' prefixes of a group's virtual modules: the group named by its patterns (story files or docs pages),
+ * its "Used in", its reach, its search indexes, its texts.
+ */
 const VIRTUAL_PREFIXES = [
+    FILES_SPECIFIER_PREFIX,
+    DOCS_PAGES_SPECIFIER_PREFIX,
     USAGE_PREFIX,
     REACH_PREFIX,
     SEARCH_PREFIX,
@@ -55,6 +63,13 @@ export const virtualId = (source) => {
         return TOKENS_ID;
     return VIRTUAL_PREFIXES.some((prefix) => source.startsWith(prefix)) ? `\0${source}` : undefined;
 };
+/**
+ * Whether an id names a group's module: one whose patterns are written in the id itself, so that whoever writes the id
+ * chooses what the plugin reads.
+ *
+ * @param id - the module's id.
+ */
+export const isGroupId = (id) => VIRTUAL_PREFIXES.some((prefix) => id.startsWith(`\0${prefix}`));
 /** The resolved id of the configuration's data module. */
 export const CONFIG_ID = `\0${CONFIG_MODULE}`;
 /** The resolved id of the design tokens' module. */

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

@@ -11,9 +11,12 @@
 import type { DiskCache } from "./diskCache.ts";
 import type { DocsExtractor, DocsResult } from "./docsExtractor.ts";
 import type { PackJson } from "./packedModule.ts";
-import { type GroupLoaders, type IndexedStoryFile, type KeptIndex } from "./storyFilesModule.ts";
-/** The id of a pattern's module: virtual, with the declaring module's folder and the pattern after it. */
-export declare const FILES_PREFIX = "\0forgebook-files:";
+import { type GroupLoaders, type IndexedStoryFile, type IsFileKept, type KeptIndex } from "./storyFilesModule.ts";
+/**
+ * The id of a group of story files' module: virtual, with the declaring module's folder and the patterns after it,
+ * whether a `?forgebook-files` import or the group's specifier (`FILES_SPECIFIER_PREFIX`) names it.
+ */
+export declare const FILES_PREFIX = "\0virtual:forgebook-files:";
 /** The resolved id of a group's "Used in" module: Rollup's mark of a virtual module, then its import's specifier. */
 export declare const USAGE_ID_PREFIX = "\0virtual:forgebook-usage:";
 /** The resolved id of a group's reach module, the same way. */
@@ -42,7 +45,7 @@ export declare const docsModule: (component: DocsResult, watch: (file: string) =
     moduleType: "js";
 };
 /**
- * The module of a `?forgebook-files` pattern: every matched story file's index and loaders; with the files, indexed,
+ * The module of a group of story files: every listed story file's index and loaders; with the files, indexed,
  * which the dev server keeps to tell an edit that changes the list.
  *
  * @param id - the module's id (`FILES_PREFIX`, then the group: `storyFilesGroupText`).
@@ -52,13 +55,35 @@ export declare const docsModule: (component: DocsResult, watch: (file: string) =
  * @param warm - starts reading the docs of a story file ahead of its request; none in a test run.
  * @param startTexts - a build's: starts reading the files' docs, code and pages, which the module imports from the
  * group's texts module (`builtTexts.ts`); none imports each from its query.
+ * @param isKept - whether a listed file may be read; every one by default.
  * @throws when a story file cannot be indexed.
  */
-export declare const patternModule: (id: string, watch: (file: string) => void, loaders: GroupLoaders, cache: DiskCache<KeptIndex> | undefined, warm: ((storyFile: string) => void) | undefined, startTexts?: (files: readonly IndexedStoryFile[]) => void) => {
+export declare const patternModule: (id: string, watch: (file: string) => void, loaders: GroupLoaders, cache: DiskCache<KeptIndex> | undefined, warm: ((storyFile: string) => void) | undefined, startTexts?: (files: readonly IndexedStoryFile[]) => void, isKept?: IsFileKept) => {
     code: string;
     moduleType: "js";
     files: readonly IndexedStoryFile[];
 };
+/**
+ * Whether a story file added or removed changes what a group of story files lists: listed now and not when its module
+ * was served, or the other way round. A file no pattern lists, or one a `!` pattern leaves out, changes nothing, so
+ * the pages need no reload for it.
+ *
+ * @param id - the group's module's id (`FILES_PREFIX`, then the group).
+ * @param listed - the files its module listed when served, absolute in Vite's form; none when it could not be made.
+ * @param file - the file added or removed.
+ * @param isKept - whether a listed file may be read; every one by default.
+ */
+export declare const isListingChanged: (id: string, listed: ReadonlySet<string> | undefined, file: string, isKept?: IsFileKept) => boolean;
+/**
+ * The modules a story file added or removed renews: the groups whose list it changes (`isListingChanged`) and, with
+ * them, the modules that read their files; none when it changes no list.
+ *
+ * @param served - the groups' modules, with the files each listed when served.
+ * @param file - the file added or removed.
+ * @param readers - the modules that read the groups' files: their "Used in" and search indexes.
+ * @param isKept - whether a listed file may be read; every one by default.
+ */
+export declare const listingRenewals: (served: ReadonlyMap<string, ReadonlySet<string> | undefined>, file: string, readers: readonly string[], isKept?: IsFileKept) => readonly string[] | undefined;
 /**
  * A group's "Used in" module: for each component, the components that use it, packed once per title and list of
  * stories (`packedUsage`), which a page reads.
@@ -68,8 +93,9 @@ export declare const patternModule: (id: string, watch: (file: string) => void,
  * @param usage - reads the facts in the docs worker.
  * @param cache - the pattern's index kept between starts; none reads every file.
  * @param pack - writes the module's JSON as its value: as it is on a dev server, in a gzipped file of a build's.
+ * @param isKept - whether a listed file may be read; every one by default.
  */
-export declare const usageModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined, pack: PackJson) => Promise<{
+export declare const usageModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined, pack: PackJson, isKept?: IsFileKept) => Promise<{
     code: string;
     moduleType: "js";
 }>;
@@ -82,8 +108,9 @@ export declare const usageModule: (id: string, watch: (file: string) => void, us
  * @param watch - adds a file whose edit renews the module (each story file).
  * @param usage - reads the facts in the docs worker.
  * @param cache - the pattern's index kept between starts; none reads every file.
+ * @param isKept - whether a listed file may be read; every one by default.
  */
-export declare const reachModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined) => Promise<{
+export declare const reachModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined, isKept?: IsFileKept) => Promise<{
     code: string;
     moduleType: "js";
 }>;
@@ -103,13 +130,14 @@ export type SearchIndexModule = {
  *
  * @param id - the module's id.
  * @param watch - adds a file whose edit renews the module.
- * @param read - a story file's component docs, and how the module writes its JSON.
+ * @param read - a story file's component docs, how the module writes its JSON, and which listed files may be read.
  * @returns the index; none for another id.
  */
 export declare const searchIndexModule: (id: string, watch: (file: string) => void, read: {
     readonly docsOf: (storyFile: string) => Promise<DocsResult>;
     readonly isServing: boolean;
     readonly pack: PackJson;
+    readonly isKept: IsFileKept;
 }) => Promise<SearchIndexModule | undefined>;
 /** What a catalogue's search indexes read and tell: what `searchIndexes` makes. */
 export type SearchIndexes = {
@@ -130,11 +158,12 @@ export type SearchIndexes = {
 /**
  * The search's indexes of a plugin: a build reads each component's docs once, for its page and its index.
  *
- * @param read - reads a story file's component docs, says whether a dev server runs, and keeps each index's id with the
- * modules an edit renews (a docs pages' index with the docs pages').
+ * @param read - reads a story file's component docs, says whether a dev server runs, keeps each index's id with the
+ * modules an edit renews (a docs pages' index with the docs pages'), and says which listed files may be read.
  */
 export declare const searchIndexes: (read: {
     readonly extract: (storyFile: string) => Promise<DocsResult>;
     readonly isServing: () => boolean;
     readonly track: (id: string, isPages: boolean) => void;
+    readonly isKept: IsFileKept;
 }) => SearchIndexes;