forgebook 0.4.0 → 0.4.1

package/dist/src/shell/useFrameQueue.d.ts

@@ -1,12 +1,17 @@
 /**
- * Which frames of a page of many stories may load: those near the visible part of the page, a few at a time, so the
- * browser is never asked for thousands of modules at once.
+ * Which frames of a page of many stories may load: those near the visible part of the page, nearest first, a few at a
+ * time, so the browser is never asked for thousands of modules at once.
  *
  * @remarks
  * In development every frame loads its sources' modules one by one (a few hundred requests); twenty frames at once
  * exhaust the browser ("insufficient resources") and stories stay blank. A frame loads once its story is near the
  * visible part of the scrolling page and fewer than `MAX_LOADING` frames are still loading; once loaded it stays.
  *
+ * The reader may be anywhere on the page, so a free place goes to the waiting story nearest the visible part, not to
+ * the first one in the page's order (`frameOrder.ts`); and no frame starts while the page scrolls fast
+ * (`useScrollSettled.ts`), so the stories a scroll flies past never hold a place the stories where it stops need. A
+ * frame already loading finishes wherever the page goes.
+ *
  * @module
  */
 import { type RefObject } from "react";
@@ -21,7 +26,7 @@ export type FrameQueue = {
     readonly observerOf: (storyId: string, place?: number) => (element: HTMLElement | null) => void;
     /** Records a story whose frame finished loading. */
     readonly markReady: (storyId: string) => void;
-    /** Loads every frame of the page, wherever it is, still a few at a time. */
+    /** Loads every frame of the page, wherever it is, still a few at a time and nearest first. */
     readonly loadAll: () => void;
 };
 /**

package/dist/src/shell/useFrameQueue.js

@@ -1,19 +1,44 @@
 /**
- * Which frames of a page of many stories may load: those near the visible part of the page, a few at a time, so the
- * browser is never asked for thousands of modules at once.
+ * Which frames of a page of many stories may load: those near the visible part of the page, nearest first, a few at a
+ * time, so the browser is never asked for thousands of modules at once.
  *
  * @remarks
  * In development every frame loads its sources' modules one by one (a few hundred requests); twenty frames at once
  * exhaust the browser ("insufficient resources") and stories stay blank. A frame loads once its story is near the
  * visible part of the scrolling page and fewer than `MAX_LOADING` frames are still loading; once loaded it stays.
  *
+ * The reader may be anywhere on the page, so a free place goes to the waiting story nearest the visible part, not to
+ * the first one in the page's order (`frameOrder.ts`); and no frame starts while the page scrolls fast
+ * (`useScrollSettled.ts`), so the stories a scroll flies past never hold a place the stories where it stops need. A
+ * frame already loading finishes wherever the page goes.
+ *
  * @module
  */
 import { useCallback, useEffect, useRef, useState } from "react";
+import { distanceFromView, nearestFrames } from "./frameOrder.js";
+import { useScrollSettled } from "./useScrollSettled.js";
 /** The most frames loading at once. */
 const MAX_LOADING = 2;
 /** How far beyond the visible part a story counts as near, as an IntersectionObserver margin. */
 const NEAR_MARGIN = "600px 0px";
