forgebook 0.1.8 → 0.3.0

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

@@ -1,11 +1,53 @@
+/**
+ * A catalogue's configuration file read: found in its folder, loaded, checked, and merged with its presets, as the
+ * plugin and the `forgebook` command use it.
+ *
+ * @remarks
+ * Node loads the file with its types stripped (`forgebook.config.ts`, `.mts` or `.js`). A preset's switches,
+ * languages and head come before the catalogue's, and a switch or language the catalogue declares with the same id
+ * replaces the preset's; its preview sits under the catalogue's. Every problem is named with the file it comes from.
+ *
+ * @module
+ */
 import type { StoryLanguage } from "@forgebook/story-format/source";
 import type { CatalogueLists } from "../catalogue.ts";
+import type { ForgebookPlugin } from "../plugin.ts";
 import { type ViewSwitch } from "../switches.ts";
 import type { FrameworkAdapter } from "./adapter.ts";
-import type { ForgebookConfig } from "./config.ts";
+import type { BuildOptions, ForgebookConfig } from "./config.ts";
+import { type ResolvedFrames } from "./framesConfig.ts";
+import { type VitePaths } from "./vitePaths.ts";
 /** The names a configuration file may have, in the order they are looked for. */
 export declare const CONFIG_FILES: string[];
-/** A configuration ready for the pages: its folder, its presets merged, its paths absolute. */
+/**
+ * The name the written home has beside the configuration. Prefixed as the preview is, so a `home.md` a project
+ * keeps for another reason never replaces the generated home of a catalogue that did not ask for it.
+ */
+export declare const HOME_FILE = "forgebook.home.md";
+/** The shell's look, ready for its page. */
+export type ResolvedShell = {
+    /** The theme, as CSS; empty for none. */
+    readonly themeCss: string;
+    /** What the frames need of the theme, as CSS; empty for none. */
+    readonly frameCss: string;
+    /** Whether Forgebook's mark stands in for a catalogue without a logo. */
+    readonly hasBranding: boolean;
+    /** The style sheets it loads after its own, absolute, the presets' first. */
+    readonly styleSheets: readonly string[];
+    /** What in the theme will not work, for a warning. */
+    readonly problems: readonly string[];
+};
+/** A tokens file, its path absolute. */
+export type ResolvedTokensFile = {
+    /** The file's absolute path. */
+    readonly path: string;
+    /** The theme it belongs to; none for the base. */
+    readonly mode: string | undefined;
+};
+/**
+ * A configuration ready for the pages: its folder, its presets merged, its paths absolute and in Vite's form (forward
+ * slashes on every system, `vitePaths.ts`), so they compare with Vite's ids and can be written into generated code.
+ */
 export type ResolvedConfig = {
     /** The folder the configuration file is in: Vite's root. */
     readonly dir: string;
@@ -13,12 +55,16 @@ export type ResolvedConfig = {
     readonly framework: FrameworkAdapter;
     /** The catalogue's name. */
     readonly title: string;
-    /** The logo's absolute path; none for Forgebook's own mark. */
+    /** The logo's absolute path; none for Forgebook's own mark, or the title alone without branding. */
     readonly logo: string | undefined;
     /** The heights file's address, relative to the pages. */
     readonly heights: string | undefined;
     /** The project's own story globs, from the configuration's folder. */
     readonly stories: readonly string[];
+    /** The project's own docs pages' globs, from the configuration's folder. */
+    readonly docs: readonly string[];
+    /** The written home's absolute path; none for the generated home. */
+    readonly home: string | undefined;
     /** The sources' module specifiers. */
     readonly sources: readonly string[];
     /** The switches, the presets' and the catalogue's merged; none when neither declares any. */
@@ -29,12 +75,22 @@ export type ResolvedConfig = {
     readonly previews: readonly string[];
     /** The tags for every frame's `<head>`. */
     readonly head: string;
+    /** The shell's look, the presets' and the catalogue's merged. */
+    readonly shell: ResolvedShell;
+    /** The tokens files, absolute, the base first. */
+    readonly tokens: readonly ResolvedTokensFile[];
     /** The folders the dev server watches for new story files, absolute. */
     readonly watch: readonly string[];
     /** The lists (widths, backgrounds, story groups…), the presets' and the catalogue's merged. */
     readonly lists: CatalogueLists;
     /** Whether the project installs Testing Library, whose `canvas` and `userEvent` every play then receives. */
     readonly hasPlayTools: boolean;
+    /** The plugins, checked, in the configuration's order. */
+    readonly plugins: readonly ForgebookPlugin[];
+    /** Where the stories' frames run. */
+    readonly frames: ResolvedFrames;
+    /** How `forgebook build` writes the catalogue, every option given its default. */
+    readonly build: Required<BuildOptions>;
 };
 /** The packages of the play tools: both installed, or the plays get neither. */
 export declare const PLAY_TOOLS_PACKAGES: readonly ["@testing-library/dom", "@testing-library/user-event"];
@@ -53,20 +109,22 @@ export declare const findConfigFile: (dir: string) => string | undefined;
 /**
  * The lists of the presets and the catalogue, in that order, merged: a single value (a width range, the grid's step)
  * the last that gives one; the backgrounds, the story groups and the texts entry by entry, a later one replacing an
- * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar the last
- * that names one.
+ * earlier one with the same id or name; the tabs, the controls and the rules turned off by any, and the accessibility
+ * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * component docs are read the last that names one; the device field by field.
  *
  * @param all - the presets' lists, then the catalogue's.
  */
 export declare const mergedLists: (all: readonly CatalogueLists[]) => CatalogueLists;
 /**
- * A configuration with its presets merged and its paths made absolute.
+ * A configuration with its presets merged and its paths made absolute, in Vite's form.
  *
  * @param config - the configuration.
- * @param dir - the folder of its file.
+ * @param fileDir - the folder of its file.
+ * @param paths - the path functions; the running system's unless a test names another.
  * @throws when the merged switches cannot be used.
  */
-export declare const resolveConfig: (config: ForgebookConfig, dir: string) => ResolvedConfig;
+export declare const resolveConfig: (config: ForgebookConfig, fileDir: string, paths?: VitePaths) => ResolvedConfig;
 /**
  * Loads a configuration file and resolves it.
  *
@@ -74,4 +132,3 @@ export declare const resolveConfig: (config: ForgebookConfig, dir: string) => Re
  * @throws when the file does not load, or exports no usable configuration.
  */
 export declare const loadConfigFile: (file: string) => Promise<ResolvedConfig>;
-//# sourceMappingURL=configFile.d.ts.map

package/dist/src/vite/configFile.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 /**
  * A catalogue's configuration file read: found in its folder, loaded, checked, and merged with its presets, as the
  * plugin and the `forgebook` command use it.
@@ -17,13 +9,35 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *
  * @module
  */
-import { existsSync } from "node:fs";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { AUDIENCE_IDS } from "../audiences.js";
+import { deviceSettingProblem } from "../deviceView.js";
+import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
+import { frameThemeCss, mergedThemes, shellThemeCss, shellThemeProblems, themeValueProblem } from "../shellTheme.js";
 import { switchesProblem } from "../switches.js";
+import { framesProblem, resolvedFrames } from "./framesConfig.js";
+import { pluginsProblem, withPluginSwitches } from "./pluginConfig.js";
+import { patternsProblem } from "./storyPatterns.js";
+import { tokenThemeOf } from "./themeFromTokens.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /** The names a configuration file may have, in the order they are looked for. */
 export const CONFIG_FILES = ["forgebook.config.ts", "forgebook.config.mts", "forgebook.config.js"];
+/**
+ * The name the written home has beside the configuration. Prefixed as the preview is, so a `home.md` a project
+ * keeps for another reason never replaces the generated home of a catalogue that did not ask for it.
+ */
+export const HOME_FILE = "forgebook.home.md";
 /** The names a preview may have beside the configuration, in the order they are looked for. */
 const PREVIEW_FILES = ["forgebook.preview.ts", "forgebook.preview.tsx", "forgebook.preview.js"];
 /** The packages of the play tools: both installed, or the plays get neither. */
@@ -84,13 +98,18 @@ const singleValues = (lists) => ({
     ...(lists.gridStep === undefined ? {} : { gridStep: lists.gridStep }),
     ...(lists.toolbar === undefined ? {} : { toolbar: lists.toolbar }),
     ...(lists.usedIn === undefined ? {} : { usedIn: lists.usedIn }),
-    ...(lists.appearance === undefined ? {} : { appearance: lists.appearance })
+    ...(lists.componentDocs === undefined ? {} : { componentDocs: lists.componentDocs }),
+    ...(lists.audience === undefined ? {} : { audience: lists.audience }),
+    ...(lists.appearance === undefined ? {} : { appearance: lists.appearance }),
+    ...(lists.propGroups === undefined ? {} : { propGroups: lists.propGroups }),
+    ...(lists.requiredFirst === undefined ? {} : { requiredFirst: lists.requiredFirst })
 });
 /**
  * The lists of the presets and the catalogue, in that order, merged: a single value (a width range, the grid's step)
  * the last that gives one; the backgrounds, the story groups and the texts entry by entry, a later one replacing an
- * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar the last
- * that names one.
+ * earlier one with the same id or name; the tabs, the controls and the rules turned off by any, and the accessibility
+ * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * component docs are read the last that names one; the device field by field.
  *
  * @param all - the presets' lists, then the catalogue's.
  */
@@ -100,7 +119,11 @@ export const mergedLists = (all) => {
     const strings = {};
     const keys = {};
     let merged = {};
+    // the device field by field, as a story's lies over its meta's: a preset's model stays under a catalogue's frame
+    let device;
     for (const lists of all) {
+        if (lists.device !== undefined)
+            device = { ...device, ...lists.device };
         Object.assign(tabs, lists.tabs);
         Object.assign(controls, lists.controls);
         Object.assign(strings, lists.strings);
@@ -108,9 +131,11 @@ export const mergedLists = (all) => {
         merged = { ...merged, ...singleValues(lists) };
     }
     const builtIn = all.findLast((lists) => lists.backgrounds?.builtIn !== undefined)?.backgrounds?.builtIn;
-    const tags = all.findLast((lists) => lists.a11y?.tags !== undefined)?.a11y?.tags;
+    const rules = all.flatMap((lists) => lists.a11y === undefined || lists.a11y === false ? [] : [lists.a11y]);
+    const tags = rules.findLast((each) => each.tags !== undefined)?.tags;
     return {
         ...merged,
+        ...(device === undefined ? {} : { device }),
         backgrounds: {
             ...(builtIn === undefined ? {} : { builtIn }),
             custom: mergedById(all.map((lists) => lists.backgrounds?.custom))
@@ -118,16 +143,36 @@ export const mergedLists = (all) => {
         storyGroups: mergedById(all.map((lists) => lists.storyGroups)),
         tabs,
         controls,
-        a11y: {
-            ...(tags === undefined ? {} : { tags }),
-            disabledRules: [...new Set(all.flatMap((lists) => lists.a11y?.disabledRules ?? []))]
-        },
+        // a check one list turns off stays off, as a tab does: a preset's library may have no use for it
+        a11y: all.some((lists) => lists.a11y === false)
+            ? false
+            : {
+                ...(tags === undefined ? {} : { tags }),
+                disabledRules: [...new Set(rules.flatMap((each) => each.disabledRules ?? []))]
+            },
         strings,
         keys,
         // a later list's view of the same name replaces an earlier one's, where it was
         views: [...new Map(all.flatMap((lists) => lists.views ?? []).map((view) => [view.name, view])).values()]
     };
 };
+/** Whether a configuration's list has something in it. */
+const isListed = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list) && list.length > 0;
+};
+/**
+ * Why a configuration's list of globs lists nothing by construction (only `!` patterns), or none.
+ *
+ * @param config - what the file exports by default.
+ * @param key - the list's key.
+ */
+const globsProblem = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list)
+        ? patternsProblem(list.filter((item) => typeof item === "string"))
+        : undefined;
+};
 /**
  * Why a loaded configuration cannot be used, or none.
  *
@@ -140,11 +185,19 @@ const configProblem = (config) => {
         return "it names no framework (`framework: react()`)";
     if (!("title" in config) || typeof config.title !== "string")
         return "it names no title";
-    const hasStories = "stories" in config && Array.isArray(config.stories) && config.stories.length > 0;
-    const hasSources = "sources" in config && Array.isArray(config.sources) && config.sources.length > 0;
-    if (!hasStories && !hasSources)
+    if ("home" in config &&
+        config.home !== undefined &&
+        config.home !== false &&
+        typeof config.home !== "string")
+        return 'its home is neither a path (`home: "docs/home.md"`) nor false';
+    if (!["stories", "sources", "docs"].some((key) => isListed(config, key)))
         return 'it names no stories (`stories: ["src/**/*.stories.tsx"]`) and no sources';
-    return undefined;
+    for (const key of ["stories", "docs"]) {
+        const problem = globsProblem(config, key);
+        if (problem !== undefined)
+            return `its ${key} list nothing: ${problem}`;
+    }
+    return framesProblem("frames" in config ? config.frames : undefined);
 };
 /**
  * Whether a loaded configuration is one: checked by `configProblem`.
@@ -152,44 +205,195 @@ const configProblem = (config) => {
  * @param config - what the file exports by default.
  */
 const isConfig = (config) => configProblem(config) === undefined;
