forgebook 0.3.3 → 0.4.1

package/dist/src/storyArgTypes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A story's `argTypes` as its module writes them (Storybook's): read in the frame into the form that crosses to the shell
+ * (`argTypes.ts`), and their `mapping` applied to the args the story receives. The commands read them the same way.
+ *
+ * @remarks
+ * Option values that cannot cross (a component, a function) are sent as their `mapping` keys, which the frame turns back
+ * into the values. Pure.
+ *
+ * @module
+ */
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+import type { PanelArgTypes, PanelControl } from "./argTypes.ts";
+/** Storybook's control names, as the panel draws them (the inline variants look the same here). */
+export declare const CONTROLS: Readonly<Record<string, PanelControl>>;
+/**
+ * The `argTypes` of the meta and the story, merged: each arg's entry from both, the story's fields over the meta's.
+ *
+ * @param meta - the meta's `argTypes`.
+ * @param story - the story's `argTypes`.
+ */
+export declare const mergedArgTypes: (meta: unknown, story: unknown) => Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * The arg types the frame sends: each entry read, and the args `parameters.controls.exclude` names hidden.
+ *
+ * @param argTypes - the merged `argTypes`.
+ * @param excluded - the args `parameters.controls.exclude` names.
+ */
+export declare const panelArgTypesOf: (argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>, excluded: readonly string[]) => PanelArgTypes;
+/**
+ * The args with each `mapping` applied: an arg whose value is a key of its entry's `mapping` receives the value the
+ * key stands for, as Storybook's (an arg written as the key in the story, or chosen in the panel).
+ *
+ * @param args - the args.
+ * @param argTypes - the merged `argTypes`.
+ */
+export declare const mappedArgs: (args: Readonly<Record<string, unknown>>, argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => Readonly<Record<string, unknown>>;
+/**
+ * The props the panel can set, as the story's parameters say: `false` none, a list or `{ include }` those, anything
+ * else every one.
+ *
+ * @param value - `parameters.controls`.
+ */
+export declare const controlsOfParameter: (value: unknown) => StoryControlsSetting;
+/**
+ * The args `parameters.controls.exclude` hides.
+ *
+ * @param value - `parameters.controls`.
+ */
+export declare const excludedControls: (value: unknown) => readonly string[];
+/**
+ * The args whose calls the Events tab records as actions: those whose value is a spy, and those whose `argTypes`
+ * entry names an `action`. Explicit only: no arg is recorded for its name alone.
+ *
+ * @param args - the story's args.
+ * @param argTypes - the merged `argTypes`.
+ */
+export declare const actionNames: (args: Readonly<Record<string, unknown>>, argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => readonly string[];

package/dist/src/storyArgTypes.js

@@ -0,0 +1,195 @@
+import { argConditionOf } from "./argConditions.js";
+import { isArgValue } from "./messages.js";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Storybook's control names, as the panel draws them (the inline variants look the same here). */
+export const CONTROLS = {
+    select: "select",
+    radio: "radio",
+    "inline-radio": "radio",
+    check: "check",
+    "inline-check": "check",
+    "multi-select": "multi-select",
+    boolean: "boolean",
+    text: "text",
+    number: "number",
+    range: "range",
+    color: "color",
+    date: "date",
+    object: "object",
+    file: "file",
+    textarea: "textarea",
+    token: "token"
+};
+/** A number field of an object, when it is a finite number. */
+const numberOf = (part, name) => {
+    const value = part[name];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+};
+/** The labels of a control, when every one is a text. */
+const labelsOf = (value) => isRecord(value) && Object.values(value).every((label) => typeof label === "string")
+    ? Object.fromEntries(Object.entries(value).map(([option, label]) => [option, String(label)]))
+    : undefined;
+/**
+ * The control an entry names: `false` and a disabled control are none, a name or `{ type }` is that control, and
+ * options without a control make a select.
+ */
+const controlOf = (entry) => {
+    const control = entry["control"];
+    if (control === false)
+        return "none";
+    if (typeof control === "string")
+        return Object.hasOwn(CONTROLS, control) ? CONTROLS[control] : undefined;
+    if (isRecord(control)) {
+        if (control["disable"] === true)
+            return "none";
+        const type = control["type"];
+        if (typeof type === "string")
+            return Object.hasOwn(CONTROLS, type) ? CONTROLS[type] : undefined;
+    }
+    return Array.isArray(entry["options"]) ? "select" : undefined;
+};
+/**
+ * The options as they cross: texts and numbers as they are; any other value only through `mapping`, whose keys are
+ * the options then.
+ */
+const optionsOf = (entry) => {
+    const options = entry["options"];
+    if (!Array.isArray(options))
+        return undefined;
+    return options.filter((option) => typeof option === "string" || typeof option === "number");
+};
+/** A name among the controls an entry writes that is none of the panel's: a custom control's. */
+const customControlOf = (control) => {
+    if (isRecord(control) && control["disable"] === true)
+        return undefined;
+    const name = isRecord(control) ? control["type"] : control;
+    return typeof name === "string" && !Object.hasOwn(CONTROLS, name) ? name : undefined;
+};
+/** What a `token`, a `file` and a custom control say of themselves. */
+const editorSettingsOf = (settings) => {
+    const { of, format, accept } = settings;
+    const own = settings["settings"];
+    return {
+        ...(own !== undefined && isArgValue(own) ? { settings: own } : {}),
+        ...(typeof of === "string" ? { tokens: { of, ...(typeof format === "string" ? { format } : {}) } } : {}),
+        ...(typeof accept === "string" ? { accept } : {})
+    };
+};
+/**
+ * One entry as the panel reads it.
+ *
+ * @param entry - the `argTypes` entry, the story's laid over the meta's.
+ * @param isExcluded - whether `parameters.controls.exclude` names the arg.
+ */
+const panelArgTypeOf = (entry, isExcluded) => {
+    const control = controlOf(entry);
+    const options = optionsOf(entry);
+    const settings = isRecord(entry["control"]) ? entry["control"] : {};
+    const table = entry["table"];
+    const name = entry["name"];
+    const description = entry["description"];
+    const labels = labelsOf(settings["labels"]);
+    const min = numberOf(settings, "min");
+    const max = numberOf(settings, "max");
+    const step = numberOf(settings, "step");
+    const condition = argConditionOf(entry["if"]);
+    const customControl = customControlOf(entry["control"]);
+    return {
+        isHidden: isExcluded || (isRecord(table) && table["disable"] === true),
+        ...(typeof name === "string" ? { label: name } : {}),
+        ...(typeof description === "string" ? { description } : {}),
+        ...(control === undefined ? {} : { control }),
+        ...(options === undefined ? {} : { options }),
+        ...(labels === undefined ? {} : { labels }),
+        ...(min === undefined ? {} : { min }),
+        ...(max === undefined ? {} : { max }),
+        ...(step === undefined ? {} : { step }),
+        ...(condition === undefined ? {} : { if: condition }),
+        ...editorSettingsOf(settings),
+        ...(customControl === undefined ? {} : { customControl })
+    };
+};
+/**
+ * The `argTypes` of the meta and the story, merged: each arg's entry from both, the story's fields over the meta's.
+ *
+ * @param meta - the meta's `argTypes`.
+ * @param story - the story's `argTypes`.
+ */
+export const mergedArgTypes = (meta, story) => {
+    const merged = {};
+    for (const part of [meta, story]) {
+        if (!isRecord(part))
+            continue;
+        for (const [name, entry] of Object.entries(part)) {
+            if (isRecord(entry))
+                merged[name] = { ...merged[name], ...entry };
+        }
+    }
+    return merged;
+};
+/**
+ * The arg types the frame sends: each entry read, and the args `parameters.controls.exclude` names hidden.
+ *
+ * @param argTypes - the merged `argTypes`.
+ * @param excluded - the args `parameters.controls.exclude` names.
+ */
+export const panelArgTypesOf = (argTypes, excluded) => {
+    const names = [...new Set([...Object.keys(argTypes), ...excluded])];
+    return Object.fromEntries(names.map((name) => [name, panelArgTypeOf(argTypes[name] ?? {}, excluded.includes(name))]));
+};
+/**
+ * The args with each `mapping` applied: an arg whose value is a key of its entry's `mapping` receives the value the
+ * key stands for, as Storybook's (an arg written as the key in the story, or chosen in the panel).
+ *
+ * @param args - the args.
+ * @param argTypes - the merged `argTypes`.
+ */
+export const mappedArgs = (args, argTypes) => Object.fromEntries(Object.entries(args).map(([name, value]) => {
+    const mapping = argTypes[name]?.["mapping"];
+    if (!isRecord(mapping) || (typeof value !== "string" && typeof value !== "number"))
+        return [name, value];
+    const key = String(value);
+    // the mapping's own keys only: a value a shared link chose (`constructor`) never reaches its prototype
+    return [name, Object.hasOwn(mapping, key) ? mapping[key] : value];
+}));
+/**
+ * The props the panel can set, as the story's parameters say: `false` none, a list or `{ include }` those, anything
+ * else every one.
+ *
+ * @param value - `parameters.controls`.
+ */
+export const controlsOfParameter = (value) => {
+    if (value === false)
+        return [];
+    if (Array.isArray(value) && value.every((name) => typeof name === "string"))
+        return value;
+    const include = isRecord(value) ? value["include"] : undefined;
+    if (Array.isArray(include) && include.every((name) => typeof name === "string"))
+        return include;
+    return "all";
+};
+/**
+ * The args `parameters.controls.exclude` hides.
+ *
+ * @param value - `parameters.controls`.
+ */
+export const excludedControls = (value) => {
+    const exclude = isRecord(value) ? value["exclude"] : undefined;
+    return Array.isArray(exclude) ? exclude.filter((name) => typeof name === "string") : [];
+};
+/** Whether a value is a spy (`fn()` of `storybook/test` or Vitest): a function with its calls under `mock`. */
+const isSpy = (value) => typeof value === "function" && "mock" in value;
+/**
+ * The args whose calls the Events tab records as actions: those whose value is a spy, and those whose `argTypes`
+ * entry names an `action`. Explicit only: no arg is recorded for its name alone.
+ *
+ * @param args - the story's args.
+ * @param argTypes - the merged `argTypes`.
+ */
+export const actionNames = (args, argTypes) => [
+    ...new Set([
+        ...Object.entries(args).flatMap(([name, value]) => (isSpy(value) ? [name] : [])),
+        ...Object.entries(argTypes).flatMap(([name, entry]) => typeof entry["action"] === "string" || entry["action"] === true ? [name] : [])
+    ])
+];

package/dist/src/storyBackground.js

@@ -1,4 +1,5 @@
 import { backdropColor } from "./backdrops.js";
+import { shownSwitches } from "./switches.js";
 import { isMoreContrastOf, schemeOf } from "./viewState.js";
 /**
  * A source's page colour for a view, or the colour of the view's backdrop.
@@ -20,7 +21,17 @@ export const storyBackground = (background, view, catalogue, isSystemDark) => {
         return backdrop;
     if (background === undefined)
         return undefined;
-    if (isDark)
-        return isMoreContrast ? (background.darkMore ?? background.dark) : background.dark;
-    return isMoreContrast ? (background.lightMore ?? background.light) : background.light;
+    const colourIn = (colours) => {
+        if (isDark)
+            return (isMoreContrast ? colours?.darkMore : undefined) ?? colours?.dark;
+        return (isMoreContrast ? colours?.lightMore : undefined) ?? colours?.light;
+    };
+    const values = shownSwitches(view.switches, switches);
+    // the first switch whose value gives this scheme's colour: a value that gives only `dark` leaves `light` to the next
+    for (const each of switches) {
+        const colour = colourIn(background.bySwitch?.[each.id]?.[values[each.id] ?? each.default]);
+        if (colour !== undefined)
+            return colour;
+    }
+    return colourIn(background);
 };

package/dist/src/storyCheck.d.ts

@@ -8,7 +8,8 @@
  * when it runs (the core has no browser), and reads the report back through `isStoryCheckReport`, since it crossed a
  * dynamic import. The problems are those the catalogue's browser tests fail on, with the same messages: a frame that
  * could not show its story, axe's rules, spills, overlays past the frame, and the page's errors (a failed play among
- * them: its rejection reaches the page). Pure.
+ * them: its rejection reaches the page). A story its frame gave up on is neither passed nor failed: `notVerified` says
+ * so. Pure.
  *
  * @module
  */
@@ -27,10 +28,24 @@ 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. */
     readonly id: string;
+    /** Its file, as the catalogue lists it: what a report names when the story cannot be shown. */
+    readonly file?: string;
     /**
      * The id an earlier rule gave it, when it differs from `id`: a baseline stored under that id is still its baseline
      * until `forgebook shot --update` stores one under its id.
@@ -57,6 +72,8 @@ export type StoryCheckRequest = {
     readonly views: readonly string[];
     /** Check every variant the catalogue's browser tests check instead of the views given. */
     readonly isAllVariants: boolean;
+    /** How many pages to open at once; one by default. */
+    readonly concurrency?: number;
     /** The model that judges what axe cannot see; none leaves the pages on this machine. */
     readonly semantic?: SemanticModel;
 };
@@ -86,6 +103,21 @@ 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
+     * `problems` holds.
+     */
+    readonly notVerified?: string;
+    /** Whether the story drew nothing a reader could see: no text, and no element with a size. Absent otherwise. */
+    readonly isBlank?: boolean;
+    /**
+     * Whether the frame did not wait for what the story loads, as it asks (`parameters.suspense.expected`): the checks read
+     * it as it first drew. Absent otherwise.
+     */
+    readonly isNotAwaited?: boolean;
     /** What the model judged, when one was asked; a text says why it could not. */
     readonly judgements?: readonly StoryJudgement[] | string;
 };
