forgebook 0.3.3 → 0.4.1

package/dist/src/vite/compositionCheck.js

@@ -0,0 +1,243 @@
+/**
+ * What a change writes against how a design system says its components fit together: allowed parents, children and
+ * siblings, and plain elements a component stands in for.
+ *
+ * @remarks
+ * Pure, from the syntax tree of the changed files, for what the lines a change adds put there. It says only what the file
+ * shows: an element at the root of what a component returns, or held in a prop, may be drawn anywhere, so its parent is not
+ * known and it is left alone. Only what an author wrote is enforced, so a design system with no rules gets no findings. A
+ * `.vue` or `.svelte` template has no tree here, so only scripts with JSX are read, and the answer does not claim more.
+ *
+ * @module
+ */
+import { basename, dirname } from "node:path";
+import { parseSync } from "vite";
+import { rootsOf } from "./jsxTree.js";
+import { isTooDeep, lineStarts } from "./sourceText.js";
+/** What says a composition is meant: its rule and why, in a comment. */
+const IGNORE = /(?:\/\/|\/\*|<!--|\{\/\*)\s*forgebook-ignore\s+composition\s*:\s*([^*\n]{3,120})/;
+/** A script that can hold JSX. */
+const SCRIPT_FILE = /\.[jt]sx$/;
+/** What a file imports: each local name, what the module calls it, and from where. */
+const localNames = (program) => new Map(program.body.flatMap((statement) => statement.type !== "ImportDeclaration"
+    ? []
+    : statement.specifiers.map((each) => {
+        const module = statement.source.value;
+        const name = each.type === "ImportSpecifier" && "name" in each.imported
+            ? String(each.imported.name)
+            : each.local.name;
+        return [each.local.name, { name, module }];
+    })));
+/** Whether a module is a third party's: what it exports is not the project's component of that name. */
+const isThirdParty = (module, packages) => {
+    if (/^(?:\.{1,2}\/|[@~#]\/)/.test(module))
+        return false;
+    return !packages.some(({ name }) => name !== "" && (module === name || module.startsWith(`${name}/`)));
+};
+/** Whether a name is a component's and not a plain element's. */
+const isComponent = (name) => /^[A-Z]/.test(name) || /^[a-zA-Z]+\.[A-Z]/.test(name);
+/** Whether a name means a listed one: `Select.Root` is a `Select`, and `UI.Select` too. */
+const isListedName = (list, name) => {
+    const parts = name.split(".");
+    return list.includes(name) || list.includes(parts[0] ?? "") || list.includes(parts.at(-1) ?? "");
+};
+/** What an added element breaks of what may stand around it. */
+const checkParents = ({ real, line }, ancestors, rules, walk) => {
+    const { parents } = rules;
+    const inComponents = ancestors.filter(isComponent);
+    if (parents === undefined || inComponents.length === 0)
+        return;
+    // a component above that renders an allowed parent itself passes its children on to it
+    if (ancestors.some((each) => isListedName(parents, each) || walk.rendersAny(each, parents)))
+        return;
+    walk.found.push({
+        line,
+        value: real,
+        message: `${real} belongs inside ${parents.join(" or ")}, not ${inComponents.at(-1) ?? ""}.`
+    });
+};
+/** What an element's added children break of what may stand inside it. */
+const checkChildren = (real, children, rules, walk) => {
+    const allowed = rules.children;
+    if (allowed === undefined)
+        return;
+    for (const child of children) {
+        const name = walk.real(child.name);
+        const isFine = !isComponent(name) || isListedName(allowed, name) || walk.rendersAny(name, allowed);
+        if (!isFine && walk.isAdded(child.line)) {
+            walk.found.push({
+                line: child.line,
+                value: name,
+                message: `${real} takes ${allowed.join(" or ")} inside it, not ${name}.`
+            });
+        }
+    }
+};
+/** What an element and those beside it break of what may stand beside it, where either is added. */
+const checkSiblings = (element, siblings, rules, walk) => {
+    const allowed = rules.siblings;
+    if (allowed === undefined || element.isAlternative)
+        return;
+    const real = walk.real(element.name);
+    for (const sibling of siblings) {
+        const other = walk.real(sibling.name);
+        const isFine = sibling.isAlternative || other === real || !isComponent(other) || isListedName(allowed, other);
+        if (!isFine && (walk.isAdded(element.line) || walk.isAdded(sibling.line))) {
+            walk.found.push({
+                line: sibling.line,
+                value: real,
+                message: `${real} stands beside ${allowed.join(" or ")}, not ${other}.`
+            });
+        }
+    }
+};
+/** What one element breaks, standing where it stands. */
+const checkElement = (element, { ancestors, siblings }, walk) => {
+    const { name, line, children, isOutOfSight: isHidden } = element;
+    const isAdded = walk.isAdded(line);
+    const standIn = walk.standIn.get(name);
+    if (isAdded && standIn !== undefined && !isHidden) {
+        walk.found.push({ line, value: name, fix: standIn, message: `A plain <${name}>: use ${standIn}.` });
+    }
+    const rules = walk.rulesOf(name);
+    if (rules === undefined)
+        return;
+    const real = walk.real(name);
+    if (isAdded)
+        checkParents({ real, line }, ancestors, rules, walk);
+    checkChildren(real, children, rules, walk);
+    checkSiblings(element, siblings, rules, walk);
+};
+/** Walks elements with what stands above and beside each. */
+const walked = (elements, ancestors, walk) => {
+    for (const element of elements) {
+        checkElement(element, { ancestors, siblings: elements.filter((each) => each !== element) }, walk);
+        walked(element.children, [...ancestors, walk.real(element.name)], walk);
+    }
+};
+/**
+ * The rules of each name. A name the project gives twice with different rules could be either, and one component of it
+ * with none says the rules may not be meant for this use, so neither counts; copies that agree do.
+ */
+const rulesByName = (components) => {
+    const named = new Map();
+    for (const each of components) {
+        const list = named.get(each.name);
+        if (list === undefined)
+            named.set(each.name, [each]);
+        else
+            list.push(each);
+    }
+    return new Map([...named].flatMap(([name, list]) => {
+        const [first] = list;
+        const written = new Set(list.map((each) => JSON.stringify(each.rules ?? null)));
+        return written.size === 1 && first?.rules !== undefined ? [[name, first.rules]] : [];
+    }));
+};
+/** What each name renders, whichever component of the name: looked up for every element of a change. */
+const rendersByName = (components) => {
+    const renders = new Map();
+    for (const { name, renders: own } of components) {
+        const list = renders.get(name);
+        if (list === undefined)
+            renders.set(name, [...own]);
+        else
+            list.push(...own);
+    }
+    return renders;
+};
+/**
+ * Whether a file is in a component's own library, whose files are what the stand-in is made of: its folder, or the folder
+ * above when each component has a folder of its own (`ui/button/Button.tsx`).
+ */
+const isInLibraryOf = (component, file) => {
+    const folder = dirname(component);
+    const isOwnFolder = basename(component)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase() === basename(folder).toLowerCase();
+    return file.startsWith(`${isOwnFolder ? dirname(folder) : folder}/`);
+};
+/** The walk for one file, its imports followed. */
+const walkOf = ({ file, program, lines }, { components, ruled, renders, packages }) => {
+    const added = new Set(lines.map(({ line }) => line));
+    const imported = localNames(program);
+    const real = (written) => {
+        const [head = "", ...rest] = written.split(".");
+        return [imported.get(head)?.name ?? head, ...rest].join(".");
+    };
+    const rulesOf = (written) => {
+        const module = imported.get(written.split(".")[0] ?? "")?.module;
+        if (module !== undefined && isThirdParty(module, packages))
+            return undefined;
+        const name = real(written);
+        return ruled.get(name) ?? ruled.get(name.split(".").at(-1) ?? "");
+    };
+    return {
+        rulesOf,
+        real,
+        standIn: new Map(components.flatMap((each) => isInLibraryOf(each.file, file) || each.rules?.insteadOf === undefined
+            ? []
+            : each.rules.insteadOf.map((element) => [element, each.name]))),
+        rendersAny: (name, wanted) => (renders.get(name) ?? []).some((each) => wanted.includes(each) || (renders.get(each) ?? []).some((inner) => wanted.includes(inner))),
+        isAdded: (line) => added.has(line),
+        found: []
+    };
+};
+/** What composition found in one file, with what a comment excuses set apart. */
+const inFile = ({ file, text }, lines, system) => {
+    if (!SCRIPT_FILE.test(file) || isTooDeep(text))
+        return { problems: [], excused: [] };
+    const { program, errors } = parseSync(file, text);
+    if (errors.length > 0)
+        return { problems: [], excused: [] };
+    const walk = walkOf({ file, program, lines }, system);
+    for (const root of rootsOf(program, lineStarts(text)))
+        walked(root, [], walk);
+    const reasons = new Map(lines.flatMap(({ line, text: written }) => {
+        const reason = IGNORE.exec(written)?.[1];
+        return reason === undefined
+            ? []
+            : [
+                [line, reason.trim()],
+                [line + 1, reason.trim()]
+            ];
+    }));
+    return {
+        problems: walk.found
+            .filter(({ line }) => !reasons.has(line))
+            .map(({ line, value, fix, message }) => ({
+            rule: "composition",
+            file,
+            line,
+            value,
+            ...(fix === undefined ? {} : { fix }),
+            message
+        })),
+        excused: walk.found.flatMap(({ line, value }) => {
+            const reason = reasons.get(line);
+            return reason === undefined
+                ? []
+                : [{ file, line, rule: "composition", reason: `${value}: ${reason}` }];
+        })
+    };
+};
+/**
+ * What a change writes against how the system says its components fit together.
+ *
+ * @param added - the lines it adds.
+ * @param changed - the changed files as they are now.
+ * @param components - every component of the project.
+ * @param packages - the repository's packages, to tell a third party's component of the same name; none by default.
+ */
+export const compositionFindings = (added, changed, components, packages = []) => {
+    if (!components.some((each) => each.rules !== undefined))
+        return { problems: [], excused: [] };
+    const system = {
+        components,
+        ruled: rulesByName(components),
+        renders: rendersByName(components),
+        packages
+    };
+    const found = changed.map((file) => inFile(file, added.filter((line) => line.file === file.file), system));
+    return { problems: found.flatMap((each) => each.problems), excused: found.flatMap((each) => each.excused) };
+};

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

@@ -16,6 +16,7 @@ import type { ForgebookPlugin } from "../plugin.ts";
 import type { ShellOptions } from "../shellTheme.types.ts";
 import type { ViewSwitch } from "../switches.ts";
 import type { FrameworkAdapter } from "./adapter.ts";
+import type { AppBuildOption } from "./appBuildOption.ts";
 import type { FramesOption } from "./framesConfig.ts";
 /** What a library's preset gives a catalogue. */
 export type ForgebookPreset = CatalogueLists & {
@@ -31,6 +32,40 @@ export type ForgebookPreset = CatalogueLists & {
     readonly head?: string;
     /** The shell's look, under the catalogue's: its theme, and a style sheet by absolute path. */
     readonly shell?: ShellOptions;
+    /**
+     * Custom controls of the props panel it brings to every catalogue that lists it, by name, each module by absolute path
+     * or a package's specifier: a catalogue's registration of the same name replaces it. They run in the catalogue's page
+     * with a plugin's trust, as the catalogue's own do.
+     */
+    readonly argControls?: Readonly<Record<string, string | ArgControlOption>>;
+};
+/**
+ * Which props a custom control takes without a story naming it: each field given must hold, so `{ typeName, propName }`
+ * takes only that prop of that type.
+ */
+export type ArgControlMatch = {
+    /**
+     * The type's name as the props are read: as the source writes it (`IconComponent`), or any alias it is declared
+     * through (`type ButtonIcon = IconComponent`), without `undefined` and `null`; a union only when every member goes by it.
+     */
+    readonly typeName?: string;
+    /** The prop's name (`icon`). */
+    readonly propName?: string;
+};
+/** A custom control with more than its module: its frame module, and the props it takes on its own. */
+export type ArgControlOption = {
+    /** The module the panel draws it with, exporting `mount` and `schema`. */
+    readonly module: string;
+    /**
+     * A module of the stories' frames exporting `toStoryValue(value, argType)`, which turns the panel's JSON value into
+     * what the story receives (a name into an icon); none gives the story the JSON value.
+     */
+    readonly frame?: string;
+    /**
+     * The props it is the control of in every story that names no control for them, by type or by name; one or a list,
+     * of which any may match. A match by name wins over one by type, then the catalogue's controls over its presets'.
+     */
+    readonly matches?: ArgControlMatch | readonly ArgControlMatch[];
 };
 /** A tokens file: its path from the configuration's folder, with its theme when it is a theme's. */
 export type TokensFile = StoryTokensFile;
@@ -74,9 +109,18 @@ export type ForgebookConfig = CatalogueLists & {
     /**
      * Its design tokens, DTCG 2025.10 files by path from the configuration's folder, the base first; a theme is a file of
      * its own (`["tokens.json", { file: "dark.tokens.json", mode: "dark" }]`). What tools and agents read tokens from,
-     * after each source's: a name given twice takes the catalogue's value, and tools report the clash.
+     * after each source's: a name given twice takes the catalogue's value, and tools report the clash. With none named here
+     * or on a source, what the application already declares is read instead (custom properties, Tailwind, `components.json`);
+     * `[]` says there is no system, so nothing is.
      */
     readonly tokens?: readonly TokensFile[];
+    /**
+     * Custom controls of the props panel, by the name a story's `argTypes` use (`{ rating: "./controls/rating.ts" }`): each a
+     * module, by path from the configuration's folder or a package's specifier, exporting `mount` and `schema`, or an
+     * `ArgControlOption` with a frame module and the props it matches. It loads when a story's panel shows it, and runs in
+     * the shell's page with a plugin's trust. A name its presets register is replaced; `false` removes theirs.
+     */
+    readonly argControls?: Readonly<Record<string, string | ArgControlOption | false>>;
     /** Its preview's path from the configuration's folder; `forgebook.preview.ts` (or `.tsx`) beside it when there. */
     readonly preview?: string;
     /** Tags for every frame's `<head>` (a font's link); none by default. */
@@ -95,6 +139,28 @@ export type ForgebookConfig = CatalogueLists & {
     readonly frames?: FramesOption;
     /** How `forgebook build` writes the catalogue. */
     readonly build?: BuildOptions;
+    /**
+     * How much of the app's own build its stories are drawn with: `tsconfig.json`'s `paths`, the `vite.config` beside this
+     * file (its aliases, its plugins except the framework's and those only an app's build needs) and its PostCSS. All by
+     * default; loading a `vite.config` or a `postcss.config` runs its code, as the app's build does. `false` reads none,
+     * and each part can be turned off.
+     */
+    readonly appBuild?: AppBuildOption;
+    /**
+     * Other catalogues, built and deployed, shown in the sidebar after this one's stories, by an id of lower-case words
+     * (`{ "design-system": { title: "Design system", url: "https://ds.example.com/" } }`). Each is read from the index
+     * its `forgebook build --agent-index` writes, when its section is first opened, and its stories are drawn by its own
+     * page on its own origin, read-only, with this catalogue's switches. Its host must let this catalogue fetch the index
+     * (CORS) and frame its page. None by default.
+     */
+    readonly refs?: Readonly<Record<string, RefOption>>;
+};
+/** A catalogue shown in another's sidebar (`refs`). */
+export type RefOption = {
+    /** Its name, as its section's heading. */
+    readonly title: string;
+    /** The address it is served at, its folder (`https://ds.example.com/catalogue/`). */
+    readonly url: string;
 };
 /** How `forgebook build` writes the catalogue. */
 export type BuildOptions = {

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

@@ -10,12 +10,15 @@
  * @module
  */
 import type { StoryLanguage } from "@forgebook/story-format/source";
-import type { CatalogueLists } from "../catalogue.ts";
+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 ResolvedAppBuild } from "./appBuildOption.ts";
+import { type ResolvedArgControls } from "./argControlsConfig.ts";
 import type { BuildOptions, ForgebookConfig } from "./config.ts";
 import { type ResolvedFrames } from "./framesConfig.ts";
+import { type ResolvedRefs } from "./refsConfig.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[];
@@ -24,6 +27,8 @@ export declare const CONFIG_FILES: string[];
  * 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 names a preview may have beside the configuration, in the order they are looked for. */
+export declare const PREVIEW_FILES: string[];
 /** The shell's look, ready for its page. */
 export type ResolvedShell = {
     /** The theme, as CSS; empty for none. */
@@ -79,6 +84,10 @@ export type ResolvedConfig = {
     readonly shell: ResolvedShell;
     /** The tokens files, absolute, the base first. */
     readonly tokens: readonly ResolvedTokensFile[];
+    /** Whether the configuration says `tokens: []`: no system at all, so the application's own files are not read for one. */
+    readonly isAppTokensOff?: boolean;
+    /** The custom controls by name, the catalogue's and its presets', in their precedence. */
+    readonly argControls: ResolvedArgControls;
     /** 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. */
@@ -89,8 +98,12 @@ export type ResolvedConfig = {
     readonly plugins: readonly ForgebookPlugin[];
     /** Where the stories' frames run. */
     readonly frames: ResolvedFrames;
+    /** The catalogues shown in the sidebar after this one's stories, in the configuration's order. */
+    readonly refs: ResolvedRefs;
     /** How `forgebook build` writes the catalogue, every option given its default. */
     readonly build: Required<BuildOptions>;
+    /** How much of the app's own build its stories are drawn with. */
+    readonly appBuild: ResolvedAppBuild;
 };
 /** 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"];
@@ -110,7 +123,7 @@ 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, and the accessibility
- * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * check too (`a11y: false`); the statuses status by status and field by field; 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.

package/dist/src/vite/configFile.js

@@ -19,16 +19,25 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { AUDIENCE_IDS } from "../audiences.js";
+import { catalogueSettings, playProblem } from "../catalogue.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 { mergedStatuses, statusesProblem } from "../storyStatuses.js";
+import { catalogueSwitches, switchesProblem } from "../switches.js";
+import { appBuildProblem, resolvedAppBuild } from "./appBuildOption.js";
+import { resolvedArgControls } from "./argControlsConfig.js";
+import { saysNoTokens, unknownKeysProblem } from "./configKeys.js";
+import { configLoadMessage } from "./configLoadError.js";
 import { framesProblem, resolvedFrames } from "./framesConfig.js";
 import { pluginsProblem, withPluginSwitches } from "./pluginConfig.js";
-import { patternsProblem } from "./storyPatterns.js";
+import { realFolder } from "./realFolder.js";
+import { refsProblem, resolvedRefs } from "./refsConfig.js";
+import { filesProblem } from "./storyPatterns.js";
+import { switchValuesProblem, withAbsoluteValueFiles } from "./switchValuesCheck.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. */
@@ -39,15 +48,38 @@ export const CONFIG_FILES = ["forgebook.config.ts", "forgebook.config.mts", "for
  */
 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"];
+export 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. */
 export const PLAY_TOOLS_PACKAGES = ["@testing-library/dom", "@testing-library/user-event"];
+/**
+ * Whether a package's folder is in the `node_modules` folders going up from a folder. Node also reads `NODE_PATH`, which
+ * pnpm's command shims point at its own store's hoisted packages, and Vite does not: a package found that way alone is one
+ * Vite then fails on, for every story.
+ *
+ * @param dir - the folder.
+ * @param name - the package or one of its subpaths.
+ */
+const isUnderNodeModules = (dir, name) => {
+    const parts = name.split("/");
+    const packageName = parts.slice(0, name.startsWith("@") ? 2 : 1).join("/");
+    let current = resolve(dir);
+    while (true) {
+        if (existsSync(join(current, "node_modules", packageName)))
+            return true;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+};
 /**
  * Resolves packages as Node does from a folder: a package's (or subpath's) file, or none when it is not there.
  *
  * @param dir - the folder, the configuration's.
  */
 export const packageResolver = (dir) => (name) => {
+    if (!isUnderNodeModules(dir, name))
+        return undefined;
     const require = createRequire(resolve(dir, "package.json"));
     try {
         return require.resolve(name);
@@ -102,13 +134,26 @@ const singleValues = (lists) => ({
     ...(lists.audience === undefined ? {} : { audience: lists.audience }),
     ...(lists.appearance === undefined ? {} : { appearance: lists.appearance }),
     ...(lists.propGroups === undefined ? {} : { propGroups: lists.propGroups }),
-    ...(lists.requiredFirst === undefined ? {} : { requiredFirst: lists.requiredFirst })
+    ...(lists.requiredFirst === undefined ? {} : { requiredFirst: lists.requiredFirst }),
+    ...(lists.play === undefined ? {} : { play: lists.play })
 });
+/**
+ * Checks a list's statuses, which a configuration writes by JavaScript too, where no type stops a mistake.
+ *
+ * @param statuses - the statuses written.
+ * @param dir - the configuration's folder, for the message.
+ * @throws when a status cannot be used.
+ */
+const checkStatuses = (statuses, dir) => {
+    const problem = statusesProblem(statuses);
+    if (problem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${problem}`);
+};
 /**
  * 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, and the accessibility
- * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * check too (`a11y: false`); the statuses status by status and field by field; 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.
@@ -152,27 +197,14 @@ export const mergedLists = (all) => {
             },
         strings,
         keys,
+        ...mergedStatuses(all.map((lists) => lists.statuses)),
         // 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 where its frames run or what it reads of the app's build cannot be used, or none. */
+const placementProblem = (config) => framesProblem("frames" in config ? config.frames : undefined) ??
+    appBuildProblem("appBuild" in config ? config.appBuild : undefined);
 /**
  * Why a loaded configuration cannot be used, or none.
  *
@@ -181,6 +213,10 @@ const globsProblem = (config, key) => {
 const configProblem = (config) => {
     if (typeof config !== "object" || config === null)
         return "it exports no configuration (`export default defineConfig({ … })`)";
+    // first: a misspelt `title` or `framework` is better named as such than as one left out
+    const keysProblem = unknownKeysProblem(config);
+    if (keysProblem !== undefined)
+        return keysProblem;
     if (!("framework" in config) || typeof config.framework !== "object" || config.framework === null)
         return "it names no framework (`framework: react()`)";
     if (!("title" in config) || typeof config.title !== "string")
@@ -190,14 +226,7 @@ const configProblem = (config) => {
         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';
-    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);
+    return filesProblem(config) ?? placementProblem(config) ?? refsProblem(config);
 };
 /**
  * Whether a loaded configuration is one: checked by `configProblem`.
@@ -240,18 +269,19 @@ const deviceProblem = (device) => {
 /**
  * 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`.
+ * `false`, a status that is no tag of the catalogue's or reads wrongly.
  *
  * @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`.
+ * @throws when a device cannot be used, `requiredFirst` is none of its layouts, `a11y` is neither rules nor
+ *   `false`, or a status cannot be used.
  */
 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}`);
+        checkStatuses(lists.statuses, dir);
         // 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`);
@@ -275,7 +305,29 @@ const mergedListsProblem = (lists) => {
         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;
+    return playProblem(lists.play);
+};
+/**
+ * What the shell would refuse when it starts, refused on Node instead: a toolbar naming no control, a key that cannot be
+ * used, a view that cannot be read. Without this a command or a build succeeds, and the mistake surfaces as a blank page
+ * in a reader's browser. The same call the shell makes (`catalogueContext.ts`), so both refuse the same things.
+ *
+ * @param resolved - the configuration's merged title, switches, languages, lists and plugins, with its folder.
+ * @throws what the shell would, with the configuration's name.
+ */
+const checkSettings = (resolved) => {
+    const { dir, title, switches, languages, lists, plugins } = resolved;
+    try {
+        const shown = catalogueSwitches(switches, languages, lists.controls);
+        const problem = switchValuesProblem(shown, dir);
+        if (problem !== undefined)
+            throw new Error(problem);
+        catalogueSettings(title, shown, lists, plugins.flatMap((plugin) => (plugin.tabs ?? []).map((tab) => tab.id)));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${message}`);
+    }
 };
 /** What a catalogue shows: its own stories and docs pages, and the sources; none where it names none. */
 const shownFiles = (config) => ({
@@ -357,6 +409,8 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
     const themeProblem = themeValueProblem(theme);
     if (themeProblem !== undefined)
         throw new Error(`${resolve(dir, "forgebook.config")}: ${themeProblem}`);
+    const languages = mergedById([...presets.map((preset) => preset.languages), config.languages]);
+    checkSettings({ dir, title: config.title, switches, languages, lists, plugins });
     const ownPreview = config.preview === undefined
         ? PREVIEW_FILES.map((name) => paths.join(dir, name)).find((file) => existsSync(file))
         : absolute(config.preview);
@@ -368,8 +422,8 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
         logo: config.logo === undefined ? undefined : absolute(config.logo),
         heights: config.heights,
         ...shownFiles(config),
-        switches,
-        languages: mergedById([...presets.map((preset) => preset.languages), config.languages]),
+        switches: switches === undefined ? undefined : withAbsoluteValueFiles(switches, dir, paths),
+        languages,
         previews: [
             ...presets.flatMap((preset) => (preset.preview === undefined ? [] : [ownPath(preset.preview)])),
             ...(ownPreview === undefined ? [] : [ownPreview])
@@ -388,12 +442,20 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
             problems: [...tokenThemed.problems, ...shellThemeProblems(theme)]
         },
         tokens,
+        isAppTokensOff: saysNoTokens(config),
+        argControls: resolvedArgControls(config, dir, {
+            absolute,
+            isAbsolute: paths.isAbsolute,
+            normalize: paths.normalize
+        }),
         watch: (config.watch ?? []).map(absolute),
         lists,
         hasPlayTools: hasPlayToolsIn(dir),
         plugins,
         frames: resolvedFrames(config.frames),
-        build: { readableNames: config.build?.readableNames === true }
+        refs: resolvedRefs(config.refs),
+        build: { readableNames: config.build?.readableNames === true },
+        appBuild: resolvedAppBuild(config.appBuild)
     };
 };
 /**
@@ -403,9 +465,16 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
  * @throws when the file does not load, or exports no usable configuration.
  */
 export const loadConfigFile = async (file) => {
-    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    }
+    catch (error) {
+        throw new Error(await configLoadMessage(file, error));
+    }
     const config = typeof module === "object" && module !== null && "default" in module ? module.default : undefined;
     if (!isConfig(config))
         throw new Error(`${file}: ${configProblem(config) ?? "it cannot be read"}`);
-    return resolveConfig(config, dirname(file));
+    // the folder as Vite makes its root, so the pages named under it compare with it
+    return resolveConfig(config, realFolder(dirname(file)));
 };