forgebook 0.3.2 → 0.4.0

package/dist/src/vite/forgebookPlugin.js

@@ -23,30 +23,36 @@
 import { extname, join, resolve } from "node:path";
 import { checksA11y, offersUsedIn, readsComponentDocs } from "../catalogue.js";
 import { SAME_ORIGIN } from "../frameOrigins.js";
-import { createLiveErrors, isLiveErrorReport, LIVE_ERROR_EVENT } from "../liveErrors.js";
+import { createLiveErrors } from "../liveErrors.js";
 import { agentMiddleware, FRAMED_AGENT_PAGES } from "./agentRoutes.js";
 import { STORY_FILE } from "./autoTitle.js";
 import { axeBuildAsset } from "./axeScript.js";
 import { groupTexts } from "./builtTexts.js";
 import { catalogueConfig } from "./catalogueConfig.js";
+import { currentCheckoutWatch } from "./checkoutWatch.js";
 import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
 import { codeStamp, diskCache } from "./diskCache.js";
 import { createDocsExtractor, NO_DOCS_EXTRACTOR } from "./docsExtractor.js";
+import { sayEmptyStoryGlobs } from "./emptyStoryGlobs.js";
 import { devServerAccess, VITEST_HOOKS } from "./fileAccess.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
+import { receiveFrameErrors } from "./frameErrors.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 { filesModuleHot, renewedModule, servedPatterns, storyFileHotHooks } from "./hotSnippets.js";
+import { jsxInScripts } from "./jsxInScripts.js";
 import { inlineJson, packedJsonOf } from "./packedModule.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, listingRenewals, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
-import { isKeptIndex, storyFilesGroupOf } from "./storyFilesModule.js";
+import { docsModule, docsModuleOf, docsValue, FILES_PREFIX, invalidateEverywhere, keptListing, listingRenewals, pagesReloaded, patternModule, REACH_ID_PREFIX, reachModule, searchIndexes, USAGE_ID_PREFIX, usageModule } from "./pluginModules.js";
+import { checkAtStart } from "./runningVersions.js";
+import { scriptProblems } from "./scriptProblems.js";
+import { isKeptIndex } from "./storyFilesModule.js";
 import { tokensModule } from "./storylessRoutes.js";