@@ -98,6 +130,67 @@ export type StoryCheckReport = {
     /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no result ran axe. Absent when it does. */
     readonly a11y?: "off";
 };
+/** One case of a stress run: the values given, the window, the view, and what it found that the plain story does not. */
+export type StressCase = {
+    /** Its name: `long-text`, `unbreakable`, `huge-number`, `empty`, `rtl`, `zoom-200`, `narrow`, `dark`, `contrast`. */
+    readonly name: string;
+    /** The story's id. */
+    readonly storyId: string;
+    /** The values given over the story's own, by prop. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The frame, in its view. */
+    readonly frame: string;
+    /** The problems the plain story does not have; none when it holds. */
+    readonly problems: readonly StoryProblem[];
+    /** Why it could not be judged: the story did not draw in it, or not in the plain case. */
+    readonly notVerified?: string;
+};
+/** One case to run, as the command builds it from the story's props and the catalogue's switches. */
+export type StressCaseRequest = {
+    /** Its name. */
+    readonly name: string;
+    /** The values to give, as the props panel gives them. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The view, in the address's form (`theme=dark`); empty for the default. */
+    readonly view: string;
+    /** The window's width, in CSS px; the default window's when none. */
+    readonly width?: number;
+    /** Whether the frame's document reads right to left. */
+    readonly isRtl?: boolean;
+    /** The axe rules whose finding the case's own values cause, which say nothing of the component. */
+    readonly expectedRules?: readonly string[];
+};
+/** What a stress run is asked. */
+export type StressRequest = {
+    /** The catalogue's frame page, absolute. */
+    readonly frameUrl: string;
+    /** The stories, each with its cases. */
+    readonly stories: readonly {
+        readonly story: StoryCheckStory;
+        readonly cases: readonly StressCaseRequest[];
+    }[];
+    /** The catalogue's switches. */
+    readonly switches: readonly ViewSwitch[];
+    /** The catalogue's lists: its accessibility rules. */
+    readonly lists: CatalogueLists;
+};
+/** What a stress run found. */
+export type StressReport = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** One result per story and case. */
+    readonly cases: readonly StressCase[];
+    /** The cases not run, each with its story and why: a case with nothing to set is never counted as passed. */
+    readonly skipped: readonly string[];
+    /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no case ran axe. Absent when it does. */
+    readonly a11y?: "off";
+};
+/**
+ * Whether what the testing package answered is a stress run's report.
+ *
+ * @param value - the answer.
+ */
+export declare const isStressReport: (value: unknown) => value is StressReport;
 /**
  * Whether what the testing package answered is a check's report.
  *
@@ -119,8 +212,11 @@ export type StoryShot = {
     readonly frame: string;
     /** The picture, a PNG file's absolute path. */
     readonly file: string;
