forgebook 0.1.7 → 0.2.0

package/dist/src/vite/forgebookPlugin.js

@@ -9,8 +9,8 @@
  * `?forgebook-docs`, answered with the component's props as the framework reads them (`adapter.ts`, in a worker) or
  * `{ error }` for the panel, `?forgebook-code`, answered with each story's `render` as written (`storyCode.ts`),
  * `?forgebook-page`, answered with the component's documentation file as HTML (`componentPage.ts`), and
- * `?forgebook-markdown`, a source's own Markdown file (its introduction on the home) as HTML. It also sets
- * Lightning CSS as the CSS transformer with the forced-states visitor (`forcedStates.ts`) and lets Sass resolve
+ * `?forgebook-markdown`, a source's own Markdown file (its introduction on the home) as HTML. A source's docs pages
+ * come the same way, with `?forgebook-docs-pages` (`docPagesModule.ts`), and the written home with `?forgebook-home`. It also sets Lightning CSS as the CSS transformer with the forced-states visitor (`forcedStates.ts`) and lets Sass resolve
  * `pkg:` URLs, which the library's style sheets use.
  *
  * A pattern's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
@@ -19,37 +19,33 @@
  *
  * @module
  */
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import ts from "typescript-6";
+import { existsSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { isFileLoadingAllowed } from "vite";
+import { SAME_ORIGIN } from "../frameOrigins.js";
 import { createLiveErrors, isLiveErrorReport, LIVE_ERROR_EVENT } from "../liveErrors.js";
-import { agentMiddleware } from "./agentRoutes.js";
+import { agentMiddleware, FRAMED_AGENT_PAGES } from "./agentRoutes.js";
 import { STORY_FILE } from "./autoTitle.js";
-import { componentPage, markdownHtml } from "./componentPage.js";
+import { axeAddress, axeBuildAsset } from "./axeScript.js";
+import { groupTexts } from "./builtTexts.js";
+import { catalogueConfig } from "./catalogueConfig.js";
+import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
+import { codeStamp, diskCache } from "./diskCache.js";
 import { createDocsExtractor } from "./docsExtractor.js";
-import { moduleSummaryOf } from "./docsProgram.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
-import { highlightCode } from "./highlightCode.js";
-import { AGENT_SOURCES_FILE, agentSourcesModule, CONFIG_MODULE, configModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, STORIES_SOURCE_FILE, shellEntry, storiesSourceModule } from "./pages.js";
-import { prebundled, scannedEntries } from "./prebundled.js";
-import { storyCode } from "./storyCode.js";
-import { indexedStoryFiles, storyFilesGroupOf, storyFilesGroupText, storyFilesModule, USAGE_PREFIX } from "./storyFilesModule.js";
-import { componentImport } from "./storyMeta.js";
-import { joinedUsage } from "./usageModule.js";
-/**
- * A file's text, or none when it cannot be read.
- *
- * @param file - the file.
- */
-const readTextFile = (file) => {
-    try {
-        return readFileSync(file, "utf8");
-    }
-    catch {
-        return undefined;
-    }
-};
+import { builtPlacement } from "./framesConfig.js";
+import { serveFrames } from "./framesServer.js";
+import { missingHeightsMiddleware } from "./heightsRoute.js";
+import { FILES_MODULE_HOT, renewedModule, servedPatterns, storyFileHotHooks } from "./hotSnippets.js";
+import { inlineJson, packedJsonOf } from "./packedModule.js";
+import { AGENT_SOURCES_FILE, agentSourcesModule, configModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, shellEntry, storiesSourceModule } from "./pages.js";
+import { CONFIG_ID, DOCS_PAGES_PREFIX, patternId, TOKENS_ID, virtualId } from "./pluginIds.js";
+import { docsModule, docsValue, FILES_PREFIX, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
+import { isKeptIndex, storyFilesGroupOf } from "./storyFilesModule.js";
+import { tokensModule } from "./storylessRoutes.js";
+import { CODE_QUERY, DOCS_PAGE_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /** This module's folder, in the core's package: the core's own dependencies resolve from here, not the project's. */
 const PACKAGE_DIR = import.meta.dirname;
 /**
@@ -62,160 +58,50 @@ const sassOptions = async () => {
     const { NodePackageImporter } = await import("sass-embedded");
     return { preprocessorOptions: { scss: { importers: [new NodePackageImporter()] } } };
 };
-/** The query that asks for the story files a pattern matches (`../src/**\/*.stories.tsx?forgebook-files`). */
-const FILES_QUERY = "?forgebook-files";
-/** The id of a pattern's module: virtual, with the declaring module's folder and the pattern after it. */
-const FILES_PREFIX = "\0forgebook-files:";
-/** The query that asks for a story file's code: each story's `render` as written. */
-const CODE_QUERY = "?forgebook-code";
-/** The query that asks for a story file's component page: its documentation file as HTML. */
-const PAGE_QUERY = "?forgebook-page";
-/** The query a source's Markdown file is imported with (its introduction on the home), answered with its HTML. */
-const MARKDOWN_QUERY = "?forgebook-markdown";
+/** A docs page, whose file added or removed changes what the sidebar lists. */
+const DOCS_PAGE_FILE = /\.md$/;
 /** A TypeScript source file, whose edit may change a component's docs. */
 const SOURCE_FILE = /\.tsx?$/;
 /** The query that asks for a story file's component docs. */
 const DOCS_QUERY = "?forgebook-docs";
+/** The queries `textModules.ts` answers. */
+const TEXT_QUERIES = [CODE_QUERY, PAGE_QUERY, MARKDOWN_QUERY];
+/** The queries of a story file's modules the shell reads, which hand an edit to it in place on a dev server. */
+const RENEWED_QUERIES = [DOCS_QUERY, CODE_QUERY, PAGE_QUERY];
+/** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
+const FILE_QUERIES = [
+    DOCS_QUERY,
+    CODE_QUERY,
+    PAGE_QUERY,
+    MARKDOWN_QUERY,
+    DOCS_PAGE_QUERY,
+    HOME_QUERY
+];
 /**
- * The module that answers a `?forgebook-docs` import: the story file's component docs, or `{ error }` for the panel.
- *
- * @param component - what the extractor read for the story file.
- * @param watch - adds a file whose edit renews the module.
- */
-const docsModule = (component, watch) => {
-    // the docs come from the component's files, not the story file the id names: Vite renews them on an edit only if
-    // it watches those files too
-    if (typeof component !== "string" && "sources" in component) {
-        for (const file of component.sources)
-            watch(file);
-    }
-    const value = typeof component === "string" ? { error: component } : component.docs;
-    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
-};
-/**
- * The module that answers a `?forgebook-code` import: each story's `render` text and its coloured HTML, or `{ error }`
- * for the card.
- *
- * @param storyFile - the story file's absolute path; Vite renews the module when it changes, as the id names it.
- */
-const codeModule = (storyFile) => {
-    const code = storyCode(storyFile, readFileSync(storyFile, "utf8"));
-    const value = typeof code === "string"
-        ? { error: code }
-        : Object.fromEntries(Object.entries(code).map(([name, text]) => [name, { text, html: highlightCode(text, "tsx") }]));
-    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
-};
-/**
- * The file of a story file's component, from the meta's import, resolved as the app resolves it.
- *
- * @param storyFile - the story file's absolute path.
- * @param resolve - resolves an import of the story file to its file; none when it does not resolve.
- * @returns the component's file, or none when the meta names no imported component.
- */
-const componentFileOf = async (storyFile, resolve) => {
-    const specifier = componentImport(storyFile, readFileSync(storyFile, "utf8"));
-    return specifier === undefined ? undefined : resolve(specifier);
-};
-/**
- * The module that answers a `?forgebook-page` import: the component's documentation file as HTML (empty without
- * one), and its file's summary, the first paragraph of its `@module` comment, for the page's lead.
- *
- * @remarks
- * The summary is read here, from the component's file alone, rather than with the docs: the docs wait for the
- * package's TypeScript program, and the lead would come seconds after the rest of the page.
- *
- * @param storyFile - the story file's absolute path.
- * @param componentFile - the component's file, as the story file's import resolves; none when it names none.
- * @param watch - adds a file whose edit renews the module (the documentation file, the component's file).
- */
-const pageModule = (storyFile, componentFile, watch) => {
-    const page = componentPage(storyFile);
-    if (page !== undefined)
-        watch(page.file);
-    if (componentFile !== undefined)
-        watch(componentFile);
-    const summary = componentFile === undefined
-        ? ""
-        : moduleSummaryOf(ts.createSourceFile(componentFile, readFileSync(componentFile, "utf8"), ts.ScriptTarget.Latest, true));
-    const value = { html: page?.html ?? "", summary };
-    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
-};
-/**
- * The module that answers a `?forgebook-markdown` import: a source's Markdown file (its introduction) as HTML.
+ * Whether a dev server may read the file a query names: a plugin's answer never passes Vite's own check of
+ * `server.fs`, so without this any file could be asked for by adding a query to its address.
  *
- * @param file - the Markdown file's absolute path.
- * @param watch - adds a file whose edit renews the module (the Markdown file).
- */
-const markdownModule = (file, watch) => {
-    watch(file);
-    const value = { html: markdownHtml(readFileSync(file, "utf8")) };
-    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
-};
-/**
- * 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)}`;
-/**
- * The module of a `?forgebook-files` pattern: every matched story file's index and loaders.
- *
- * @param id - the module's id (`FILES_PREFIX`, then the group: `storyFilesGroupText`).
- * @param watch - adds a file whose edit renews the module (each story file).
- * @param warm - builds the program that holds a story file, so the package's docs are ready before a page asks.
- * @param hasUsage - whether the group offers its "Used in" loader.
- * @throws when a story file cannot be indexed.
- */
-const patternModule = (id, watch, warm, hasUsage) => {
-    const { root, pattern } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
-    let first;
-    const code = storyFilesModule(root, pattern, (file) => {
-        first ??= file;
-        watch(file);
-    }, hasUsage);
-    if (first !== undefined)
-        warm(first);
-    return { code, moduleType: "js" };
-};
-/** The resolved id of a group's "Used in" module: Rollup's mark of a virtual module, then its import's specifier. */
-const USAGE_ID_PREFIX = `\0${USAGE_PREFIX}`;
-/**
- * The id of a virtual module the plugin makes (the configuration's data, a group's "Used in"), when the import names
- * one.
- *
- * @param source - the import's specifier.
+ * @param id - the module's id.
+ * @param server - the dev server; none in a build, which reads only what the sources import.
  */
-const virtualId = (source) => {
-    if (source === CONFIG_MODULE)
-        return CONFIG_ID;
-    return source.startsWith(USAGE_PREFIX) ? `\0${source}` : undefined;
-};
+const isReadable = (id, server) => server === undefined ||
+    !FILE_QUERIES.some((query) => id.endsWith(query)) ||
+    isFileLoadingAllowed(server.config, id.slice(0, id.lastIndexOf("?")));
 /**
- * A group's "Used in" module: its story files indexed, what their stories render read in the docs worker, joined.
+ * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
  *
- * @param id - the module's id (`USAGE_ID_PREFIX`, then the group: `storyFilesGroupText`).
- * @param watch - adds a file whose edit renews the module (each story file).
- * @param usage - reads the facts in the docs worker.
+ * @param server - the dev server.
+ * @param ids - the modules' ids.
  */
-const usageModule = async (id, watch, usage) => {
-    const { root, pattern } = storyFilesGroupOf(id.slice(USAGE_ID_PREFIX.length));
-    const files = indexedStoryFiles(root, pattern, watch);
-    const graph = await usage(files.map((file) => ({
-        storyFile: file.file,
-        exports: file.index.stories.map((story) => story.exportName)
-    })));
-    const answer = typeof graph === "string"
-        ? { error: graph }
-        : joinedUsage(graph, files.map((file) => ({
-            storyFile: file.file,
-            title: file.index.title,
-            related: file.index.related ?? []
-        })));
-    return { code: `export default ${JSON.stringify(answer)};`, moduleType: "js" };
+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);
+        }
+    }
 };
