forgebook 0.1.8 → 0.3.0

package/dist/src/vite/agentRoutes.js

@@ -1,12 +1,48 @@
-import { join } from "node:path";
-import { mergedPreviews, readPreview } from "../frame/storyModule.js";
+/**
+ * The dev server's answers to tools and agents, under `/__forgebook/api/`: `stories` (every story) and `story?id=…`
+ * (one in detail), `pages` and `page?id=…` (the docs pages), `search?query=…` (everything, by its text), each with an
+ * optional `view` (the view's query, `theme=dark&lang=it`) the links open in; and `preview?id=…`, the page that shows a
+ * story inside a client that renders apps, the one answer that is not JSON.
+ *
+ * @remarks
+ * The server loads the sources with the same imports the pages use (`AGENT_SOURCES_FILE`), so a tool sees what the
+ * shell shows. A story module that fails on Node (it reads `window` while it loads) gives its story a problem in the
+ * answer instead of an error. A preview is written for a browser, and only its args and parameters are read here: it
+ * loads with what it imports that needs a browser left as placeholders (`previewRunner.ts`), and one that still fails is
+ * left out of the answers and named among their problems, so it costs a tool neither the catalogue nor answers changed
+ * without a word. Served by the dev server only, where
+ * Vite listens (localhost by default); a build has none of it.
+ *
+ * @module
+ */
+import { realpath } from "node:fs/promises";
+import { createIdResolver } from "vite";
+import { offersUsedIn, readsComponentDocs } from "../catalogue.js";
+import { mergedPreviews, NO_PREVIEW, readPreview } from "../frame/storyModule.js";
 import { sourceFiles } from "../sourceFiles.js";
-import { findStory, storyTree } from "../storyTree.js";
+import { findComponentByTitle, findStory, storyTree } from "../storyTree.js";
 import { sourceUsage } from "../usedIn.js";
-import { storiesDocument, storyDocument } from "./agentApi.js";
-import { AGENT_SOURCES_FILE } from "./pages.js";
+import { frameAddressOf } from "../viewState.js";
+import { storiesDocument, storyDocument, storyLinks } from "./agentApi.js";
+import { agentIndexAnswer } from "./agentIndexRoute.js";
+import { pageAnswer, pagesAnswer } from "./docPagesRoute.js";
+import { findAnswer } from "./findRoute.js";
+import { framesOriginOf } from "./framesConfig.js";
+import { hostOf } from "./framesServer.js";
+import { catalogueChangedFiles, changeBase, changedFiles } from "./gitChange.js";
+import { AGENT_SOURCES_FILE, pageModulePath } from "./pages.js";
+import { PREVIEW_ROUTE } from "./previewRoute.js";
+import { loadPreview } from "./previewRunner.js";
+import { searchAnswer } from "./searchRoute.js";
+import { catalogueTokens, STORYLESS_ROUTES } from "./storylessRoutes.js";
+import { affectedStories } from "./storyReach.js";
 /** The path the answers live under. */
 export const AGENT_API = "/__forgebook/api/";
+/**
+ * The pages under `AGENT_API` another origin's page may frame: a client's inline preview. They show a story and act on
+ * nothing, so the catalogue's guard lets another origin open them, as it does the catalogue's page.
+ */
+export const FRAMED_AGENT_PAGES = new Set([`${AGENT_API}${PREVIEW_ROUTE}`]);
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a value is a source, as far as the answers read one: its id, name and story files. */
@@ -14,15 +50,35 @@ const isStorySource = (value) => isRecord(value) &&
     typeof value["id"] === "string" &&
     typeof value["name"] === "string" &&
     Array.isArray(value["files"]);