+/**
+ * How far each waiting story is from the visible part of the page: its nearest place, for a story shown twice.
+ *
+ * @param waiting - the stories waiting for their frame.
+ * @param elements - the elements that hold the page's frames, with their story.
+ * @param root - the element that scrolls the page; the window when there is none.
+ */
+const distancesOf = (waiting, elements, root) => {
+    const view = root?.getBoundingClientRect() ?? { top: 0, bottom: window.innerHeight };
+    const distances = new Map();
+    for (const [element, storyId] of elements) {
+        if (!waiting.has(storyId))
+            continue;
+        const distance = distanceFromView(element.getBoundingClientRect(), view);
+        distances.set(storyId, Math.min(distance, distances.get(storyId) ?? distance));
+    }
+    return distances;
+};
 /**
  * The queue of a page's frames.
  *
@@ -30,6 +55,7 @@ export const useFrameQueue = (storyIds, root) => {
     const observerRef = useRef(undefined);
     const elements = useRef(new Map());
     const observers = useRef(new Map());
+    const isSettled = useScrollSettled(root);
     useEffect(() => {
         const observer = new IntersectionObserver((entries) => setNear((current) => {
             const next = new Set(current);
@@ -46,17 +72,21 @@ export const useFrameQueue = (storyIds, root) => {
         observerRef.current = observer;
         return () => observer.disconnect();
     }, [root]);
-    // a few more frames whenever a story comes near or a frame finishes loading; a frame the page no longer lists never
-    // finishes, and must not hold a place
+    // a few more frames whenever a story comes near, a frame finishes loading or the page stops flying; a frame the page
+    // no longer lists never finishes, and must not hold a place
     useEffect(() => {
-        setMounted((current) => {
-            const nearIds = new Set([...near].map((element) => elements.current.get(element)));
-            const loading = [...current].filter((id) => storyIds.includes(id) && !ready.has(id)).length;
-            const waiting = storyIds.filter((id) => (isEveryStoryNear || nearIds.has(id)) && !current.has(id));
-            const next = waiting.slice(0, Math.max(0, MAX_LOADING - loading));
-            return next.length === 0 ? current : new Set([...current, ...next]);
-        });
-    }, [storyIds, near, ready, isEveryStoryNear]);
+        if (!isSettled)
+            return;
+        const free = MAX_LOADING - [...mounted].filter((id) => storyIds.includes(id) && !ready.has(id)).length;
+        if (free <= 0)
+            return;
+        const nearIds = new Set([...near].map((element) => elements.current.get(element)));
+        const waiting = storyIds.filter((id) => (isEveryStoryNear || nearIds.has(id)) && !mounted.has(id));
+        if (waiting.length === 0)
+            return;
+        const next = nearestFrames(waiting, distancesOf(new Set(waiting), elements.current, root.current), free);
+        setMounted(new Set([...mounted, ...next]));
+    }, [storyIds, near, ready, isEveryStoryNear, isSettled, mounted, root]);
     const observerOf = useCallback((storyId, place = 0) => {
         const key = `${storyId}\n${place}`;
         const known = observers.current.get(key);

package/dist/src/shell/useScrollSettled.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether a scrolling page has stopped flying past its content, for the frame queue (`useFrameQueue`).
+ *
+ * @remarks
+ * A fast scroll to the end of a long page passes over stories the reader never looks at: a frame started for one of
+ * them takes a loading place from the stories where the scroll stops. The page counts as unsettled while it scrolls
+ * faster than `FAST_SCROLL`, and settles `SETTLE_MS` after its last fast step; a slow scroll, a reader's, stays
+ * settled, so stories keep loading as they come near.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/**
+ * Whether the page is settled: true unless it scrolled fast in the last `SETTLE_MS`.
+ *
+ * @param root - the element that scrolls the page; the hook reads nothing when it is not there.
+ */
+export declare const useScrollSettled: (root: RefObject<HTMLElement | null>) => boolean;

package/dist/src/shell/useScrollSettled.js

@@ -0,0 +1,56 @@
+/**
+ * Whether a scrolling page has stopped flying past its content, for the frame queue (`useFrameQueue`).
+ *
+ * @remarks
+ * A fast scroll to the end of a long page passes over stories the reader never looks at: a frame started for one of
+ * them takes a loading place from the stories where the scroll stops. The page counts as unsettled while it scrolls
+ * faster than `FAST_SCROLL`, and settles `SETTLE_MS` after its last fast step; a slow scroll, a reader's, stays
+ * settled, so stories keep loading as they come near.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+/** The scroll speed above which the page flies past its stories, in CSS px per millisecond: 2000 px a second. */
+const FAST_SCROLL = 2;
+/** How long after its last fast step the page counts as settled, in milliseconds. */
+const SETTLE_MS = 150;
+/**
+ * The longest time read between two scroll events, in milliseconds: a jump after a pause (the End key, a link to a
+ * story further down) counts as fast, not as a long slow step.
+ */
+const LONGEST_STEP_MS = 100;
+/**
+ * Whether the page is settled: true unless it scrolled fast in the last `SETTLE_MS`.
+ *
+ * @param root - the element that scrolls the page; the hook reads nothing when it is not there.
+ */
+export const useScrollSettled = (root) => {
+    const [isSettled, setIsSettled] = useState(true);
+    useEffect(() => {
+        const element = root.current;
+        if (element === null)
+            return undefined;
+        let lastTop = element.scrollTop;
+        let lastTime = performance.now();
+        let timer;
+        const onScroll = () => {
+            const now = performance.now();
+            const step = Math.min(Math.max(now - lastTime, 1), LONGEST_STEP_MS);
+            const speed = Math.abs(element.scrollTop - lastTop) / step;
+            lastTop = element.scrollTop;
+            lastTime = now;
+            if (speed <= FAST_SCROLL)
+                return;
+            setIsSettled(false);
+            clearTimeout(timer);
+            timer = setTimeout(() => setIsSettled(true), SETTLE_MS);
+        };
+        element.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            element.removeEventListener("scroll", onScroll);
+            clearTimeout(timer);
+            setIsSettled(true);
+        };
+    }, [root]);
+    return isSettled;
+};

