forgebook 0.1.8 → 0.3.0

package/dist/src/vite/packedModule.js

@@ -0,0 +1,74 @@
+/**
+ * A module's JSON kept out of a build's JavaScript: gzipped in a file of its own, unpacked when the module loads
+ * (`packedText.ts`).
+ *
+ * @remarks
+ * A static catalogue's "Used in" is read by few visits and compresses to a tenth, so a build writes it as a file and
+ * the module keeps only its address; a story file's docs, code and page are written the same way (`builtTexts.ts`). A
+ * dev server answers with the JSON itself.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+import { codeLiteral, codeOfJson } from "../codeLiteral.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/**
+ * The module the page unpacks with, by its own path: the generated code imports it as a file of this package, so it is
+ * no public subpath and a project need not resolve the package by name.
+ */
+const PACKED_TEXT = VITE_PATHS.normalize(fileURLToPath(new URL(`../packedText${extname(import.meta.url)}`, import.meta.url)));
+/** The JSON as code of the same value, on a dev server. */
+export const inlineJson = (json) => codeOfJson(json);
+/**
+ * The name a build gives a JSON document's gzipped file: its content's hash, so a host may keep it for ever. Twelve
+ * hex digits: a build writes up to three per story file, and two documents of one name would show one in place of the
+ * other with no error.
+ *
+ * @param json - the document.
+ */
+export const packedFileName = (json) => `assets/${createHash("sha256").update(json).digest("hex").slice(0, 12)}.bin`;
+/**
+ * A JSON document gzipped, as a build writes it.
+ *
+ * @param json - the document.
+ */
+export const gzippedJson = (json) => 
+// gzip's default level: a higher one takes twice as long on a large index for the same size
+gzipSync(json);
+/**
+ * The code of a function that makes the loader of a packed file by its name (`packedFileName`): the module the page
+ * unpacks with loads on the first such load, never with the code that holds the loaders. A loader keeps its answer,
+ * as an imported module's default is kept, and forgets a failure, so the next load asks again.
+ *
+ * @param name - the function's name in the generated code.
+ */
+export const packedLoaderMaker = (name) => [
+    `const ${name} = (file) => {`,
+    "  let loading;",
+    "  return () => {",
+    `    loading ??= import(${codeLiteral(PACKED_TEXT)})`,
+    "      .then((module) => module.packedJson(import.meta.env.BASE_URL + file))",
+    "      .catch((error) => {",
+    "        loading = undefined;",
+    "        throw error;",
+    "      });",
+    "    return loading;",
+    "  };",
+    "};"
+].join("\n");
+/**
+ * The JSON in a gzipped file named by its content, for a build. The module's value is the promise of it, which its
+ * loader (`import(…).then((module) => module.default)`) waits for: no top-level await, which a catalogue's lower
+ * `build.target` would refuse.
+ *
+ * @param emit - writes the file.
+ */
+export const packedJsonOf = (emit) => (json) => {
+    const fileName = packedFileName(json);
+    emit({ type: "asset", fileName, source: gzippedJson(json) });
+    const address = `import.meta.env.BASE_URL + ${codeLiteral(fileName)}`;
+    return `import(${codeLiteral(PACKED_TEXT)}).then((module) => module.packedJson(${address}))`;
+};

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

@@ -1,10 +1,14 @@
+import type { FramesPlacement } from "../frameOrigins.ts";
 import { type ResolvedConfig } from "./configFile.ts";
+import { type VitePaths } from "./vitePaths.ts";
 /** The pages, by their file name. */
 export declare const PAGE_FILES: readonly ["index.html", "frame.html"];
 /** A page's file name. */
 export type PageFile = (typeof PAGE_FILES)[number];
 /** The module the pages read the configuration's data from. */
 export declare 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 declare const TOKENS_MODULE = "virtual:forgebook/tokens";
 /**
  * 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
@@ -15,47 +19,97 @@ export declare const PAGE_ENTRIES: Readonly<Record<PageFile, string>>;
 export declare const STORIES_SOURCE_FILE = ".forgebook-stories.ts";
 /**
  * The file name, in the configuration's folder, of the module the dev server loads to answer tools and agents: the
- * sources and the previews, as the frame gets them (never written to disk).
+ * sources, as the frame gets them (never written to disk).
  */
 export declare const AGENT_SOURCES_FILE = ".forgebook-agent.ts";
