forgebook 0.1.8 → 0.2.0

package/dist/src/vite/pages.js

@@ -11,12 +11,21 @@
  *
  * @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 { 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 +39,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 +179,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 +198,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 +217,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 +285,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 +322,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 +330,94 @@ 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: one `?forgebook-files` or `?forgebook-docs-pages` import per
+ * glob, 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`)};`),
+    ...config.stories.map((pattern, index) => `import files${index} from ${codeLiteral(`./${pattern.replace(/^\.\//, "")}?forgebook-files`)};`),
+    ...config.docs.map((pattern, index) => `import docs${index} from ${codeLiteral(`./${pattern.replace(/^\.\//, "")}?forgebook-docs-pages`)};`),
     "export const source = {",
-    `  id: ${JSON.stringify(OWN_SOURCE_ID)},`,
-    `  name: ${JSON.stringify(config.title)},`,
+    `  id: ${codeLiteral(OWN_SOURCE_ID)},`,
+    `  name: ${codeLiteral(config.title)},`,
     `  files: [${config.stories.map((_pattern, index) => `files${index}`).join(", ")}],`,
+    ...(config.docs.length === 0
+        ? []
+        : [`  docs: [${config.docs.map((_pattern, index) => `docs${index}`).join(", ")}],`]),
     "  sheets: { required: [], theme: [], restyled: [] }",
     "};",
     ""
 ].join("\n");
-//# sourceMappingURL=pages.js.map

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;

package/dist/src/vite/parsedFiles.js

@@ -0,0 +1,91 @@
+/**
+ * The files the docs' TypeScript programs parse, kept between programs and shared by every configuration that parses
+ * alike, as TypeScript's language service groups them.
+ *
+ * @remarks
+ * A renewed program reuses a file only when its compiler host hands back the same object, so without a kept parse
+ * every renewal parses everything again; and in a monorepo whose paths lead every package to every other's sources,
+ * each package's program holds the same thousands of files. A kept parse is reused while the file is unchanged, told by
+ * its change time and size (`stampOf`), which a write moves even when it keeps the modification time. A build, which
+ * changes no file, skips that check until something says files may change (`checkFileChanges`).
+ *
+ * The standard library's declarations and `@types` packages are parsed without their documentation: most of what
+ * `lib.dom.d.ts` and a framework's types weigh, which no component's docs read. Other declarations in `node_modules`
+ * keep theirs, since a catalogue may document an installed library.
+ *
+ * @module
+ */
+import { statSync } from "node:fs";
+import { dirname } from "node:path";
+import ts from "typescript-6";
+/** What tells which configurations parse a file alike, as TypeScript's language service groups them. */
+const DOCUMENT_REGISTRY = ts.createDocumentRegistry();
+/** The parsed files of each way of parsing, by file name and version. */
+const parsedFiles = new Map();
+/** Whether files may change while they are kept: a dev server's, or any reader told of an edit. */
+let mayChange = false;
+/** From now on a kept parse is checked against its file before it is reused. */
+export const checkFileChanges = () => {
+    mayChange = true;
+};
+/** Whether files may change while the programs read them: a dev server's, or any reader told of an edit. */
+export const mayFilesChange = () => mayChange;
+/**
+ * A file's stamp: its change time, in nanoseconds, and its size; none for a file that is not there.
+ *
+ * @param fileName - the file.
+ */
+const stampOf = (fileName) => {
+    const stats = statSync(fileName, { bigint: true, throwIfNoEntry: false });
+    return stats === undefined ? undefined : `${stats.ctimeNs}:${stats.size}`;
+};
+/**
+ * Whether a file's documentation is left out of its parse: the standard library's, or an `@types` package's.
+ *
+ * @param fileName - the file, as TypeScript names it (forward slashes).
+ * @param libraryFolder - the standard library's folder, the same way.
+ */
+const isUndocumented = (fileName, libraryFolder) => dirname(fileName) === libraryFolder || fileName.includes("/node_modules/@types/");
+/**
+ * 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 const keptParse = (options, parse) => {
+    const libraryFolder = dirname(ts.getDefaultLibFilePath(options)).replaceAll("\\", "/");
+    const shared = DOCUMENT_REGISTRY.getKeyForCompilationSettings(options);
+    const kept = parsedFiles.get(shared) ?? new Map();
+    parsedFiles.set(shared, kept);
+    return (fileName, languageVersion, onError, shouldCreate) => {
+        const stamp = mayChange ? stampOf(fileName) : undefined;
+        const version = typeof languageVersion === "object" ? languageVersion : { languageVersion };
+        const entry = `${fileName}|${version.languageVersion}|${version.impliedNodeFormat ?? ""}`;
+        const known = kept.get(entry);
+        if (known !== undefined && known.stamp === stamp && shouldCreate !== true)
+            return known.file;
+        const file = parse(fileName, isUndocumented(fileName, libraryFolder)
+            ? { ...version, jsDocParsingMode: ts.JSDocParsingMode.ParseNone }
+            : version, onError, shouldCreate);
+        kept.set(entry, { stamp, file });
+        return file;
+    };
+};
+/**
+ * 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 const keepParsesOf = (programs) => {
+    const held = new Set();
+    for (const program of programs)
+        for (const file of program.getSourceFiles())
+            held.add(file);
+    for (const [shared, kept] of parsedFiles) {
+        for (const [entry, parsed] of kept)
+            if (parsed.file === undefined || !held.has(parsed.file))
+                kept.delete(entry);
+        if (kept.size === 0)
+            parsedFiles.delete(shared);
+    }
+};

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

@@ -0,0 +1,20 @@
+/**
+ * The languages outside the TypeScript family that a component's documentation writes, split into coloured pieces: CSS,
+ * SCSS, JSON, shell and HTML.
+ *
+ * @remarks
+ * Each is a short list of patterns tried in order at every position, since a page shows short examples and colouring
+ * them needs no parser: a general highlighter would add 9 MB to every install for five small grammars. The patterns
+ * take negated classes and no nested repetition, so a long text cannot slow them down.
+ *
+ * @module
+ */
+import type { CodePiece } from "./typeScriptPieces.ts";
+/**
+ * A piece of documentation's code as coloured pieces.
+ *
+ * @param code - the code.
+ * @param language - its language, as a Markdown fence names it.
+ * @returns the pieces, or none for a language with no grammar here.
+ */
+export declare const grammarPieces: (code: string, language: string) => readonly CodePiece[] | undefined;