forgebook 0.3.3 → 0.4.1

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 { refsLines } from "./refsConfig.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";
@@ -27,6 +28,8 @@ export const PAGE_FILES = ["index.html", "frame.html"];
 export const CONFIG_MODULE = "virtual:forgebook/config";
 /** The module the shell reads the design tokens from, imported on first use: a page that shows none never loads it. */
 export const TOKENS_MODULE = "virtual:forgebook/tokens";
+/** The previews of the catalogue's galleries, with each picture's address: loaded when a gallery first opens. */
+export const SWITCH_PREVIEWS_MODULE = "virtual:forgebook/switch-previews";
 /**
  * The entries the pages load, by page: file names in the configuration's folder, never written to disk. Named as
  * files rather than virtual modules because the build names a page's chunk and its style sheet after its entry, and a
@@ -80,6 +83,18 @@ export const pageModuleOf = (path, dir, paths = VITE_PATHS) => {
  * @param text - the text.
  */
 const escaped = (text) => text.replace(/[&<>"]/g, (character) => `&#${character.charCodeAt(0)};`);
+/**
+ * A script as the page carries it: each line without its indent, and the lines that only comment left out. Every
+ * frame of a catalogue loads it, and a build counts it in every frame page it writes; the source keeps its indents and
+ * comments for whoever reads it.
+ *
+ * @param script - the script, one statement or brace per line, no string that spans lines.
+ */
+const compactScript = (script) => script
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && !line.startsWith("//"))
+    .join("\n");
 /**
  * What a frame shows when its code fails before the frame starts: a preview or a source that throws while it loads, or
  * a module that cannot be loaded at all. The frame's own code never runs then, so without this the frame stays blank
@@ -189,25 +204,86 @@ export const pageHtml = (page, config, placement) => [
     "  </head>",
     "  <body>",
     '    <div id="root"></div>',
-    ...(page === "frame.html" ? [`    <script>${frameLoadGuard(placement)}</script>`] : []),
+    ...(page === "frame.html" ? [`    <script>${compactScript(frameLoadGuard(placement))}</script>`] : []),
     `    <script type="module" src="/${PAGE_ENTRIES[page]}"></script>`,
     "  </body>",
     "</html>",
     ""
 ].join("\n");
+/**
+ * A switch as the pages read it from the configuration's data: without its values' previews and sheets, which the
+ * pages' entries import by themselves, so each first load carries no more than a name for what it may never fetch.
+ *
+ * @param each - the switch.
+ */
+const pageSwitch = (each) => ({
+    ...each,
+    values: each.values.map(({ preview: _preview, sheet: _sheet, ...value }) => value)
+});
+/**
+ * An import of a file for its address alone. Never inlined, whatever its size: a small file's bytes would otherwise
+ * land in the page that imports it, in the first load of a catalogue that may never draw it.
+ *
+ * @param name - the imported name.
+ * @param file - the file's path.
+ */
+const addressImport = (name, file) => `import ${name} from ${codeLiteral(`${file}?url&no-inline`)};`;
+/**
+ * The module of the galleries' previews: by switch id then value, with each picture's address.
+ *
+ * @param config - the configuration.
+ */
+export const switchPreviewsModule = (config) => {
+    const imports = [];
+    const switches = (config.switches ?? []).flatMap((each) => {
+        const values = each.values.flatMap(({ value, preview }) => {
+            if (preview === undefined)
+                return [];
+            if (!("image" in preview)) {
+                // only the checked fields: serialising the object itself would let a `toJSON` write what was not checked
+                const { swatches, font } = preview;
+                return [`${codeLiteral(value)}: ${codeLiteral({ swatches: [...swatches], font })}`];
+            }
+            const name = `picture${imports.length}`;
+            imports.push(addressImport(name, preview.image));
+            return [`${codeLiteral(value)}: { image: ${name} }`];
+        });
+        return values.length === 0 ? [] : [`${codeLiteral(each.id)}: { ${values.join(", ")} }`];
+    });
+    return [...imports, `export default { ${switches.join(", ")} };`, ""].join("\n");
+};
+/**
+ * The imports of the switches' values' sheets, and the frame's list of their addresses.
+ *
+ * @param config - the configuration.
+ */
+const valueSheetsCode = (config) => {
+    const imports = [];
+    const list = (config.switches ?? []).flatMap((each) => each.values.flatMap(({ value, sheet }) => {
+        if (sheet === undefined)
+            return [];
+        const name = `valueSheet${imports.length}`;
+        imports.push(addressImport(name, sheet));
+        return [`${codeLiteral(`${each.id}=${value}`)}: ${name}`];
+    }));
+    return { imports, list };
+};
 /**
  * The configuration's data, as the pages' module exports it.
  *
  * @param config - the configuration.
  * @param frames - where the frames run: known on the dev server once both of its ports listen.
  */
-export const configModule = (config, frames) => {
+export const configModule = (config, frames, isServing) => {
     const data = {
         title: config.title,
         heights: config.heights,
-        switches: config.switches,
+        switches: config.switches?.map(pageSwitch),
+        // only a dev server draws a home with no story: a built catalogue carries nothing of the project's layout
+        ...(isServing ? { storyGlobs: config.stories } : {}),
         languages: config.languages,
-        lists: config.lists,
+        // a reader of published docs did not ask for a story to play; a dev server's author did
+        lists: isServing ? config.lists : { play: "off", ...config.lists },
         frames
     };
     return `export default ${codeLiteral(data)};`;
@@ -277,6 +353,32 @@ const pluginViewLines = (config) => {
             `    pluginHosts: () => import(${codeLiteral(PLUGIN_HOSTS_MODULE)}).then((module) => module.pluginHosts),`
         ];
 };
+/**
+ * The shell's list of the custom controls, each with the import that loads it when a story names it; nothing for a
+ * catalogue without any, whose entry is then what it would be with no such feature.
+ *
+ * @param config - the configuration.
+ */
+const argControlLines = (config) => {
+    const controls = Object.entries(config.argControls);
+    return controls.length === 0
+        ? []
+        : [
+            "    argControls: {",
+            ...controls.map(([name, { module }]) => `      ${codeLiteral(name)}: () => import(${codeLiteral(module)}),`),
+            "    },"
+        ];
+};
+/**
+ * The frame's list of the custom controls' frame modules, each with the import that loads it when the shell first gives
+ * the story a value of that control; nothing for a catalogue whose controls have none.
+ *
+ * @param config - the configuration.
+ */
+const argControlFrameLines = (config) => {
+    const frames = Object.entries(config.argControls).flatMap(([name, { frame }]) => frame === undefined ? [] : [`      ${codeLiteral(name)}: () => import(${codeLiteral(frame)}),`]);
+    return frames.length === 0 ? [] : ["    argControls: {", ...frames, "    },"];
+};
 /**
  * The shell's entry: the shell mounted with the configuration's data, the logo, the sources and the code writer.
  *
@@ -300,12 +402,15 @@ export const shellEntry = (config) => {
         ...(config.heights === undefined ? [] : ["    heights: config.heights,"]),
         ...(config.home === undefined ? [] : [`    home: ${writtenHomeCode(config.home)},`]),
         `    sources: ${sources.list},`,
+        ...(config.stories.length === 0 ? [] : ["    storyGlobs: config.storyGlobs,"]),
         '    frameUrl: "frame.html",',
         "    frames: config.frames,",
         "    languages: config.languages,",
         ...(config.switches === undefined ? [] : ["    switches: config.switches,"]),
         "    lists: config.lists,",
+        ...refsLines(config),
         ...pluginViewLines(config),
+        ...argControlLines(config),
         ...(config.framework.addressTexts === undefined
             ? []
             : [`    addressTexts: ${codeLiteral(config.framework.addressTexts)},`]),
@@ -313,6 +418,12 @@ export const shellEntry = (config) => {
         ...(config.tokens.length === 0 && config.sources.length === 0
             ? []
             : [`    loadTokens: () => import(${codeLiteral(TOKENS_MODULE)}).then((module) => module.default),`]),
+        // only for a catalogue with previews: the others' first load carries not even the way to them
+        ...(config.switches?.some((each) => each.values.some((value) => value.preview !== undefined))
+            ? [
+                `    loadSwitchPreviews: () => import(${codeLiteral(SWITCH_PREVIEWS_MODULE)}).then((module) => module.default),`
+            ]
+            : []),
         "    codeOf",
         "  });",
         ""
@@ -356,6 +467,7 @@ const previewsHot = (previews) => previews.length === 0
  *   found, which leaves the card to say so.
  */
 export const frameEntry = (config, axe) => {
+    const valueSheets = valueSheetsCode(config);
     const sources = sourcesCode(config);
     const frames = config.plugins.flatMap((plugin) => {
         const frame = pluginFrameModule(plugin, config.framework.name);
@@ -366,6 +478,7 @@ export const frameEntry = (config, axe) => {
         `import config from ${codeLiteral(CONFIG_MODULE)};`,
         ...(axe?.imports ?? []),
         ...sources.imports,
+        ...valueSheets.imports,
         ...config.previews.map((file, index) => `import * as preview${index} from ${codeLiteral(file)};`),
         ...frames.map((plugin, index) => `import { frame as pluginFrame${index} } from ${codeLiteral(plugin.frame)};`),
         'const root = document.getElementById("root");',
@@ -375,9 +488,11 @@ export const frameEntry = (config, axe) => {
         ...(axe === undefined ? [] : [`    axeUrl: ${axe.value},`]),
         "    languages: config.languages,",
         ...(config.switches === undefined ? [] : ["    switches: config.switches,"]),
+        ...(valueSheets.list.length === 0 ? [] : [`    valueSheets: { ${valueSheets.list.join(", ")} },`]),
         "    lists: config.lists,",
         "    frames: config.frames,",
         ...(config.hasPlayTools ? [playToolsLoader()] : []),
+        ...argControlFrameLines(config),
         ...(frames.length === 0
             ? []
             : [

package/dist/src/vite/pluginConfig.js

@@ -101,6 +101,10 @@ const shapeProblem = (plugin) => {
     ];
     if (named.some((name) => typeof name !== "string"))
         return `the plugin "${plugin.id}" adds something with no id`;
+    // a configuration is not type-checked: what a value brings stays the catalogue's to declare
+    const isOverreaching = (plugin.switches ?? []).some((each) => (each.values ?? []).some((value) => ["implies", "preview", "sheet"].some((key) => key in value)));
+    if (isOverreaching)
+        return `the plugin "${plugin.id}" gives a switch's value implies, preview or sheet: those are the catalogue's`;
     const { frame } = plugin;
     const isFrame = frame === undefined || typeof frame === "string" || (typeof frame === "object" && frame !== null);
     return isFrame ? undefined : `the plugin "${plugin.id}" names a frame that is no specifier`;

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

@@ -40,3 +40,5 @@ export declare const namesGroup: (code: string) => boolean;
 export declare const CONFIG_ID = "\0virtual:forgebook/config";
 /** The resolved id of the design tokens' module. */
 export declare const TOKENS_ID = "\0virtual:forgebook/tokens";
+/** The resolved id of the galleries' previews. */
+export declare const SWITCH_PREVIEWS_ID = "\0virtual:forgebook/switch-previews";

package/dist/src/vite/pluginIds.js

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { CONFIG_MODULE, TOKENS_MODULE } from "./pages.js";
+import { CONFIG_MODULE, SWITCH_PREVIEWS_MODULE, TOKENS_MODULE } from "./pages.js";
 import { FILES_PREFIX } from "./pluginModules.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`). */
@@ -61,6 +61,8 @@ export const virtualId = (source) => {
         return CONFIG_ID;
     if (source === TOKENS_MODULE)
         return TOKENS_ID;
+    if (source === SWITCH_PREVIEWS_MODULE)
+        return SWITCH_PREVIEWS_ID;
     return VIRTUAL_PREFIXES.some((prefix) => source.startsWith(prefix)) ? `\0${source}` : undefined;
 };
 /**
@@ -97,3 +99,5 @@ export const namesGroup = (code) => [FILES_QUERY, DOCS_PAGES_QUERY, ...VIRTUAL_P
 export const CONFIG_ID = `\0${CONFIG_MODULE}`;
 /** The resolved id of the design tokens' module. */
 export const TOKENS_ID = `\0${TOKENS_MODULE}`;
+/** The resolved id of the galleries' previews. */
+export const SWITCH_PREVIEWS_ID = `\0${SWITCH_PREVIEWS_MODULE}`;

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

@@ -8,10 +8,12 @@
  *
  * @module
  */
+import type { ViteDevServer } from "vite";
+import type { ResolvedConfig } from "./configFile.ts";
 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 IsFileKept, type KeptIndex } from "./storyFilesModule.ts";
+import { type GroupLoaders, type IndexedStoryFile, type IsFileKept, type KeptIndex, type RefusedStoryFile } 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.
@@ -52,38 +54,99 @@ export declare const docsModule: (component: DocsResult, watch: (file: string) =
  * @param watch - adds a file whose edit renews the module (each story file).
  * @param loaders - the group's loaders besides its story files'.
  * @param cache - the pattern's index kept between starts; none reads every file.
- * @param warm - starts reading the docs of a story file ahead of its request; none in a test run.
+ * @param warm - starts reading the docs of the group's story files ahead of their requests; 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.
+ * @param isForgiving - whether a file that cannot be indexed is named among the catalogue's problems while the others
+ * draw (a person at a dev server), rather than failing the module (a build, a test run).
+ * @param catalogue - the catalogue, whose previews' tags every story takes; none has none.
+ * @param scriptProblems - the project's scripts that do not parse, named among the catalogue's problems with the files
+ * that cannot be indexed (`scriptProblems.ts`), where those are (a dev server); none by default.
+ * @throws when a story file cannot be indexed, unless it is forgiven.
  */
-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) => {
+export declare const patternModule: (id: string, watch: (file: string) => void, loaders: GroupLoaders, cache: DiskCache<KeptIndex> | undefined, warm: ((storyFiles: readonly string[]) => void) | undefined, startTexts?: (files: readonly IndexedStoryFile[]) => void, isKept?: IsFileKept, isForgiving?: boolean, catalogue?: {
+    readonly previews: readonly string[];
+}, scriptProblems?: readonly string[]) => {
     code: string;
     moduleType: "js";
     files: readonly IndexedStoryFile[];
+    refused: readonly RefusedStoryFile[];
 };
 /**
- * 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.
+ * The versions of a group's module served since the pages last reloaded: a page holds one of them, or loads the module
+ * after the next change.
+ */
+export type ServedListings = {
+    /** The files any of those versions listed. */
+    readonly some: ReadonlySet<string>;
+    /** The files every one of them listed; none when no version was served since. */
+    readonly every: ReadonlySet<string> | undefined;
+};
+/**
+ * Whether a story file added or removed changes what a page may hold of a group of story files: listed now and missing
+ * from a version served since the pages last reloaded, or gone and listed by one. A file no pattern lists, or one a
+ * `!` pattern leaves out, changes nothing, so the pages need no reload for it.
+ *
+ * @remarks
+ * The module's last version is no measure: another reader (a second tab, a frame, the agents' API) may load it again
+ * between the change on the disk and the file's event, and a page that loaded it before would then never reload. A
+ * branch switch makes that window wide, as its events arrive after the files are written. Every version since the last
+ * reload counts, and no earlier one: that reload renewed the pages that held those.
  *
  * @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 served - the versions served since the pages last reloaded; none when the module 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;
+export declare const isListingChanged: (id: string, served: ServedListings | undefined, file: string, isKept?: IsFileKept) => boolean;
+/**
+ * A docs pages' module, when the id is a pattern's, a page's or the written home's. The Markdown reader loads with the
+ * first: a catalogue may have no docs pages, and a story's page reads none.
+ *
+ * @param id - the module's id.
+ * @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.
+ */
+export declare const docsModuleOf: (id: string, watch: (file: string) => void, isServing: boolean, plugins: ResolvedConfig["plugins"], isKept: IsFileKept) => Promise<{
+    code: string;
+    moduleType: "js";
+} | undefined>;
+/**
+ * Makes a group's module and adds the version to those served since the pages last reloaded (`isListingChanged`).
+ * While it is made, and when making it fails, the list is unknown.
+ *
+ * @param listings - the groups' modules, with the versions served.
+ * @param id - the group's module's id.
+ * @param make - makes the module.
+ * @returns the module made.
+ */
+export declare const keptListing: <TModule extends {
+    readonly files: readonly {
+        readonly file: string;
+    }[];
+    readonly refused: readonly {
+        readonly file: string;
+    }[];
+}>(listings: Map<string, ServedListings | undefined>, id: string, make: () => TModule) => TModule;
+/**
+ * Forgets the versions served before a reload the pages were sent: each page loads the module again.
+ *
+ * @param listings - the groups' modules, with the versions served.
+ */
+export declare const pagesReloaded: (listings: Map<string, ServedListings | undefined>) => void;
 /**
  * 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 served - the groups' modules, with the versions served since the pages last reloaded.
  * @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;
+export declare const listingRenewals: (served: ReadonlyMap<string, ServedListings | 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.
@@ -167,3 +230,10 @@ export declare const searchIndexes: (read: {
     readonly track: (id: string, isPages: boolean) => void;
     readonly isKept: IsFileKept;
 }) => SearchIndexes;
+/**
+ * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
+ *
+ * @param server - the dev server.
+ * @param ids - the modules' ids.
+ */
+export declare const invalidateEverywhere: (server: ViteDevServer, ids: Iterable<string>) => void;

package/dist/src/vite/pluginModules.js

@@ -10,8 +10,11 @@
  */
 import { codeLiteral } from "../codeLiteral.js";
 import { packedUsage } from "../usedIn.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 { DOCS_PAGES_PREFIX } from "./pluginIds.js";
+import { previewTagsOf, withPreviewTags } from "./previewTags.js";
+import { EVERY_FILE, FILES_SPECIFIER_PREFIX, PAGES_SEARCH_PREFIX, REACH_PREFIX, readStoryFiles, refusalError, SEARCH_PREFIX, storyFileKeys, storyFilesCode, storyFilesGroupOf, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
 import { storyReach } from "./storyReach.js";
+import { DOCS_PAGE_QUERY, HOME_QUERY } from "./textQueries.js";
 import { joinedUsage } from "./usageModule.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /**
@@ -62,44 +65,112 @@ export const docsModule = (component, watch) => ({
  * @param watch - adds a file whose edit renews the module (each story file).
  * @param loaders - the group's loaders besides its story files'.
  * @param cache - the pattern's index kept between starts; none reads every file.
- * @param warm - starts reading the docs of a story file ahead of its request; none in a test run.
+ * @param warm - starts reading the docs of the group's story files ahead of their requests; 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.
+ * @param isForgiving - whether a file that cannot be indexed is named among the catalogue's problems while the others
+ * draw (a person at a dev server), rather than failing the module (a build, a test run).
+ * @param catalogue - the catalogue, whose previews' tags every story takes; none has none.
+ * @param scriptProblems - the project's scripts that do not parse, named among the catalogue's problems with the files
+ * that cannot be indexed (`scriptProblems.ts`), where those are (a dev server); none by default.
+ * @throws when a story file cannot be indexed, unless it is forgiven.
  */
-export const patternModule = (id, watch, loaders, cache, warm, startTexts, isKept = EVERY_FILE) => {
+export const patternModule = (id, watch, loaders, cache, warm, startTexts, isKept = EVERY_FILE, isForgiving = false, catalogue, scriptProblems = []) => {
     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);
+    const { files, refused } = readStoryFiles(root, patterns, watch, cache, isKept);
+    if (refused.length > 0 && !isForgiving)
+        throw refusalError(refused);
+    warm?.(files.map(({ file }) => file));
     startTexts?.(files);
-    const code = storyFilesCode(root, patterns, files, loaders, startTexts !== undefined);
-    return { code, moduleType: "js", files };
+    const code = storyFilesCode(root, patterns, withPreviewTags(files, previewTagsOf(catalogue, watch)), loaders, startTexts !== undefined, refused, isForgiving ? scriptProblems : []);
+    return { code, moduleType: "js", files, refused };
 };
 /**
- * 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.
+ * Whether a story file added or removed changes what a page may hold of a group of story files: listed now and missing
+ * from a version served since the pages last reloaded, or gone and listed by one. A file no pattern lists, or one a
+ * `!` pattern leaves out, changes nothing, so the pages need no reload for it.
+ *
+ * @remarks
+ * The module's last version is no measure: another reader (a second tab, a frame, the agents' API) may load it again
+ * between the change on the disk and the file's event, and a page that loaded it before would then never reload. A
+ * branch switch makes that window wide, as its events arrive after the files are written. Every version since the last
+ * reload counts, and no earlier one: that reload renewed the pages that held those.
  *
  * @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 served - the versions served since the pages last reloaded; none when the module 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)
+export const isListingChanged = (id, served, file, isKept = EVERY_FILE) => {
+    if (served === 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));
+    const key = VITE_PATHS.normalize(file);
+    return isListed ? served.every !== undefined && !served.every.has(key) : served.some.has(key);
+};
+/**
+ * A docs pages' module, when the id is a pattern's, a page's or the written home's. The Markdown reader loads with the
+ * first: a catalogue may have no docs pages, and a story's page reads none.
+ *
+ * @param id - the module's id.
+ * @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.
+ */
+export 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))
+        return undefined;
+    const { docPageModule, docPagesModule, homeModule } = await import("./docPagesModule.js");
+    if (isHome)
+        return { code: homeModule(id.slice(0, -HOME_QUERY.length), watch, isServing, plugins), moduleType: "js" };
+    if (isPage) {
+        const file = id.slice(0, -DOCS_PAGE_QUERY.length);
+        return { code: docPageModule(file, watch, isServing, plugins), moduleType: "js" };
+    }
+    const { root, patterns } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
+    return { code: docPagesModule(root, patterns, watch, isServing, plugins, isKept), moduleType: "js" };
+};
+/**
+ * Makes a group's module and adds the version to those served since the pages last reloaded (`isListingChanged`).
+ * While it is made, and when making it fails, the list is unknown.
+ *
+ * @param listings - the groups' modules, with the versions served.
+ * @param id - the group's module's id.
+ * @param make - makes the module.
+ * @returns the module made.
+ */
+export const keptListing = (listings, id, make) => {
+    const before = listings.get(id);
+    listings.set(id, undefined);
+    const made = make();
+    const listed = new Set([...made.files, ...made.refused].map(({ file }) => file));
+    const every = before?.every;
+    listings.set(id, {
+        some: new Set([...(before?.some ?? []), ...listed]),
+        every: every === undefined ? listed : new Set([...every].filter((file) => listed.has(file)))
+    });
+    return made;
+};
+/**
+ * Forgets the versions served before a reload the pages were sent: each page loads the module again.
+ *
+ * @param listings - the groups' modules, with the versions served.
+ */
+export const pagesReloaded = (listings) => {
+    for (const [id, served] of listings)
+        if (served !== undefined)
+            listings.set(id, { some: new Set(), every: undefined });
 };
 /**
  * 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 served - the groups' modules, with the versions served since the pages last reloaded.
  * @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.
@@ -111,7 +182,8 @@ export const listingRenewals = (served, file, readers, isKept = EVERY_FILE) => {
     return changed.length === 0 ? undefined : [...changed, ...readers];
 };
 /**
- * A group's facts: its story files indexed, what their stories render read in the docs worker.
+ * A group's facts: its story files indexed, what their stories render read in the docs worker. A file that cannot be
+ * indexed adds nothing here: the group's own module names it.
  *
  * @param group - the group (`storyFilesGroupText`).
  * @param watch - adds a file whose edit renews the module (each story file).
@@ -121,7 +193,7 @@ export const listingRenewals = (served, file, readers, isKept = EVERY_FILE) => {
  */
 const groupUsage = async (group, watch, usage, cache, isKept) => {
     const { root, patterns } = storyFilesGroupOf(group);
-    const files = indexedStoryFiles(root, patterns, watch, cache, isKept);
+    const { files } = readStoryFiles(root, patterns, watch, cache, isKept);
     const graph = await usage(files.map((file) => ({
         storyFile: file.file,
         exports: file.index.stories.map((story) => story.exportName)
@@ -163,8 +235,9 @@ export const usageModule = async (id, watch, usage, cache, pack, isKept = EVERY_
  */
 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);
+    // the reason, not an empty list: no story reached and no story found are different answers
     const reach = typeof graph === "string"
-        ? []
+        ? graph
         : storyReach(graph, files.map((file) => ({ storyFile: file.file, title: file.index.title })));
     return { code: `export default ${codeLiteral(reach)};`, moduleType: "js" };
 };
@@ -219,3 +292,18 @@ export const searchIndexes = (read) => {
         }
     };
 };
+/**
+ * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
+ *
+ * @param server - the dev server.
+ * @param ids - the modules' ids.
+ */
+export const invalidateEverywhere = (server, ids) => {
+    for (const environment of Object.values(server.environments)) {
+        for (const id of ids) {
+            const module = environment.moduleGraph.getModuleById(id);
+            if (module !== undefined)
+                environment.moduleGraph.invalidateModule(module);
+        }
+    }
+};