-/** The project's own stories' source id. */
-export declare const OWN_SOURCE_ID = "stories";
+/** A module the plugin generates in the configuration's folder: a page, a page's entry, or one of the two sources. */
+export type PageModule = {
+    readonly kind: "page";
+    readonly page: PageFile;
+} | {
+    readonly kind: "entry";
+    readonly page: PageFile;
+} | {
+    readonly kind: "stories-source";
+} | {
+    readonly kind: "agent-sources";
+};
+/**
+ * A generated module's path, in Vite's form: what the pages import, what Vite's ids name.
+ *
+ * @param dir - the configuration's folder.
+ * @param file - the module's file name (`PAGE_FILES`, `PAGE_ENTRIES`, `STORIES_SOURCE_FILE`, `AGENT_SOURCES_FILE`).
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export declare const pageModulePath: (dir: string, file: string, paths?: VitePaths) => string;
+/**
+ * The generated module a path names, when it names one: an id from Vite (`C:/app/.forgebook-shell.ts` on Windows) or
+ * a path from Node (`C:\app\frame.html`, as the build's inputs may arrive) both match.
+ *
+ * @param path - the id or path.
+ * @param dir - the configuration's folder.
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export declare const pageModuleOf: (path: string, dir: string, paths?: VitePaths) => PageModule | undefined;
 /**
  * A page's HTML: its title, the frame's head tags, the root the entry mounts in.
  *
  * @param page - the page.
  * @param config - the configuration.
+ * @param placement - where the frames run, which the frame's load guard tells its errors by.
  */
-export declare const pageHtml: (page: PageFile, config: ResolvedConfig) => string;
+export declare const pageHtml: (page: PageFile, config: ResolvedConfig, placement: FramesPlacement) => string;
 /**
  * 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 declare const configModule: (config: ResolvedConfig, frames: FramesPlacement) => string;
+/** The module the entry loads the written home's view from, on first use. */
+export declare const WRITTEN_HOME_MODULE = "forgebook/shell/home";
+/** The module the entry loads the code that draws the plugins' views from, on first use. */
+export declare const PLUGIN_HOSTS_MODULE = "forgebook/shell/plugin-hosts";
+/**
+ * Whether a catalogue lists a plugin with a view in the shell: a tab or a docs block.
+ *
+ * @param config - the configuration.
  */
-export declare const configModule: (config: ResolvedConfig) => string;
+export declare const hasPluginViews: (config: ResolvedConfig) => boolean;
 /**
  * The shell's entry: the shell mounted with the configuration's data, the logo, the sources and the code writer.
  *
  * @param config - the configuration.
  */
 export declare const shellEntry: (config: ResolvedConfig) => string;
+/** How a frame's entry gets the address of axe's script (`axeScript.ts`). */
+export type AxeAddress = {
+    /** The imports it needs. */
+    readonly imports: readonly string[];
+    /** The expression that gives the address. */
+    readonly value: string;
+};
 /**
  * The frame's entry: the framework's frame mounted with the sources, the configuration's data and the previews.
  *
  * @param config - the configuration.
+ * @param axe - how the entry gets the address of axe's script, for the Accessibility card; none when it cannot be
+ *   found, which leaves the card to say so.
  */