package/dist/src/shell/valueEditors/ValueField.js

@@ -10,6 +10,7 @@ import { useState } from "react";
 import { isArgList, isArgObject, isDateArg, isNamedArg } from "../../messages.js";
 import { isValueOfShape } from "../../shapeValues.js";
 import { MOST_PLAIN_OPTIONS } from "../PropFields.js";
+import { Switch } from "../Switch.js";
 import { STRINGS } from "../strings.js";
 import { EDITOR_STRINGS } from "./editorStrings.js";
 import { JsonEditor } from "./JsonEditor.js";
@@ -134,7 +135,7 @@ export const ValueField = (props) => {
         case "date":
             return _jsx(DateLeaf, { ...props });
         case "boolean":
-            return (_jsx("input", { type: "checkbox", "aria-label": props.label, "aria-describedby": props.describedBy, checked: shape.only ?? props.value === true, disabled: shape.only !== undefined, onChange: (event) => props.onChange(event.target.checked) }));
+            return (_jsx(Switch, { label: props.label, isOn: shape.only ?? props.value === true, describedBy: props.describedBy, disabled: shape.only !== undefined, onChange: props.onChange }));
         case "choice":
             return _jsx(ChoiceLeaf, { ...props, shape: shape });
         case "named":

package/dist/src/storyCheck.d.ts

@@ -28,6 +28,18 @@ export type StoryProblem = {
     /** What is wrong, as the catalogue's tests say it. */
     readonly message: string;
 };
+/**
+ * Something a check found that does not fail the story: a static file it asks for (an image, a font) that answers 404.
+ * The story still runs and a person sees what is missing, so it is said, not counted.
+ */
+export type StoryWarning = {
+    /** What it is. */
+    readonly kind: "missing-file";
+    /** The file's path, with its query: the same in every run. */
+    readonly path: string;
+    /** What it means, in a sentence. */
+    readonly message: string;
+};
 /** A story to check: its id, and the height its scene declares. */
 export type StoryCheckStory = {
     /** The story's id. */
@@ -91,6 +103,8 @@ export type StoryCheckResult = {
     readonly frame: string;
     /** The problems; none when it passes. */
     readonly problems: readonly StoryProblem[];
+    /** What was found that does not fail it: its missing static files. Absent when there is none. */
+    readonly warnings?: readonly StoryWarning[];
     /**
      * Why the story's checks did not run: its frame gave up waiting for what it loads, or cannot tell (status `pending`),
      * so no check saw the story in its final state. Absent when they ran; present, the story has not passed, whatever

package/dist/src/storyCheck.js

@@ -31,6 +31,19 @@ const isProblem = (value) => typeof value === "object" &&
     KINDS.some((kind) => kind === value.kind) &&
     "message" in value &&
     typeof value.message === "string";
+/**
+ * Whether a value is a warning.
+ *
+ * @param value - the value.
+ */
+const isWarning = (value) => typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "missing-file" &&
+    "path" in value &&
+    typeof value.path === "string" &&
+    "message" in value &&
+    typeof value.message === "string";
 /**
  * Whether a value is a result.
  *
@@ -47,6 +60,9 @@ const isResult = (value) => typeof value === "object" &&
     "problems" in value &&
     Array.isArray(value.problems) &&
     value.problems.every(isProblem) &&
+    (!("warnings" in value) ||
+        value.warnings === undefined ||
+        (Array.isArray(value.warnings) && value.warnings.every(isWarning))) &&
     (!("notVerified" in value) || value.notVerified === undefined || typeof value.notVerified === "string") &&
     (!("isNotAwaited" in value) || value.isNotAwaited === undefined || typeof value.isNotAwaited === "boolean");
 /**

package/dist/src/storyCodeText.d.ts

@@ -24,6 +24,11 @@ export type StoryCodeSource = {
     readonly args: PanelArgs;
     /** The args the panel or an agent set, written from their values; none by default. */
     readonly edited?: readonly string[];
+    /**
+     * The code a custom control writes some values as, by arg (`controlCode.ts`): used where the file writes no code of
+     * its own for the arg, or the arg was set; none by default.
+     */
+    readonly argCode?: Readonly<Record<string, string>>;
 };
 /**
  * The story's render as written, when it has one.
@@ -32,11 +37,12 @@ export type StoryCodeSource = {
  */
 export declare const renderCodeOf: ({ code, exportName }: StoryCodeSource) => StoryCode | undefined;
 /**
- * The args the story's file writes as code, but those the panel or an agent set.
+ * The args written as code: those the story's file writes, but those the panel or an agent set, over those a control
+ * writes.
  *
  * @param source - the file's code, the story and what was set.
  */
-export declare const writtenArgsOf: ({ code, exportName, edited }: StoryCodeSource) => Readonly<Record<string, string>>;
+export declare const writtenArgsOf: ({ code, exportName, edited, argCode }: StoryCodeSource) => Readonly<Record<string, string>>;
 /**
  * The story's code as text, as copied.
  *

package/dist/src/storyCodeText.js

@@ -8,15 +8,18 @@ export const renderCodeOf = ({ code, exportName }) => {
     return entry !== undefined && "text" in entry ? entry : undefined;
 };
 /**
- * The args the story's file writes as code, but those the panel or an agent set.
+ * The args written as code: those the story's file writes, but those the panel or an agent set, over those a control
+ * writes.
  *
  * @param source - the file's code, the story and what was set.
  */
-export const writtenArgsOf = ({ code, exportName, edited = [] }) => {
+export const writtenArgsOf = ({ code, exportName, edited = [], argCode = {} }) => {
     const entry = code[exportName];
-    if (entry === undefined || !("args" in entry))
-        return {};
-    return Object.fromEntries(Object.entries(entry.args).filter(([name]) => !edited.includes(name)));
+    const own = entry === undefined || !("args" in entry) ? {} : entry.args;
+    return {
+        ...argCode,
+        ...Object.fromEntries(Object.entries(own).filter(([name]) => !edited.includes(name)))
+    };
 };
 /**
  * The story's code as text, as copied.

package/dist/src/storyControls.d.ts

@@ -10,6 +10,7 @@ import { type AddressTexts } from "./addressTexts.ts";
 import type { ValueSchema } from "./argControl.ts";
 import { type PanelArgTypes, type PanelControl, type TokenRequest } from "./argTypes.ts";
 import type { PropDocs } from "./componentDocs.ts";
+import type { ControlCoders } from "./controlCode.ts";
 import { type ArgValue, type PanelArgs } from "./messages.ts";
 import type { NamedValues } from "./namedValues.ts";
 import { type ValueShape } from "./valueShape.ts";
@@ -88,6 +89,8 @@ export declare const checkedSetArgs: (text: string, declaration: StoryDeclaratio
 export type CustomControlsRead = {
     /** The schemas, by control. */
     readonly schemas: CustomSchemas;
+    /** What writes each control's values as code, by control, those whose module could be read. */
+    readonly coders: ControlCoders;
     /** Why a control could not be read, by control. */
     readonly problems: Readonly<Record<string, string>>;
 };

package/dist/src/vite/agent.types.d.ts

@@ -16,7 +16,7 @@ import type { LiveError } from "../liveErrors.ts";
 import type { PluginCondition } from "../plugin.ts";
 import type { SearchHitKind, SearchReason, SearchResult } from "../search.ts";
 import type { SearchCorrection } from "../searchTypos.ts";
-import type { StoryCheckResult, StoryDiffStatus } from "../storyCheck.ts";
+import type { StoryCheckResult, StoryDiffStatus, StoryWarning } from "../storyCheck.ts";
 import type { SetArgs, StoryControl } from "../storyControls.ts";
 import type { SwitchControlKind, SwitchPreview, SwitchRole } from "../switches.ts";
 import type { CodeAdvice, CodeProblem, CodeRule, ExcusedValue } from "./checkCode.ts";
@@ -469,6 +469,11 @@ export type VerifyFailure = {
     /** The links that open the story; those of a server started for the run would be dead by now. */
     readonly links?: StoryLinks;
 };
+/** A static file the change's stories asked for that is not there: said, never counted against the change. */
+export type VerifyWarning = StoryWarning & {
+    /** The stories that asked for it, each once. */
+    readonly stories: readonly string[];
+};
 /** The one answer to whether a change is verified. */
 export type VerifyDocument = {
     /** The shape's version: this shape is not the first `verify` answered. */
@@ -499,6 +504,8 @@ export type VerifyDocument = {
     readonly failures: readonly VerifyFailure[];
     /** The pairs no check saw in their final state: their frame gave up on what the story loads. None of them passed. */
     readonly notVerified: readonly VerifyNotVerified[];
+    /** What the stories found that does not fail the change, one per file: static files that answer 404. */
+    readonly warnings: readonly VerifyWarning[];
     /** What the change adds, by `check-code`. */
     readonly code: {
         /** What was checked. */

package/dist/src/vite/agentRoutes.js

@@ -1,5 +1,6 @@
 import { createIdResolver } from "vite";
 import { offersUsedIn, readsComponentDocs } from "../catalogue.js";
+import { isComponentDocs } from "../componentDocs.js";
 import { mergedPreviews, NO_PREVIEW, readPreview } from "../frame/storyModule.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { catalogueStatuses } from "../storyStatuses.js";
@@ -165,15 +166,16 @@ export const storyAnswer = async (context) => {
     // the story's own file: its module, and the docs of the component its meta names, which its args are for
     const file = location.story.file;
     const storyModule = await settled(files.stories[file]);
+    const docs = await settled(files.docs[file]);
     const parts = {
         module: storyModule,
-        docs: await settled(files.docs[file]),
+        docs,
         preview: loaded.preview,
         namedValues: source.namedValues,
         setArgs: params.get("args") ?? undefined,
         customControls: context.server === undefined
             ? undefined
-            : await customControlsRead(customControlNames(storyModule, location), config, context.server),
+            : await customControlsRead([...customControlNames(storyModule, location), ...typedControlNames(docs)], config, context.server),
         addressTexts: config.framework.addressTexts
     };
     const code = context.server === undefined
@@ -181,7 +183,8 @@ export const storyAnswer = async (context) => {
         : {
             code: await settled(files.code[file]),
             writer: await codeWriterOf(config, context.server),
-            namedValues: source.namedValues
+            namedValues: source.namedValues,
+            coders: parts.customControls?.coders ?? {}
         };
     const index = offersUsedIn(config.lists) ? await sourceUsage(source) : undefined;
     // a usage that cannot be read leaves "Used in" out, never the story
@@ -219,18 +222,39 @@ const codeWriterOf = async (config, server) => {
         return undefined;
     }
 };
+/**
+ * The controls the catalogue gives a story's props by type or name, as its component's docs say: their modules load for
+ * the story's document too.
+ *
+ * @param docs - the docs, as the dev server loaded them.
+ */
+const typedControlNames = (docs) => "value" in docs && isComponentDocs(docs.value)
+    ? docs.value.props.flatMap((prop) => prop.customControl ?? [])
+    : [];
 /** How long a control's module may take to load for an answer: one that hangs must not hold every answer with it. */
 const CONTROL_LOAD_MS = 5000;
-/** A control's schema, loaded on the server; a text says why there is none. */
-const controlSchemaOf = async (module, server) => {
+/** A control's module as the server reads it: its schema and what writes its values as code; a text says why not. */
+const controlReadOf = async (module, server) => {
     try {
         const id = await server.resolveSource(module);
         const timeout = new Promise((_resolve, reject) => {
             setTimeout(() => reject(new Error(`no answer in ${CONTROL_LOAD_MS} ms`)), CONTROL_LOAD_MS).unref();
         });
         const loaded = await Promise.race([server.load(id ?? module), timeout]);
-        const schema = typeof loaded === "object" && loaded !== null && "schema" in loaded ? loaded.schema : undefined;
-        return isValueSchema(schema) ? schema : "its module exports no schema Forgebook can read";
+        const isModule = typeof loaded === "object" && loaded !== null;
+        const schema = isModule && "schema" in loaded ? loaded.schema : undefined;
+        const toCode = isModule && "toCode" in loaded ? loaded.toCode : undefined;
+        if (!isValueSchema(schema))
+            return "its module exports no schema Forgebook can read";
+        return {
+            schema,
+            toCode: typeof toCode === "function"
+                ? (value, argType) => {
+                    const code = toCode(value, argType);
+                    return typeof code === "string" ? code : undefined;
+                }
+                : undefined
+        };
     }
     catch (error) {
         return `its module cannot be read on the server: ${error instanceof Error ? error.message : String(error)}`;
@@ -246,10 +270,14 @@ const controlSchemaOf = async (module, server) => {
  * @param server - what the answers ask of the dev server.
  */
 const customControlsRead = async (names, config, server) => {
-    const known = names.filter((name) => Object.hasOwn(config.argControls, name));
-    const read = await Promise.all(known.map(async (name) => [name, await controlSchemaOf(config.argControls[name] ?? "", server)]));
+    const known = names.flatMap((name) => {
+        const control = Object.hasOwn(config.argControls, name) ? config.argControls[name] : undefined;
+        return control === undefined ? [] : [[name, control.module]];
+    });
+    const read = await Promise.all(known.map(async ([name, module]) => [name, await controlReadOf(module, server)]));
     return {
-        schemas: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [] : [[name, each]]))),
+        schemas: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [] : [[name, each.schema]]))),
+        coders: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [] : [[name, each.toCode]]))),
         problems: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [[name, each]] : [])))
     };
 };

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

