forgebook 0.4.0 → 0.4.1

package/README.md

@@ -252,6 +252,9 @@ too, with a warning.
   them and hides the rest in the View menu; their browser keeps it ([below](#the-toolbar)).
 - **A light and a dark catalogue**: the reader picks Light, Dark or System in the Interface menu at the sidebar's foot
   (their browser keeps it); `appearance` in the configuration sets the default. The stories keep their own theme, from the view's switches.
+- **Contained or full width**: the button beside the Stories picker, and at the top of the home, sets the home and a
+  component's page in a centred column (pressed, the default) or across the whole width; their browser keeps it. A
+  docs page keeps its reading column, and a story's page its own width controls.
 - **Keys and named views**: `?` lists the keys, as does the menu at the sidebar's foot, where a reader can turn off every
   key without a modifier for this browser; a key pressed inside a story, in a text field or in a custom element stays
   theirs. A key cycles a control's values (`t` the theme, Shift+`t` back); the catalogue sets the
@@ -727,8 +730,9 @@ The editors are one chunk that loads when the first such prop is drawn: a catalo
 
 ### Controls of your own
 
-A control the panel lacks is a module of yours, registered by name and loaded when a story names it. A catalogue that
-registers none loads nothing for this.
+A control the panel lacks is a module of yours, registered by name and loaded when a story names it, or a prop it
+matches by type is shown ([below](#controls-by-type-and-from-a-librarys-preset)). A catalogue that registers none loads
+nothing for this.
 
 ```ts
 // forgebook.config.ts
@@ -752,7 +756,7 @@ export const mount = (element: HTMLElement, props: ArgControlProps) => {
 };
 ```
 
-`mount(element, { value, onChange, argType })` draws in the element and returns what takes it away. It is a function rather
+`mount(element, { value, onChange, argType, strings })` draws in the element and returns what takes it away. It is a function rather
 than a component, so it can be written in any framework, whatever the stories' is: `createApp` in Vue, `mount` in Svelte,
 plain DOM. `argType` holds the arg's `name`, `label` and `description`, and the control's `options`, `min`, `max`, `step`
 and `settings`. The control keeps what it draws: it is mounted again only when the value changes from outside it.
@@ -775,6 +779,77 @@ agents its module also loads on the dev server when a command asks about a story
 touches the page inside `mount`. A name that no control has (`control: "selct"`) is read as a custom control, and says so
 beside the field.
 
+### Controls by type, and from a library's preset
+
+A control can take a prop in every story without any story naming it: by the prop's type, its name, or both. A library
+registers its controls in its preset, so every catalogue that lists the preset gets them, with no `argTypes` to write:
+
+```ts
+// the library's preset (its `./forgebook` export)
+export const acmePreset = (): ForgebookPreset =>
+  definePreset({
+    name: "acme-ui",
+    argControls: {
+      icon: {
+        module: "@acme/ui/forgebook/icon-picker", // mount and schema, drawn in the panel
+        frame: "@acme/ui/forgebook/icon-value", // toStoryValue, run in the story's frame
+        matches: { typeName: "IconComponent" }
+      }
+    },
+    strings: { "argControls.icon.none": "No icon" }
+  });
+```
+
+```ts
+// @acme/ui/forgebook/icon-value
+import type { ArgControlFrameModule } from "forgebook/arg-control";
+import { ICONS } from "../src/icons";
+
+export const toStoryValue: ArgControlFrameModule["toStoryValue"] = (name) =>
+  typeof name === "string" && Object.hasOwn(ICONS, name) ? ICONS[name] : undefined;
+
+// optional: the story's own icon named back, so the picker shows what the story draws
+export const toPanelValue: ArgControlFrameModule["toPanelValue"] = (icon) =>
+  Object.entries(ICONS).find(([, each]) => each === icon)?.[0];
+```
+
+- **What matches.** `matches` is one `{ typeName, propName }` or a list of them; each field given must hold. `typeName`
+  is the type as the props are read: as the source writes it (`IconComponent`), or any alias it is declared through
+  (`type ChipIcon = IconComponent`), an import's new name, with `undefined` and `null` left out, so `icon?: IconComponent`
+  and `icon?: IconComponent | undefined` match; a union matches only when every member goes by the name. `forgebook story
+  --json` writes the names a prop's type goes by as `typeNames` when they are more than its `type`. An event never
+  matches.
+- **Which control wins.** A control a story's `argTypes` name for the prop wins over any match; a `description` or a
+  `label` alone keeps the matched control. Among controls that match, one that names the prop wins over one that names
+  only its type, then the catalogue's own before its presets', each in the order written. Only props the component has
+  get a control: no story gains a prop.
+- **The value.** The panel, a link and an agent keep the control's JSON value (`"IconSearch"`), checked against its
+  `schema`. A `frame` module turns it into what the story receives, in the frame, with `toStoryValue(value, { name,
+  settings })`; a value it cannot turn, or a module that fails, leaves the story its own value and says why. Without a
+  `frame` module the story receives the JSON value. `toPanelValue`, optional, names a value the story gives itself.
+- **Its code.** The Code tab and `forgebook story` write a value as the story receives it when the control's module
+  exports `toCode(value, argType)`, the expression the attribute holds: `toCode: (name) => name` writes
+  `icon={IconStar}`, not `icon="IconStar"`. Without it, or for a value it gives `undefined`, the JSON value is written;
+  the story file's own code for an arg stays as written until the panel sets it. It runs in the page and on the dev
+  server.
+- **When it loads.** The module loads when the panel first shows a prop it takes, the frame module when a story's frame
+  is first given a value of it: neither on the catalogue's first load. A frame reads its story's component docs, to
+  know which props a control takes, only once a module may have work: the panel gives a value, the story's `argTypes`
+  name a control with a frame module, or the story gives itself a value plain data cannot show (an icon to name back).
+  A story of plain values that nobody edits loads neither.
+- **Texts.** A control receives `strings` (always given; optional in the type, so its own tests need not build it): the
+  catalogue's `strings` whose key starts with `argControls.<name>.`, by the rest of the key. A preset words its control
+  there, and the catalogue's own `strings` replace a preset's.
+- **The catalogue decides.** Its registration of a name replaces a preset's, and `argControls: { icon: false }` removes
+  it (a name no preset registers is an error, so a typo is not silent). A preset names its modules by absolute path or a
+  package's specifier, as its preview; no module is an address (`https:`, `data:`). A preset cannot take every prop of a
+  keyword type (`{ typeName: "string" }`) without a `propName`.
+
+**A preset's control runs in the catalogue's page, with a plugin's trust**, as the catalogue's own do. A preset is
+already code the catalogue runs on Node (its configuration calls it, and the dev server loads a control's module for
+its `schema`); what changes is that its control also runs in the page. Its frame module runs in the stories' frames, as
+its preview does.
+
 ## Docs pages
 
 Guides, foundations and recipes are Markdown files with a little front matter, not MDX: a page is read at build time, and
@@ -1629,6 +1704,11 @@ its `frame-src`, in the preview's `frameDomains`).
 - **`server.fs.deny` wins over your globs.** A file it refuses stays out of the catalogue, its search and "Used in", with
   a warning. A file your globs name outside `server.fs.allow` is listed and served, as Vite serves any file a module of
   the project imports.
+- **A missing file is a 404, never your app's page.** The catalogue's two pages are its own, so the dev server has no
+  single-page fallback: a story's image under a path nothing serves answers 404, and the checks list it among their
+  warnings by its path, without failing.
+  Your app's `index.html` is never served, so its entry and every package it reaches stay unloaded. A Vite configuration
+  of your own that runs the plugin and sets `appType` keeps it.
 
 A command, an agent or `curl` sends no browser headers: `forgebook mcp`, `forgebook stories` and the agent API
 (`/__forgebook/api/`) work as usual, and anyone who can reach the port can use them. With `--host` that means your whole

package/dist/bin/forgebook/agentText.js

@@ -127,6 +127,11 @@ export const checkText = (report, style) => (report.a11y === "off" ? "Accessibil
                 result.view || "default",
                 `${problem.kind}: ${problem.message}`
             ])),
+        ...(result.warnings ?? []).map((warning) => [
+            result.storyId,
+            result.view || "default",
+            `warning: ${warning.message}`
+        ]),
         ...judgementLines(result)
     ]), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Result" }] }, uncut(style));
 /**
@@ -332,6 +337,7 @@ export const verifyText = (document, style) => {
     const outdated = (document.outdated ?? []).map((each) => `${each.file}  out of date: written for props ${each.written}, now ${each.current}. Fix: ${each.fix}`);
     const notes = document.code.notes.map((each) => `${each.file}${each.line === undefined ? "" : `:${each.line}`}  note: ${each.message}`);
     const advice = (document.code.advice ?? []).map((each) => `${each.file}:${each.line}  ${each.message}`);
+    const warnings = document.warnings.map((each) => `${each.path}  warning: ${each.message}, in ${each.stories.length === 1 ? "1 story" : `${each.stories.length} stories`}`);
     const results = [
         ...document.failures,
         ...document.notVerified.map((each) => ({ ...each, problems: [] }))
@@ -344,6 +350,7 @@ export const verifyText = (document, style) => {
         ...outdated,
         ...notes,
         ...advice,
+        ...warnings,
         ...stories,
         document.summary
     ].join("\n");

package/dist/bin/forgebook/guide/commands.md

@@ -46,6 +46,11 @@ not report `partly-verified` as verified: say what `skipped` says. A file in `ui
 `verify` again. `coverage: "through"` means it ran in another component's stories. A UI file is a component or a style
 sheet by its extension, a story file, or a script that defines or draws a component; anything else does not fail.
 
+A static file a story asks for that is not there (an image, a font, a style sheet answering 404) is a warning, not a
+failure: `verify` lists it once in `warnings` with its `path` and the `stories` that asked for it, and says it in
+`summary`; `check` gives it in each result's `warnings`. Name it when you report, and add the file to the public folder
+if the change should have one. A module or a script that answers 404, and any error on the page, still fail.
+
 A story file `forgebook new` wrote carries `// forgebook-props: <signature>`, the props it was written for. When the change
 reaches it and its component's props no longer give that signature, `verify` lists it in `outdated` and fails: its args
 may pass a prop that is gone or miss one now required. Check them against `story <id>`'s props, then set the line to

package/dist/bin/forgebook/guide/stories.md

@@ -27,8 +27,13 @@ The framework's own guide (`forgebook guide <framework>`) has what differs in yo
   value over the story's own; an empty text is `""`; a `Date` is `{ "forgebookDate": "<ISO>" }`. Give a person the `address` link to look at them: `forgebook shot` draws
   a frame alone, with the story's own values.
 - A custom control (`control: "custom"`, `custom` its name) takes a value that fits `schema`, in `controls`; set it as any
-  other. A new one is a module exporting `mount(el, { value, onChange, argType })`, returning an unmount, and `schema`,
-  registered in `argControls` of `forgebook.config`; keep what touches the page inside `mount`, so the commands can read it.
+  other. A new one is a module exporting `mount(el, { value, onChange, argType, strings })`, returning an unmount, and
+  `schema`, registered in `argControls` of `forgebook.config` or of a library's preset; keep what touches the page inside
+  `mount`, so the commands can read it. Registered as `{ module, frame, matches: { typeName: "IconComponent" } }`, it takes
+  every prop of that type (or `propName`) in stories whose `argTypes` name no control for it, with no story code: a prop's
+  `typeNames` say the aliases its type goes through. The value stays JSON (an icon's name); the `frame` module's
+  `toStoryValue(value, argType)` turns it into what the story receives; the module's optional `toCode(value, argType)`
+  gives the expression the story's code writes (`icon={IconStar}`).
 - A prop's TSDoc can ask for design tokens (`@token color`, a token's type or a part of its name), a story's arg with
   `argTypes: { x: { control: { type: "token", of: "space", format: "var(--{name})" } } }`.
 - Story ids are Storybook's (`inputs-readmore--open-by-default`, prefixed by the source's id); the commands also take

package/dist/bin/forgebook/verifyBase.js

@@ -16,6 +16,7 @@
  * @module
  */
 import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
 import { findConfigFile } from "../../src/vite/configFile.js";
 import { gitOutput, gitOutputIn } from "../../src/vite/gitChange.js";