-/** The resolved id of the configuration's data module. */
-const CONFIG_ID = `\0${CONFIG_MODULE}`;
 /**
  * The page a request names, when it names one: `/` is the shell's.
  *
@@ -227,39 +113,67 @@ const requestedPage = (url) => {
     return PAGE_FILES.find((page) => page === name);
 };
 /**
- * A module the plugin answers from a file's text alone, when the id asks for one: a story file's code, or a Markdown
- * file as HTML.
+ * 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.
  */
-const textModule = (id, watch) => {
-    if (id.endsWith(CODE_QUERY))
-        return codeModule(id.slice(0, -CODE_QUERY.length));
-    if (id.endsWith(MARKDOWN_QUERY))
-        return markdownModule(id.slice(0, -MARKDOWN_QUERY.length), watch);
-    return undefined;
+const docsModuleOf = async (id, watch, isServing, plugins) => {
+    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, pattern } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
+    return { code: docPagesModule(root, pattern, watch, isServing, plugins), moduleType: "js" };
 };
 /**
- * A module the plugin generates for a catalogue's pages, when the id names one: the configuration's data, an entry,
- * the project's own stories' source, or a page's HTML (unless the folder has one of its own).
+ * A module the plugin generates for a catalogue's pages, when the id names one: an entry, the project's own stories'
+ * source, or a page's HTML (unless the folder has one of its own). The configuration's data waits for the frames'
+ * placement, so the plugin's `load` makes it.
  *
  * @param id - the module's id.
  * @param config - the catalogue's configuration.
+ * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
  */