+/** The fields of a device setting, by name, and the type each is written in. */
+const DEVICE_FIELDS = {
+    frame: "boolean",
+    model: "string",
+    orientation: "string",
+    touch: "boolean",
+    edgeToEdge: "boolean"
+};
+/**
+ * Why a device setting cannot be used, or none: not an object of `frame`, `model`, `orientation` and `touch`, a field
+ * of another type, or a model or an orientation that is none. A configuration is code, so its types are not a
+ * promise.
+ *
+ * @param device - the setting as a configuration or a preset gives it.
+ */
+const deviceProblem = (device) => {
+    if (typeof device !== "object" || device === null || Array.isArray(device))
+        return 'write it as an object: { frame: true, model: "iphone-16" }';
+    for (const [name, value] of Object.entries(device)) {
+        const type = DEVICE_FIELDS[name];
+        if (type === undefined)
+            return `it has no field "${name}": it takes ${Object.keys(DEVICE_FIELDS).join(", ")}`;
+        if (value !== undefined && typeof value !== type)
+            return `its ${name} must be ${type === "boolean" ? "true or false" : "a text"}`;
+    }
+    const model = Reflect.get(device, "model");
+    const orientation = Reflect.get(device, "orientation");
+    return deviceSettingProblem({
+        ...(typeof model === "string" ? { model } : {}),
+        ...(typeof orientation === "string" ? { orientation } : {})
+    });
+};
+/**
+ * The configuration's and the presets' lists, once checked where the shell would leave a mistake out: a device that
+ * cannot be used, a place for the required props that is none, an accessibility setting that is neither rules nor
+ * `false`.
+ *
+ * @param all - the presets' lists, then the configuration's.
+ * @param dir - the configuration's folder, for the message.
+ * @throws when a device cannot be used, `requiredFirst` is none of its layouts, or `a11y` is neither rules nor
+ *   `false`.
+ */
+const checkedLists = (all, dir) => {
+    for (const lists of all) {
+        const problem = lists.device === undefined ? undefined : deviceProblem(lists.device);
+        if (problem !== undefined)
+            throw new Error(`${resolve(dir, "forgebook.config")}: Forgebook's device: ${problem}`);
+        // a configuration is written by JavaScript too, which no type stops
+        if (lists.requiredFirst !== undefined && !REQUIRED_FIRST_LAYOUTS.includes(lists.requiredFirst))
+            throw new Error(`${resolve(dir, "forgebook.config")}: requiredFirst is ${typeof lists.requiredFirst === "string" ? `"${lists.requiredFirst}"` : String(lists.requiredFirst)}, none of "in-groups", "section" and false`);
+        const a11y = lists.a11y;
+        if (a11y !== undefined &&
+            a11y !== false &&
+            (typeof a11y !== "object" || a11y === null || Array.isArray(a11y)))
+            throw new Error(`${resolve(dir, "forgebook.config")}: a11y is ${String(a11y)}: write its rules ({ tags, disabledRules }), or false to check nothing`);
+    }
+    return all;
+};
+/**
+ * Why the merged lists ask for what cannot be, or none: an audience that is none of the ids (the page reads it as one,
+ * and a configuration is written by JavaScript too, which no type stops), or "Used in" turned on with the component
+ * docs off, whose TypeScript programs read the import graph it is joined from.
+ *
+ * @param lists - the presets' lists and the configuration's, merged.
+ */
+const mergedListsProblem = (lists) => {
+    if (lists.audience !== undefined && !AUDIENCE_IDS.includes(lists.audience))
+        return `the audience "${lists.audience}" is none of ${AUDIENCE_IDS.join(", ")}`;
+    if (lists.usedIn === true && lists.componentDocs === false)
+        return "usedIn is true with componentDocs false: Used in reads the import graph with the programs componentDocs turns off";
+    return undefined;
+};
+/** What a catalogue shows: its own stories and docs pages, and the sources; none where it names none. */
+const shownFiles = (config) => ({
+    stories: config.stories ?? [],
+    docs: config.docs ?? [],
+    sources: config.sources ?? []
+});
+/**
+ * The written home's absolute path: the configuration's `home`, else `forgebook.home.md` beside it when there; none
+ * with `home: false`.
+ *
+ * @param config - the configuration.
+ * @param dir - the folder of its file.
+ * @throws when the configuration names a home that is not there.
+ */
+const homeOf = (config, dir) => {
+    if (config.home === false)
+        return undefined;
+    if (config.home === undefined) {
+        const beside = VITE_PATHS.join(dir, HOME_FILE);
+        return existsSync(beside) ? beside : undefined;
+    }
+    const home = VITE_PATHS.resolve(dir, config.home);
+    if (!existsSync(home) || !statSync(home).isFile())
+        throw new Error(`${resolve(dir, "forgebook.config")}: its home "${config.home}" is not a file there`);
+    return home;
+};
 /**
- * A configuration with its presets merged and its paths made absolute.
+ * A configuration's plugins, once they can be used.
  *
  * @param config - the configuration.
  * @param dir - the folder of its file.
+ * @throws when they cannot.
+ */
+const checkedPlugins = (config, dir) => {
+    const plugins = config.plugins ?? [];
+    const problem = pluginsProblem(plugins, config.framework.name, dir);
+    if (problem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${problem}`);
+    return plugins;
+};
+/**
+ * Whether Forgebook's mark may stand in for a logo: on, unless the last that says so turns it off.
+ *
+ * @param all - the presets, then the catalogue.
+ */
+const hasBrandingIn = (all) => all.findLast((each) => each.shell?.branding !== undefined)?.shell?.branding !== false;
+/**
+ * A configuration with its presets merged and its paths made absolute, in Vite's form.
+ *
+ * @param config - the configuration.
+ * @param fileDir - the folder of its file.
+ * @param paths - the path functions; the running system's unless a test names another.
  * @throws when the merged switches cannot be used.
  */
-export const resolveConfig = (config, dir) => {
+export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
     const presets = config.presets ?? [];
-    const absolute = (path) => (isAbsolute(path) ? path : resolve(dir, path));
+    const dir = paths.normalize(fileDir);
+    const absolute = (path) => paths.resolve(dir, path);
+    // a preset's preview and style sheet are absolute paths (its own files) or a package's specifier, kept as written
+    const ownPath = (path) => (paths.isAbsolute(path) ? paths.normalize(path) : path);
     const declared = [...presets.map((preset) => preset.switches), config.switches];
-    const switches = declared.some((list) => list !== undefined) ? mergedById(declared) : undefined;
+    const plugins = checkedPlugins(config, dir);
+    const switches = withPluginSwitches(declared.some((list) => list !== undefined) ? mergedById(declared) : undefined, plugins);
     const problem = switches === undefined ? undefined : switchesProblem(switches);
     if (problem !== undefined)
         throw new Error(`${resolve(dir, "forgebook.config")}: ${problem}`);
+    const declaredThemes = [...presets.map((preset) => preset.shell?.theme ?? {}), config.shell?.theme ?? {}];
+    const tokens = (config.tokens ?? []).map((each) => typeof each === "string"
+        ? { path: absolute(each), mode: undefined }
+        : { path: absolute(each.file), mode: each.mode });
+    const fromTokens = Object.assign({}, ...declaredThemes.map((each) => each.fromTokens));
+    const tokenThemed = tokenThemeOf(fromTokens, tokens, dir);
+    const theme = mergedThemes([tokenThemed.theme, ...declaredThemes]);
+    const lists = mergedLists(checkedLists([...presets, config], dir));
+    const listsProblem = mergedListsProblem(lists);
+    if (listsProblem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${listsProblem}`);
+    const themeProblem = themeValueProblem(theme);
+    if (themeProblem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${themeProblem}`);
     const ownPreview = config.preview === undefined
-        ? PREVIEW_FILES.map((name) => resolve(dir, name)).find((file) => existsSync(file))
+        ? PREVIEW_FILES.map((name) => paths.join(dir, name)).find((file) => existsSync(file))
         : absolute(config.preview);
     return {
         dir,
         framework: config.framework,
         title: config.title,
+        home: homeOf(config, dir),
         logo: config.logo === undefined ? undefined : absolute(config.logo),
         heights: config.heights,
-        stories: config.stories ?? [],
-        sources: config.sources ?? [],
+        ...shownFiles(config),
         switches,
         languages: mergedById([...presets.map((preset) => preset.languages), config.languages]),
         previews: [
-            ...presets.flatMap((preset) => (preset.preview === undefined ? [] : [preset.preview])),
+            ...presets.flatMap((preset) => (preset.preview === undefined ? [] : [ownPath(preset.preview)])),
             ...(ownPreview === undefined ? [] : [ownPreview])
         ],
         head: [...presets.map((preset) => preset.head ?? ""), config.head ?? ""]
             .filter((tags) => tags !== "")
             .join("\n"),
+        shell: {
+            themeCss: shellThemeCss(theme),
+            frameCss: frameThemeCss(theme),
+            hasBranding: hasBrandingIn([...presets, config]),
+            styleSheets: [
+                ...presets.flatMap((preset) => (preset.shell?.css === undefined ? [] : [ownPath(preset.shell.css)])),
+                ...(config.shell?.css === undefined ? [] : [absolute(config.shell.css)])
+            ],
+            problems: [...tokenThemed.problems, ...shellThemeProblems(theme)]
+        },
+        tokens,
         watch: (config.watch ?? []).map(absolute),
-        lists: mergedLists([...presets, config]),
-        hasPlayTools: hasPlayToolsIn(dir)
+        lists,
+        hasPlayTools: hasPlayToolsIn(dir),
+        plugins,
+        frames: resolvedFrames(config.frames),
+        build: { readableNames: config.build?.readableNames === true }
     };
 };
 /**
@@ -205,4 +409,3 @@ export const loadConfigFile = async (file) => {
         throw new Error(`${file}: ${configProblem(config) ?? "it cannot be read"}`);
     return resolveConfig(config, dirname(file));
 };
-//# sourceMappingURL=configFile.js.map

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

@@ -0,0 +1,75 @@
+/**
+ * Design tokens read from DTCG files (the Design Tokens Format, 2025.10): a flat list with references followed and
+ * themes applied, every value as CSS writes it.
+ *
+ * @remarks
+ * Pure: parsed JSON in, tokens out. The format has no themes of its own, so a theme is a file of its own read over the
+ * base (`tokens: ["tokens.json", { file: "dark.json", mode: "dark" }]`). References are followed over base and theme
+ * together: a theme can alias the base, and a base alias follows what a theme overrides, which is why semantic tokens
+ * over a palette change with the theme at all. That is why files are collected first and resolved only once all are
+ * known. A token that cannot be used is named in `problems` with its file, and the others stay usable: nothing vanishes
+ * in silence, since a token an agent cannot find is a colour it writes by hand.
+ *
+ * Files of a catalogue's sources are read before its own, so its aliases reach a library's palette and a later file
+ * replaces an earlier one's token. Within one author's files that is plain layering; between authors it is a clash,
+ * reported and never refused: the catalogue is what puts the libraries together, so its value is the one in use.
+ *
+ * @module
+ */
+import { type TokenClash } from "./tokenClashes.ts";
+/** A token, ready to read. */
+export type DesignToken = {
+    /** Its name, the groups joined by dots (`color.brand.primary`). */
+    readonly name: string;
+    /** Its type (`color`, `dimension`…). */
+    readonly type: string;
+    /** Its value, as CSS writes it; the first theme's when only themes define it. */
+    readonly value: string;
+    /** The token it is an alias of. */
+    readonly alias?: string;
+    /** What it is for. */
+    readonly description?: string;
+    /** Why not to use it, when it is deprecated. */
+    readonly deprecated?: string;
+    /** Its value in each theme where it differs, by theme. */
+    readonly modes: Readonly<Record<string, string>>;
+    /** Whether only themes define it, so `value` does not hold everywhere. */
+    readonly isThemeOnly?: true;
+    /** The source that gives it, by its id or, when it writes none, by its module; none for the catalogue's own. */
+    readonly source?: string;
+};
+/** What the files gave. */
+export type ParsedTokens = {
+    /** The tokens that can be used, in the files' order. */
+    readonly tokens: readonly DesignToken[];
+    /** What could not be used, one line each, naming its file. */
+    readonly problems: readonly string[];
+    /** The names two authors give different values, with whose stands. */
+    readonly clashes: readonly TokenClash[];
+};
+/** A tokens file, parsed. */
+export type TokensInput = {
+    /** What a problem calls it: its name in the configuration. */
+    readonly label: string;
+    /** The theme; none for the base. */
+    readonly mode: string | undefined;
+    /** The file's content. */
+    readonly file: unknown;
+    /** The source it comes from; none for the catalogue's own. */
+    readonly source?: string;
+};
+/**
+ * Reads the files of a catalogue: the base first, then each theme over it. A theme gives a token a value when it names
+ * the token, or when a reference brings it a different one. The files of one theme are one layer, the later replacing,
+ * so a catalogue's dark file reaches what a library's dark file sets.
+ *
+ * @param inputs - the files: each source's in the catalogue's order, then the catalogue's own.
+ */
+export declare const readTokens: (inputs: readonly TokensInput[]) => ParsedTokens;
+/**
+ * The tokens of a category: a type (`color`), or a first group (`space`).
+ *
+ * @param tokens - the tokens.
+ * @param category - the category; none for all of them.
+ */
+export declare const filteredTokens: (tokens: readonly DesignToken[], category: string | undefined) => DesignToken[];