@@ -74,6 +75,13 @@ const twinModules = (from, to, root, folder) => {
             symlinkSync(linkTarget(entry, root, folder), join(to, name), "junction");
     }
 };
+/**
+ * How the base's folder is removed: tried again for a moment while it is still being written in. A server Vite closes
+ * while its first pre-bundle runs (a base with none of the stories asked for closes at once) cancels the run, but the
+ * bundler still writes its files into the cache folder inside, and the removal would fail on a folder not empty. The
+ * removal waits between tries without holding the process, so what is still writing can finish.
+ */
+const BASE_REMOVAL = { recursive: true, force: true, maxRetries: 10, retryDelay: 50 };
 /** The prefix of the folders a base runs in, beside the repository. */
 const folderPrefix = (root) => `.${basename(root)}-forgebook-base-`;
 /**
@@ -189,8 +197,8 @@ export const runOnBase = async (config, base, ids, isAllVariants, runEnv) => {
     finally {
         // the links go first, so nothing that removes the worktree can follow one into the working tree
         for (const twin of twins)
-            rmSync(twin, { recursive: true, force: true });
+            await rm(twin, BASE_REMOVAL);
         await gitOutputIn(root, env, "worktree", "remove", "--force", folder).catch(() => undefined);
-        rmSync(folder, { recursive: true, force: true });
+        await rm(folder, BASE_REMOVAL);
     }
 };

package/dist/bin/forgebook/verifyVerdict.js

@@ -198,6 +198,30 @@ const failuresOf = (results, links) => results
     const storyLinks = links.get(storyId);
     return { storyId, view, problems: found, ...(storyLinks === undefined ? {} : { links: storyLinks }) };
 });
+/**
+ * The warnings of the pairs that ran, one per file, with the stories that asked for it.
+ *
+ * @param results - the pairs that ran.
+ */
+const warningsOf = (results) => {
+    const byPath = new Map();
+    for (const result of results)
+        for (const warning of result.warnings ?? []) {
+            const found = byPath.get(warning.path) ?? { warning, stories: new Set() };
+            found.stories.add(result.storyId);
+            byPath.set(warning.path, found);
+        }
+    return [...byPath.values()].map(({ warning, stories }) => ({ ...warning, stories: [...stories] }));
+};
+/**
+ * The end of the verdict's line for the warnings: a missing file does not change the verdict, so the line names it, so
+ * it is not missed; nothing without any.
+ *
+ * @param warnings - the warnings.
+ */
+const warningWords = (warnings) => warnings.length === 0
+    ? ""
+    : `; ${counted(warnings.length, "warning")}: ${warnings.map((each) => `${each.path} is missing`).join(", ")}`;
 /** What the comparison with the base leaves unchecked: a base that could not run, stories it never saw. */
 const baseSkips = (compared) => [
     ...(compared.notCompared === undefined
@@ -226,6 +250,7 @@ export const verifyDocument = (input) => {
     const uiFiles = changed.uiFiles.map((file) => verifiedFile(file, ran, notRun));
     const links = new Map(changed.stories.map((story) => [story.id, story.links]));
     const failures = failuresOf(results, links);
+    const warnings = warningsOf(results);
     const notVerified = results.flatMap(({ storyId, view, notVerified: reason }) => {
         if (reason === undefined)
             return [];
@@ -272,6 +297,7 @@ export const verifyDocument = (input) => {
         ran: seenResults.length,
         failures,
         notVerified,
+        warnings,
         code: {
             checked: code.checked,
             problems: codeProblems,
@@ -292,6 +318,6 @@ export const verifyDocument = (input) => {
     const old = existingProblems === 0
         ? ""
         : `; ${counted(existingProblems, "problem")} the stories had before the change not counted (existing; --all-problems counts them)`;
-    const summary = `${summaryOf({ ...body, verdict, skipped: allSkipped }, catalogueProblems)}${old}`;
+    const summary = `${summaryOf({ ...body, verdict, skipped: allSkipped }, catalogueProblems)}${old}${warningWords(warnings)}`;
     return { schema: 2, verdict, summary, skipped: allSkipped, ...body };
 };

package/dist/src/argControl.d.ts

@@ -1,11 +1,12 @@
 /**
- * A custom control's contract: a module a catalogue registers by name (`argControls` in `forgebook.config`) and a story
- * uses as `argTypes: { x: { control: "name" } }`.
+ * A custom control's contract: a module a catalogue or a library's preset registers by name (`argControls`) and a story
+ * uses as `argTypes: { x: { control: "name" } }`, or that takes the props of a type in every story (`matches`); and its
+ * frame module, which turns the control's value into the story's.
  *
  * @remarks
  * `mount` rather than a component, so a team writes one in whatever its stories are written in: the shell knows nothing of
  * how it draws. The value is always JSON with a declared schema, so a link keeps working and an agent can set it with no
- * UI. The module runs in the shell's page, with a plugin's trust.
+ * UI. The module runs in the shell's page, with a plugin's trust; the frame module in the stories' frames, as a preview.
  *
  * @module
  */
@@ -84,6 +85,13 @@ export type ArgControlProps = {
     readonly onChange: (value: JsonValue | undefined) => void;
     /** What the story says of the arg. */
     readonly argType: ControlArgType;
+    /**
+     * The control's texts as the catalogue words them: its `strings` (a preset's, then the catalogue's own over them) whose
+     * key starts with `argControls.<name>.`, by the rest of the key (`none` for `argControls.icon.none`). A control falls
+     * back to its own words for a key it does not find. Always given by the panel; optional so a control's own tests need
+     * not build it.
+     */
+    readonly strings?: Readonly<Record<string, string>>;
 };
 /** A custom control's module. */
 export type ArgControlModule = {
@@ -97,4 +105,44 @@ export type ArgControlModule = {
     readonly mount: (element: HTMLElement, props: ArgControlProps) => () => void;
     /** What its value looks like: a link's value and each `onChange` are checked against it. */
     readonly schema: ValueSchema;
+    /**
+     * The code a value is written as in the story's code (the Code tab, `forgebook story`), when it is not the value as
+     * JSON: the expression the attribute holds, `IconStar` for the icon the name `"IconStar"` gives the story (written
+     * `icon={IconStar}`). None, or `undefined` for a value, writes the JSON value. Runs in the page and on the dev server,
+     * so it reads nothing of either.
+     *
+     * @param value - the panel's value.
+     * @param argType - what the story says of the arg.
+     * @returns the expression, as code.
+     */
+    readonly toCode?: (value: JsonValue, argType: ControlArgType) => string | undefined;
+};
+/** What a frame module is told of the arg whose value it turns into the story's. */
+export type FrameArgType = {
+    /** The arg's name. */
+    readonly name: string;
+    /** The control's `settings` the story's `argTypes` write, as JSON; none when they write none. */
+    readonly settings?: JsonValue;
+};
+/** A custom control's frame module: loaded in a story's frame when the panel first gives it a value of that control. */
+export type ArgControlFrameModule = {
+    /**
+     * The value the story receives for the panel's: a name turned into the component it names, say. Links and agents keep
+     * the JSON value; this runs only in the frame, after the shell checked the value against the control's schema. A link
+     * chose it, so read it as any JSON: look a name up among your own entries (`Object.hasOwn`), never through a prototype.
+     *
+     * @param value - the panel's value, as JSON.
+     * @param argType - the arg.
+     * @returns what the story receives; `undefined` gives the story no value.
+     */
+    readonly toStoryValue: (value: JsonValue, argType: FrameArgType) => unknown;
+    /**
+     * The panel's value for a value the story gives itself (the icon its `args` name back into its name), so the control
+     * shows what the story draws; none leaves the control without one, as for any value JSON cannot hold.
+     *
+     * @param value - the story's own value.
+     * @param argType - the arg.
+     * @returns the panel's value, which the control's schema must take; `undefined` when it has none.
+     */
+    readonly toPanelValue?: (value: unknown, argType: FrameArgType) => JsonValue | undefined;
 };

package/dist/src/argTypes.js

@@ -97,9 +97,11 @@ const withArgType = (prop, argType, own) => {
     const { control } = argType;
     // a control the panel cannot draw makes the prop one it lists for reading, never one that takes a text
     const isReadOnly = control === "none";
-    const { canTakeText: _canTakeText, ...rest } = prop;
+    // a control the story names wins over the one the catalogue gives the prop's type
+    const { customControl: _typed, ...untyped } = prop;
+    const { canTakeText: _canTakeText, ...rest } = untyped;
     // a control the story names decides what its value is: the type's shape no longer draws nor checks it
-    const { shape: _shape, ...shapeless } = isReadOnly || argType.customControl !== undefined ? rest : prop;
+    const { shape: _shape, ...shapeless } = isReadOnly || argType.customControl !== undefined ? rest : untyped;
     return {
         ...(control === undefined && argType.customControl === undefined ? prop : shapeless),
         ...(control === undefined ? {} : { kind: KIND_OF_CONTROL[control], control }),

package/dist/src/componentDocs.d.ts

@@ -129,12 +129,24 @@ export type PropDocs = {
      * union by the types it happened to meet first, so it changed between reads of a program kept in memory.
      */
     readonly type: string;
+    /**
+     * The names its type goes by, when they are more than `type`: the name written, the name it was declared with when an
+     * import renamed it, and each alias it is declared through (`ButtonIcon`, `IconComponent` for
+     * `type ButtonIcon = IconComponent`), without `undefined` and `null`; for a union, the names every member goes by. Left
+     * out when `type` says them all.
+     */
+    readonly typeNames?: readonly string[];
     /** The first paragraph of its TSDoc; empty when it has none. */
     readonly description: string;
     /** Its `@defaultValue`, when the TSDoc gives one. */
     readonly defaultValue?: string;
     /** Whether the prop must be passed. */
     readonly isRequired: boolean;
+    /**
+     * The custom control the catalogue gives it by its type or its name (a control's `matches`), when one does: the
+     * plugin adds it as it serves the docs, so the panel draws it in every story that names no control for the prop.
+     */
+    readonly customControl?: string;
     /** For a choice, its values in the order of the type. */
     readonly choices?: readonly (string | number)[];
     /** For an event, its signature. */

package/dist/src/componentDocs.js

@@ -32,7 +32,11 @@ const isMemberDocs = (value) => isRecord(value) &&
     (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
 /** Whether a value is a note with a reason: what the reference reads first. */
 const isNote = (value) => isRecord(value) && typeof value["reason"] === "string";
-/** Whether a value is one prop's docs. */
+/**
+ * Whether a value is one prop's docs. Some fields are left to what reads them, as a choice's values and a signature are:
+ * a custom control's name is only looked up among the catalogue's own controls, so a wrong one finds none and says so
+ * beside the field; the shell reads no type's names.
+ */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
     PROP_KINDS.some((kind) => kind === value["kind"]) &&

package/dist/src/controlCode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a custom control is told of its arg, and the code its values are written as in a story's code: the expression a
+ * control's `toCode` gives (`IconStar` for the name `"IconStar"`), for the Code tab and `forgebook story`. Pure.
+ *
+ * @module
+ */
+import type { ArgControlModule, ControlArgType } from "./argControl.ts";
+import type { PanelProp } from "./argTypes.ts";
+import { type PanelArgs } from "./messages.ts";
+/**
+ * What a control is told of its arg.
+ *
+ * @param prop - the prop, with the story's `argTypes` laid over it.
+ */
+export declare const controlArgTypeOf: (prop: PanelProp) => ControlArgType;
+/** A control's `toCode`, by control: what writes its values as code. */
+export type ControlCoders = Readonly<Record<string, ArgControlModule["toCode"]>>;
+/**
+ * The code each arg of a custom control is written as, by arg: the expression its control's `toCode` gives for its
+ * value. An arg without a value, with the panel's "no value", whose control writes no code, or whose `toCode` throws
+ * or gives nothing, is written from its value as before.
+ *
+ * @param props - the props the panel sets, with the story's `argTypes` laid over them.
+ * @param args - the values the code is written from.
+ * @param coders - each control's `toCode`, by control.
+ */
+export declare const controlCodeOf: (props: readonly PanelProp[], args: PanelArgs, coders: ControlCoders) => Readonly<Record<string, string>>;

package/dist/src/controlCode.js

@@ -0,0 +1,41 @@
+import { isArgValue, isUnsetArg } from "./messages.js";
+/**
+ * What a control is told of its arg.
+ *
+ * @param prop - the prop, with the story's `argTypes` laid over it.
+ */
+export const controlArgTypeOf = (prop) => ({
+    name: prop.name,
+    label: prop.label ?? prop.name,
+    description: prop.description,
+    ...(prop.choices === undefined ? {} : { options: prop.choices }),
+    ...(prop.min === undefined ? {} : { min: prop.min }),
+    ...(prop.max === undefined ? {} : { max: prop.max }),
+    ...(prop.step === undefined ? {} : { step: prop.step }),
+    // the frame's word, read here since only a control needs it: what is no plain data never reaches a control
+    ...(prop.settings === undefined || !isArgValue(prop.settings) ? {} : { settings: prop.settings })
+});
+/**
+ * The code each arg of a custom control is written as, by arg: the expression its control's `toCode` gives for its
+ * value. An arg without a value, with the panel's "no value", whose control writes no code, or whose `toCode` throws
+ * or gives nothing, is written from its value as before.
+ *
+ * @param props - the props the panel sets, with the story's `argTypes` laid over them.
+ * @param args - the values the code is written from.
+ * @param coders - each control's `toCode`, by control.
+ */
+export const controlCodeOf = (props, args, coders) => Object.fromEntries(props.flatMap((prop) => {
+    const control = prop.customControl;
+    const value = Object.hasOwn(args, prop.name) ? args[prop.name] : undefined;
+    const toCode = control !== undefined && Object.hasOwn(coders, control) ? coders[control] : undefined;
+    if (toCode === undefined || value === undefined || isUnsetArg(value))
+        return [];
+    try {
+        const code = toCode(value, controlArgTypeOf(prop));
+        return typeof code === "string" && code !== "" ? [[prop.name, code]] : [];
+    }
+    catch {
+        // the control's code is its own: a failure writes the value as JSON, as a control without `toCode`
+        return [];
+    }
+}));

package/dist/src/frame/controlValues.d.ts

@@ -0,0 +1,39 @@
+import { type PanelArgs } from "../messages.ts";
+import { panelArgTypesOf } from "../storyArgTypes.ts";
+import type { ControlFrameLoaders } from "./panelControls.ts";
+/** What the frame modules made of the values. */
+export type ControlValues = {
+    /** What the story receives, by arg, over what the panel's JSON gives it. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** The args whose value could not be made: the story keeps its own. */
+    readonly dropped: readonly string[];
+    /** The story's own values as the panel shows them, by arg, for those a frame module names. */
+    readonly own: PanelArgs;
+    /** What went wrong, one sentence per failure. */
+    readonly problems: readonly string[];
+};
+/** The story, as the frame modules read it. */
+export type ControlStory = {
+    /** Its own args. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Its `argTypes`: the controls they name, and a control's `settings`. */
+    readonly argTypes: Parameters<typeof panelArgTypesOf>[0];
+    /** Loads its component's docs, which name the controls the catalogue gives props by type; none without docs. */
+    readonly loadDocs?: (() => Promise<unknown>) | undefined;
+};
+/**
+ * The custom control of each arg, as the panel draws it: a control the story's `argTypes` name, else the one the
+ * catalogue gives the prop by type, unless the `argTypes` name another control for it.
+ *
+ * @param argTypes - the story's `argTypes`, as the panel reads them.
+ * @param docs - its component's docs, as the plugin served them.
+ */
+export declare const argControlsOf: (argTypes: ReturnType<typeof panelArgTypesOf>, docs: unknown) => Readonly<Record<string, string>>;
+/**
+ * The values of the controls with a frame module, as the story and the panel take them.
+ *
+ * @param args - the panel's values, checked by the shell.
+ * @param loaders - the frame modules, by control.
+ * @param story - the story's own args, its `argTypes` and its docs.
+ */
+export declare const controlValuesOf: (args: PanelArgs, loaders: ControlFrameLoaders, story: ControlStory) => Promise<ControlValues>;