forgebook 0.2.0 → 0.3.1

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,28 @@ 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 group a project's module names for a group's module: the story files of their "Used in", reach, search index and
+ * texts, the docs pages of their search index. Those read the same files and only their group's module imports them, so
+ * a client that already holds the group's module needs no other import to have been seen.
+ *
+ * @param id - a group's module's id.
+ */
+export declare const namingGroupOf: (id: string) => string;
+/**
+ * Whether a module's text names a group. Its transform must run for the plugin to see the import, so a cache of
+ * transforms must not keep it.
+ *
+ * @param code - the module's text.
+ */
+export declare const namesGroup: (code: 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,36 @@ 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 modules that read a group of story files' own files: named once its story files are. */
+const STORY_FILES_READERS = [USAGE_PREFIX, REACH_PREFIX, SEARCH_PREFIX, TEXTS_PREFIX];
+/**
+ * The group a project's module names for a group's module: the story files of their "Used in", reach, search index and
+ * texts, the docs pages of their search index. Those read the same files and only their group's module imports them, so
+ * a client that already holds the group's module needs no other import to have been seen.
+ *
+ * @param id - a group's module's id.
+ */
+export const namingGroupOf = (id) => {
+    const pagesSearch = `\0${PAGES_SEARCH_PREFIX}`;
+    if (id.startsWith(pagesSearch))
+        return `${DOCS_PAGES_PREFIX}${id.slice(pagesSearch.length)}`;
+    const reader = STORY_FILES_READERS.map((prefix) => `\0${prefix}`).find((mark) => id.startsWith(mark));
+    return reader === undefined ? id : `${FILES_PREFIX}${id.slice(reader.length)}`;
+};
+/**
+ * Whether a module's text names a group. Its transform must run for the plugin to see the import, so a cache of
+ * transforms must not keep it.
+ *
+ * @param code - the module's text.
+ */
+export const namesGroup = (code) => [FILES_QUERY, DOCS_PAGES_QUERY, ...VIRTUAL_PREFIXES].some((name) => code.includes(name));
 /** 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;

package/dist/src/vite/pluginModules.js

@@ -10,11 +10,15 @@
  */
 import { codeLiteral } from "../codeLiteral.js";
 import { packedUsage } from "../usedIn.js";
-import { indexedStoryFiles, PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFilesCode, storyFilesGroupOf, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
+import { EVERY_FILE, FILES_SPECIFIER_PREFIX, indexedStoryFiles, PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFileKeys, storyFilesCode, storyFilesGroupOf, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
 import { storyReach } from "./storyReach.js";
 import { joinedUsage } from "./usageModule.js";
-/** The id of a pattern's module: virtual, with the declaring module's folder and the pattern after it. */
-export const FILES_PREFIX = "\0forgebook-files:";
+import { VITE_PATHS } from "./vitePaths.js";
+/**
+ * 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 const FILES_PREFIX = `\0${FILES_SPECIFIER_PREFIX}`;
 /** The resolved id of a group's "Used in" module: Rollup's mark of a virtual module, then its import's specifier. */
 export const USAGE_ID_PREFIX = `\0${USAGE_PREFIX}`;
 /** The resolved id of a group's reach module, the same way. */
@@ -51,7 +55,7 @@ export const docsModule = (component, watch) => ({
     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`).
@@ -61,18 +65,51 @@ export const docsModule = (component, watch) => ({
  * @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 const patternModule = (id, watch, loaders, cache, warm, startTexts) => {
-    const { root, pattern } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
-    const files = indexedStoryFiles(root, pattern, watch, cache);
+export const patternModule = (id, watch, loaders, cache, warm, startTexts, isKept = EVERY_FILE) => {
+    const { root, patterns } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
+    const files = indexedStoryFiles(root, patterns, watch, cache, isKept);
     const [first] = files;
     if (first !== undefined)
         warm?.(first.file);
     startTexts?.(files);
-    const code = storyFilesCode(root, pattern, files, loaders, startTexts !== undefined);
+    const code = storyFilesCode(root, patterns, files, loaders, startTexts !== undefined);
     return { code, moduleType: "js", files };
 };
+/**
+ * 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 const isListingChanged = (id, listed, file, isKept = EVERY_FILE) => {
+    if (listed === undefined)
+        return true;
+    const { root, patterns } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
+    const isListed = storyFileKeys(root, patterns, isKept).includes(VITE_PATHS.relativeKey(root, file));
+    return isListed !== listed.has(VITE_PATHS.normalize(file));
+};
+/**
+ * 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 const listingRenewals = (served, file, readers, isKept = EVERY_FILE) => {
+    const changed = [...served]
+        .filter(([id, listed]) => isListingChanged(id, listed, file, isKept))
+        .map(([id]) => id);
+    return changed.length === 0 ? undefined : [...changed, ...readers];
+};
 /**
  * A group's facts: its story files indexed, what their stories render read in the docs worker.
  *
@@ -80,10 +117,11 @@ export const patternModule = (id, watch, loaders, cache, warm, startTexts) => {
  * @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.
  */
-const groupUsage = async (group, watch, usage, cache) => {
-    const { root, pattern } = storyFilesGroupOf(group);
-    const files = indexedStoryFiles(root, pattern, watch, cache);
+const groupUsage = async (group, watch, usage, cache, isKept) => {
+    const { root, patterns } = storyFilesGroupOf(group);
+    const files = indexedStoryFiles(root, patterns, watch, cache, isKept);
     const graph = await usage(files.map((file) => ({
         storyFile: file.file,
         exports: file.index.stories.map((story) => story.exportName)
@@ -99,9 +137,10 @@ const groupUsage = async (group, watch, usage, cache) => {
  * @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 const usageModule = async (id, watch, usage, cache, pack) => {
-    const { files, graph } = await groupUsage(id.slice(USAGE_ID_PREFIX.length), watch, usage, cache);
+export const usageModule = async (id, watch, usage, cache, pack, isKept = EVERY_FILE) => {
+    const { files, graph } = await groupUsage(id.slice(USAGE_ID_PREFIX.length), watch, usage, cache, isKept);
     const answer = typeof graph === "string"
         ? { error: graph }
         : packedUsage(joinedUsage(graph, files.map((file) => ({
@@ -120,9 +159,10 @@ export const usageModule = async (id, watch, usage, cache, pack) => {
  * @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 const reachModule = async (id, watch, usage, cache) => {
-    const { files, graph } = await groupUsage(id.slice(REACH_ID_PREFIX.length), watch, usage, cache);
+export const reachModule = async (id, watch, usage, cache, isKept = EVERY_FILE) => {
+    const { files, graph } = await groupUsage(id.slice(REACH_ID_PREFIX.length), watch, usage, cache, isKept);
     const reach = typeof graph === "string"
         ? []
         : storyReach(graph, files.map((file) => ({ storyFile: file.file, title: file.index.title })));
@@ -134,7 +174,7 @@ export const reachModule = async (id, watch, usage, cache) => {
  *
  * @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 const searchIndexModule = async (id, watch, read) => {
@@ -142,17 +182,17 @@ export const searchIndexModule = async (id, watch, read) => {
     if (!isPages && !id.startsWith(SEARCH_ID_PREFIX))
         return undefined;
     const { storySearchModule, pagesSearchModule } = await import("./searchModule.js");
-    const { root, pattern } = storyFilesGroupOf(id.slice((isPages ? PAGES_SEARCH_ID_PREFIX : SEARCH_ID_PREFIX).length));
+    const { root, patterns } = storyFilesGroupOf(id.slice((isPages ? PAGES_SEARCH_ID_PREFIX : SEARCH_ID_PREFIX).length));
     const code = isPages
-        ? pagesSearchModule(root, pattern, watch, read.pack)
-        : await storySearchModule(root, pattern, watch, read.docsOf, read.isServing, read.pack);
+        ? pagesSearchModule(root, patterns, watch, read.pack, read.isKept)
+        : await storySearchModule(root, patterns, watch, read.docsOf, read.isServing, read.pack, read.isKept);
     return { module: { code, moduleType: "js" }, isPages };
 };
 /**
  * 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 const searchIndexes = (read) => {
     const built = new Map();
@@ -166,7 +206,12 @@ export const searchIndexes = (read) => {
     return {
         docsOf,
         moduleOf: async (id, watch, pack) => {
-            const search = await searchIndexModule(id, watch, { docsOf, isServing: read.isServing(), pack });
+            const search = await searchIndexModule(id, watch, {
+                docsOf,
+                isServing: read.isServing(),
+                pack,
+                isKept: read.isKept
+            });
             if (search === undefined)
                 return undefined;
             read.track(id, search.isPages);

package/dist/src/vite/prebundled.js

@@ -86,6 +86,7 @@ export const scannedEntries = (config, resolve, readText) => {
             return [];
         return [...text.matchAll(FILES_IMPORT)].flatMap((match) => match[1] === undefined ? [] : [VITE_PATHS.join(VITE_PATHS.dirname(file), match[1])]);
     });
-    // the previews too: what they import loads with the first story, and found then it reloads the page
+    // the previews too: what they import loads with the first story, and found then it reloads the page; the project's
+    // `!` patterns stay as they are, which Vite's scanner reads as fast-glob does, from the same folder
     return [...config.stories, ...fromSources, ...config.previews];
 };

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

@@ -2,6 +2,7 @@ import type { DocBlock } from "../docPages.ts";
 import type { SearchSection } from "../searchIndex.ts";
 import type { DocsResult } from "./docsExtractor.ts";
 import type { PackJson } from "./packedModule.ts";
+import { type IsFileKept } from "./storyFilesModule.ts";
 /**
  * HTML as stretches of documentation, one per heading that carries an anchor.
  *
@@ -20,7 +21,7 @@ export declare const blockSections: (blocks: readonly DocBlock[]) => SearchSecti
  * A group of story files' search index, as the code of its module.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module.
  * @param extract - reads a story file's component.
  * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
@@ -28,13 +29,14 @@ export declare const blockSections: (blocks: readonly DocBlock[]) => SearchSecti
  * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
  * few visits read.
  */
-export declare const storySearchModule: (root: string, pattern: string, watch: (file: string) => void, extract: (storyFile: string) => Promise<DocsResult>, isServing: boolean, pack: PackJson) => Promise<string>;
+export declare const storySearchModule: (root: string, patterns: readonly string[], watch: (file: string) => void, extract: (storyFile: string) => Promise<DocsResult>, isServing: boolean, pack: PackJson, isKept?: IsFileKept) => Promise<string>;
 /**
  * A group of docs pages' search index, as the code of its module.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module.
  * @param pack - writes the index's JSON as the module's value.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export declare const pagesSearchModule: (root: string, pattern: string, watch: (file: string) => void, pack: PackJson) => string;
+export declare const pagesSearchModule: (root: string, patterns: readonly string[], watch: (file: string) => void, pack: PackJson, isKept?: IsFileKept) => string;

package/dist/src/vite/searchModule.js

@@ -14,7 +14,7 @@ import { readFileSync } from "node:fs";
 import { componentPage } from "./componentPage.js";
 import { compiledDocPage } from "./docPageMarkdown.js";
 import { indexedDocPages } from "./docPagesModule.js";
-import { indexedStoryFiles } from "./storyFilesModule.js";
+import { EVERY_FILE, indexedStoryFiles } from "./storyFilesModule.js";
 /** A heading of the pages' HTML: its anchor, and what is inside it. */
 const HEADING = /<h[1-6] id="doc-([^"]*)"[^>]*>([\s\S]*?)<\/h[1-6]>/g;
 /** A tag: `>` inside a quoted attribute does not end it. */
@@ -177,7 +177,7 @@ const entryOf = (file, read, watch) => {
  * A group of story files' search index, as the code of its module.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module.
  * @param extract - reads a story file's component.
  * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
@@ -185,8 +185,8 @@ const entryOf = (file, read, watch) => {
  * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
  * few visits read.
  */
-export const storySearchModule = async (root, pattern, watch, extract, isServing, pack) => {
-    const files = indexedStoryFiles(root, pattern, watch);
+export const storySearchModule = async (root, patterns, watch, extract, isServing, pack, isKept = EVERY_FILE) => {
+    const files = indexedStoryFiles(root, patterns, watch, undefined, isKept);
     const entries = await Promise.all(files.map(async (file) => ({ file, ...entryOf(file, await extract(file.file), watch) })));
     const problems = entries.flatMap(({ problem }) => problem ?? []);
     const index = {
@@ -199,12 +199,13 @@ export const storySearchModule = async (root, pattern, watch, extract, isServing
  * A group of docs pages' search index, as the code of its module.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module.
  * @param pack - writes the index's JSON as the module's value.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export const pagesSearchModule = (root, pattern, watch, pack) => {
-    const pages = indexedDocPages(root, pattern, watch).map(({ key, file }) => [
+export const pagesSearchModule = (root, patterns, watch, pack, isKept = EVERY_FILE) => {
+    const pages = indexedDocPages(root, patterns, watch, [], isKept).map(({ key, file }) => [
         key,
         blockSections(compiledDocPage(file, readFileSync(file, "utf8")).blocks)
     ]);