-const generatedModule = (id, config) => {
-    if (id === CONFIG_ID)
-        return { code: configModule(config), moduleType: "js" };
-    if (id === join(config.dir, PAGE_ENTRIES["index.html"]))
-        return { code: shellEntry(config), moduleType: "js" };
-    if (id === join(config.dir, PAGE_ENTRIES["frame.html"]))
-        return { code: frameEntry(config), moduleType: "js" };
-    if (id === join(config.dir, STORIES_SOURCE_FILE))
+const generatedModule = (id, config, command) => {
+    const named = pageModuleOf(id, config.dir);
+    if (named === undefined)
+        return undefined;
+    if (named.kind === "entry") {
+        const code = named.page === "index.html" ? shellEntry(config) : frameEntry(config, axeAddress(command, PACKAGE_DIR));
+        return { code, moduleType: "js" };
+    }
+    if (named.kind === "stories-source")
         return { code: storiesSourceModule(config), moduleType: "js" };
-    if (id === join(config.dir, AGENT_SOURCES_FILE))
+    if (named.kind === "agent-sources")
         return { code: agentSourcesModule(config), moduleType: "js" };
-    const page = PAGE_FILES.find((candidate) => id === join(config.dir, candidate));
-    return page !== undefined && !existsSync(id) ? pageHtml(page, config) : undefined;
+    return existsSync(id) ? undefined : pageHtml(named.page, config, builtPlacement(config.frames));
+};
+/**
+ * The id of a module the plugin generates for a catalogue's pages, when an import names one: a page or an entry by
+ * its address (`/index.html`, `/.forgebook-shell.ts`) or by its path, a source by its path.
+ *
+ * @param source - the import's specifier.
+ * @param dir - the configuration's folder.
+ */
+const generatedId = (source, dir) => {
+    const byAddress = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}`);
+    if (byAddress !== undefined)
+        return pageModulePath(dir, PAGE_ENTRIES[byAddress]);
+    const pageByAddress = PAGE_FILES.find((page) => source === `/${page}`);
+    if (pageByAddress !== undefined)
+        return pageModulePath(dir, pageByAddress);
+    return pageModuleOf(source, dir) === undefined ? undefined : VITE_PATHS.normalize(source);
 };
 /**
  * The catalogue's Vite plugin: the story index, the docs, the code and the Markdown of the stories, the forced-states
@@ -272,11 +186,74 @@ const generatedModule = (id, config) => {
 export const forgebookPlugin = (options = {}) => {
     /** The modules of the patterns, renewed when a story file is added or removed. */
     const filesModules = new Set();
+    // what each pattern's module was served with: an edit of a story file that changes its list reloads the pages
+    const served = servedPatterns();
     /** The groups' "Used in" modules, renewed when a source file changes: any edit may change what reaches what. */
     const usageModules = new Set();
+    /** The docs pages' modules, renewed when a Markdown file is added or removed. */
+    const docsModules = new Set();
+    /** The groups' search indexes: any edit may change what a component's docs say. */
+    const searchModules = new Set();
     /** The errors the open frames report, for `forgebook errors` and the agents. */
     const live = createLiveErrors();
+    /** Where the frames run: the dev server's second port once it listens, the configuration's choice in a build. */
+    let framesPlacement = async () => config === undefined ? SAME_ORIGIN : builtPlacement(config.frames);
     let config = options.config;
+    /**
+     * A module the plugin generates for the catalogue's pages: the configuration's data, once the frames are placed, or
+     * one `generatedModule` makes; none without a configuration or for another id.
+     *
+     * @param id - the module's id.
+     */
+    const pagesModule = async (id) => {
+        if (config === undefined)
+            return undefined;
+        if (id === CONFIG_ID)
+            return { code: configModule(config, await framesPlacement()), moduleType: "js" };
+        return generatedModule(id, config, command);
+    };
+    /** The dev server; none in a build. */
+    let devServer;
+    /** The files followed one by one, so an edit reaches the dev server at once. */
+    const watching = currentCloseWatch();
+    /** Whether a dev server runs, or a build: tools ask only the former. */
+    let command = "serve";
+    const isServing = () => command === "serve";
+    // the search's indexes, a build reading each component's docs once for its page and its index
+    const search = searchIndexes({
+        extract: (storyFile) => extractor().extract(storyFile),
+        isServing,
+        track: (id, isPages) => (isPages ? docsModules : searchModules).add(id)
+    });
+    // a build's docs, code and pages of each group's story files, read while the build loads the stories
+    const texts = groupTexts();
+    // whether an edited story file is drawn anew in its open frames: a dev server's, unless the framework cannot
+    const isRedrawing = () => isServing() && (config?.framework ?? options.framework)?.redrawsEditedStories !== false;
+    /**
+     * Whether the server runs tests (Vitest's mode): no person waits for a page, so no docs program is warmed. A worker
+     * still loading TypeScript when the tests end is stopped by Node mid-parse, which aborts the process.
+     */
+    let isTestRun = false;
+    /** Where answers are kept between starts (`diskCache.ts`): in Vite's cache folder, so what clears it clears them. */
+    let cacheFolder;
+    /** The stamp of the plugin's own code, which makes the kept indexes and code: another version is a miss. */
+    let pluginCode;
+    const keptCache = (kind, isValue) => {
+        if (cacheFolder === undefined)
+            return undefined;
+        // the plugin's own folder holds the code that makes them, with the parser and the highlighter it reads with: an
+        // edit or another version of any is a miss; a stamp that cannot be read keeps nothing
+        try {
+            const resolvePackage = packageResolver(PACKAGE_DIR);
+            const tools = ["vite", "typescript-6", "highlight.js"].flatMap((name) => resolvePackage(name) ?? []);
+            pluginCode ??= codeStamp([PACKAGE_DIR], tools);
+        }
+        catch {
+            return undefined;
+        }
+        return diskCache(join(cacheFolder, kind), pluginCode, isValue);
+    };
+    const indexCache = () => keptCache("index", isKeptIndex);
     // the docs are read in a worker, made once the framework is known: a package's TypeScript program takes seconds to
     // build and would hold every other answer of the dev server meanwhile
     let docs;
@@ -284,47 +261,83 @@ export const forgebookPlugin = (options = {}) => {
         const framework = config?.framework ?? options.framework;
         if (framework === undefined)
             throw new Error("Forgebook has no framework: add forgebook.config.ts, or give the plugin `framework`");
-        docs ??= createDocsExtractor(framework.docsModule);
+        // a build reads every story's docs, a dev server one component at a time
+        docs ??= createDocsExtractor(framework.docsModule, {
+            readsEverything: !isServing(),
+            ...(cacheFolder === undefined ? {} : { cacheFolder })
+        });
         return docs;
     };
     /**
-     * Renews what an edited source file may change: the docs' programs, and every group's "Used in".
+     * Renews what an edited source file may change: the docs' programs, and every group's "Used in" and search index.
      *
      * @param server - the dev server.
      * @param file - the edited file.
      */
     const renewOnChange = (server, file) => {
-        if (!SOURCE_FILE.test(file))
+        const componentFiles = (config?.framework ?? options.framework)?.componentFiles;
+        if (!SOURCE_FILE.test(file) && componentFiles?.extension !== extname(file))
             return;
         docs?.changed();
-        const graph = server.environments.client.moduleGraph;
-        for (const id of usageModules) {
-            const module = graph.getModuleById(id);
-            if (module !== undefined)
-                graph.invalidateModule(module);
-        }
+        invalidateEverywhere(server, [...usageModules, ...searchModules]);
     };
     /**
-     * A pattern's module or a group's "Used in" module, when the id is one.
+     * A pattern's module, or a group's "Used in" or reach module, when the id is one.
      *
      * @param id - the module's id.
      * @param watch - adds a file whose edit renews the module.
+     * @param pack - writes a module's JSON as its value: as it is, or kept out of a build's JavaScript.
+     * @param startTexts - a build's browser files': starts reading a pattern's docs, code and pages, which its module
+     * imports from the group's texts module; none imports each from its query.
      * @throws when a story file cannot be indexed.
      */
-    const storiesModule = async (id, watch) => {
+    const storiesModule = async (id, watch, pack, startTexts) => {
         if (id.startsWith(USAGE_ID_PREFIX)) {
             usageModules.add(id);
-            return usageModule(id, watch, extractor().usage);
+            return usageModule(id, watch, extractor().usage, indexCache(), pack);
+        }
+        // what each story reaches is for the dev server's tools only: a build ships none of it
+        if (id.startsWith(REACH_ID_PREFIX)) {
+            usageModules.add(id);
+            return isServing()
+                ? reachModule(id, watch, extractor().usage, indexCache())
+                : { code: "export default [];", moduleType: "js" };
         }
         if (!id.startsWith(FILES_PREFIX))
             return undefined;
         filesModules.add(id);
-        return patternModule(id, watch, extractor().warm, config?.lists.usedIn !== false);
+        const hasUsage = config?.lists.usedIn !== false;
+        // the worker starts while Vite loads the pages, unless the disk keeps the docs; a test run asks for no page
+        const { files, code } = patternModule(id, watch, { hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts);
+        if (!isRedrawing())
+            return { code, moduleType: "js" };
+        served.keep(id, files);
+        return { code: `${code}\n${FILES_MODULE_HOT}`, moduleType: "js" };
+    };
+    /**
+     * Tells the docs a source file was added or removed: it may be what an import now finds, so no kept docs are read
+     * again this session.
+     *
+     * @param file - the file.
+     */
+    const noteListing = (file) => {
+        const framework = config?.framework ?? options.framework;
+        if (framework === undefined)
+            return;
+        if (SOURCE_FILE.test(file) || framework.componentFiles?.extension === extname(file))
+            extractor().listed();
+    };
+    /**
+     * The modules a file added or removed changes; none when it changes no list.
+     *
+     * @param file - the file.
+     */
+    const modulesListing = (file) => {
+        // the patterns' modules list the story files; the groups' "Used in" read them
+        if (STORY_FILE.test(file))
+            return [...filesModules, ...usageModules, ...searchModules];
+        return DOCS_PAGE_FILE.test(file) && docsModules.size > 0 ? [...docsModules] : undefined;
     };
-    const pagePath = (page) => config === undefined ? undefined : join(config.dir, page);
-    const entryPath = (page) => config === undefined ? undefined : join(config.dir, PAGE_ENTRIES[page]);
-    const storiesSource = () => config === undefined ? undefined : join(config.dir, STORIES_SOURCE_FILE);
-    const agentSources = () => config === undefined ? undefined : join(config.dir, AGENT_SOURCES_FILE);
     /**
      * A module a story file's query asks for (`?forgebook-docs`, `-code`, `-page`, `-markdown`), when the id is one.
      *
@@ -333,41 +346,60 @@ export const forgebookPlugin = (options = {}) => {
      * @param resolveImport - resolves an import of a file as the app resolves it.
      */
     const queryModule = async (id, watch, resolveImport) => {
-        if (id.endsWith(DOCS_QUERY)) {
-            return docsModule(await extractor().extract(id.slice(0, -DOCS_QUERY.length)), watch);
+        if (id === TOKENS_ID && config !== undefined) {
+            // a source's tokens are found from its module, imported as the generated pages import it
+            const importer = pageModulePath(config.dir, AGENT_SOURCES_FILE);
+            return tokensModule(config, watch, (specifier) => resolveImport(specifier, importer));
         }
-        if (id.endsWith(PAGE_QUERY)) {
-            const storyFile = id.slice(0, -PAGE_QUERY.length);
-            const componentFile = await componentFileOf(storyFile, (specifier) => resolveImport(specifier, storyFile));
-            return pageModule(storyFile, componentFile, watch);
+        if (id.endsWith(DOCS_QUERY)) {
+            return docsModule(await search.docsOf(id.slice(0, -DOCS_QUERY.length)), watch);
         }
-        return textModule(id, watch);
+        if (id.startsWith(DOCS_PAGES_PREFIX))
+            docsModules.add(id);
+        const docsPages = await docsModuleOf(id, watch, isServing(), config?.plugins ?? []);
+        if (docsPages !== undefined)
+            return docsPages;
+        if (!TEXT_QUERIES.some((query) => id.endsWith(query)))
+            return undefined;
+        // loaded on the first of these queries: the highlighter, the Markdown reader and what they need stay out of a
+        // server whose pages never ask
+        const { isKeptCode, textModule } = await import("./textModules.js");
+        const componentFiles = (config?.framework ?? options.framework)?.componentFiles;
+        return textModule(id, { watch, resolveImport, componentFiles, cache: keptCache("code", isKeptCode) });
+    };
+    /**
+     * A group's module (a pattern's, its search index, its "Used in", a build's texts), when the id names one.
+     *
+     * @param id - the module's id.
+     * @param watch - adds a file whose edit renews the module.
+     * @param resolveImport - resolves an import of a file as the app resolves it.
+     * @param emit - a build's browser files': writes a packed file; none keeps the JSON in the modules.
+     * @throws when a story file cannot be indexed.
+     */
+    const groupModule = async (id, watch, resolveImport, emit) => {
+        const pack = emit === undefined ? inlineJson : packedJsonOf(emit);
+        const componentFiles = (config?.framework ?? options.framework)?.componentFiles;
+        const docsOf = async (storyFile) => docsValue(await search.docsOf(storyFile), watch);
+        const sources = { docsOf, watch, resolveImport, componentFiles };
+        // a build's browser files only: a dev server answers each text from its query, and no texts module
+        const startTexts = emit === undefined ? undefined : texts.starter(id, sources);
+        return ((emit === undefined ? undefined : await texts.moduleOf(id, sources, emit)) ??
+            (await search.moduleOf(id, watch, pack)) ??
+            (await storiesModule(id, watch, pack, startTexts)) ??
+            null);
     };
     return {
         name: "forgebook",
         enforce: "pre",
-        config: async (userConfig) => {
+        config: async (userConfig, environment) => {
+            command = environment.command;
+            isTestRun = environment.mode === "test";
             if (config === undefined && options.framework === undefined) {
                 const file = findConfigFile(resolve(userConfig.root ?? process.cwd()));
                 if (file !== undefined)
                     config = await loadConfigFile(file);
             }
-            const pages = config === undefined
-                ? {}
-                : {
-                    root: config.dir,
-                    // the pages are generated, so Vite's scanner cannot find what they import: it is named here, and the
-                    // story files (the project's and the sources') are scanned for what their components import
-                    optimizeDeps: {
-                        include: prebundled(config, packageResolver(config.dir), packageResolver(PACKAGE_DIR)),
-                        entries: scannedEntries(config, packageResolver(config.dir), readTextFile)
-                    },
-                    build: {
-                        rolldownOptions: {
-                            input: { index: join(config.dir, "index.html"), frame: join(config.dir, "frame.html") }
-                        }
-                    }
-                };
+            const pages = config === undefined ? {} : catalogueConfig(config, userConfig);
             return {
                 ...pages,
                 css: {
@@ -381,25 +413,41 @@ export const forgebookPlugin = (options = {}) => {
             const virtual = virtualId(source);
             if (virtual !== undefined)
                 return virtual;
-            const entry = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}` || source === entryPath(page));
-            if (entry !== undefined)
-                return entryPath(entry) ?? null;
-            if (source === storiesSource() || source === agentSources())
-                return source;
-            const page = PAGE_FILES.find((candidate) => source === pagePath(candidate) || source === `/${candidate}`);
-            if (page !== undefined)
-                return pagePath(page) ?? null;
-            if (!source.endsWith(FILES_QUERY) || importer === undefined)
-                return null;
-            return filesId(dirname(importer), source.slice(0, -FILES_QUERY.length));
+            const generated = config === undefined ? undefined : generatedId(source, config.dir);
+            if (generated !== undefined)
+                return generated;
+            return importer === undefined ? null : patternId(source, VITE_PATHS.dirname(importer));
+        },
+        // a warning and not a failure: a theme a reader can still use must not stop a catalogue from building
+        configResolved: (resolved) => {
+            // a dev server's answers only: a build reads everything once, and stamping each answer's files costs it more than
+            // a later build would save
+            if (isServing())
+                cacheFolder = join(resolved.cacheDir, "forgebook");
+            for (const problem of config?.shell.problems ?? [])
+                resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
         },
         configureServer: (server) => {
+            devServer = server;
+            // no person waits for a page in a test run
+            watching.serve(isTestRun ? undefined : server);
             server.httpServer?.on("close", () => void docs?.close());
+            // first: the frames' own origin, and the guard that keeps every other origin's page from reading this one
+            if (config !== undefined)
+                serveFrames(server, config, (placement) => (framesPlacement = placement), FRAMED_AGENT_PAGES);
             // an edited component or type file changes its docs: the worker renews its programs on their next read
             server.watcher.on("change", (file) => renewOnChange(server, file));
             // the answers to tools and agents (`forgebook stories`, `forgebook mcp`), from the same sources as the pages
             if (config !== undefined)
-                server.middlewares.use(agentMiddleware(server, config, live));
+                server.middlewares.use(agentMiddleware(server, config, live, () => framesPlacement()));
+            if (config?.heights !== undefined) {
+                const file = {
+                    heights: config.heights,
+                    base: server.config.base,
+                    publicDir: server.config.publicDir
+                };
+                server.middlewares.use(missingHeightsMiddleware(file));
+            }
             server.ws.on(LIVE_ERROR_EVENT, (report) => {
                 if (isLiveErrorReport(report))
                     live.add(report, new Date());
@@ -407,12 +455,13 @@ export const forgebookPlugin = (options = {}) => {
             // the catalogue's pages, made here: no HTML file is written
             server.middlewares.use((request, response, next) => {
                 const page = requestedPage(request.url ?? "/");
-                if (config === undefined || page === undefined) {
+                const served = config;
+                if (served === undefined || page === undefined) {
                     next();
                     return;
                 }
-                server
-                    .transformIndexHtml(request.url ?? "/", pageHtml(page, config))
+                framesPlacement()
+                    .then((placement) => server.transformIndexHtml(request.url ?? "/", pageHtml(page, served, placement)))
                     .then((html) => {
                     response.setHeader("Content-Type", "text/html");
                     response.end(html);
@@ -425,36 +474,55 @@ export const forgebookPlugin = (options = {}) => {
             if (watched.length > 0)
                 server.watcher.add(watched);
             const refresh = (file) => {
-                if (!STORY_FILE.test(file))
+                noteListing(file);
+                const renewed = modulesListing(file);
+                if (renewed === undefined)
                     return;
-                const graph = server.environments.client.moduleGraph;
-                // the patterns' modules list the files; the groups' "Used in" read them
-                for (const id of [...filesModules, ...usageModules]) {
-                    const module = graph.getModuleById(id);
-                    if (module !== undefined)
-                        graph.invalidateModule(module);
-                }
+                invalidateEverywhere(server, renewed);
                 server.ws.send({ type: "full-reload" });
             };
             server.watcher.on("add", refresh);
             server.watcher.on("unlink", refresh);
         },
+        generateBundle() {
+            // axe's script, for the frames' Accessibility card: loaded by the frame, never imported; the browser's build only
+            if (this.environment.name !== "client")
+                return;
+            const axe = config === undefined ? undefined : axeBuildAsset(PACKAGE_DIR);
+            if (axe !== undefined)
+                this.emitFile({ type: "asset", fileName: axe.fileName, source: axe.source });
+        },
+        // a dev server without an HTTP server of its own (middleware mode) ends its close watch here only
+        closeServer: (context) => {
+            if (context.reason === "close")
+                watching.close();
+        },
         closeBundle: async () => {
             await docs?.close();
         },
+        ...storyFileHotHooks(isRedrawing, served.changedBy, watching),
         async load(id) {
-            const generated = config === undefined ? undefined : generatedModule(id, config);
+            const generated = await pagesModule(id);
             if (generated !== undefined)
                 return generated;
-            const watch = (file) => this.addWatchFile(file);
-            const answered = await queryModule(id, watch, async (specifier, importer) => {
+            // an answer, not an error: an error would raise Vite's overlay on every reader's open page
+            if (!isReadable(id, devServer))
+                return { code: "export default null;", moduleType: "js" };
+            // in Vite's form, the text Vite's module graph knows a file by: a Node path on Windows (`C:\app\x.md`) is another
+            const watch = (file) => this.addWatchFile(VITE_PATHS.normalize(file));
+            const resolveImport = async (specifier, importer) => {
                 const resolved = await this.resolve(specifier, importer);
                 return resolved?.id;
-            });
+            };
+            const answered = await queryModule(id, watch, resolveImport);
             if (answered !== undefined)
-                return answered;
+                return renewedModule(id, answered, RENEWED_QUERIES, isServing());
+            // a build's browser files only: a server environment's output is no page's to fetch
+            const emit = isServing() || this.environment.name !== "client"
+                ? undefined
+                : (asset) => this.emitFile(asset);
             try {
-                return (await storiesModule(id, watch)) ?? null;
+                return await groupModule(id, watch, resolveImport, emit);
             }
             catch (error) {
                 this.error(error instanceof Error ? error.message : String(error));
@@ -462,4 +530,3 @@ export const forgebookPlugin = (options = {}) => {
         }
     };
 };
-//# sourceMappingURL=forgebookPlugin.js.map