-export declare const frameEntry: (config: ResolvedConfig) => string;
+export declare const frameEntry: (config: ResolvedConfig, axe?: AxeAddress) => string;
 /**
- * The module the dev server loads to answer tools and agents: the sources and the previews the frame mounts, as
- * values (`sources`, `previews`), loaded on the server with the same imports the pages use.
+ * The module the dev server loads to answer tools and agents: the sources the frame mounts (`sources`), with the same
+ * imports the pages use. The previews are loaded beside it, each on its own (`previewRunner.ts`): a browser's code may
+ * keep one from loading on the server.
  *
  * @param config - the configuration.
  */
 export declare const agentSourcesModule: (config: ResolvedConfig) => string;
 /**
- * The source of the project's own stories: one `?forgebook-files` import per glob, named after the catalogue.
+ * The source of the project's own stories and docs pages: its `stories` as one group of story files and its `docs` as
+ * one group of docs pages, each imported by its patterns (`FILES_SPECIFIER_PREFIX`), so a `!` pattern leaves files out
+ * of what all the others list and a file two patterns list comes once; named after the catalogue.
  *
  * @param config - the configuration.
  */
 export declare const storiesSourceModule: (config: ResolvedConfig) => string;
-//# sourceMappingURL=pages.d.ts.map

package/dist/src/vite/pages.js

@@ -11,12 +11,22 @@
  *
  * @module
  */
-import { join } from "node:path";
+import { codeLiteral } from "../codeLiteral.js";
+import { OWN_SOURCE_ID } from "../docPages.js";
+import { FRAME_STARTED_ATTRIBUTE, STATUS_ATTRIBUTE } from "../frame/frameStatus.js";
+import { LOAD_RELOADS_KEY } from "../frame/staleModule.js";
+import { PREVIEWS_EVENT } from "../hotModules.js";
 import { PLAY_TOOLS_PACKAGES } from "./configFile.js";
+import { pluginFrameModule } from "./pluginConfig.js";
+import { DOCS_PAGES_SPECIFIER_PREFIX, FILES_SPECIFIER_PREFIX, storyFilesGroupText } from "./storyFilesModule.js";
+import { HOME_QUERY } from "./textQueries.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /** The pages, by their file name. */
 export const PAGE_FILES = ["index.html", "frame.html"];
 /** The module the pages read the configuration's data from. */
 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 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
