forgebook 0.3.3 → 0.4.1

package/dist/src/vite/appTokens.js

@@ -0,0 +1,275 @@
+/**
+ * The design system an application already has, read from its files with nothing written for it: custom properties,
+ * Tailwind's `@theme` and configuration, and what shadcn's `components.json` points at.
+ *
+ * @remarks
+ * Nobody writes a tokens file for a catalogue they did not ask for, and an agent that finds no tokens writes colours by
+ * hand, so this is what a catalogue with no tokens file reads. No project code runs: the files are read as text
+ * (`appTokenFiles.ts`, `tailwindConfigTokens.ts`). Tailwind's default theme counts, since a project on Tailwind has it
+ * whether or not it writes any of its own, but it comes last in a list: it is not what makes this project's system.
+ *
+ * Later sources stand over earlier ones, and a difference between two files is a clash, reported as a tokens file's
+ * would be: other sheets, then the configuration, then the sheet `components.json` names.
+ *
+ * @module
+ */
+import { realpathSync } from "node:fs";
+import { dirname, relative } from "node:path";
+import { packageFile, readConfigs, readSheets, shadcnConfig, smallFileText } from "./appTokenFiles.js";
+import { readCssText } from "./cssDeclarations.js";
+import { colorWrappers, resolvedTokens } from "./cssTokenValues.js";
+import { readTailwindPalette } from "./tailwindConfigTokens.js";
+import { tokenClashes } from "./tokenClashes.js";
+import { unresolvedTokens } from "./unresolvedTokens.js";
+/** A custom property's name, and no more. */
+const TOKEN_NAME = /^--[\w.-]{1,100}$/;
+/** Past this a value is not a token's, in characters. */
+const LONGEST_TOKEN_VALUE = 500;
+/** A block with this many custom properties is a system's root and not one component's variables. */
+const SYSTEM_BLOCK = 12;
+/** The steps of Tailwind's spacing scale that classes write, in units of its base. */
+const SPACING_STEPS = [
+    0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56,
+    60, 64, 72, 80, 96
+];
+/** Tailwind 3's font sizes, which its configuration file does not list unless it changes them. */
+const OLD_FONT_SIZES = {
+    xs: "0.75rem",
+    sm: "0.875rem",
+    base: "1rem",
+    lg: "1.125rem",
+    xl: "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "1.875rem",
+    "4xl": "2.25rem",
+    "5xl": "3rem",
+    "6xl": "3.75rem",
+    "7xl": "4.5rem",
+    "8xl": "6rem",
+    "9xl": "8rem"
+};
+/** Tailwind 3's radii. */
+const OLD_RADII = {
+    sm: "0.125rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem"
+};
+/** Plugins whose additions to the theme are not tokens worth saying they are unknown. */
+const KNOWN_PLUGIN = /typography|forms|animate|container-queries|aspect-ratio/;
+/** A path with forward slashes on every system, for an answer that travels. */
+const toPosix = (path) => path.replaceAll("\\", "/");
+/** Selectors holding enough custom properties to be a system's root, in a sheet. */
+const systemSelectors = ({ declarations }) => {
+    const counts = new Map();
+    for (const { place } of declarations) {
+        if (place.kind === "selector")
+            counts.set(place.selector, (counts.get(place.selector) ?? 0) + 1);
+    }
+    return new Set([...counts].flatMap(([selector, count]) => count >= SYSTEM_BLOCK && /^[.#[][\w-]+\]?$/.test(selector) ? [selector] : []));
+};
+/** The kind and theme of a declaration read from a sheet, when it makes a token at all. */
+const sheetToken = (place, system) => {
+    if (place.kind === "theme")
+        return { kind: "tailwind-theme", mode: undefined };
+    if (place.kind === "root")
+        return { kind: "css-variables", mode: undefined };
+    if (place.kind === "mode")
+        return { kind: "css-variables", mode: place.mode };
+    return place.kind === "selector" && system.has(place.selector)
+        ? { kind: "css-variables", mode: place.mode }
+        : undefined;
+};
+/**
+ * Whether a declaration is a token: not a framework's internals, a private variable or a way of clearing a namespace. A
+ * name is plain and a value short, since both reach an agent's context as its next step, and a file may be written by
+ * someone who wants that.
+ */
+const isTokenName = (name) => TOKEN_NAME.test(name) && !name.startsWith("--tw-") && !name.startsWith("--_");
+/** Whether a value is short enough to be a value. */
+const isTokenValue = (value) => value !== "initial" && value.length <= LONGEST_TOKEN_VALUE;
+/** The namespaces sheets clear (`--color-*: initial`), where Tailwind's defaults no longer apply. */
+const clearedNamespaces = (sheets) => sheets.flatMap(({ reading }) => reading.declarations.flatMap(({ name, value }) => value === "initial" && name.endsWith("*") ? [name.slice(0, -1)] : []));
+/** A sheet's declarations, in the shape tokens are made from. */
+const sheetDeclarations = (dir, { file, reading }) => {
+    const system = systemSelectors(reading);
+    const label = toPosix(relative(dir, file));
+    return reading.declarations.flatMap(({ name, value, line, place }) => {
+        const token = sheetToken(place, system);
+        if (token === undefined || !isTokenName(name) || !isTokenValue(value))
+            return [];
+        return [
+            {
+                name,
+                value,
+                mode: token.mode,
+                origin: { kind: token.kind, file: label, line },
+                ...(place.kind === "selector" ? { isScoped: true } : {})
+            }
+        ];
+    });
+};
+/** Tailwind 4's default theme as declarations, when a sheet brings it in and it is installed. */
+const themeDefaults = (sheets, cleared, unread) => {
+    const importing = sheets.find(({ reading }) => reading.importsTailwindTheme);
+    if (importing === undefined)
+        return [];
+    const file = packageFile(dirname(importing.file), "tailwindcss/theme.css");
+    const text = file === undefined ? undefined : smallFileText(file);
+    if (text === undefined) {
+        unread.push("Tailwind's default theme: tailwindcss is not installed here");
+        return [];
+    }
+    return readCssText(text).declarations.flatMap(({ name, value, line, place }) => place.kind === "theme" &&
+        isTokenName(name) &&
+        isTokenValue(value) &&
+        !cleared.some((prefix) => name.startsWith(prefix))
+        ? [{ name, value, mode: undefined, origin: { kind: "tailwind-default", file: "tailwindcss", line } }]
+        : []);
+};
+/** The spacing scale's steps as tokens: Tailwind makes them from one base, and classes write them. */
+const spacingScale = (base, origin, declared) => SPACING_STEPS.flatMap((step) => {
+    const name = `--spacing-${step}`;
+    return declared.has(name)
+        ? []
+        : [{ name, value: `calc(${base} * ${step})`, mode: undefined, origin, type: "dimension" }];
+});
+/** Tailwind's published palette, read as text from the installed package; none when it is not there. */
+const installedPalette = (dir) => {
+    const installed = packageFile(dir, "tailwindcss/lib/public/colors.js");
+    return installed === undefined ? undefined : readTailwindPalette(installed, smallFileText(installed) ?? "");
+};
+/** The colours a configuration takes from the palette by name: `brand: colors.blue` is a whole scale under `brand`. */
+const paletteAliased = (aliases, palette, origin) => aliases.flatMap(({ name, palette: wanted }) => palette.flatMap(({ name: named, value, type }) => {
+    const full = `--color-${wanted}`;
+    if (named !== full && !named.startsWith(`${full}-`))
+        return [];
+    return [{ name: `${name}${named.slice(full.length)}`, value, mode: undefined, type, origin }];
+}));
+/** Tailwind's default palette and scale as declarations, for a project on a configuration file (before version 4). */
+const configDefaults = (dir, configs, unread) => {
+    const replaced = new Set(configs.flatMap(({ reading }) => reading.replaced));
+    const palette = installedPalette(dir);
+    if (palette === undefined) {
+        unread.push("Tailwind's default palette: tailwindcss is not installed here");
+        return [];
+    }
+    const origin = { kind: "tailwind-default", file: "tailwindcss" };
+    const colors = replaced.has("colors")
+        ? []
+        : palette.map(({ name, value, type }) => ({ name, value, mode: undefined, type, origin }));
+    const scale = replaced.has("spacing") ? [] : spacingScale("0.25rem", origin, new Set());
+    const named = (prefix, values, key) => replaced.has(key)
+        ? []
+        : Object.entries(values).map(([name, value]) => ({
+            name: `${prefix}${name}`,
+            value,
+            mode: undefined,
+            type: "dimension",
+            origin
+        }));
+    return [
+        ...colors,
+        ...scale,
+        ...named("--text-", OLD_FONT_SIZES, "fontSize"),
+        ...named("--radius-", OLD_RADII, "borderRadius")
+    ];
+};
+/** A configuration's tokens as declarations. */
+const configDeclarations = (dir, { file, reading }) => {
+    const origin = { kind: "tailwind-config", file: toPosix(relative(dir, file)) };
+    return [
+        ...paletteAliased(reading.paletteAliases, installedPalette(dirname(file)) ?? [], origin),
+        ...reading.tokens.map(({ name, value, type }) => ({ name, value, mode: undefined, type, origin }))
+    ].filter(({ name, value }) => isTokenName(name) && isTokenValue(value));
+};
+/** The clashes between files: each theme compared with itself. */
+const clashesOf = (authors) => tokenClashes(authors.flatMap(({ label, declarations }) => [...new Set(declarations.map((each) => each.mode))].map((mode) => ({
+    mode,
+    raw: declarations
+        .filter((each) => each.mode === mode)
+        .map(({ name, value }) => ({ name, value, label, source: label }))
+}))));
+/** What the tokens came from, each file once with how many it gave. */
+const sourcesOf = (tokens) => {
+    const counts = new Map();
+    for (const { origin } of tokens) {
+        if (origin === undefined)
+            continue;
+        const key = `${origin.kind}\0${origin.file}`;
+        const known = counts.get(key);
+        counts.set(key, { kind: origin.kind, file: origin.file, tokens: (known?.tokens ?? 0) + 1 });
+    }
+    return [...counts.values()];
+};
+/** Tailwind's defaults for a project, whichever version it is on, and the spacing scale over its own declarations. */
+const defaultDeclarations = (dir, sheets, configs, own, unread) => {
+    const cleared = clearedNamespaces(sheets);
+    const hasTheme = sheets.some(({ reading }) => reading.importsTailwindTheme);
+    const isOnConfig = sheets.some(({ reading }) => reading.usesTailwindDirectives) || configs.length > 0;
+    if (!hasTheme) {
+        return isOnConfig ? configDefaults(dir, configs, unread) : [];
+    }
+    const defaults = themeDefaults(sheets, cleared, unread);
+    const base = [...defaults, ...own].findLast((each) => each.name === "--spacing" && each.mode === undefined);
+    const scale = base === undefined || cleared.includes("--spacing-")
+        ? []
+        : spacingScale(base.value, { kind: "tailwind-default", file: base.origin.file }, new Set(own.map((each) => each.name)));
+    return [...defaults, ...scale];
+};
+/**
+ * Reads what an application declares of its design system.
+ *
+ * @param folder - the catalogue's folder.
+ */
+export const readAppTokens = (folder) => {
+    // a sheet's path comes back with its links followed, and the labels are relative to this
+    const dir = realpathSync(folder);
+    const unread = [];
+    const shadcn = shadcnConfig(dir);
+    const sheets = readSheets(dir, shadcn, unread);
+    const configs = readConfigs(dir, shadcn, sheets, unread);
+    for (const { file, reading } of configs) {
+        unread.push(...reading.unread.map((each) => `${toPosix(relative(dir, file))}: ${each}`));
+    }
+    for (const plugin of new Set(sheets.flatMap(({ reading }) => reading.plugins))) {
+        if (!KNOWN_PLUGIN.test(plugin))
+            unread.push(`Tailwind plugin ${plugin}: what it adds to the theme is known only by running it`);
+    }
+    const authorOf = (file, declarations) => ({
+        label: toPosix(relative(dir, file)),
+        declarations
+    });
+    const fromSheets = sheets.map((sheet) => authorOf(sheet.file, sheetDeclarations(dir, sheet)));
+    const named = shadcn?.css === undefined ? undefined : toPosix(relative(dir, shadcn.css));
+    const authors = [
+        ...fromSheets.filter(({ label }) => label !== named),
+        ...configs.map((config) => authorOf(config.file, configDeclarations(dir, config))),
+        ...fromSheets.filter(({ label }) => label === named)
+    ];
+    const declared = authors.flatMap(({ declarations }) => declarations);
+    const onDocument = new Set(declared.filter((each) => each.isScoped !== true).map((each) => each.name));
+    const own = declared.filter((each) => each.isScoped !== true || !onDocument.has(each.name));
+    const lowest = defaultDeclarations(dir, sheets, configs, own, unread);
+    const wrappers = colorWrappers([...sheets, ...configs].map(({ text }) => text));
+    const declarations = [...lowest, ...own];
+    const tokens = resolvedTokens(declarations, wrappers);
+    const unresolved = unresolvedTokens(dir, { sheets, configs, declarations });
+    const isDefault = (token) => token.origin?.kind === "tailwind-default";
+    const ordered = [...tokens.filter((token) => !isDefault(token)), ...tokens.filter(isDefault)];
+    return {
+        tokens: ordered,
+        clashes: clashesOf(authors),
+        sources: [
+            ...(shadcn === undefined
+                ? []
+                : [{ kind: "components-json", file: toPosix(relative(dir, shadcn.file)), tokens: 0 }]),
+            ...sourcesOf(ordered)
+        ],
+        problems: unresolved.problems,
+        unread: [...unread, ...unresolved.unread],
+        files: [...sheets, ...configs].map(({ file }) => file).concat(shadcn === undefined ? [] : [shadcn.file])
+    };
+};

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

@@ -0,0 +1,30 @@
+import type { ArgControlMatch, ForgebookConfig } from "./config.ts";
+/** A custom control ready for the pages. */
+export type ResolvedArgControl = {
+    /** Its module, drawn in the panel: a path absolute, a package's specifier as written. */
+    readonly module: string;
+    /** Its frame module, which turns its value into the story's; none when the story receives the JSON value. */
+    readonly frame?: string;
+    /** The props it takes in every story that names no control for them; empty when only `argTypes` name it. */
+    readonly matches: readonly ArgControlMatch[];
+};
+/** The custom controls by name, in their precedence: the catalogue's, then its presets'. */
+export type ResolvedArgControls = Readonly<Record<string, ResolvedArgControl>>;
+/** The path functions the resolution needs, so a test can name another system's. */
+export type ControlPaths = {
+    /** A path from the configuration's folder, made absolute in Vite's form. */
+    readonly absolute: (path: string) => string;
+    /** Whether a path is absolute already. */
+    readonly isAbsolute: (path: string) => boolean;
+    /** An absolute path in Vite's form. */
+    readonly normalize: (path: string) => string;
+};
+/**
+ * The catalogue's custom controls and its presets', checked, merged, in their precedence.
+ *
+ * @param config - the configuration, its presets included.
+ * @param dir - its folder.
+ * @param paths - the path functions.
+ * @throws when a name, a module or a match cannot be used.
+ */
+export declare const resolvedArgControls: (config: Pick<ForgebookConfig, "argControls" | "presets">, dir: string, paths: ControlPaths) => ResolvedArgControls;

package/dist/src/vite/argControlsConfig.js

@@ -0,0 +1,176 @@
+/**
+ * A catalogue's custom controls, its own and its presets', checked and merged: what the pages load and what the props
+ * docs are matched against.
+ *
+ * @remarks
+ * A preset's control runs in the catalogue's page as the catalogue's own do, so it passes the same checks: a name a story
+ * can write that no control of the panel has, and a module named as a path or a package's specifier, never an address
+ * (`https:`, `data:`) that would load code from elsewhere. A preset names its files by absolute path, as its preview: a
+ * relative path would be read from wherever the catalogue is; nor can it take every prop of a keyword type (`string`). The catalogue's
+ * registration of a name replaces a preset's, and `false` removes it; a later preset's replaces an earlier one's. The
+ * order kept is the precedence among controls that match the same prop: the catalogue's first, then the presets' in
+ * their order.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { CONTROLS } from "../storyArgTypes.js";
+/** The keys a control's option may have. */
+const OPTION_KEYS = ["module", "frame", "matches"];
+/** The keys a match may have. */
+const MATCH_KEYS = ["typeName", "propName"];
+/** The type names TypeScript writes as keywords: a preset that takes one by type alone would take most of a catalogue. */
+const KEYWORD_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "bigint",
+    "symbol",
+    "object",
+    "unknown",
+    "any",
+    "null",
+    "undefined",
+    "never",
+    "void"
+];
+/** An address with a scheme (`https:`, `data:`), which would load code from elsewhere; a Windows drive's letter is none. */
+const SCHEME = /^[A-Za-z][\w+.-]+:/;
+/** Whether a value is an object that is not a list. */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A key of an object no version reads, when it has one.
+ *
+ * @param value - the object.
+ * @param known - its keys.
+ */
+const unknownKey = (value, known) => Object.keys(value).find((key) => !known.includes(key));
+/**
+ * One field of a match, checked: a text, or none.
+ *
+ * @param match - the match.
+ * @param key - the field.
+ * @param where - where it is written, for a problem.
+ */
+const matchField = (match, key, where) => {
+    const value = Reflect.get(match, key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value === "")
+        throw new Error(`${where}: a match's ${key} is no name`);
+    return value;
+};
+/**
+ * The matches a control's option writes, checked.
+ *
+ * @param value - its `matches`.
+ * @param where - where it is written, for a problem.
+ */
+const matchesOf = (value, where) => {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map((match) => {
+        if (!isObject(match))
+            throw new Error(`${where}: a match is an object ({ typeName } or { propName })`);
+        const key = unknownKey(match, MATCH_KEYS);
+        if (key !== undefined)
+            throw new Error(`${where}: a match has no key "${key}"; it takes typeName, propName`);
+        const typeName = matchField(match, "typeName", where);
+        const propName = matchField(match, "propName", where);
+        if (typeName === undefined && propName === undefined)
+            throw new Error(`${where}: a match names a typeName, a propName, or both`);
+        return {
+            ...(typeName === undefined ? {} : { typeName }),
+            ...(propName === undefined ? {} : { propName })
+        };
+    });
+};
+/**
+ * One control, checked and resolved; `false` removes a preset's control of its name.
+ *
+ * @param name - its name.
+ * @param value - what the list writes for it.
+ * @param where - where the list is, for a problem.
+ * @param place - places a module it names.
+ */
+const resolvedControl = (name, value, where, place) => {
+    const at = `${where}: "${name}"`;
+    if (Object.hasOwn(CONTROLS, name))
+        throw new Error(`${at} is a control of the panel already`);
+    if (!/^[A-Za-z][\w-]*$/.test(name))
+        throw new Error(`${at} is no name a control can have`);
+    if (value === false)
+        return false;
+    if (!isObject(value))
+        return { module: place(value, at), matches: [] };
+    const key = unknownKey(value, OPTION_KEYS);
+    if (key !== undefined)
+        throw new Error(`${at} has no key "${key}"; it takes ${OPTION_KEYS.join(", ")}`);
+    const frame = Reflect.get(value, "frame");
+    return {
+        module: place(Reflect.get(value, "module"), at),
+        ...(frame === undefined ? {} : { frame: place(frame, `${at}: its frame`) }),
+        matches: matchesOf(Reflect.get(value, "matches"), at)
+    };
+};
+/**
+ * A list's controls, checked and resolved, in its order.
+ *
+ * @param controls - the list.
+ * @param where - where it is, for a problem.
+ * @param place - places a module it names.
+ */
+const listed = (controls, where, place) => {
+    if (controls !== undefined && !isObject(controls))
+        throw new Error(`${where} is an object of controls by name`);
+    return Object.entries(controls ?? {}).map(([name, value]) => [
+        name,
+        resolvedControl(name, value, where, place)
+    ]);
+};
+/**
+ * The catalogue's custom controls and its presets', checked, merged, in their precedence.
+ *
+ * @param config - the configuration, its presets included.
+ * @param dir - its folder.
+ * @param paths - the path functions.
+ * @throws when a name, a module or a match cannot be used.
+ */
+export const resolvedArgControls = (config, dir, paths) => {
+    const file = resolve(dir, "forgebook.config");
+    const named = (module, where) => {
+        if (typeof module !== "string" || module === "")
+            throw new Error(`${where} names no module, as a path or a package's specifier`);
+        if (SCHEME.test(module))
+            throw new Error(`${where} names an address, not a path or a package's specifier`);
+        return module;
+    };
+    const own = listed(config.argControls, `${file}: argControls`, (module, where) => {
+        const path = named(module, where);
+        return path.startsWith(".") || paths.isAbsolute(path) ? paths.absolute(path) : path;
+    });
+    // a later preset's control replaces an earlier one's of the same name, where the first was
+    const fromPresets = new Map();
+    for (const preset of config.presets ?? []) {
+        const where = `${file}: its preset "${preset.name}": argControls`;
+        for (const [name, control] of listed(preset.argControls, where, (module, at) => {
+            const path = named(module, at);
+            if (path.startsWith("."))
+                throw new Error(`${at}: a preset names a module by absolute path or package`);
+            return paths.isAbsolute(path) ? paths.normalize(path) : path;
+        })) {
+            if (control === false)
+                throw new Error(`${where}: "${name}": only a catalogue removes a control`);
+            const keyword = control.matches.find((match) => match.propName === undefined && KEYWORD_TYPES.includes(match.typeName ?? ""));
+            if (keyword !== undefined)
+                throw new Error(`${where}: "${name}": a preset takes no "${keyword.typeName}" prop by its type alone`);
+            fromPresets.set(name, control);
+        }
+    }
+    // a removal that removes nothing is a misspelt name
+    const removing = own.find(([name, control]) => control === false && !fromPresets.has(name));
+    if (removing !== undefined)
+        throw new Error(`${file}: argControls: "${removing[0]}" is no preset's control to remove`);
+    const ownNames = new Set(own.map(([name]) => name));
+    return Object.fromEntries([...own, ...[...fromPresets].filter(([name]) => !ownNames.has(name))].flatMap(([name, control]) => (control === false ? [] : [[name, control]])));
+};

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

@@ -10,6 +10,11 @@
  * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
  * the loader answers the text, as the query's module's default did.
  *
+ * The packed texts of a group go in shared files, in the rows' order, up to `PACK_LIMIT` of JSON each, rather than a
+ * file each: gzip reads each file alone, and the docs of neighbouring components repeat their keys, their types and
+ * their wording, which a file of one text cannot share. On a library of small components a file each weighs ten times
+ * what the same texts weigh together, and a page that asks for one text fetches a few kilobytes more.
+ *
  * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
  * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
  * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
@@ -23,6 +28,11 @@ import { type IndexedStoryFile } from "./storyFilesModule.ts";
 import type { ComponentPageText, KeptCode, TextModuleContext } from "./textModules.ts";
 /** A story file's texts as their queries' modules answer them: its component's docs, its stories' code, its page. */
 export type FileTexts = readonly [docs: unknown, code: KeptCode, page: ComponentPageText];
+/**
+ * The JSON a packed file holds at most, in characters, unless one text alone is longer: enough for the docs of a few
+ * components to share their words, little enough that a page asking for one text fetches a few kilobytes.
+ */
+export declare const PACK_LIMIT: number;
 /**
  * The code of a group's texts module: the functions its loaders call, then, as its default, each file's loaders of its
  * docs, code and page, in the order of the group's rows.

package/dist/src/vite/builtTexts.js

@@ -10,6 +10,11 @@
  * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
  * the loader answers the text, as the query's module's default did.
  *
+ * The packed texts of a group go in shared files, in the rows' order, up to `PACK_LIMIT` of JSON each, rather than a
+ * file each: gzip reads each file alone, and the docs of neighbouring components repeat their keys, their types and
+ * their wording, which a file of one text cannot share. On a library of small components a file each weighs ten times
+ * what the same texts weigh together, and a page that asks for one text fetches a few kilobytes more.
+ *
  * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
  * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
  * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
@@ -25,37 +30,64 @@ import { indexedStoryFiles, storyFilesGroupOf, storyFilesGroupText } from "./sto
 import { VITE_PATHS } from "./vitePaths.js";
 /** The function that makes a packed file's loader, in the generated code. */
 const PACKED = "packedText";
+/** The function that makes the loader of one text of a packed file, in the generated code. */
+const PART = "packedPart";
+/** The loaders of the packed files, in the generated code, numbered. */
+const PACKED_FILE = "packedTexts";
 /** The function that makes the loader of a text written in the module, in the generated code. */
 const WRITTEN = "writtenText";
 /**
- * Writes texts as loaders: each in a gzipped file, or in the module when that weighs no more than the file and its
- * address (an empty page's JSON is shorter than its gzip header and the fetch it would cost). A text written in the
- * module is written once, however many files share it (most story files have no code and no page), and its loader
- * shared with them.
- *
- * @param emit - writes a packed file.
+ * The JSON a packed file holds at most, in characters, unless one text alone is longer: enough for the docs of a few
+ * components to share their words, little enough that a page asking for one text fetches a few kilobytes.
  */
-const textWriter = (emit) => {
-    const names = new Map();
-    const written = (json) => {
-        const name = names.get(json) ?? `${WRITTEN}${names.size}`;
-        names.set(json, name);
-        return name;
+export const PACK_LIMIT = 64 * 1024;
+/**
+ * Writes texts as loaders: each in a packed file shared with its neighbours, or in the module when it weighs no more
+ * than its loader there (an empty page, a story file with no code). A text is written once, however many files share
+ * it, and its loader shared with them.
+ */
+const textWriter = () => {
+    const written = new Map();
+    const packed = new Map();
+    const packs = [];
+    const pack = (json) => {
+        const known = packed.get(json);
+        if (known !== undefined)
+            return known;
+        let last = packs.at(-1);
+        if (last === undefined || (last.texts.length > 0 && last.length + json.length > PACK_LIMIT)) {
+            last = { texts: [], length: 0 };
+            packs.push(last);
+        }
+        const loader = `${PART}(${PACKED_FILE}${packs.length - 1},${last.texts.length})`;
+        last.texts.push(json);
+        last.length += json.length;
+        packed.set(json, loader);
+        return loader;
     };
     return {
         loaderOf: (value) => {
             const json = JSON.stringify(value);
-            const fileName = packedFileName(json);
-            const address = codeLiteral(fileName);
-            const packed = gzippedJson(json);
-            if (json.length <= address.length + packed.length)
-                return written(json);
-            emit({ type: "asset", fileName, source: packed });
-            return `${PACKED}(${address})`;
+            if (written.has(json) || json.length <= `${PART}(${PACKED_FILE}${packs.length},0)`.length) {
+                const name = written.get(json) ?? `${WRITTEN}${written.size}`;
+                written.set(json, name);
+                return name;
+            }
+            return pack(json);
         },
-        written: () => [...names].map(([json, name]) => `const ${name} = () => Promise.resolve(${codeOfJson(json)});`)
+        code: (emit) => [
+            ...[...written].map(([json, name]) => `const ${name} = () => Promise.resolve(${codeOfJson(json)});`),
+            ...packs.map((each, at) => {
+                const json = `[${each.texts.join(",")}]`;
+                const fileName = packedFileName(json);
+                emit({ type: "asset", fileName, source: gzippedJson(json) });
+                return `const ${PACKED_FILE}${at} = ${PACKED}(${codeLiteral(fileName)});`;
+            })
+        ]
     };
 };
+/** The code of the function that makes the loader of one text of a packed file: it answers the same value each time. */
+const PART_MAKER = `const ${PART} = (load, at) => () => load().then((texts) => texts[at]);`;
 /**
  * Every file's texts, read: a build reads them all once, as it would for their modules.
  *
@@ -73,10 +105,15 @@ const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.a
  */
 export const textsModuleCode = (texts, emit) => {
     // written in the files' order once all are read, so the names in the module do not depend on which read ended first
-    const writer = textWriter(emit);
+    const writer = textWriter();
     // a text not read (the docs of a catalogue that reads none) has no loader, and its place stays in the row
     const rows = texts.map((each) => `[${each.map((text) => (text === undefined ? "null" : writer.loaderOf(text))).join(", ")}]`);
-    return [packedLoaderMaker(PACKED), ...writer.written(), `export default [${rows.join(",\n")}];`].join("\n");
+    return [
+        packedLoaderMaker(PACKED),
+        PART_MAKER,
+        ...writer.code(emit),
+        `export default [${rows.join(",\n")}];`
+    ].join("\n");
 };
 /**
  * A build's readers of the texts: the code and the pages as their queries answer them, read with the modules that

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

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