-    /** Why the story did not draw (`error`, or `silent` when it never said); none when it did. */
-    readonly status?: "error" | "silent";
+    /**
+     * Why the picture is not of the story as drawn (`error`; `silent` when it never said; `pending` when the frame gave up
+     * on what it loads, so this may picture a fallback); none when it is.
+     */
+    readonly status?: "error" | "silent" | "pending";
 };
 /** The pictures taken. */
 export type StoryShotReport = {

package/dist/src/storyCheck.js

@@ -1,3 +1,23 @@
+/**
+ * Whether what the testing package answered is a stress run's report.
+ *
+ * @param value - the answer.
+ */
+export const isStressReport = (value) => typeof value === "object" &&
+    value !== null &&
+    "schema" in value &&
+    value.schema === 1 &&
+    "cases" in value &&
+    Array.isArray(value.cases) &&
+    value.cases.every((each) => typeof each === "object" &&
+        each !== null &&
+        "name" in each &&
+        typeof each.name === "string" &&
+        "storyId" in each &&
+        typeof each.storyId === "string" &&
+        "problems" in each &&
+        Array.isArray(each.problems) &&
+        each.problems.every(isProblem));
 /** Every kind, for reading a report back. */
 const KINDS = ["frame", "axe", "spill", "overlay", "focus", "error"];
 /**
@@ -11,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.
  *
@@ -26,7 +59,12 @@ const isResult = (value) => typeof value === "object" &&
     typeof value.frame === "string" &&
     "problems" in value &&
     Array.isArray(value.problems) &&
-    value.problems.every(isProblem);
+    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");
 /**
  * Whether what the testing package answered is a check's report.
  *

package/dist/src/storyCodeText.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A story's code as text, as the shell shows and copies it and as `forgebook story` gives it to an agent: its `render`
+ * as written, or, for a story drawn from its args, the component in the framework's code with the args its file writes
+ * as code (functions, elements) as written and the values of the moment for the rest.
+ *
+ * @remarks
+ * An arg the panel or an agent set is written from its value, not from the file's text, which no longer says what the
+ * story draws. Pure: the shell and the dev server read the same text.
+ *
+ * @module
+ */
+import type { StoryCode, StoryFileCode } from "@forgebook/story-format/source";
+import type { StoryCodeWriter } from "./frame/renderer.ts";
+import type { PanelArgs } from "./messages.ts";
+/** Which story's code, and the values its code is drawn from when it has no `render`. */
+export type StoryCodeSource = {
+    /** The story file's code. */
+    readonly code: StoryFileCode;
+    /** The story's export name. */
+    readonly exportName: string;
+    /** The component's name as code writes it (`codeNameOf`), for the code of a story drawn from its args. */
+    readonly componentName: string;
+    /** The values of the moment: the story's args, with the panel's over them on the story page. */
+    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.
+ *
+ * @param source - the file's code and the story.
+ */
+export declare const renderCodeOf: ({ code, exportName }: StoryCodeSource) => StoryCode | undefined;
+/**
+ * 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, argCode }: StoryCodeSource) => Readonly<Record<string, string>>;
+/**
+ * The story's code as text, as copied.
+ *
+ * @param source - the file's code, the story, the component's name and the args.
+ * @param write - the framework's code writer, for a story drawn from its args.
+ */
+export declare const storyCodeText: (source: StoryCodeSource, write: StoryCodeWriter) => string;

package/dist/src/storyCodeText.js

@@ -0,0 +1,30 @@
+/**
+ * The story's render as written, when it has one.
+ *
+ * @param source - the file's code and the story.
+ */
+export const renderCodeOf = ({ code, exportName }) => {
+    const entry = code[exportName];
+    return entry !== undefined && "text" in entry ? entry : undefined;
+};
+/**
+ * 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 = [], argCode = {} }) => {
+    const entry = code[exportName];
+    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.
+ *
+ * @param source - the file's code, the story, the component's name and the args.
+ * @param write - the framework's code writer, for a story drawn from its args.
+ */
+export const storyCodeText = (source, write) => renderCodeOf(source)?.text ?? write(source.componentName, source.args, writtenArgsOf(source));

package/dist/src/storyControls.d.ts

@@ -0,0 +1,103 @@
+/**
+ * What a story's controls are, for whoever sets its values without the panel: each prop's control and what its value
+ * looks like, as an agent reads them, and the values an agent asks to set, checked as a link's are. Pure.
+ *
+ * @module
+ */
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+import { type DroppedArg } from "./addressArgs.ts";
+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";
+/** How a value of a prop is set: the panel's control, or a choice among the source's named values. */
+export type ControlKind = Exclude<PanelControl, "none"> | "named" | "custom";
+/** One prop a story's values can set. */
+export type StoryControl = {
+    /** The prop's name: the key in `args`. */
+    readonly name: string;
+    /** Its control, which says what its value is. */
+    readonly control: ControlKind;
+    /** Its type, as the source writes it. */
+    readonly type: string;
+    /** Whether the prop must be passed. */
+    readonly isRequired: boolean;
+    /** What its value looks like, for a value of more than one part. */
+    readonly shape?: ValueShape;
+    /** A choice's values. */
+    readonly choices?: readonly (string | number)[];
+    /** A number's lowest value. */
+    readonly min?: number;
+    /** A number's highest value. */
+    readonly max?: number;
+    /** The names a `named` control takes, as `{ of: type, named: name }`. */
+    readonly named?: readonly string[];
+    /** A `custom` control's name, of those `argControls` registers. */
+    readonly custom?: string;
+    /** A `custom` control's `settings`, as the story writes them. */
+    readonly settings?: ArgValue;
+    /** A `custom` control's schema: what its value must fit. Left out when its module cannot be read. */
+    readonly schema?: ValueSchema;
+    /** A `token` control's tokens, and what the story receives for one (`forgebook tokens` lists them). */
+    readonly tokens?: TokenRequest;
+};
+/** The custom controls' schemas, by name. */
+export type CustomSchemas = Readonly<Record<string, ValueSchema>>;
+/** What a story declares of its args, as the server reads it from the story's module. */
+export type StoryDeclaration = {
+    /** The props its component's types give. */
+    readonly props: readonly PropDocs[];
+    /** Its `argTypes`, as the panel reads them. */
+    readonly argTypes: PanelArgTypes;
+    /** The props the story lets the panel set. */
+    readonly controls: StoryControlsSetting;
+    /** The story's own args, as the panel reads them. */
+    readonly storyArgs: PanelArgs;
+    /** The source's named values. */
+    readonly namedValues: NamedValues;
+    /** The custom controls' schemas, by name, those whose module could be read. */
+    readonly customSchemas?: CustomSchemas;
+};
+/**
+ * The props a story's values can set.
+ *
+ * @param declaration - what the story declares.
+ */
+export declare const storyControlsOf: (declaration: StoryDeclaration) => readonly StoryControl[];
+/** What became of the values asked for. */
+export type SetArgs = {
+    /** The values the story takes, by prop; the links carry them. */
+    readonly accepted: Readonly<Record<string, ArgValue>>;
+    /** The values left out, with the reason. */
+    readonly dropped: readonly DroppedArg[];
+    /** `args=` as the links write it; empty when none is taken. */
+    readonly param: string;
+};
+/**
+ * The values an agent asks to set, checked as a link's are.
+ *
+ * @param text - the values, as JSON.
+ * @param declaration - what the story declares.
+ * @param addressTexts - how the framework's stories take a link's texts; `any` by default.
+ */
+export declare const checkedSetArgs: (text: string, declaration: StoryDeclaration, addressTexts?: AddressTexts) => SetArgs;
+/** The custom controls as the server read them. */
+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>>;
+};
+/**
+ * What is wrong with the custom controls a story names: one no configuration registers, or whose module did not load.
+ *
+ * @param controls - the story's controls.
+ * @param read - the custom controls as the server read them.
+ */
+export declare const customControlProblems: (controls: readonly StoryControl[], read: CustomControlsRead | undefined) => readonly string[];