-import { DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, RENEWED_QUERIES, TEXT_QUERIES } from "./textQueries.js";
+import { DOCS_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;
@@ -64,21 +70,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?$/;
-/**
- * Renews modules in every environment that loaded them: the agents' routes load them on the server too.
- *
- * @param server - the dev server.
- * @param ids - the modules' ids.
- */
-const invalidateEverywhere = (server, ids) => {
-    for (const environment of Object.values(server.environments)) {
-        for (const id of ids) {
-            const module = environment.moduleGraph.getModuleById(id);
-            if (module !== undefined)
-                environment.moduleGraph.invalidateModule(module);
-        }
-    }
-};
 /**
  * The page a request names, when it names one: `/` is the shell's.
  *
@@ -89,31 +80,6 @@ const requestedPage = (url) => {
     const name = path === "/" ? "index.html" : path.replace(/^\//, "");
     return PAGE_FILES.find((page) => page === name);
 };
-/**
- * A docs pages' module, when the id is a pattern's, a page's or the written home's. The Markdown reader loads with the
- * first: a catalogue may have no docs pages, and a story's page reads none.
- *
- * @param id - the module's id.
- * @param watch - adds a file whose edit renews the module.
- * @param isServing - whether a dev server runs.
- * @param plugins - the catalogue's plugins, whose fences a page may draw.
- * @param isKept - whether a page its group lists may be read.
- */
-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))
-        return undefined;
-    const { docPageModule, docPagesModule, homeModule } = await import("./docPagesModule.js");
-    if (isHome)
-        return { code: homeModule(id.slice(0, -HOME_QUERY.length), watch, isServing, plugins), moduleType: "js" };
-    if (isPage) {
-        const file = id.slice(0, -DOCS_PAGE_QUERY.length);
-        return { code: docPageModule(file, watch, isServing, plugins), moduleType: "js" };
-    }
-    const { root, 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
  * rewrite of every style sheet and, with a configuration, the catalogue's two pages.
@@ -124,8 +90,8 @@ const docsModuleOf = async (id, watch, isServing, plugins, isKept) => {
  */
 export const forgebookPlugin = (options = {}) => {
     /**
-     * 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.
+     * The modules of the groups of story files, with the versions served since the pages last reloaded (none while it
+     * could not be made), renewed when a story file is added to or removed from what a page may hold.
      */
     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
@@ -153,11 +119,13 @@ export const forgebookPlugin = (options = {}) => {
         if (config === undefined)
             return undefined;
         if (id === CONFIG_ID)
-            return { code: configModule(config, await framesPlacement()), moduleType: "js" };
+            return { code: configModule(config, await framesPlacement(), isServing()), moduleType: "js" };
         return generatedModule(id, config, command);
     };
     /** The files followed one by one, so an edit reaches the dev server at once. */
     const watching = currentCloseWatch();
+    /** Git's checkouts, so the files a branch switch rewrites reach the dev server when the system's events do not. */
+    const checkouts = currentCheckoutWatch();
     /** Whether a dev server runs, or a build: tools ask only the former. */
     let command = "serve";
     const isServing = () => command === "serve";
@@ -170,6 +138,9 @@ export const forgebookPlugin = (options = {}) => {
     });
     // a build's docs, code and pages of each group's story files, read while the build loads the stories
     const texts = groupTexts();
+    // whether a story file that cannot be read is named while the rest draws: a build must fail on it, and a test run has
+    // no page to name it on
+    const isForgiving = () => isServing() && !isTestRun;
     // whether an edited story file is drawn anew in its open frames: a dev server's, unless the framework cannot
     const isRedrawing = () => isServing() && (config?.framework ?? options.framework)?.redrawsEditedStories !== false;
     /**
@@ -177,8 +148,10 @@ export const forgebookPlugin = (options = {}) => {
      * still loading TypeScript when the tests end is stopped by Node mid-parse, which aborts the process.
      */
     let isTestRun = false;
+    const scripts = { ...scriptProblems(), isQuick: options.isQuickScan === true };
     /** Where answers are kept between starts (`diskCache.ts`): in Vite's cache folder, so what clears it clears them. */
     let cacheFolder;
+    const jsxScripts = jsxInScripts(() => config?.framework ?? options.framework);
     /** The stamp of the plugin's own code, which makes the kept indexes and code: another version is a miss. */
     let pluginCode;
     const keptCache = (kind, isValue) => {
@@ -235,7 +208,7 @@ export const forgebookPlugin = (options = {}) => {
      * @param pack - writes a module's JSON as its value: as it is, or kept out of a build's JavaScript.
      * @param startTexts - a build's browser files': starts reading a pattern's docs, code and pages, which its module
      * imports from the group's texts module; none imports each from its query.
-     * @throws when a story file cannot be indexed.
+     * @throws when a story file cannot be indexed, and no person at a dev server is told instead (a build, a test run).
      */
     const storiesModule = async (id, watch, pack, startTexts) => {
         if (id.startsWith(USAGE_ID_PREFIX)) {
@@ -251,16 +224,14 @@ export const forgebookPlugin = (options = {}) => {
         }
         if (!id.startsWith(FILES_PREFIX))
             return undefined;
-        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, { 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)));
+        const { files, refused, code } = keptListing(filesModules, id, () => patternModule(id, watch, { hasDocs: readsComponentDocs(lists), hasUsage, hasReach: hasUsage && isServing() }, indexCache(), isTestRun ? undefined : extractor().warm, startTexts, access.isKept, isForgiving(), config, scripts.list()));
         if (!isRedrawing())
             return { code, moduleType: "js" };
-        served.keep(id, files);
-        return { code: `${code}\n${FILES_MODULE_HOT}`, moduleType: "js" };
+        served.keep(id, { files, refused });
+        return { code: `${code}\n${filesModuleHot(refused)}`, moduleType: "js" };
     };
     /**
      * Tells the docs a source file was added or removed: it may be what an import now finds, so no kept docs are read
@@ -342,6 +313,13 @@ export const forgebookPlugin = (options = {}) => {
             (await storiesModule(id, watch, pack, startTexts)) ??
             null);
     };
+    // whatever its mode: a run of Vitest has no page to name a file on, and must fail on it
+    const vitestHooks = {
+        configureVitest: (context) => {
+            isTestRun = true;
+            VITEST_HOOKS.configureVitest(context);
+        }
+    };
     return {
         name: "forgebook",
         enforce: "pre",
@@ -353,7 +331,7 @@ export const forgebookPlugin = (options = {}) => {
                 if (file !== undefined)
                     config = await loadConfigFile(file);
             }
-            const pages = config === undefined ? {} : catalogueConfig(config, userConfig);
+            const pages = config === undefined ? {} : catalogueConfig(config, userConfig, scripts);
             return {
                 ...pages,
                 css: {
@@ -382,14 +360,16 @@ export const forgebookPlugin = (options = {}) => {
                 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) => {
+            jsxScripts.remember(resolved);
+            checkAtStart(resolved, config?.shell.problems ?? []);
             // a dev server's answers only: a build reads everything once, and stamping each answer's files costs it more than
             // a later build would save
             if (isServing())
                 cacheFolder = join(resolved.cacheDir, "forgebook");
-            for (const problem of config?.shell.problems ?? [])
-                resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
+            scripts.start(resolved.logger, cacheFolder);
+            if (config !== undefined && !isTestRun)
+                sayEmptyStoryGlobs(config, isServing(), resolved.logger);
         },
         configureServer: (server) => {
             access.serve(server, config === undefined ? undefined : pageModulePath(config.dir, AGENT_SOURCES_FILE));
@@ -397,7 +377,9 @@ export const forgebookPlugin = (options = {}) => {
                 access.settle(request.url ?? "/").then(() => next(), next);
             });
             // no person waits for a page in a test run
-            watching.serve(isTestRun ? undefined : server);
+            const followed = isTestRun ? undefined : server;
+            watching.serve(followed);
+            checkouts.serve(followed);
             server.httpServer?.on("close", () => void docs?.close());
             // first: the frames' own origin, and the guard that keeps every other origin's page from reading this one
             if (config !== undefined)
@@ -415,10 +397,7 @@ export const forgebookPlugin = (options = {}) => {
                 };
                 server.middlewares.use(missingHeightsMiddleware(file));
             }
-            server.ws.on(LIVE_ERROR_EVENT, (report) => {
-                if (isLiveErrorReport(report))
-                    live.add(report, new Date());
-            });
+            receiveFrameErrors(server, live);
             // the catalogue's pages, made here: no HTML file is written
             server.middlewares.use((request, response, next) => {
                 const page = requestedPage(request.url ?? "/");
@@ -447,6 +426,7 @@ export const forgebookPlugin = (options = {}) => {
                     return;
                 invalidateEverywhere(server, renewed);
                 server.ws.send({ type: "full-reload" });
+                pagesReloaded(filesModules);
             };
             server.watcher.on("add", refresh);
             server.watcher.on("unlink", refresh);
@@ -462,21 +442,21 @@ export const forgebookPlugin = (options = {}) => {
         },
         // a dev server without an HTTP server of its own (middleware mode) ends its close watch here only
         closeServer: (context) => {
-            if (context.reason === "close")
+            if (context.reason === "close") {
                 watching.close();
+                checkouts.close();
+            }
         },
         closeBundle: async () => {
             await docs?.close();
         },
-        ...storyFileHotHooks(isRedrawing, served.changedBy, watching),
-        ...VITEST_HOOKS,
+        ...storyFileHotHooks(isRedrawing, served, watching, scripts),
+        ...vitestHooks,
         async load(id) {
-            const generated = await pagesModule(id);
-            if (generated !== undefined)
-                return generated;
-            const refusal = access.refusal(id);
-            if (refusal !== undefined)
-                return refusal;
+            // a generated module, a file the server refuses, or a `.js` file whose JSX is compiled as it loads
+            const early = (await pagesModule(id)) ?? access.refusal(id) ?? (await jsxScripts.load(id));
+            if (early !== null)
+                return early;
             // 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/frameErrors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What the dev server does with the errors the open frames report: keeps each, with the place its stack maps to, and
+ * answers the frame with the stack in the lines of the files as written.
+ *
+ * @remarks
+ * The mapping runs here, on the maps of the modules the server served (`stackLines.ts`), so the frame loads no decoder
+ * and no map. A stack that cannot be mapped is kept and answered as it came. Used by the plugin's dev server.
+ *
+ * @module
+ */
+import type { ViteDevServer } from "vite";
+import { type LiveErrors } from "../liveErrors.ts";
+/**
+ * Listens to the frames' error reports on the dev server's connection.
+ *
+ * @param server - the dev server.
+ * @param live - where the errors are kept.
+ */
+export declare const receiveFrameErrors: (server: ViteDevServer, live: LiveErrors) => void;

package/dist/src/vite/frameErrors.js

@@ -0,0 +1,70 @@
+import { isLiveErrorReport, LIVE_ERROR_EVENT, MAPPED_STACK_EVENT } from "../liveErrors.js";
+import { mappedStack } from "./stackLines.js";
+/**
+ * The module the dev server served at an address, with its map: none for another address or one it keeps no map of.
+ *
+ * @param server - the dev server.
+ * @param address - the address, as a stack names it: the server's own or its frames' origin, which serve the same
+ *   modules.
+ */
+const servedModule = async (server, address) => {
+    let url;
+    try {
+        const parsed = new URL(address);
+        url = `${parsed.pathname}${parsed.search}`;
+    }
+    catch {
+        return undefined;
+    }
+    const module = await server.environments.client.moduleGraph.getModuleByUrl(url);
+    const map = module?.transformResult?.map;
+    if (module?.file == null || map == null || !("version" in map))
+        return undefined;
+    return { file: module.file, map };
+};
+/**
+ * A report's stack mapped, or as it came when the mapping fails.
+ *
+ * @param server - the dev server.
+ * @param stack - the stack the frame sent.
+ */
+const mapped = async (server, stack) => {
+    try {
+        return await mappedStack(stack, (address) => servedModule(server, address), server.config.root);
+    }
+    catch {
+        return { stack };
+    }
+};
+/**
+ * Keeps a report, its stack swapped for the place it maps to, and answers the frame with the stack mapped.
+ *
+ * @param server - the dev server.
+ * @param live - the errors kept.
+ * @param report - the frame's report.
+ * @param client - the frame's connection.
+ */
+const keep = async (server, live, report, client) => {
+    const { stack, ...kept } = report;
+    if (stack === undefined) {
+        live.add(kept, new Date());
+        return;
+    }
+    const result = await mapped(server, stack);
+    live.add(result.place === undefined ? kept : { ...kept, place: result.place }, new Date());
+    const answer = { sent: stack, stack: result.stack };
+    client.send(MAPPED_STACK_EVENT, answer);
+};
+/**
+ * Listens to the frames' error reports on the dev server's connection.
+ *
+ * @param server - the dev server.
+ * @param live - where the errors are kept.
+ */
+export const receiveFrameErrors = (server, live) => {
+    server.ws.on(LIVE_ERROR_EVENT, (report, client) => {
+        if (!isLiveErrorReport(report))
+            return;
+        keep(server, live, report, client).catch((error) => server.config.logger.error(`Forgebook could not keep a frame's error: ${error instanceof Error ? error.message : String(error)}`));
+    });
+};

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

@@ -3,6 +3,18 @@ import type { ViteDevServer } from "vite";
 import { type FramesPlacement } from "../frameOrigins.ts";
 import type { ResolvedConfig } from "./configFile.ts";
 import type { ResolvedFrames } from "./framesConfig.ts";
+/**
+ * The ports the frames try, in order, 0 for any free one: the one the configuration gives, alone; else the catalogue's
+ * + 1 and the ones after it, as Vite moves on from a port taken. A catalogue on any free port (a command's own server)
+ * gives its frames any free port too: the system hands out such ports in order on some platforms, so the one after the
+ * catalogue's is the next process's, which Vite has just found free and is about to take.
+ *
+ * @param configured - the frames' port the configuration gives (`frames.port`, `--frame-port`); none for the default.
+ * @param catalogue - the port the catalogue listens on.
+ * @param isCatalogueOnAnyPort - whether the catalogue asked for any free port (`port: 0`).
+ * @returns the ports, in order.
+ */
+export declare const framesPortTries: (configured: number | undefined, catalogue: number, isCatalogueOnAnyPort: boolean) => readonly number[];
 /** A Connect middleware. */
 type Middleware = (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
 /** The frames' side of a dev server. */

package/dist/src/vite/framesServer.js

@@ -22,6 +22,24 @@ import { catalogueAnswer, FRAME_PAGE_PATH, framesAnswer, graphUrlOf, pageEntries
 import { pageHtml } from "./pages.js";
 /** How many ports after the default one the frames try before taking any free port. */
 const PORT_TRIES = 20;
+/**
+ * The ports the frames try, in order, 0 for any free one: the one the configuration gives, alone; else the catalogue's
+ * + 1 and the ones after it, as Vite moves on from a port taken. A catalogue on any free port (a command's own server)
+ * gives its frames any free port too: the system hands out such ports in order on some platforms, so the one after the
+ * catalogue's is the next process's, which Vite has just found free and is about to take.
+ *
+ * @param configured - the frames' port the configuration gives (`frames.port`, `--frame-port`); none for the default.
+ * @param catalogue - the port the catalogue listens on.
+ * @param isCatalogueOnAnyPort - whether the catalogue asked for any free port (`port: 0`).
+ * @returns the ports, in order.
+ */
+export const framesPortTries = (configured, catalogue, isCatalogueOnAnyPort) => {
+    if (configured !== undefined)
+        return [configured];
+    if (isCatalogueOnAnyPort)
+        return [0];
+    return [...Array.from({ length: PORT_TRIES }, (_, index) => catalogue + 1 + index), 0];
+};
 /**
  * A header's single value.
  *
@@ -188,6 +206,8 @@ export const framesServing = (server, frames, frameHtml, framedPages) => {
     const framesRequests = new WeakSet();
     const sharedPaths = frames.kind === "isolated" ? frames.paths : [];
     let framesPort;
+    // read before the catalogue listens: once it does, Vite's resolved options name the port it took
+    const isCatalogueOnAnyPort = server.config.server.port === 0;
     let settle = () => undefined;
     const placed = new Promise((resolvePlacement) => {
         settle = resolvePlacement;
@@ -283,10 +303,7 @@ export const framesServing = (server, frames, frameHtml, framedPages) => {
             throw new Error("Forgebook's frames start once the catalogue listens");
         const framesServer = framesHttpServer(server, server.httpServer, handleFrames);
         const wanted = frames.port ?? catalogue.port + 1;
-        // a port the configuration gives is that port; the default moves on, as Vite's own does
-        const tries = frames.port === undefined
-            ? [...Array.from({ length: PORT_TRIES }, (_, index) => wanted + index), 0]
-            : [wanted];
+        const tries = framesPortTries(frames.port, catalogue.port, isCatalogueOnAnyPort);
         const listened = await listenOnFirstFree(framesServer, tries, catalogue.address);
         if (listened === undefined)
             throw new Error(`Forgebook's frames: port ${wanted} is taken (frames.port, --frame-port)`);

package/dist/src/vite/functionComponentDocs.js

@@ -19,6 +19,8 @@ import { moduleSummaryOf } from "./moduleSummary.js";
 import { declarationOrder, declaredSymbol, isForeign, partsOf, propDocs } from "./propDocs.js";
 import { signatureDocs } from "./signatureDocs.js";
 import { metaComponent, metaSubcomponents } from "./storyMeta.js";
+import { bindingsOf } from "./typeParameters.js";
+import { propsOfType } from "./unionProps.js";
 import { guidanceOf } from "./usageGuidance.js";
 /**
  * How a component is called: as a function of its props, or constructed with them into something that renders (a
@@ -32,6 +34,37 @@ const componentSignatures = (type) => [
         .getConstructSignatures()
         .filter((signature) => signature.getReturnType().getProperty("render") !== undefined)
 ];
+/**
+ * The name an export's component is written by: a default export's symbol is named `default`, its declaration by what
+ * the file calls it (`export default function Card`).
+ *
+ * @param symbol - the declared symbol.
+ */
+const writtenName = (symbol) => {
+    const [declaration] = symbol.declarations ?? [];
+    const name = declaration === undefined ? undefined : ts.getNameOfDeclaration(declaration);
+    return symbol.getName() === "default" && name !== undefined && ts.isIdentifier(name)
+        ? name.text
+        : symbol.getName();
+};
+/**
+ * Why a component lists no props although it takes some: it cannot be called with props, its props are `any`, or
+ * every one of them is declared outside its package.
+ *
+ * @param signature - its first call or construct signature, if any.
+ * @param propsType - the type of its props, if it takes any.
+ * @param listed - how many props it lists.
+ * @param all - how many props its props type has, left out ones included.
+ */
+const propsNoteOf = (signature, propsType, listed, all) => {
+    if (signature === undefined)
+        return { reason: "no-signature" };
+    if (propsType === undefined || listed > 0)
+        return undefined;
+    if (propsType.flags & ts.TypeFlags.Any)
+        return { reason: "untyped" };
+    return all > 0 ? { reason: "outside-package", count: all } : undefined;
+};
 /**
  * A component's props, read at the expression that names it.
  *
@@ -47,9 +80,37 @@ const componentProps = (symbol, expression, checker, storyFile) => {
     const propsType = propsSymbol === undefined
         ? undefined
         : checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(propsSymbol, expression));
-    const ownProps = declarationOrder((propsType?.getProperties() ?? []).filter((prop) => !isForeign(prop)), dirname(symbol.declarations?.[0]?.getSourceFile().fileName ?? storyFile));
-    return { propsType, ownProps };
+    const { props, variantOnly } = propsType === undefined ? { props: [], variantOnly: new Map() } : propsOfType(propsType, checker);
+    const ownProps = declarationOrder(props.filter((prop) => !isForeign(prop)), dirname(symbol.declarations?.[0]?.getSourceFile().fileName ?? storyFile));
+    return {
+        propsType,
+        ownProps,
+        variantOnly,
+        bindings: propsType === undefined ? new Map() : bindingsOf(propsType, checker),
+        propsNote: propsNoteOf(signature, propsType, ownProps.length, props.length)
+    };
 };
+/**
+ * The docs of a component's listed props: a prop only some variants declare is never required, and says when it can
+ * be passed.
+ *
+ * @param props - the component's props, as `componentProps` read them.
+ * @param checker - the program's checker.
+ * @param expression - where the code names the component.
+ */
+const listedProps = (props, checker, expression) => props.ownProps.map((prop) => {
+    const variant = props.variantOnly.get(prop);
+    const { bindings } = props;
+    if (variant === undefined)
+        return propDocs(prop, checker, expression, { bindings });
+    const variants = variant.declarations.filter((declaration) => declaration !== prop);
+    const { onlyWhen } = variant;
+    return {
+        ...propDocs(prop, checker, expression, { variants, bindings }),
+        isRequired: false,
+        ...(onlyWhen === undefined ? {} : { onlyWhen })
+    };
+});
 /**
  * The files a component's docs come from: the one declaring it and those declaring its own props.
  *
@@ -76,13 +137,13 @@ const subcomponentsOf = (source, checker) => {
         if (symbol === undefined) {
             return `${source.fileName}: the meta's subcomponent ${subcomponent.name} cannot be resolved`;
         }
-        const { ownProps } = componentProps(symbol, subcomponent.expression, checker, source.fileName);
+        const props = componentProps(symbol, subcomponent.expression, checker, source.fileName);
         docs.push({
             name: subcomponent.name,
             description: summaryOf(symbol, checker),
-            props: ownProps.map((prop) => propDocs(prop, checker, subcomponent.expression))
+            props: listedProps(props, checker, subcomponent.expression)
         });
-        sources.push(...docsSources(symbol, ownProps, source.fileName));
+        sources.push(...docsSources(symbol, props.ownProps, source.fileName));
     }
     return { docs, sources };
 };
@@ -96,22 +157,24 @@ const subcomponentsOf = (source, checker) => {
  * @param subcomponents - the subcomponents' docs and files; none outside a story file.
  */
 const componentOf = (symbol, expression, checker, file, subcomponents) => {
-    const { propsType, ownProps } = componentProps(symbol, expression, checker, file);
-    const props = ownProps.map((prop) => propDocs(prop, checker, expression));
+    const read = componentProps(symbol, expression, checker, file);
+    const { propsType, ownProps, propsNote } = read;
+    const props = listedProps(read, checker, expression);
     const parts = partsOf(propsType, checker, expression);
     const declarationFile = symbol.declarations?.[0]?.getSourceFile();
     const sources = docsSources(symbol, ownProps, file);
     const signature = signatureDocs(symbol, expression, checker);
     return {
         docs: {
-            name: symbol.getName(),
+            name: writtenName(symbol),
             description: summaryOf(symbol, checker),
             summary: declarationFile === undefined ? "" : moduleSummaryOf(declarationFile.text),
             props,
             parts,
             subcomponents: subcomponents.docs,
             ...guidanceOf(symbol, checker),
-            ...(signature === undefined ? {} : { signature })
+            ...(signature === undefined ? {} : { signature }),
+            ...(propsNote === undefined ? {} : { propsNote })
         },
         file: sources[0] ?? file,
         sources: [...new Set([...sources, ...subcomponents.sources])]
@@ -155,7 +218,7 @@ export const functionComponentDocs = (storyFile) => {
     return typeof component === "string" ? component : component.docs;
 };
 /** Whether an export is a component: a name in PascalCase whose value can be called or constructed. */
-const isComponentExport = (symbol, checker, node) => /^[A-Z]/.test(symbol.getName()) &&
+const isComponentExport = (symbol, checker, node) => /^[A-Z]/.test(writtenName(symbol)) &&
     componentSignatures(checker.getTypeOfSymbolAtLocation(symbol, node)).length > 0;
 /**
  * A component a file exports, read from its types, for writing its first stories (`forgebook new`).
@@ -175,9 +238,12 @@ export const functionFileComponent = (file, exportName) => {
     const moduleSymbol = checker.getSymbolAtLocation(source);
     if (moduleSymbol === undefined)
         return `${file} exports nothing`;
-    const components = checker
+    const exported = checker
         .getExportsOfModule(moduleSymbol)
         .filter((each) => isComponentExport(declaredSymbol(each, checker) ?? each, checker, source));
+    // a component exported both by name and as the default is one component, imported by its name unless asked otherwise
+    const named = new Set(exported.filter((each) => each.getName() !== "default").map((each) => declaredSymbol(each, checker)));
+    const components = exported.filter((each) => each.getName() !== "default" || exportName === "default" || !named.has(declaredSymbol(each, checker)));
     const chosen = chosenExport(components.map((each) => each.getName()), exportName, file);
     if (typeof chosen !== "string")
         return chosen.problem;
@@ -189,5 +255,8 @@ export const functionFileComponent = (file, exportName) => {
     const name = declaration === undefined ? undefined : ts.getNameOfDeclaration(declaration);
     if (name === undefined || !ts.isIdentifier(name))
         return `${file}: ${export_.getName()} has no name to read it at`;
-    return componentOf(symbol, name, checker, file, { docs: [], sources: [] });
+    const component = componentOf(symbol, name, checker, file, { docs: [], sources: [] });
+    return typeof component === "string" || export_.getName() !== "default"
+        ? component
+        : { ...component, isDefaultExport: true };
 };

package/dist/src/vite/generatedModules.js

@@ -1,6 +1,6 @@
 /**
  * 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.
+ * stories' source, the agents' sources, the galleries' previews 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.
@@ -11,7 +11,7 @@ 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 { agentSourcesModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, pageModuleOf, pageModulePath, SWITCH_PREVIEWS_MODULE, shellEntry, storiesSourceModule, switchPreviewsModule } 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;
@@ -25,6 +25,8 @@ const PACKAGE_DIR = import.meta.dirname;
  * @param command - whether a dev server runs, or a build: where the frame finds axe's script.
  */
 export const generatedModule = (id, config, command) => {
+    if (id === `\0${SWITCH_PREVIEWS_MODULE}`)
+        return { code: switchPreviewsModule(config), moduleType: "js" };
     const named = pageModuleOf(id, config.dir);
     if (named === undefined)
         return undefined;