-/** The agent module read, or why it is not what the plugin generates. */
-const agentModuleOf = (module) => {
-    if (!isRecord(module) || !Array.isArray(module["sources"]) || !Array.isArray(module["previews"]))
+/** A preview, read from what loads it, or why it cannot load on the server. */
+const loadedPreview = async (load) => {
+    try {
+        return readPreview(await load());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `a preview did not load on the server, so its args and parameters are left out of these answers: ${message}`;
+    }
+};
+/**
+ * The agent module read with the catalogue's previews, or why it is not what the plugin generates.
+ *
+ * @param module - the module of `AGENT_SOURCES_FILE`, as the server loaded it.
+ * @param previews - what loads each preview, in the configuration's order.
+ */
+export const agentModuleOf = async (module, previews) => {
+    if (!isRecord(module) || !Array.isArray(module["sources"]))
         throw new Error("The catalogue's sources did not load");
     const sources = module["sources"].filter(isStorySource);
-    return { sources, preview: mergedPreviews(module["previews"].map(readPreview)) };
+    const loaded = await Promise.all(previews.map(loadedPreview));
+    return {
+        sources,
+        preview: mergedPreviews(loaded.map((each) => (typeof each === "string" ? NO_PREVIEW : each))),
+        problems: loaded.filter((each) => typeof each === "string")
+    };
 };
 /** A loader's value, or why it failed. */
-const settled = async (load) => {
+export const settled = async (load) => {
     if (load === undefined)
         return { value: { name: null } };
     try {
@@ -41,6 +97,22 @@ const usageBySource = async (sources) => {
     const answers = await Promise.all(sources.map(async (source) => [source.id, await sourceUsage(source)]));
     return new Map(answers.flatMap(([id, index]) => (typeof index === "string" ? [] : [[id, index]])));
 };
+/**
+ * What the answers ask of a dev server.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration, whose generated module the sources are imported from.
+ */
+export const agentServer = (server, config) => {
+    // Vite's resolver, not Node's: a catalogue's aliases and a package's export conditions lead to the same file; `scan`
+    // keeps it on the package's own file and away from the optimizer, which would answer with a prebundle
+    const resolveId = createIdResolver(server.config, { scan: true });
+    return {
+        load: (id) => server.ssrLoadModule(id),
+        loadPreview: (file) => loadPreview(server.environments.ssr, file),
+        resolveSource: (specifier) => resolveId(server.environments.client, specifier, pageModulePath(config.dir, AGENT_SOURCES_FILE))
+    };
+};
 /** The header that names the catalogue's folder, so a client knows the server it found serves its catalogue. */
 export const ROOT_HEADER = "forgebook-root";
 /**
@@ -71,19 +143,55 @@ const errorsAnswer = (context, live) => {
  *
  * @param context - what the routes read.
  */
-const storiesAnswer = async (context) => {
+export const storiesAnswer = async (context) => {
     const { config, params, tree, pages, view, loaded } = context;
-    const usage = config.lists.usedIn !== false && params.get("usedIn") === "true"
+    const usage = offersUsedIn(config.lists) && params.get("usedIn") === "true"
         ? await usageBySource(loaded.sources)
         : undefined;
     return { status: 200, body: storiesDocument(config.title, tree, pages, view, usage) };
 };
+/** Whether a value is a list of stories with what they reach. */
+const isReach = (value) => Array.isArray(value);
+/**
+ * The stories a change touches, read from the files git names and the import graph "Used in" reads.
+ *
+ * @param context - what the routes read.
+ */
+const changedAnswer = async ({ config, loaded, tree, params, pages, view }) => {
+    const since = params.get("since") || "HEAD";
+    const base = await changeBase(config.dir, since);
+    if (base === undefined)
+        return { status: 400, body: { error: `"${since}" names no commit here` } };
+    const { root, files } = await changedFiles(config.dir, base);
+    const reaches = await Promise.all(loaded.sources.flatMap((source) => source.files.map(async (group) => {
+        const reach = await group.reach?.();
+        return { source: source.id, reach: isReach(reach) ? reach : [] };
+    })));
+    const changed = catalogueChangedFiles(config.dir, await realpath(config.dir), root, files);
+    const stories = reaches.flatMap(({ source, reach }) => affectedStories(reach, changed).flatMap((story) => {
+        const component = findComponentByTitle(tree, source, story.title)?.component;
+        const found = [...(component?.stories ?? []), ...(component?.unlisted ?? [])].find((each) => each.exportName === story.exportName);
+        return found === undefined
+            ? []
+            : [{ id: found.id, title: story.title, links: storyLinks(pages, found.id, view) }];
+    }));
+    // without the import graph no story is found, which must not read as a change that touches none
+    const problems = offersUsedIn(config.lists)
+        ? []
+        : [
+            readsComponentDocs(config.lists)
+                ? "No story is found through the imports: the catalogue turns Used in off (usedIn: false), whose import graph this reads"
+                : "No story is found through the imports: the catalogue reads no component docs (componentDocs: false), whose programs read the import graph"
+        ];
+    const body = { schema: 1, since, files, stories, problems };
+    return { status: 200, body };
+};
 /**
  * One story in detail, its component's "Used in" when offered.
  *
  * @param context - what the routes read.
  */
-const storyAnswer = async (context) => {
+export const storyAnswer = async (context) => {
     const { config, params, tree, pages, view, loaded } = context;
     const id = params.get("id") ?? "";
     const location = findStory(tree, id);
@@ -91,38 +199,49 @@ const storyAnswer = async (context) => {
     if (location === undefined || source === undefined)
         return { status: 404, body: { error: `No story "${id}"` } };
     const files = sourceFiles(source);
-    const file = location.component.file;
+    // the story's own file: its module, and the docs of the component its meta names, which its args are for
+    const file = location.story.file;
     const parts = {
         module: await settled(files.stories[file]),
         docs: await settled(files.docs[file]),
         preview: loaded.preview
     };
-    const index = config.lists.usedIn === false ? undefined : await sourceUsage(source);
+    const index = offersUsedIn(config.lists) ? await sourceUsage(source) : undefined;
     // a usage that cannot be read leaves "Used in" out, never the story
     const usage = index === undefined || typeof index === "string" ? undefined : { tree, index };
-    return { status: 200, body: storyDocument(location, parts, pages, view, usage) };
+    const document = storyDocument(location, parts, pages, view, usage);
+    // an agent must tell docs turned off from a story file that names no component
+    const body = readsComponentDocs(config.lists)
+        ? document
+        : { ...document, componentDocs: "off" };
+    return { status: 200, body };
 };
 /**
  * Answers one of the API's paths.
  *
- * @param load - loads a module on the server (the dev server's `ssrLoadModule`).
+ * @param server - what the answers ask of the dev server.
  * @param config - the catalogue's configuration.
  * @param route - the path under `AGENT_API` (`stories`, `story`).
- * @param params - the query: `id` for a story, `view` for the links, `usedIn=true` for the list's "Used in" (a
+ * @param params - the query: `id` for a story, `view` for the links, `category`, `name`, `value` and `type` for the
+ *   tokens, `query` and `limit` for a search, `usedIn=true` for the list's "Used in" (a
  *   story's comes with it when the catalogue offers it).
- * @param origin - where the catalogue is served (`http://localhost:5173`), for the links.
+ * @param origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.
  * @param live - the errors the open frames reported, on a dev server a browser uses; none for a server of the
  *   command's own, which no frame reports to.
  */
-export const agentAnswer = async (load, config, route, params, origin, live) => {
+export const agentAnswer = async (server, config, route, params, origins, live) => {
     try {
-        const loaded = agentModuleOf(await load(join(config.dir, AGENT_SOURCES_FILE)));
+        const answerAlone = STORYLESS_ROUTES[route];
+        if (answerAlone !== undefined)
+            return await answerAlone(config, params, server.resolveSource);
+        const loaded = await agentModuleOf(await server.load(pageModulePath(config.dir, AGENT_SOURCES_FILE)), config.previews.map((file) => () => server.loadPreview(file)));
+        const tree = storyTree(loaded.sources);
         const context = {
             loaded,
-            tree: storyTree(loaded.sources),
+            tree: { ...tree, problems: [...loaded.problems, ...tree.problems] },
             config,
             params,
-            pages: { page: `${origin}/`, frame: `${origin}/frame.html` },
+            pages: { page: `${origins.catalogue}/`, frame: `${origins.frames}/frame.html` },
             view: params.get("view") ?? ""
         };
         if (route === "errors")
@@ -131,28 +250,67 @@ export const agentAnswer = async (load, config, route, params, origin, live) =>
             return await storiesAnswer(context);
         if (route === "story")
             return await storyAnswer(context);
+        if (route === "find")
+            return await findAnswer(context);
+        if (route === "search")
+            return await searchAnswer(context);
+        if (route === "pages")
+            return await pagesAnswer(context);
+        if (route === "page")
+            return await pageAnswer(context);
+        if (route === "changed")
+            return await changedAnswer(context);
+        if (route === "agent-index")
+            return await agentIndexAnswer(context, await catalogueTokens(config, server.resolveSource));
         return { status: 404, body: { error: `No answer at ${AGENT_API}${route}` } };
     }
     catch (error) {
         return { status: 500, body: { error: error instanceof Error ? error.message : String(error) } };
     }
 };
+/**
+ * Answers a story's preview page. Its code is read here, on the first request for one: a dev server no client asks for a
+ * preview never loads it.
+ *
+ * @param url - the request's address: `id` and `view` in its query.
+ * @param framesOrigin - the frames' origin, where the page loads the story's frame.
+ * @param response - the answer.
+ */
+const answerPreview = async (url, framesOrigin, response) => {
+    const { previewRelayPage } = await import("./previewPages.js");
+    const id = url.searchParams.get("id") ?? "";
+    const frame = frameAddressOf(`${framesOrigin}/frame.html`, id, url.searchParams.get("view") ?? "");
+    response.setHeader("Content-Type", "text/html");
+    response.setHeader("Cache-Control", "no-store");
+    response.end(previewRelayPage(frame, id));
+};
 /**
  * The middleware that answers under `AGENT_API`, for a catalogue's dev server.
  *
  * @param server - the dev server, which loads the modules.
  * @param config - the catalogue's configuration.
  * @param live - the errors the open frames report.
+ * @param placement - where the frames run, for the links to them.
  * @returns a Connect middleware: it answers its own paths and passes every other request on.
  */
-export const agentMiddleware = (server, config, live) => (request, response, next) => {
-    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+export const agentMiddleware = (server, config, live, placement) => (request, response, next) => {
+    const scheme = server.config.server.https === undefined ? "http:" : "https:";
+    const url = new URL(request.url ?? "/", `${scheme}//${hostOf(request) ?? "localhost"}`);
     if (!url.pathname.startsWith(AGENT_API)) {
         next();
         return;
     }
     const route = url.pathname.slice(AGENT_API.length);
-    void agentAnswer((id) => server.ssrLoadModule(id), config, route, url.searchParams, url.origin, live)
+    const origins = placement().then((frames) => ({
+        catalogue: url.origin,
+        frames: framesOriginOf(frames, url.href) ?? url.origin
+    }));
+    if (route === PREVIEW_ROUTE) {
+        void origins.then((each) => answerPreview(url, each.frames, response)).catch(next);
+        return;
+    }
+    void origins
+        .then((each) => agentAnswer(agentServer(server, config), config, route, url.searchParams, each, live))
         .then(({ status, body }) => {
         response.statusCode = status;
         response.setHeader("Content-Type", "application/json");
@@ -165,4 +323,3 @@ export const agentMiddleware = (server, config, live) => (request, response, nex
         response.end(`${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n`);
     });
 };
-//# sourceMappingURL=agentRoutes.js.map

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

@@ -25,4 +25,3 @@ export declare const patternBase: (pattern: string) => string;
  * @param file - the file, relative to the same folder as `base`.
  */
 export declare const autoTitle: (base: string, file: string) => string | undefined;
-//# sourceMappingURL=autoTitle.d.ts.map

package/dist/src/vite/autoTitle.js

@@ -41,4 +41,3 @@ export const autoTitle = (base, file) => {
         segments.push(last);
     return segments.length === 0 ? undefined : segments.join("/");
 };
-//# sourceMappingURL=autoTitle.js.map

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

@@ -0,0 +1,20 @@
+import type { AxeAddress } from "./pages.ts";
+/**
+ * How the frame's entry gets axe's address: a `?url` import on a dev server, the build's file under the base in a
+ * build.
+ *
+ * @param command - whether a dev server runs, or a build.
+ * @param packageDir - the core's folder.
+ * @returns the address, or none when axe cannot be found.
+ */
+export declare const axeAddress: (command: "serve" | "build", packageDir: string) => AxeAddress | undefined;
+/**
+ * The file a build writes: axe's script, gzipped.
+ *
+ * @param packageDir - the core's folder.
+ * @returns its name and bytes; none when axe cannot be found.
+ */
+export declare const axeBuildAsset: (packageDir: string) => {
+    readonly fileName: string;
+    readonly source: Buffer;
+} | undefined;

package/dist/src/vite/axeScript.js

@@ -0,0 +1,60 @@
+/**
+ * Where a frame finds axe's script, for the Accessibility card: Vite serves the file on a dev server, and a build
+ * writes it gzipped.
+ *
+ * @remarks
+ * axe is a minified file already, more than half a megabyte, for a card most visits never open. Loaded as a module it
+ * would pass through Vite's pre-bundling on every cold start and through the minifier on every build; loaded as a
+ * script it does neither (`checkStory.ts`). A build keeps it gzipped, since it would otherwise be close to half of what
+ * a static catalogue weighs, and the frame unpacks it when asked.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+import { codeLiteral } from "../codeLiteral.js";
+import { packageResolver } from "./configFile.js";
+/**
+ * axe's script, in the core's dependencies; none when it cannot be found.
+ *
+ * @param packageDir - the core's folder.
+ */
+const axeScript = (packageDir) => packageResolver(packageDir)("axe-core/axe.min.js");
+/**
+ * A build's compressed copy of axe's script: its name, from its text, so a new version of axe is a new file. `.bin`,
+ * since `.gz` makes some hosts send it with `Content-Encoding: gzip`, which the browser would unpack before the frame.
+ *
+ * @param text - the script's text.
+ */
+const axeBuildFile = (text) => `assets/axe-${createHash("sha256").update(text).digest("hex").slice(0, 8)}.bin`;
+/**
+ * How the frame's entry gets axe's address: a `?url` import on a dev server, the build's file under the base in a
+ * build.
+ *
+ * @param command - whether a dev server runs, or a build.
+ * @param packageDir - the core's folder.
+ * @returns the address, or none when axe cannot be found.
+ */
+export const axeAddress = (command, packageDir) => {
+    const file = axeScript(packageDir);
+    if (file === undefined)
+        return undefined;
+    if (command === "serve")
+        return { imports: [`import axeUrl from ${codeLiteral(`${file}?url`)};`], value: "axeUrl" };
+    const name = axeBuildFile(readFileSync(file));
+    return { imports: [], value: `import.meta.env.BASE_URL + ${codeLiteral(name)}` };
+};
+/**
+ * The file a build writes: axe's script, gzipped.
+ *
+ * @param packageDir - the core's folder.
+ * @returns its name and bytes; none when axe cannot be found.
+ */
+export const axeBuildAsset = (packageDir) => {
+    const file = axeScript(packageDir);
+    if (file === undefined)
+        return undefined;
+    const text = readFileSync(file);
+    return { fileName: axeBuildFile(text), source: gzipSync(text, { level: 9 }) };
+};

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

@@ -0,0 +1,75 @@
+/**
+ * A build's story-file texts: each file's component docs, code and page, written as data in a module of their group's
+ * rather than imported as a module each.
+ *
+ * @remarks
+ * A dev server imports each text from its query (`?forgebook-docs`, `-code`, `-page`), so an edit renews the one it
+ * changes. A build knows every file's texts, and a module each costs it a script per file and its loader in the group's
+ * module, which every first load fetches. So a text is a gzipped file (the docs, a page that has something to say),
+ * read when the page asks, as "Used in" is; and one that would weigh no more than its file's address (a story file
+ * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
+ * the loader answers the text, as the query's module's default did.
+ *
+ * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
+ * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
+ * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
+ * a module of their own, the group's module is written at once and the build loads the stories while the docs are
+ * read; the reading starts with the group's module (`starter`), and the texts' module waits for it.
+ *
+ * @module
+ */
+import { type EmitAsset } from "./packedModule.ts";
+import { type IndexedStoryFile } from "./storyFilesModule.ts";
+import type { ComponentPageText, KeptCode, TextModuleContext } from "./textModules.ts";
+/** A story file's texts as their queries' modules answer them: its component's docs, its stories' code, its page. */
+export type FileTexts = readonly [docs: unknown, code: KeptCode, page: ComponentPageText];
+/**
+ * The code of a group's texts module: the functions its loaders call, then, as its default, each file's loaders of its
+ * docs, code and page, in the order of the group's rows.
+ *
+ * @param texts - each file's texts, in the files' order.
+ * @param emit - writes a packed file.
+ */
+export declare const textsModuleCode: (texts: readonly FileTexts[], emit: EmitAsset) => string;
+/** What the plugin gives a build's texts: the docs as the panel reads them, and what reading a page needs. */
+export type TextSources = Pick<TextModuleContext, "watch" | "resolveImport" | "componentFiles"> & {
+    /** A story file's component docs as the panel reads them, or `{ error }`; none when the catalogue reads none. */
+    readonly docsOf: ((storyFile: string) => Promise<unknown>) | undefined;
+};
+/** The module a build's texts are answered as. */
+type TextsModule = {
+    readonly code: string;
+    readonly moduleType: "js";
+};
+/** A build's texts, by group: read from when the group's module is written, answered as the texts' module. */
+export type GroupTexts = {
+    /**
+     * What starts reading a pattern's texts as its module is written: the build loads the stories meanwhile.
+     *
+     * @param id - the pattern's module's id (`FILES_PREFIX`, then the group).
+     * @param sources - what reading them needs.
+     * @returns what starts the reading, given the story files in the order of the module's rows.
+     */
+    readonly starter: (id: string, sources: TextSources) => (files: readonly IndexedStoryFile[]) => void;
+    /**
+     * A group's texts module once its texts are read, when the id names one (`TEXTS_ID_PREFIX`). The files the reading
+     * watched are watched by this module, the one an edit of them changes.
+     *
+     * @param id - the module's id.
+     * @param sources - what reading them needs: its own `watch`, and the rest when its pattern's module did not start
+     * the reading (a module loaded again).
+     * @param emit - writes a packed file.
+     * @returns the module; none for another id.
+     */
+    readonly moduleOf: (id: string, sources: TextSources, emit: EmitAsset) => Promise<TextsModule | undefined>;
+};
+/**
+ * A build's texts, by group.
+ *
+ * @remarks
+ * A reading started is kept until its module takes it, and marked handled at once: a failure before the module asks
+ * would otherwise end the process, and the module's load still reports it. The reading outlives the load of the
+ * pattern's module that started it, so it records the files it watches and the texts' module watches them.
+ */
+export declare const groupTexts: () => GroupTexts;
+export {};

package/dist/src/vite/builtTexts.js

@@ -0,0 +1,143 @@
+/**
+ * A build's story-file texts: each file's component docs, code and page, written as data in a module of their group's
+ * rather than imported as a module each.
+ *
+ * @remarks
+ * A dev server imports each text from its query (`?forgebook-docs`, `-code`, `-page`), so an edit renews the one it
+ * changes. A build knows every file's texts, and a module each costs it a script per file and its loader in the group's
+ * module, which every first load fetches. So a text is a gzipped file (the docs, a page that has something to say),
+ * read when the page asks, as "Used in" is; and one that would weigh no more than its file's address (a story file
+ * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
+ * the loader answers the text, as the query's module's default did.
+ *
+ * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
+ * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
+ * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
+ * a module of their own, the group's module is written at once and the build loads the stories while the docs are
+ * read; the reading starts with the group's module (`starter`), and the texts' module waits for it.
+ *
+ * @module
+ */
+import { codeLiteral, codeOfJson } from "../codeLiteral.js";
+import { gzippedJson, packedFileName, packedLoaderMaker } from "./packedModule.js";
+import { FILES_PREFIX, TEXTS_ID_PREFIX } from "./pluginModules.js";
+import { indexedStoryFiles, storyFilesGroupOf, storyFilesGroupText } from "./storyFilesModule.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The function that makes a packed file's loader, in the generated code. */
+const PACKED = "packedText";
+/** The function that makes the loader of a text written in the module, in the generated code. */
+const WRITTEN = "writtenText";
+/**
+ * Writes texts as loaders: each in a gzipped file, or in the module when that weighs no more than the file and its
+ * address (an empty page's JSON is shorter than its gzip header and the fetch it would cost). A text written in the
+ * module is written once, however many files share it (most story files have no code and no page), and its loader
+ * shared with them.
+ *
+ * @param emit - writes a packed file.
+ */
+const textWriter = (emit) => {
+    const names = new Map();
+    const written = (json) => {
+        const name = names.get(json) ?? `${WRITTEN}${names.size}`;
+        names.set(json, name);
+        return name;
+    };
+    return {
+        loaderOf: (value) => {
+            const json = JSON.stringify(value);
+            const fileName = packedFileName(json);
+            const address = codeLiteral(fileName);
+            const packed = gzippedJson(json);
+            if (json.length <= address.length + packed.length)
+                return written(json);
+            emit({ type: "asset", fileName, source: packed });
+            return `${PACKED}(${address})`;
+        },
+        written: () => [...names].map(([json, name]) => `const ${name} = () => Promise.resolve(${codeOfJson(json)});`)
+    };
+};
+/**
+ * Every file's texts, read: a build reads them all once, as it would for their modules.
+ *
+ * @param files - the group's story files, indexed.
+ * @param read - reads a file's texts.
+ * @returns each file's texts, in the files' order.
+ */
+const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.all([read.docsOf?.(file), read.codeOf(file), read.pageOf(file)])));
+/**
+ * The code of a group's texts module: the functions its loaders call, then, as its default, each file's loaders of its
+ * docs, code and page, in the order of the group's rows.
+ *
+ * @param texts - each file's texts, in the files' order.
+ * @param emit - writes a packed file.
+ */
+export const textsModuleCode = (texts, emit) => {
+    // written in the files' order once all are read, so the names in the module do not depend on which read ended first
+    const writer = textWriter(emit);
+    // a text not read (the docs of a catalogue that reads none) has no loader, and its place stays in the row
+    const rows = texts.map((each) => `[${each.map((text) => (text === undefined ? "null" : writer.loaderOf(text))).join(", ")}]`);
+    return [packedLoaderMaker(PACKED), ...writer.written(), `export default [${rows.join(",\n")}];`].join("\n");
+};
+/**
+ * A build's readers of the texts: the code and the pages as their queries answer them, read with the modules that
+ * answer them, which load only when a build asks.
+ *
+ * @param sources - the docs, and what reading a page needs.
+ */
+const textReaders = async (sources) => {
+    const { storyFileCode, storyFilePage } = await import("./textModules.js");
+    return {
+        docsOf: sources.docsOf,
+        // a build keeps nothing between runs: it reads each file once
+        codeOf: (storyFile) => storyFileCode(storyFile, undefined),
+        pageOf: (storyFile) => storyFilePage(storyFile, sources)
+    };
+};
+/**
+ * A group as its texts module's id writes it: the pattern's module names the folder as its importer's, the texts'
+ * module in Vite's form (`storyFilesCode`), so both are read back and written the same way.
+ *
+ * @param group - the group (`storyFilesGroupText`).
+ */
+const groupKey = (group) => {
+    const { root, patterns } = storyFilesGroupOf(group);
+    return storyFilesGroupText(VITE_PATHS.normalize(root), patterns);
+};
+/**
+ * A build's texts, by group.
+ *
+ * @remarks
+ * A reading started is kept until its module takes it, and marked handled at once: a failure before the module asks
+ * would otherwise end the process, and the module's load still reports it. The reading outlives the load of the
+ * pattern's module that started it, so it records the files it watches and the texts' module watches them.
+ */
+export const groupTexts = () => {
+    const started = new Map();
+    const read = async (files, sources) => readTexts(files, await textReaders(sources));
+    const code = async (group, sources, emit) => {
+        const key = groupKey(group);
+        const reading = started.get(key);
+        started.delete(key);
+        if (reading === undefined) {
+            const { root, patterns } = storyFilesGroupOf(group);
+            return textsModuleCode(await read(indexedStoryFiles(root, patterns, sources.watch), sources), emit);
+        }
+        const texts = await reading.texts;
+        for (const file of reading.watched)
+            sources.watch(file);
+        return textsModuleCode(texts, emit);
+    };
+    return {
+        starter: (id, sources) => (files) => {
+            const watched = [];
+            const texts = read(files, { ...sources, watch: (file) => void watched.push(file) });
+            texts.catch(() => undefined);
+            started.set(groupKey(id.slice(FILES_PREFIX.length)), { texts, watched });
+        },
+        moduleOf: async (id, sources, emit) => {
+            if (!id.startsWith(TEXTS_ID_PREFIX))
+                return undefined;
+            return { code: await code(id.slice(TEXTS_ID_PREFIX.length), sources, emit), moduleType: "js" };
+        }
+    };
+};

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

@@ -0,0 +1,10 @@
+import type { UserConfig } from "vite";
+import { type ResolvedConfig } from "./configFile.ts";
+/**
+ * What the plugin sets in Vite's configuration for a catalogue: its folder as the root, what to pre-bundle, the pages
+ * as the build's inputs, and the dev server's reads kept to each origin.
+ *
+ * @param config - the catalogue's configuration.
+ * @param userConfig - the configuration so far, whose own `server.cors` and build output the plugin leaves alone.
+ */
+export declare const catalogueConfig: (config: ResolvedConfig, userConfig: UserConfig) => UserConfig;