@@ -30,24 +40,139 @@ export const PAGE_ENTRIES = {
 export const STORIES_SOURCE_FILE = ".forgebook-stories.ts";
 /**
  * The file name, in the configuration's folder, of the module the dev server loads to answer tools and agents: the
- * sources and the previews, as the frame gets them (never written to disk).
+ * sources, as the frame gets them (never written to disk).
  */
 export const AGENT_SOURCES_FILE = ".forgebook-agent.ts";
-/** The project's own stories' source id. */
-export const OWN_SOURCE_ID = "stories";
+/**
+ * A generated module's path, in Vite's form: what the pages import, what Vite's ids name.
+ *
+ * @param dir - the configuration's folder.
+ * @param file - the module's file name (`PAGE_FILES`, `PAGE_ENTRIES`, `STORIES_SOURCE_FILE`, `AGENT_SOURCES_FILE`).
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export const pageModulePath = (dir, file, paths = VITE_PATHS) => paths.join(dir, file);
+/**
+ * The generated module a path names, when it names one: an id from Vite (`C:/app/.forgebook-shell.ts` on Windows) or
+ * a path from Node (`C:\app\frame.html`, as the build's inputs may arrive) both match.
+ *
+ * @param path - the id or path.
+ * @param dir - the configuration's folder.
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export const pageModuleOf = (path, dir, paths = VITE_PATHS) => {
+    const named = paths.normalize(path);
+    const isAt = (file) => named === pageModulePath(dir, file, paths);
+    const entry = PAGE_FILES.find((page) => isAt(PAGE_ENTRIES[page]));
+    if (entry !== undefined)
+        return { kind: "entry", page: entry };
+    const page = PAGE_FILES.find((candidate) => isAt(candidate));
+    if (page !== undefined)
+        return { kind: "page", page };
+    if (isAt(STORIES_SOURCE_FILE))
+        return { kind: "stories-source" };
+    if (isAt(AGENT_SOURCES_FILE))
+        return { kind: "agent-sources" };
+    return undefined;
+};
 /**
  * Text set in HTML: its `<`, `>`, `&` and quotes escaped.
  *
  * @param text - the text.
  */
 const escaped = (text) => text.replace(/[&<>"]/g, (character) => `&#${character.charCodeAt(0)};`);
+/**
+ * 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
+ * and its shell waits. Plain script in the page, since a module that failed cannot report anything; it stands down
+ * once the frame has started (`FRAME_STARTED_ATTRIBUTE`), when the frame shows its own errors. It reads only errors
+ * thrown by code and module scripts that failed to load: an image, a style sheet or a classic script of the `head`
+ * (an analytics tag a blocker refuses) is not the catalogue's code.
+ *
+ * A module that could not be loaded is loaded again first, up to three times, one, two then four seconds later, once per
+ * page load, counted in the session's storage by the frame's page and story until the frame draws its story
+ * (`staleModule.ts` clears the count) or the guard gives up: in development a library served as source asks for
+ * thousands of modules, and the browser refuses some while the other frames load (`ERR_INSUFFICIENT_RESOURCES`).
+ *
+ * It tells the shell only on the catalogue's origin, worked out as `pageOrigins` does for a frame from the placement
+ * and the frame's own address, never from the address's query: a page that framed the story must not read its errors.
+ *
+ * @param placement - where the frames run.
+ */
+const frameLoadGuard = (placement) => `(function () {
+  var RELOAD_DELAY = 1000;
+  var RELOADS = 3;
+  var PLACEMENT = ${codeLiteral(placement)};
+  var root = document.documentElement;
+  var key = ${codeLiteral(LOAD_RELOADS_KEY)} + location.pathname + "?story=" + (new URLSearchParams(location.search).get("story") || "");
+  var isReloading = false;
+  function hasStarted() {
+    return root.hasAttribute(${codeLiteral(FRAME_STARTED_ATTRIBUTE)}) || root.hasAttribute(${codeLiteral(STATUS_ATTRIBUTE)});
+  }
+  function catalogueOrigin() {
+    if (PLACEMENT.kind === "origins") return PLACEMENT.catalogue;
+    var own = new URL(location.href);
+    if (PLACEMENT.kind === "ports") own.port = String(PLACEMENT.catalogue);
+    return own.origin;
+  }
+  function forget() {
+    try {
+      sessionStorage.removeItem(key);
+    } catch (error) {
+      // nothing to forget where the storage refuses access
+    }
+  }
+  function show(message) {
+    if (hasStarted()) return;
+    forget();
+    var box = document.createElement("div");
+    box.className = "forgebook-frame-error";
+    box.setAttribute("role", "alert");
+    var text = document.createElement("p");
+    text.className = "forgebook-frame-error__message";
+    text.textContent = message;
+    box.appendChild(text);
+    document.getElementById("root").replaceChildren(box);
+    root.setAttribute(${codeLiteral(STATUS_ATTRIBUTE)}, "error");
+    var storyId = new URLSearchParams(location.search).get("story") || "";
+    if (parent !== window) parent.postMessage({ type: "forgebook:error", storyId: storyId, message: message }, catalogueOrigin());
+  }
+  function reloadAgain() {
+    if (isReloading) return true;
+    var done;
+    try {
+      done = Number(sessionStorage.getItem(key) || "0");
+      if (done >= RELOADS) return false;
+      sessionStorage.setItem(key, String(done + 1));
+    } catch (error) {
+      return false;
+    }
+    isReloading = true;
+    setTimeout(function () {
+      if (!hasStarted()) location.reload();
+    }, RELOAD_DELAY * Math.pow(2, done));
+    return true;
+  }
+  addEventListener("error", function (event) {
+    if (hasStarted()) return;
+    var target = event.target;
+    if (target && target.tagName === "SCRIPT" && target.type === "module") {
+      if (reloadAgain()) return;
+      show("The catalogue's code could not be loaded (" + target.src + "): see the console");
+      return;
+    }
+    if (event instanceof ErrorEvent) {
+      show("The catalogue's code failed while it loaded: " + (event.error && event.error.message ? event.error.message : event.message));
+    }
+  }, true);
+})();`;
 /**
  * A page's HTML: its title, the frame's head tags, the root the entry mounts in.
  *
  * @param page - the page.
  * @param config - the configuration.
+ * @param placement - where the frames run, which the frame's load guard tells its errors by.
  */
-export const pageHtml = (page, config) => [
+export const pageHtml = (page, config, placement) => [
     "<!doctype html>",
     '<html lang="en">',
     "  <head>",
@@ -55,9 +180,16 @@ export const pageHtml = (page, config) => [
     '    <meta name="viewport" content="width=device-width, initial-scale=1" />',
     `    <title>${escaped(page === "index.html" ? config.title : "Story")}</title>`,
     ...(page === "frame.html" && config.head !== "" ? [config.head] : []),
+    ...(page === "frame.html" && config.shell.frameCss !== ""
+        ? [`    <style>${config.shell.frameCss}</style>`]
+        : []),
+    ...(page === "index.html" && config.shell.themeCss !== ""
+        ? [`    <style>${config.shell.themeCss}</style>`]
+        : []),
     "  </head>",
     "  <body>",
     '    <div id="root"></div>',
+    ...(page === "frame.html" ? [`    <script>${frameLoadGuard(placement)}</script>`] : []),
     `    <script type="module" src="/${PAGE_ENTRIES[page]}"></script>`,
     "  </body>",
     "</html>",
@@ -67,16 +199,18 @@ export const pageHtml = (page, config) => [
  * 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) => {
+export const configModule = (config, frames) => {
     const data = {
         title: config.title,
         heights: config.heights,
         switches: config.switches,
         languages: config.languages,
-        lists: config.lists
+        lists: config.lists,
+        frames
     };
-    return `export default ${JSON.stringify(data)};`;
+    return `export default ${codeLiteral(data)};`;
 };
 /**
  * The imports of the sources, and the list they make: the project's own stories first, then each package's.
@@ -84,13 +218,65 @@ export const configModule = (config) => {
  * @param config - the configuration.
  */
 const sourcesCode = (config) => {
-    const own = config.stories.length > 0 ? [`./${STORIES_SOURCE_FILE}`] : [];
-    const specifiers = [...own.map((file) => join(config.dir, file.slice(2))), ...config.sources];
+    const hasOwn = config.stories.length > 0 || config.docs.length > 0;
+    const own = hasOwn ? [pageModulePath(config.dir, STORIES_SOURCE_FILE)] : [];
+    const specifiers = [...own, ...config.sources];
     return {
-        imports: specifiers.map((specifier, index) => `import { source as source${index} } from ${JSON.stringify(specifier)};`),
+        imports: specifiers.map((specifier, index) => `import { source as source${index} } from ${codeLiteral(specifier)};`),
         list: `[${specifiers.map((_specifier, index) => `source${index}`).join(", ")}]`
     };
 };
+/** The module the entry loads the written home's view from, on first use. */
+export const WRITTEN_HOME_MODULE = "forgebook/shell/home";
+/**
+ * The shell's written home, as the entry writes it: loaded as the home opens, with its text, so a catalogue without
+ * one pays nothing for it, and the shell's own code holds nothing of it.
+ *
+ * @param home - the home's absolute path.
+ */
+const writtenHomeCode = (home) => [
+    "() =>",
+    `      import(${codeLiteral(WRITTEN_HOME_MODULE)}).then((module) =>`,
+    `        module.writtenHome(() => import(${codeLiteral(`${home}${HOME_QUERY}`)}).then((page) => page.default))`,
+    "      )"
+].join("\n");
+/** The module the entry loads the code that draws the plugins' views from, on first use. */
+export const PLUGIN_HOSTS_MODULE = "forgebook/shell/plugin-hosts";
+/**
+ * Whether a catalogue lists a plugin with a view in the shell: a tab or a docs block.
+ *
+ * @param config - the configuration.
+ */
+export const hasPluginViews = (config) => config.plugins.some((plugin) => (plugin.tabs ?? []).length > 0 || (plugin.docBlocks ?? []).length > 0);
+/**
+ * The shell's list of the plugins' tabs and docs blocks, each with the import that loads its view when it is first
+ * needed, and the loader of the code that draws them; nothing for a catalogue without any, whose entry is then what it
+ * would be with no plugin and whose build holds none of that code.
+ *
+ * @param config - the configuration.
+ */
+const pluginViewLines = (config) => {
+    const lines = config.plugins.flatMap((plugin) => {
+        const tabs = (plugin.tabs ?? []).map((tab) => `{ id: ${codeLiteral(tab.id)}, label: ${codeLiteral(tab.label)}, ` +
+            // a tab with no condition shows on every story: it has no `when` to write
+            (tab.when === undefined ? "" : `when: ${codeLiteral(tab.when)}, `) +
+            `load: () => import(${codeLiteral(tab.view)}) }`);
+        const blocks = (plugin.docBlocks ?? []).map((block) => `{ fence: ${codeLiteral(block.fence)}, load: () => import(${codeLiteral(block.view)}) }`);
+        return tabs.length === 0 && blocks.length === 0
+            ? []
+            : [
+                `      { id: ${codeLiteral(plugin.id)}, tabs: [${tabs.join(", ")}], docBlocks: [${blocks.join(", ")}] },`
+            ];
+    });
+    return lines.length === 0
+        ? []
+        : [
+            "    plugins: [",
+            ...lines,
+            "    ],",
+            `    pluginHosts: () => import(${codeLiteral(PLUGIN_HOSTS_MODULE)}).then((module) => module.pluginHosts),`
+        ];
+};
 /**
  * The shell's entry: the shell mounted with the configuration's data, the logo, the sources and the code writer.
  *
@@ -100,21 +286,33 @@ export const shellEntry = (config) => {
     const sources = sourcesCode(config);
     return [
         'import { mountShell } from "forgebook/shell";',
-        `import { codeOf } from ${JSON.stringify(config.framework.pages.code)};`,
-        `import config from ${JSON.stringify(CONFIG_MODULE)};`,
-        ...(config.logo === undefined ? [] : [`import logo from ${JSON.stringify(`${config.logo}?url`)};`]),
+        `import { codeOf } from ${codeLiteral(config.framework.pages.code)};`,
+        `import config from ${codeLiteral(CONFIG_MODULE)};`,
+        ...(config.logo === undefined ? [] : [`import logo from ${codeLiteral(`${config.logo}?url`)};`]),
         ...sources.imports,
+        ...config.shell.styleSheets.map((file) => `import ${codeLiteral(file)};`),
         'const root = document.getElementById("root");',
         "if (root !== null)",
         "  mountShell(root, {",
         "    title: config.title,",
         ...(config.logo === undefined ? [] : ["    logo,"]),
+        ...(config.shell.hasBranding ? [] : ["    hasBranding: false,"]),
         ...(config.heights === undefined ? [] : ["    heights: config.heights,"]),
+        ...(config.home === undefined ? [] : [`    home: ${writtenHomeCode(config.home)},`]),
         `    sources: ${sources.list},`,
         '    frameUrl: "frame.html",',
+        "    frames: config.frames,",
         "    languages: config.languages,",
         ...(config.switches === undefined ? [] : ["    switches: config.switches,"]),
         "    lists: config.lists,",
+        ...pluginViewLines(config),
+        ...(config.framework.addressTexts === undefined
+            ? []
+            : [`    addressTexts: ${codeLiteral(config.framework.addressTexts)},`]),
+        // a source may declare tokens of its own, read with the catalogue's
+        ...(config.tokens.length === 0 && config.sources.length === 0
+            ? []
+            : [`    loadTokens: () => import(${codeLiteral(TOKENS_MODULE)}).then((module) => module.default),`]),
         "    codeOf",
         "  });",
         ""
@@ -125,7 +323,7 @@ export const shellEntry = (config) => {
  * catalogue whose stories have no play never loads them.
  */
 const playToolsLoader = () => {
-    const imports = PLAY_TOOLS_PACKAGES.map((name) => `import(${JSON.stringify(name)})`).join(", ");
+    const imports = PLAY_TOOLS_PACKAGES.map((name) => `import(${codeLiteral(name)})`).join(", ");
     return [
         "    playTools: async () => {",
         `      const [dom, events] = await Promise.all([${imports}]);`,
@@ -133,60 +331,100 @@ const playToolsLoader = () => {
         "    },"
     ].join("\n");
 };
+/**
+ * What the frame's entry runs on a dev server to take the edits of its previews and of what they import, which the frame
+ * draws in place (`hotModules.ts`); without it, an edit of a component a preview imports through a library's index
+ * reloads every open page.
+ *
+ * @param previews - the previews' files, as the entry imports them.
+ */
+const previewsHot = (previews) => previews.length === 0
+    ? []
+    : [
+        "if (import.meta.hot)",
+        // plain JSON, unlike every other value here: Vite reads the accepted files as the text between the quotes,
+        // escapes undecoded, and resolves an escaped path as no file; this module is never set inline in a page
+        `  import.meta.hot.accept(${JSON.stringify(previews)}, (next) =>`,
+        `    window.dispatchEvent(new CustomEvent(${codeLiteral(PREVIEWS_EVENT)}, { detail: { next } }))`,
+        "  );"
+    ];
 /**
  * The frame's entry: the framework's frame mounted with the sources, the configuration's data and the previews.
  *
  * @param config - the configuration.
+ * @param axe - how the entry gets the address of axe's script, for the Accessibility card; none when it cannot be
+ *   found, which leaves the card to say so.
  */
-export const frameEntry = (config) => {
+export const frameEntry = (config, axe) => {
     const sources = sourcesCode(config);
+    const frames = config.plugins.flatMap((plugin) => {
+        const frame = pluginFrameModule(plugin, config.framework.name);
+        return frame === undefined ? [] : [{ id: plugin.id, frame }];
+    });
     return [
-        `import { mountFrame } from ${JSON.stringify(config.framework.pages.frame)};`,
-        `import config from ${JSON.stringify(CONFIG_MODULE)};`,
+        `import { mountFrame } from ${codeLiteral(config.framework.pages.frame)};`,
+        `import config from ${codeLiteral(CONFIG_MODULE)};`,
+        ...(axe?.imports ?? []),
         ...sources.imports,
-        ...config.previews.map((file, index) => `import * as preview${index} from ${JSON.stringify(file)};`),
+        ...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");',
         "if (root !== null)",
         "  void mountFrame(root, {",
         `    sources: ${sources.list},`,
+        ...(axe === undefined ? [] : [`    axeUrl: ${axe.value},`]),
         "    languages: config.languages,",
         ...(config.switches === undefined ? [] : ["    switches: config.switches,"]),
         "    lists: config.lists,",
+        "    frames: config.frames,",
         ...(config.hasPlayTools ? [playToolsLoader()] : []),
+        ...(frames.length === 0
+            ? []
+            : [
+                `    plugins: [${frames
+                    .map((plugin, index) => `{ id: ${codeLiteral(plugin.id)}, create: pluginFrame${index} }`)
+                    .join(", ")}],`
+            ]),
         `    previews: [${config.previews.map((_file, index) => `preview${index}`).join(", ")}]`,
         "  });",
+        ...previewsHot(config.previews),
         ""
     ].join("\n");
 };
 /**
- * The module the dev server loads to answer tools and agents: the sources and the previews the frame mounts, as
- * values (`sources`, `previews`), loaded on the server with the same imports the pages use.
+ * The module the dev server loads to answer tools and agents: the sources the frame mounts (`sources`), with the same
+ * imports the pages use. The previews are loaded beside it, each on its own (`previewRunner.ts`): a browser's code may
+ * keep one from loading on the server.
  *
  * @param config - the configuration.
  */
 export const agentSourcesModule = (config) => {
     const sources = sourcesCode(config);
-    return [
-        ...sources.imports,
-        ...config.previews.map((file, index) => `import * as preview${index} from ${JSON.stringify(file)};`),
-        `export const sources = ${sources.list};`,
-        `export const previews = [${config.previews.map((_file, index) => `preview${index}`).join(", ")}];`,
-        ""
-    ].join("\n");
+    return [...sources.imports, `export const sources = ${sources.list};`, ""].join("\n");
 };
 /**
- * The source of the project's own stories: one `?forgebook-files` import per glob, named after the catalogue.
+ * The source of the project's own stories and docs pages: its `stories` as one group of story files and its `docs` as
+ * one group of docs pages, each imported by its patterns (`FILES_SPECIFIER_PREFIX`), so a `!` pattern leaves files out
+ * of what all the others list and a file two patterns list comes once; named after the catalogue.
  *
  * @param config - the configuration.
  */
-export const storiesSourceModule = (config) => [
-    ...config.stories.map((pattern, index) => `import files${index} from ${JSON.stringify(`./${pattern.replace(/^\.\//, "")}?forgebook-files`)};`),
-    "export const source = {",
-    `  id: ${JSON.stringify(OWN_SOURCE_ID)},`,
-    `  name: ${JSON.stringify(config.title)},`,
-    `  files: [${config.stories.map((_pattern, index) => `files${index}`).join(", ")}],`,
-    "  sheets: { required: [], theme: [], restyled: [] }",
-    "};",
-    ""
-].join("\n");
-//# sourceMappingURL=pages.js.map
+export const storiesSourceModule = (config) => {
+    // the configuration's folder in Vite's form, as the plugin names an importer's: the patterns are relative to it
+    const folder = VITE_PATHS.normalize(config.dir);
+    const group = (prefix, patterns) => codeLiteral(`${prefix}${storyFilesGroupText(folder, patterns)}`);
+    const hasStories = config.stories.length > 0;
+    const hasDocs = config.docs.length > 0;
+    return [
+        ...(hasStories ? [`import files from ${group(FILES_SPECIFIER_PREFIX, config.stories)};`] : []),
+        ...(hasDocs ? [`import docs from ${group(DOCS_PAGES_SPECIFIER_PREFIX, config.docs)};`] : []),
+        "export const source = {",
+        `  id: ${codeLiteral(OWN_SOURCE_ID)},`,
+        `  name: ${codeLiteral(config.title)},`,
+        `  files: [${hasStories ? "files" : ""}],`,
+        ...(hasDocs ? ["  docs: [docs],"] : []),
+        "  sheets: { required: [], theme: [], restyled: [] }",
+        "};",
+        ""
+    ].join("\n");
+};

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

@@ -0,0 +1,18 @@
+import ts from "typescript-6";
+/** From now on a kept parse is checked against its file before it is reused. */
+export declare const checkFileChanges: () => void;
+/** Whether files may change while the programs read them: a dev server's, or any reader told of an edit. */
+export declare const mayFilesChange: () => boolean;
+/**
+ * The function a compiler host parses files with, keeping what it parsed for the next program that parses alike.
+ *
+ * @param options - the program's compiler options.
+ * @param parse - the host's own parse.
+ */
+export declare const keptParse: (options: ts.CompilerOptions, parse: ts.CompilerHost["getSourceFile"]) => ts.CompilerHost["getSourceFile"];
+/**
+ * Lets go every kept parse no program still holds: the limit on programs then bounds the parsed files too.
+ *
+ * @param programs - the programs kept.
+ */
+export declare const keepParsesOf: (programs: Iterable<ts.Program>) => void;