forgebook 0.2.0 → 0.3.1

package/dist/src/vite/forgebookPlugin.js

@@ -13,38 +13,40 @@
  * come the same way, with `?forgebook-docs-pages` (`docPagesModule.ts`), and the written home with `?forgebook-home`. It also sets Lightning CSS as the CSS transformer with the forced-states visitor (`forcedStates.ts`) and lets Sass resolve
  * `pkg:` URLs, which the library's style sheets use.
  *
- * A pattern's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
+ * A group's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
  * sources' story files live in other packages: `watch` names their folders, and a story file added or removed there
- * renews every pattern's module and reloads the page, so the sidebar lists it at once.
+ * renews the modules of the groups whose list it changes and reloads the page, so the sidebar lists it at once; one no
+ * group lists (a `!` pattern leaves it out) reloads nothing.
  *
  * @module
  */
-import { existsSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
-import { isFileLoadingAllowed } from "vite";
+import { checksA11y, offersUsedIn, readsComponentDocs } from "../catalogue.js";
 import { SAME_ORIGIN } from "../frameOrigins.js";
 import { createLiveErrors, isLiveErrorReport, LIVE_ERROR_EVENT } from "../liveErrors.js";
 import { agentMiddleware, FRAMED_AGENT_PAGES } from "./agentRoutes.js";
 import { STORY_FILE } from "./autoTitle.js";
-import { axeAddress, axeBuildAsset } from "./axeScript.js";
+import { axeBuildAsset } from "./axeScript.js";
 import { groupTexts } from "./builtTexts.js";
 import { catalogueConfig } from "./catalogueConfig.js";
 import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
 import { codeStamp, diskCache } from "./diskCache.js";
-import { createDocsExtractor } from "./docsExtractor.js";
+import { createDocsExtractor, NO_DOCS_EXTRACTOR } from "./docsExtractor.js";
+import { devServerAccess, VITEST_HOOKS } from "./fileAccess.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
 import { builtPlacement } from "./framesConfig.js";
 import { serveFrames } from "./framesServer.js";
+import { generatedId, generatedModule } from "./generatedModules.js";
 import { missingHeightsMiddleware } from "./heightsRoute.js";
 import { FILES_MODULE_HOT, renewedModule, servedPatterns, storyFileHotHooks } from "./hotSnippets.js";
 import { inlineJson, packedJsonOf } from "./packedModule.js";
-import { AGENT_SOURCES_FILE, agentSourcesModule, configModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, shellEntry, storiesSourceModule } from "./pages.js";
+import { AGENT_SOURCES_FILE, configModule, PAGE_FILES, pageHtml, pageModulePath } from "./pages.js";
 import { CONFIG_ID, DOCS_PAGES_PREFIX, patternId, TOKENS_ID, virtualId } from "./pluginIds.js";
-import { docsModule, docsValue, FILES_PREFIX, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
+import { docsModule, docsValue, FILES_PREFIX, listingRenewals, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
 import { isKeptIndex, storyFilesGroupOf } from "./storyFilesModule.js";
 import { tokensModule } from "./storylessRoutes.js";
-import { CODE_QUERY, DOCS_PAGE_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
+import { DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, RENEWED_QUERIES, TEXT_QUERIES } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** This module's folder, in the core's package: the core's own dependencies resolve from here, not the project's. */
 const PACKAGE_DIR = import.meta.dirname;
@@ -62,31 +64,6 @@ const sassOptions = async () => {
 const DOCS_PAGE_FILE = /\.md$/;
 /** A TypeScript source file, whose edit may change a component's docs. */
 const SOURCE_FILE = /\.tsx?$/;
-/** The query that asks for a story file's component docs. */
-const DOCS_QUERY = "?forgebook-docs";
-/** The queries `textModules.ts` answers. */
-const TEXT_QUERIES = [CODE_QUERY, PAGE_QUERY, MARKDOWN_QUERY];
-/** The queries of a story file's modules the shell reads, which hand an edit to it in place on a dev server. */
-const RENEWED_QUERIES = [DOCS_QUERY, CODE_QUERY, PAGE_QUERY];
-/** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
-const FILE_QUERIES = [
-    DOCS_QUERY,
-    CODE_QUERY,
-    PAGE_QUERY,
-    MARKDOWN_QUERY,
-    DOCS_PAGE_QUERY,
-    HOME_QUERY
-];
-/**
- * Whether a dev server may read the file a query names: a plugin's answer never passes Vite's own check of
- * `server.fs`, so without this any file could be asked for by adding a query to its address.
- *
- * @param id - the module's id.
- * @param server - the dev server; none in a build, which reads only what the sources import.
- */
-const isReadable = (id, server) => server === undefined ||
-    !FILE_QUERIES.some((query) => id.endsWith(query)) ||
-    isFileLoadingAllowed(server.config, id.slice(0, id.lastIndexOf("?")));
 /**
  * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
  *
@@ -120,8 +97,9 @@ const requestedPage = (url) => {
  * @param watch - adds a file whose edit renews the module.
  * @param isServing - whether a dev server runs.
  * @param plugins - the catalogue's plugins, whose fences a page may draw.
+ * @param isKept - whether a page its group lists may be read.
  */
-const docsModuleOf = async (id, watch, isServing, plugins) => {
+const docsModuleOf = async (id, watch, isServing, plugins, isKept) => {
     const isHome = id.endsWith(HOME_QUERY);
     const isPage = id.endsWith(DOCS_PAGE_QUERY);
     if (!isHome && !isPage && !id.startsWith(DOCS_PAGES_PREFIX))
@@ -133,47 +111,8 @@ const docsModuleOf = async (id, watch, isServing, plugins) => {
         const file = id.slice(0, -DOCS_PAGE_QUERY.length);
         return { code: docPageModule(file, watch, isServing, plugins), moduleType: "js" };
     }
-    const { root, pattern } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
-    return { code: docPagesModule(root, pattern, watch, isServing, plugins), moduleType: "js" };
-};
-/**
- * A module the plugin generates for a catalogue's pages, when the id names one: an entry, the project's own stories'
- * source, or a page's HTML (unless the folder has one of its own). The configuration's data waits for the frames'
- * placement, so the plugin's `load` makes it.
- *
- * @param id - the module's id.
- * @param config - the catalogue's configuration.
- * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
- */
-const generatedModule = (id, config, command) => {
-    const named = pageModuleOf(id, config.dir);
-    if (named === undefined)
-        return undefined;
-    if (named.kind === "entry") {
-        const code = named.page === "index.html" ? shellEntry(config) : frameEntry(config, axeAddress(command, PACKAGE_DIR));
-        return { code, moduleType: "js" };
-    }
-    if (named.kind === "stories-source")
-        return { code: storiesSourceModule(config), moduleType: "js" };
-    if (named.kind === "agent-sources")
-        return { code: agentSourcesModule(config), moduleType: "js" };
-    return existsSync(id) ? undefined : pageHtml(named.page, config, builtPlacement(config.frames));
-};
-/**
- * The id of a module the plugin generates for a catalogue's pages, when an import names one: a page or an entry by
- * its address (`/index.html`, `/.forgebook-shell.ts`) or by its path, a source by its path.
- *
- * @param source - the import's specifier.
- * @param dir - the configuration's folder.
- */
-const generatedId = (source, dir) => {
-    const byAddress = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}`);
-    if (byAddress !== undefined)
-        return pageModulePath(dir, PAGE_ENTRIES[byAddress]);
-    const pageByAddress = PAGE_FILES.find((page) => source === `/${page}`);
-    if (pageByAddress !== undefined)
-        return pageModulePath(dir, pageByAddress);
-    return pageModuleOf(source, dir) === undefined ? undefined : VITE_PATHS.normalize(source);
+    const { root, patterns } = storyFilesGroupOf(id.slice(DOCS_PAGES_PREFIX.length));
+    return { code: docPagesModule(root, patterns, watch, isServing, plugins, isKept), moduleType: "js" };
 };
 /**
  * The catalogue's Vite plugin: the story index, the docs, the code and the Markdown of the stories, the forced-states
@@ -184,8 +123,11 @@ const generatedId = (source, dir) => {
  * @returns the plugin, for the app's `plugins`.
  */
 export const forgebookPlugin = (options = {}) => {
-    /** The modules of the patterns, renewed when a story file is added or removed. */
-    const filesModules = new Set();
+    /**
+     * The modules of the groups of story files, with the files each listed when served (none while it could not be
+     * made), renewed when a story file is added to or removed from what one lists.
+     */
+    const filesModules = new Map();
     // what each pattern's module was served with: an edit of a story file that changes its list reloads the pages
     const served = servedPatterns();
     /** The groups' "Used in" modules, renewed when a source file changes: any edit may change what reaches what. */
@@ -194,6 +136,8 @@ export const forgebookPlugin = (options = {}) => {
     const docsModules = new Set();
     /** The groups' search indexes: any edit may change what a component's docs say. */
     const searchModules = new Set();
+    /** What a client may read of a dev server. */
+    const access = devServerAccess();
     /** The errors the open frames report, for `forgebook errors` and the agents. */
     const live = createLiveErrors();
     /** Where the frames run: the dev server's second port once it listens, the configuration's choice in a build. */
@@ -212,8 +156,6 @@ export const forgebookPlugin = (options = {}) => {
             return { code: configModule(config, await framesPlacement()), moduleType: "js" };
         return generatedModule(id, config, command);
     };
-    /** The dev server; none in a build. */
-    let devServer;
     /** The files followed one by one, so an edit reaches the dev server at once. */
     const watching = currentCloseWatch();
     /** Whether a dev server runs, or a build: tools ask only the former. */
@@ -223,7 +165,8 @@ export const forgebookPlugin = (options = {}) => {
     const search = searchIndexes({
         extract: (storyFile) => extractor().extract(storyFile),
         isServing,
-        track: (id, isPages) => (isPages ? docsModules : searchModules).add(id)
+        track: (id, isPages) => (isPages ? docsModules : searchModules).add(id),
+        isKept: access.isKept
     });
     // a build's docs, code and pages of each group's story files, read while the build loads the stories
     const texts = groupTexts();
@@ -258,6 +201,9 @@ export const forgebookPlugin = (options = {}) => {
     // build and would hold every other answer of the dev server meanwhile
     let docs;
     const extractor = () => {
+        // a catalogue that reads no component docs never starts the worker: its programs are most of the server's memory
+        if (config !== undefined && !readsComponentDocs(config.lists))
+            return NO_DOCS_EXTRACTOR;
         const framework = config?.framework ?? options.framework;
         if (framework === undefined)
             throw new Error("Forgebook has no framework: add forgebook.config.ts, or give the plugin `framework`");
@@ -294,21 +240,23 @@ export const forgebookPlugin = (options = {}) => {
     const storiesModule = async (id, watch, pack, startTexts) => {
         if (id.startsWith(USAGE_ID_PREFIX)) {
             usageModules.add(id);
-            return usageModule(id, watch, extractor().usage, indexCache(), pack);
+            return usageModule(id, watch, extractor().usage, indexCache(), pack, access.isKept);
         }
         // what each story reaches is for the dev server's tools only: a build ships none of it
         if (id.startsWith(REACH_ID_PREFIX)) {
             usageModules.add(id);
             return isServing()
-                ? reachModule(id, watch, extractor().usage, indexCache())
+                ? reachModule(id, watch, extractor().usage, indexCache(), access.isKept)
                 : { code: "export default [];", moduleType: "js" };
         }
         if (!id.startsWith(FILES_PREFIX))
             return undefined;
-        filesModules.add(id);
-        const hasUsage = config?.lists.usedIn !== false;
+        filesModules.set(id, undefined);
+        const lists = config?.lists ?? {};
+        const hasUsage = offersUsedIn(lists);
         // the worker starts while Vite loads the pages, unless the disk keeps the docs; a test run asks for no page
-        const { files, code } = patternModule(id, watch, { hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts);
+        const { files, code } = patternModule(id, watch, { hasDocs: readsComponentDocs(lists), hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts, access.isKept);
+        filesModules.set(id, new Set(files.map((file) => file.file)));
         if (!isRedrawing())
             return { code, moduleType: "js" };
         served.keep(id, files);
@@ -333,9 +281,9 @@ export const forgebookPlugin = (options = {}) => {
      * @param file - the file.
      */
     const modulesListing = (file) => {
-        // the patterns' modules list the story files; the groups' "Used in" read them
+        // the groups' modules list the story files, their "Used in" and search indexes read them
         if (STORY_FILE.test(file))
-            return [...filesModules, ...usageModules, ...searchModules];
+            return listingRenewals(filesModules, file, [...usageModules, ...searchModules], access.isKept);
         return DOCS_PAGE_FILE.test(file) && docsModules.size > 0 ? [...docsModules] : undefined;
     };
     /**
@@ -356,7 +304,7 @@ export const forgebookPlugin = (options = {}) => {
         }
         if (id.startsWith(DOCS_PAGES_PREFIX))
             docsModules.add(id);
-        const docsPages = await docsModuleOf(id, watch, isServing(), config?.plugins ?? []);
+        const docsPages = await docsModuleOf(id, watch, isServing(), config?.plugins ?? [], access.isKept);
         if (docsPages !== undefined)
             return docsPages;
         if (!TEXT_QUERIES.some((query) => id.endsWith(query)))
@@ -380,7 +328,13 @@ export const forgebookPlugin = (options = {}) => {
         const pack = emit === undefined ? inlineJson : packedJsonOf(emit);
         const componentFiles = (config?.framework ?? options.framework)?.componentFiles;
         const docsOf = async (storyFile) => docsValue(await search.docsOf(storyFile), watch);
-        const sources = { docsOf, watch, resolveImport, componentFiles };
+        const hasDocs = config === undefined || readsComponentDocs(config.lists);
+        const sources = {
+            docsOf: hasDocs ? docsOf : undefined,
+            watch,
+            resolveImport,
+            componentFiles
+        };
         // a build's browser files only: a dev server answers each text from its query, and no texts module
         const startTexts = emit === undefined ? undefined : texts.starter(id, sources);
         return ((emit === undefined ? undefined : await texts.moduleOf(id, sources, emit)) ??
@@ -410,13 +364,23 @@ export const forgebookPlugin = (options = {}) => {
             };
         },
         resolveId(source, importer) {
+            const isModule = access.isModule(importer);
             const virtual = virtualId(source);
-            if (virtual !== undefined)
+            if (virtual !== undefined) {
+                if (isModule)
+                    access.noteImported(virtual);
                 return virtual;
+            }
             const generated = config === undefined ? undefined : generatedId(source, config.dir);
             if (generated !== undefined)
                 return generated;
-            return importer === undefined ? null : patternId(source, VITE_PATHS.dirname(importer));
+            if (!access.isModule(importer))
+                return null;
+            // the importer's file: its id may carry whatever query an address gave it
+            const pattern = patternId(source, VITE_PATHS.dirname(importer.split("?")[0] ?? importer));
+            if (pattern !== null)
+                access.noteImported(pattern);
+            return pattern;
         },
         // a warning and not a failure: a theme a reader can still use must not stop a catalogue from building
         configResolved: (resolved) => {
@@ -428,7 +392,10 @@ export const forgebookPlugin = (options = {}) => {
                 resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
         },
         configureServer: (server) => {
-            devServer = server;
+            access.serve(server, config === undefined ? undefined : pageModulePath(config.dir, AGENT_SOURCES_FILE));
+            server.middlewares.use((request, _response, next) => {
+                access.settle(request.url ?? "/").then(() => next(), next);
+            });
             // no person waits for a page in a test run
             watching.serve(isTestRun ? undefined : server);
             server.httpServer?.on("close", () => void docs?.close());
@@ -469,7 +436,7 @@ export const forgebookPlugin = (options = {}) => {
                     .catch(next);
             });
             // folders outside the configuration's are watched only when named; a story file added or removed anywhere the
-            // server watches (its own folder, a story file it loaded) renews the lists either way
+            // server watches (its own folder, a story file it loaded) renews the lists that change either way
             const watched = [...(config?.watch ?? []), ...(options.watch ?? [])];
             if (watched.length > 0)
                 server.watcher.add(watched);
@@ -488,7 +455,8 @@ export const forgebookPlugin = (options = {}) => {
             // axe's script, for the frames' Accessibility card: loaded by the frame, never imported; the browser's build only
             if (this.environment.name !== "client")
                 return;
-            const axe = config === undefined ? undefined : axeBuildAsset(PACKAGE_DIR);
+            // a catalogue that checks no accessibility ships none of it
+            const axe = config === undefined || !checksA11y(config.lists) ? undefined : axeBuildAsset(PACKAGE_DIR);
             if (axe !== undefined)
                 this.emitFile({ type: "asset", fileName: axe.fileName, source: axe.source });
         },
@@ -501,13 +469,14 @@ export const forgebookPlugin = (options = {}) => {
             await docs?.close();
         },
         ...storyFileHotHooks(isRedrawing, served.changedBy, watching),
+        ...VITEST_HOOKS,
         async load(id) {
             const generated = await pagesModule(id);
             if (generated !== undefined)
                 return generated;
-            // an answer, not an error: an error would raise Vite's overlay on every reader's open page
-            if (!isReadable(id, devServer))
-                return { code: "export default null;", moduleType: "js" };
+            const refusal = access.refusal(id);
+            if (refusal !== undefined)
+                return refusal;
             // in Vite's form, the text Vite's module graph knows a file by: a Node path on Windows (`C:\app\x.md`) is another
             const watch = (file) => this.addWatchFile(VITE_PATHS.normalize(file));
             const resolveImport = async (specifier, importer) => {

package/dist/src/vite/framesServer.js

@@ -45,6 +45,20 @@ export const hostOf = (request) => headerOf(request, "host") ?? headerOf(request
  * @param url - the request's address.
  */
 const isProxied = (proxy, url) => Object.keys(proxy ?? {}).some((key) => key.startsWith("^") ? new RegExp(key).test(url) : url.startsWith(key));
+/**
+ * A request's path as an address parser reads it, which is how the routes behind the guards read it: a guard that read
+ * `//x/__forgebook/api/stories` as written would pass what the route answers as `/__forgebook/api/stories`.
+ *
+ * @param url - the request's address, as it was sent.
+ */
+const parsedPath = (url) => {
+    try {
+        return new URL(url, "http://parsed.invalid").pathname;
+    }
+    catch {
+        return (url.split("?")[0] ?? url).split("#")[0] ?? "/";
+    }
+};
 /**
  * What the browser says of a request.
  *
@@ -54,7 +68,7 @@ const factsOf = (request) => {
     const url = request.url ?? "/";
     const queryAt = url.indexOf("?");
     return {
-        path: (queryAt === -1 ? url : url.slice(0, queryAt)).split("#")[0] ?? "/",
+        path: parsedPath(url),
         query: queryAt === -1 ? "" : (url.slice(queryAt).split("#")[0] ?? ""),
         site: headerOf(request, "sec-fetch-site"),
         mode: headerOf(request, "sec-fetch-mode"),
@@ -83,14 +97,16 @@ const isPublicFile = (publicDir, path) => {
     return file.startsWith(`${publicDir}${sep}`) && existsSync(file) && statSync(file).isFile();
 };
 /**
- * Whether a module's code, as Vite served it, names an address: how a worker's file (`?worker_file`) is started.
+ * Whether a module the catalogue imports names an address in its code, as a whole string: how a worker's file
+ * (`?worker_file`) is started. Only an imported module counts, and only a whole string: an address asked for directly
+ * writes its own query into its module's code (its HMR context), and a story's script could plant any address there.
  *
  * @param modules - the graph's modules.
  * @param url - the address, as the graph reads it; its `t=` left out.
  */
 const isNamedInCode = (modules, url) => {
-    const named = url.replace(/[?&]t=\d+/, "");
-    return modules.some((module) => module.transformResult?.code.includes(named) === true);
+    const named = JSON.stringify(url.replace(/[?&]t=\d+/, ""));
+    return modules.some((module) => module.importers.size > 0 && module.transformResult?.code.includes(named) === true);
 };
 /**
  * Ends a request the guards turned down, with its status and nothing a page could use.
@@ -204,7 +220,7 @@ export const framesServing = (server, frames, frameHtml, framedPages) => {
             next();
             return;
         }
-        const answer = catalogueAnswer(factsOf(request), framedPages);
+        const answer = catalogueAnswer(factsOf(request), framedPages, (path) => isPublicFile(server.config.publicDir, path));
         if (answer === "refuse") {
             turnDown(response, 403);
             return;

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

@@ -0,0 +1,23 @@
+import type { ConfigEnv } from "vite";
+import type { ResolvedConfig } from "./configFile.ts";
+/**
+ * A module the plugin generates for a catalogue's pages, when the id names one: an entry, the project's own stories'
+ * source, or a page's HTML (unless the folder has one of its own). The configuration's data waits for the frames'
+ * placement, so the plugin's `load` makes it.
+ *
+ * @param id - the module's id.
+ * @param config - the catalogue's configuration.
+ * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
+ */
+export declare const generatedModule: (id: string, config: ResolvedConfig, command: ConfigEnv["command"]) => {
+    code: string;
+    moduleType: "js";
+} | string | undefined;
+/**
+ * The id of a module the plugin generates for a catalogue's pages, when an import names one: a page or an entry by
+ * its address (`/index.html`, `/.forgebook-shell.ts`) or by its path, a source by its path.
+ *
+ * @param source - the import's specifier.
+ * @param dir - the configuration's folder.
+ */
+export declare const generatedId: (source: string, dir: string) => string | undefined;

package/dist/src/vite/generatedModules.js

@@ -0,0 +1,58 @@
+/**
+ * The modules the plugin generates for a catalogue's pages: the shell's and the frame's entries, the project's own
+ * stories' source, the agents' sources and the pages' HTML, and the ids imports name them by.
+ *
+ * @remarks
+ * The configuration's data is not among them: it waits for the frames' placement, which only the plugin knows.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { checksA11y } from "../catalogue.js";
+import { axeAddress } from "./axeScript.js";
+import { builtPlacement } from "./framesConfig.js";
+import { agentSourcesModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, shellEntry, storiesSourceModule } from "./pages.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The core's folder, where axe's script is found from. */
+const PACKAGE_DIR = import.meta.dirname;
+/**
+ * A module the plugin generates for a catalogue's pages, when the id names one: an entry, the project's own stories'
+ * source, or a page's HTML (unless the folder has one of its own). The configuration's data waits for the frames'
+ * placement, so the plugin's `load` makes it.
+ *
+ * @param id - the module's id.
+ * @param config - the catalogue's configuration.
+ * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
+ */
+export const generatedModule = (id, config, command) => {
+    const named = pageModuleOf(id, config.dir);
+    if (named === undefined)
+        return undefined;
+    if (named.kind === "entry") {
+        const code = named.page === "index.html"
+            ? shellEntry(config)
+            : frameEntry(config, checksA11y(config.lists) ? axeAddress(command, PACKAGE_DIR) : undefined);
+        return { code, moduleType: "js" };
+    }
+    if (named.kind === "stories-source")
+        return { code: storiesSourceModule(config), moduleType: "js" };
+    if (named.kind === "agent-sources")
+        return { code: agentSourcesModule(config), moduleType: "js" };
+    return existsSync(id) ? undefined : pageHtml(named.page, config, builtPlacement(config.frames));
+};
+/**
+ * The id of a module the plugin generates for a catalogue's pages, when an import names one: a page or an entry by
+ * its address (`/index.html`, `/.forgebook-shell.ts`) or by its path, a source by its path.
+ *
+ * @param source - the import's specifier.
+ * @param dir - the configuration's folder.
+ */
+export const generatedId = (source, dir) => {
+    const byAddress = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}`);
+    if (byAddress !== undefined)
+        return pageModulePath(dir, PAGE_ENTRIES[byAddress]);
+    const pageByAddress = PAGE_FILES.find((page) => source === `/${page}`);
+    if (pageByAddress !== undefined)
+        return pageModulePath(dir, pageByAddress);
+    return pageModuleOf(source, dir) === undefined ? undefined : VITE_PATHS.normalize(source);
+};

package/dist/src/vite/hotSnippets.js

@@ -105,10 +105,14 @@ const readIndex = (root, pattern, key) => {
 };
 /** The patterns' modules a dev server serves, kept to tell an edit that changes a list. */
 export const servedPatterns = () => {
+    // by group, each story file as served: its key, the pattern that lists it, its index
     const served = new Map();
     return {
         keep: (id, files) => {
-            served.set(id, new Map(files.map((file) => [file.file, { key: file.key, index: JSON.stringify(file.index) }])));
+            served.set(id, new Map(files.map((file) => [
+                file.file,
+                { key: file.key, pattern: file.pattern, index: JSON.stringify(file.index) }
+            ])));
         },
         changedBy: (file) => [...served]
             .filter(([id, files]) => {
@@ -116,8 +120,8 @@ export const servedPatterns = () => {
             const kept = files.get(VITE_PATHS.normalize(file));
             if (kept === undefined)
                 return false;
-            const { root, pattern } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
-            const index = readIndex(root, pattern, kept.key);
+            const { root } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
+            const index = readIndex(root, kept.pattern, kept.key);
             return typeof index !== "string" && JSON.stringify(index) !== kept.index;
         })
             .map(([id]) => id)

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

@@ -17,8 +17,8 @@
  *
  * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
  * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
- * the story loads. `touch`, `logic`, `device`, `design.figma` and the meta's `propGroups` are read by the index only
- * (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
+ * the story loads. `touch`, `logic`, `device`, `requiredFirst`, `design.figma` and the meta's `propGroups` are read by
+ * the index only (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
  * A `design.figma` is checked here too, so the pages never carry the checker: one that is not a link to a Figma file is
  * noted and left out, and the file keeps its stories. A title written by code, or none, is the file's path
  * (`autoTitle`, as Storybook's auto-title); one written by code is also noted, since the author meant another. A value written plainly but wrongly

package/dist/src/vite/indexStoryFile.js

@@ -17,8 +17,8 @@
  *
  * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
  * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
- * the story loads. `touch`, `logic`, `device`, `design.figma` and the meta's `propGroups` are read by the index only
- * (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
+ * the story loads. `touch`, `logic`, `device`, `requiredFirst`, `design.figma` and the meta's `propGroups` are read by
+ * the index only (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
  * A `design.figma` is checked here too, so the pages never carry the checker: one that is not a link to a Figma file is
  * noted and left out, and the file keeps its stories. A title written by code, or none, is the file's path
  * (`autoTitle`, as Storybook's auto-title); one written by code is also noted, since the author meant another. A value written plainly but wrongly

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

@@ -1,7 +1,7 @@
 import type { StoryIndexEntry } from "@forgebook/story-format/source";
 import { type Fields } from "./indexFields.ts";
 /** What the index keeps of these parameters: each only when written. */
-export type IndexedParameters = Pick<StoryIndexEntry, "isTouch" | "isLogic" | "device">;
+export type IndexedParameters = Pick<StoryIndexEntry, "isTouch" | "isLogic" | "device" | "requiredFirst">;
 /**
  * The parameters only the index reads, each only when written, or the first problem.
  *

package/dist/src/vite/indexedParameters.js

@@ -1,4 +1,5 @@
 import { deviceSettingProblem, isDeviceOrientation } from "../deviceView.js";
+import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
 import { keyName, parameter, unwrapped } from "./indexFields.js";
 /** Why `parameters.device` cannot be read as it is written. */
 const DEVICE_PROBLEM = '`parameters.device` must be written as a plain object (`{ frame: true, model: "iphone-16" }`)';
@@ -87,6 +88,21 @@ const deviceOf = (value) => {
     const problem = deviceSettingProblem(setting);
     return problem === undefined ? setting : new Error(`\`parameters.device\`: ${problem}`);
 };
+/**
+ * `parameters.requiredFirst`: `undefined` when none, `"in-groups"`, `"section"` or `false` written plainly, or a
+ * problem otherwise.
+ *
+ * @param value - the parameter's value.
+ */
+const requiredFirstOf = (value) => {
+    if (value === undefined)
+        return undefined;
+    const written = value.type === "Literal" ? value.value : undefined;
+    const layout = REQUIRED_FIRST_LAYOUTS.find((each) => each === written);
+    if (layout !== undefined)
+        return layout;
+    return new Error('`parameters.requiredFirst` must be written as a plain `"in-groups"`, `"section"` or `false`');
+};
 /**
  * The parameters only the index reads, each only when written, or the first problem.
  *
@@ -102,9 +118,13 @@ export const indexedParameters = (fields) => {
     const device = deviceOf(parameter(fields, "device"));
     if (device instanceof Error)
         return device;
+    const requiredFirst = requiredFirstOf(parameter(fields, "requiredFirst"));
+    if (requiredFirst instanceof Error)
+        return requiredFirst;
     return {
         ...(touch === undefined ? {} : { isTouch: touch }),
         ...(logic === undefined ? {} : { isLogic: logic }),
-        ...(device === undefined ? {} : { device })
+        ...(device === undefined ? {} : { device }),
+        ...(requiredFirst === undefined ? {} : { requiredFirst })
     };
 };

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

@@ -6,7 +6,13 @@
  * @remarks
  * Vite's CORS lets any page on `localhost` or `127.0.0.1` read the dev server, whatever its port: a frame on a second
  * port would read the catalogue's agent API and files as before. So the catalogue refuses a request another origin
- * sends, unless it is a navigation (a link, an embed), which shows a page but lets nobody read it.
+ * sends, unless it opens one of its pages (a link, an embed) or a public file, which shows it but lets nobody read it.
+ * No other address is opened for another origin's page: a server's route acts when opened (`/__open-in-editor` opens a
+ * file), and a module or a source file has no use as a page.
+ *
+ * Vite checks `Host` first, on both ports, against `server.allowedHosts`: a page that reaches `127.0.0.1` through its
+ * own domain (DNS rebinding) is not told apart here, since it is same-origin for its browser, and over plain HTTP on
+ * that domain its browser sends no `Sec-Fetch-*`.
  *
  * The frames' origin would otherwise serve everything the catalogue's does, and a story's script would read the
  * project from there. It serves a script or a `fetch` (whose body a script reads) only for a module that another
@@ -23,7 +29,10 @@
  */
 /** What a browser says of a request, from its headers. */
 export type RequestFacts = {
-    /** Its path, without the query (`/frame.html`). */
+    /**
+     * Its path as an address parser reads it, without the query (`/frame.html`): the routes behind the guards read the
+     * same, so `//x/__forgebook/api/stories` or `/./__forgebook/api/stories` is the route it would reach.
+     */
     readonly path: string;
     /** Its query, with its `?` (`?raw`); empty without one. */
     readonly query: string;
@@ -44,13 +53,14 @@ export declare const FRAME_PAGE_PATH = "/frame.html";
 export type CatalogueAnswer = "serve" | "refuse" | "to-frames";
 /**
  * What the catalogue's origin does with a request: the frame page goes to the frames' origin, another origin's
- * request is refused, the rest is served.
+ * request is refused unless it opens a page or a public file, the rest is served.
  *
  * @param request - what the browser says of it.
  * @param framedPages - the server's routes that are pages made to be framed by another origin's page (a client's
  *   inline preview), which only show a story and act on nothing.
+ * @param isPublic - whether a path names a file of the public folder; asked only of another origin's navigation.
  */
-export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>) => CatalogueAnswer;
+export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>, isPublic?: (path: string) => boolean) => CatalogueAnswer;
 /** What the frames' origin does with a request: `ask-graph` serves it when another module imports it. */
 export type FramesAnswer = "serve" | "refuse" | "not-found" | "ask-graph";
 /** What the frames' origin knows of a request's path. */