@@ -1,4 +1,5 @@
 import { type ComponentDocs } from "../componentDocs.ts";
+import { type ControlCoders } from "../controlCode.ts";
 import type { StoryCodeWriter } from "../frame/renderer.ts";
 import { type LoadedPreview } from "../frame/storyModule.ts";
 import type { ArgValue } from "../messages.ts";
@@ -17,6 +18,8 @@ export type AgentCodeParts = {
     readonly writer: StoryCodeWriter | undefined;
     /** The source's named values, as the frame writes them by name. */
     readonly namedValues: NamedValues | undefined;
+    /** What writes each custom control's values as code, by control; none writes them as JSON. */
+    readonly coders?: ControlCoders;
 };
 /** The story the code is of, as the story's answer read it. */
 export type AgentCodeStory = {

package/dist/src/vite/agentStoryCode.js

@@ -1,6 +1,9 @@
+import { panelProps } from "../argTypes.js";
 import { codeNameOf } from "../componentDocs.js";
+import { controlCodeOf } from "../controlCode.js";
 import { panelArgsOf } from "../frame/panelValues.js";
 import { readStory } from "../frame/storyModule.js";
+import { panelArgTypesOf } from "../storyArgTypes.js";
 import { storyCodeText } from "../storyCodeText.js";
 /** Whether a module's answer is a story file's code, by export name. */
 const isStoryFileCode = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !("error" in value);
@@ -15,12 +18,15 @@ export const agentStoryCode = (parts, { location, module, preview, accepted = {}
     const value = "value" in parts.code ? parts.code.value : undefined;
     if (typeof loaded === "string" || !isStoryFileCode(value) || parts.writer === undefined)
         return undefined;
+    const args = { ...panelArgsOf(loaded.args, parts.namedValues), ...accepted };
+    const props = panelProps(docs?.props ?? [], panelArgTypesOf(loaded.argTypes, []), args);
     return storyCodeText({
         code: value,
         exportName: location.story.exportName,
         componentName: docs === undefined ? location.component.name : codeNameOf(docs),
-        args: { ...panelArgsOf(loaded.args, parts.namedValues), ...accepted },
-        edited: Object.keys(accepted)
+        args,
+        edited: Object.keys(accepted),
+        argCode: controlCodeOf(props, args, parts.coders ?? {})
     }, parts.writer);
 };
 /**

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

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