@valancex/common 0.13.0 → 0.15.0

package/dist/app.d.ts

@@ -10,6 +10,8 @@ export interface Built {
     readonly script: string;
     /** Stylesheet addresses, in order. Empty in development, where the script brings its styles. */
     readonly styles: ReadonlyArray<string>;
+    /** The address of the MESH runtime's WebAssembly module in a production build, which the head starts compiling at once (W11). Absent in development. */
+    readonly wasm?: string | undefined;
 }
 /** A mistake in `src/main.ts`, reported with what to change. */
 export declare class AppDefinitionError extends Error {
@@ -28,6 +30,8 @@ export declare const stateSchema: (author: DefinedApp | undefined) => Schema.Sch
 /** The command table: the framework's `go`, then the author's. */
 export declare const commandTable: (author: DefinedApp | undefined, known?: (page: string) => boolean) => (state: Parameters<typeof Valance.command>[0]) => Valance.CommandTable<any, Valance.Ambient>;
 export declare const initialState: (author: DefinedApp | undefined) => AppState;
+/** The units of the components the author registered, by the tag each is written as (its template's file name without `.mprx`). */
+export declare const unitsOf: (author: DefinedApp | undefined) => Readonly<Record<string, Valance.Unit>>;
 export declare const application: (content: Content, program: Valance.Program, author?: DefinedApp) => Valance.ApplicationDefinition<AppState, any, Valance.Ambient, "layout">;
 /** The state a request for `pathname` starts from. */
 export declare const stateFor: (content: Content, pathname: string, author?: DefinedApp) => AppState;

package/dist/app.js

@@ -7,7 +7,7 @@ import * as Nexus from "@valancex/nexus";
 import { Effect, Schema, Stream } from "effect";
 import { documentTitle, frame, FrameScope, pageAt, RESERVED } from "./scope.js";
 import { normalize } from "./routes.js";
-import { derivedOf } from "./index.js";
+import { derivedOf, isFormField } from "./index.js";
 import { Navigation } from "./navigation.js";
 import * as StoreOps from "./store.js";
 import { badDefaults, stateOf } from "./state.js";
@@ -44,6 +44,11 @@ export const checkDefinition = (author) => {
             throw new AppDefinitionError(`src/main.ts: the state field "${name}" is the framework's (which page is shown, and the pages visited); choose another`);
         }
     }
+    for (const [tag, id] of Object.entries(author?.resolve ?? {})) {
+        if (typeof id !== "string" || !/^(@[^/\s]+\/)?[^/\s]+\/[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(id) || id.split("/").at(-1) !== tag) {
+            throw new AppDefinitionError(`src/main.ts: \`resolve\` maps a tag to the qualified id of the component it means, \`${tag}: "package/${tag}"\`; got ${JSON.stringify(id)} for "${tag}"`);
+        }
+    }
     const fields = Object.keys(stateOf(author)?.schema.fields ?? {});
     for (const name of persistedFields(author)) {
         if (!fields.includes(name)) {
@@ -209,8 +214,18 @@ export const initialState = (author) => ({
     colorScheme: "light",
     ...stateOf(author)?.initial,
 });
+/** The units of the components the author registered, by the tag each is written as (its template's file name without `.mprx`). */
+export const unitsOf = (author) => {
+    const parts = [author, author?.targets?.web, author?.targets?.desktop];
+    const components = parts.flatMap((part) => [...(part?.layout === undefined ? [] : [part.layout]), ...(part?.components ?? []), ...(part?.override ?? [])]);
+    return Object.fromEntries(components.flatMap((component) => (component.unit === undefined ? [] : [[component.template.mprx.replace(/^.*[\\/]/, "").replace(/\.mprx$/, ""), component.unit]])));
+};
+/** The names of the state fields that hold a form. */
+const formsOf = (author) => Object.entries((author?.state ?? {})).flatMap(([name, value]) => (isFormField(value) ? [name] : []));
 export const application = (content, program, author) => {
     checkDefinition(author);
+    const units = unitsOf(author);
+    const forms = formsOf(author);
     return Valance.define({
         name: content.site.name,
         state: { schema: stateSchema(author), initial: initialState(author) },
@@ -230,6 +245,11 @@ export const application = (content, program, author) => {
         view: () => "layout",
         commands: commandTable(author, (page) => pageAt(content, page) !== undefined),
         ...(persisted(author).length === 0 ? {} : { start: "persist" }),
+        ...(Object.keys(units).length === 0 ? {} : { units }),
+        // A form takes the person to its first field in error each time a submit is tried (Bet 9, I13): nothing for the author to write.
+        ...(forms.length === 0
+            ? {}
+            : { focusFirstInvalid: (state) => forms.reduce((count, name) => count + (state[name]?.attempts ?? 0), 0) }),
     });
 };
 /** The state a request for `pathname` starts from. */

package/dist/client.d.ts

@@ -1,9 +1,12 @@
 import type * as Valance from "@valancex/valance";
+import type { SessionRecorder } from "@valancex/valance/replay";
 import type { DefinedApp } from "./index.js";
 import type { Content } from "./model.js";
 export interface ClientParts {
     readonly content: Content;
     readonly program: Valance.Program;
     readonly author?: DefinedApp | undefined;
+    /** A session recorder (`vlx dev --record` writes the entry that passes one): a development feature. */
+    readonly record?: SessionRecorder | undefined;
 }
-export declare const start: ({ content, program, author }: ClientParts) => Promise<void>;
+export declare const start: ({ content, program, author, record }: ClientParts) => Promise<void>;

package/dist/client.js

@@ -7,13 +7,16 @@ import { Effect } from "effect";
 import { webPlatform } from "./http.js";
 import { watchColorScheme } from "./color-scheme.js";
 import { watchViewport } from "./viewport.js";
+import { earlyModule, finishStarting, replayEarly, settleOf, snapEarly } from "./early-replay.js";
 import { application } from "./app.js";
 import { plugin } from "./web-app.js";
-export const start = async ({ content, program, author }) => {
+export const start = async ({ content, program, author, record }) => {
     const container = document.getElementById("app");
     try {
         const boot = JSON.parse(document.getElementById("valance-boot").textContent);
-        await init(wasmUrl);
+        // The module the head's shell compiled while this script downloaded (W11), else the runtime fetches it itself.
+        await init((await earlyModule()) ?? wasmUrl);
+        snapEarly();
         const host = await Web.run(application(content, program, author), {
             container,
             present: "hydrate",
@@ -22,6 +25,7 @@ export const start = async ({ content, program, author }) => {
             // What the application's commands may ask the page for: the backend (`Http`), at `api.base` of valance.web.json.
             platform: webPlatform({ base: content.site.api, interceptors: author?.http?.interceptors ?? [], store: webStore(content.site.name) }),
             shutdown: { grace: "250 millis" },
+            ...(record === undefined ? {} : { record }),
         });
         // The server rendered for a wide window; tell the application how wide this one is (and keep telling it).
         const unwatchScheme = watchColorScheme(window, (scheme) => {
@@ -32,6 +36,9 @@ export const start = async ({ content, program, author }) => {
             container.dataset["viewport"] = viewport; // for a stylesheet or a test; the layout reads the state's own `viewport`
             void Effect.runPromise(host.handle.invoke("app/resize", [{ value: viewport }])).catch(() => undefined);
         });
+        // What a person did before the application was ready (Bet 14): once, in order, at the same nodes, only if hydration kept them.
+        await replayEarly(container, host.mounted.hydration?.adopted !== false, settleOf(host.mounted));
+        finishStarting(container);
         container.dataset["valance"] = "running"; // readiness marker for whoever drives the page
         addEventListener("pagehide", (event) => {
             if (!event.persisted) {
@@ -42,6 +49,7 @@ export const start = async ({ content, program, author }) => {
         });
     }
     catch (error) {
+        finishStarting(container);
         container.dataset["valance"] = "failed";
         console.error("the application did not start", error); // the server's HTML stays as drawn
     }

package/dist/desktop.d.ts

@@ -1,4 +1,4 @@
-import type { RenderTree } from "@valancex/mesh-runtime";
+import type { BoundaryValue, RenderTree } from "@valancex/mesh-runtime";
 import type * as Valance from "@valancex/valance";
 import type { DefinedApp } from "./index.js";
 import type { Content } from "./model.js";
@@ -8,6 +8,8 @@ export interface DesktopParts {
     readonly author?: DefinedApp | undefined;
     /** Where the project's `public/` files are on this machine: an image whose address is a file there is drawn from it. Absent: images are drawn as their descriptions. */
     readonly assets?: string | undefined;
+    /** The theme, resolved for the window (`@valancex/style`'s `resolveForDesktop`): data the engine does not read, given to the window once. Absent: the window keeps its own look. */
+    readonly theme?: BoundaryValue | undefined;
     /** The MESH runtime's module, when the host reads it (the generated entry reads the copy beside the engine). */
     readonly wasm?: Uint8Array | undefined;
 }
@@ -19,4 +21,4 @@ export interface DesktopParts {
 export declare const assetPath: (assets: string, src: string) => string | undefined;
 /** The tree with each image's address turned into the file it names, where there is one. */
 export declare const withAssets: (tree: RenderTree, assets: string) => RenderTree;
-export declare const start: ({ content, program, author, wasm, assets }: DesktopParts) => Promise<void>;
+export declare const start: ({ content, program, author, wasm, assets, theme }: DesktopParts) => Promise<void>;

package/dist/desktop.js

@@ -40,7 +40,7 @@ export const withAssets = (tree, assets) => {
     };
     return { ...tree, root: walk(tree.root) };
 };
-export const start = async ({ content, program, author, wasm, assets }) => {
+export const start = async ({ content, program, author, wasm, assets, theme }) => {
     if (wasm !== undefined) {
         await init(wasm);
     }
@@ -49,6 +49,7 @@ export const start = async ({ content, program, author, wasm, assets }) => {
     await Native.run(application(content, program, author), {
         // The window follows the system's colors unless the application asks otherwise (`appearance` in `defineApp`), and the application learns the system's (`colorScheme`).
         appearanceOf: (state) => author?.appearance?.(state) ?? "system",
+        ...(theme === undefined ? {} : { theme }),
         onScheme: (scheme, handle) => handle.invoke("app/colorScheme", [{ value: scheme }]),
         // Back and Forward, as the window's keys and mouse buttons ask for them: the framework's own commands, which the author's `guard` may refuse.
         onNavigate: (direction, handle) => handle.invoke(direction === "back" ? "app/back" : "app/forward", []),

package/dist/early-replay.d.ts

@@ -0,0 +1,57 @@
+import { Effect } from "effect";
+/** At most this many events are replayed, and none older than this when it happens (H3). */
+export declare const EARLY_LIMIT = 20;
+export declare const EARLY_MAX_AGE_MS = 10000;
+interface Entry {
+    readonly k: "click" | "key";
+    readonly n: HTMLElement;
+    readonly x?: string;
+    readonly t: number;
+}
+interface Shell {
+    q: Entry[];
+    busy: HTMLElement[];
+    on: number;
+    wasm: Promise<WebAssembly.Module | void> | 0;
+    snap?: () => void;
+    fields?: Array<{
+        readonly n: HTMLInputElement | HTMLTextAreaElement;
+        readonly x: string;
+    }>;
+    focus?: {
+        readonly n: HTMLInputElement | HTMLTextAreaElement;
+        readonly s: number | null;
+        readonly e: number | null;
+    } | 0;
+    /** What the replay did, for whoever drives the page. */
+    done?: {
+        readonly replayed: number;
+        readonly dropped: number;
+    };
+}
+declare global {
+    interface Window {
+        __vlx?: Shell;
+    }
+}
+/** The shell the page's head started, if it did (a page served by something other than `vlx` has none). */
+export declare const shell: () => Shell | undefined;
+/** Reads the fields whose text differs from the server's, and the caret, just before hydration writes the application's values over them (H4, H10). */
+export declare const snapEarly: () => void;
+/** The WebAssembly module the shell compiled while the script downloaded, if it did and it worked; else nothing, and the runtime loads the module itself. */
+export declare const earlyModule: () => Promise<WebAssembly.Module | undefined>;
+export interface Replayed {
+    readonly replayed: number;
+    readonly dropped: number;
+}
+/**
+ * Replays what the shell kept, once. `adopted` is whether hydration kept the server's nodes: if it drew afresh the nodes are gone and nothing is replayed (H3). `settle` waits for the commands
+ * the last dispatch started.
+ */
+export declare const replayEarly: (container: HTMLElement, adopted: boolean, settle: () => Promise<void>, now?: () => number) => Promise<Replayed>;
+/** The page is ready, or has failed: it is no longer starting. */
+export declare const finishStarting: (container: HTMLElement) => void;
+export declare const settleOf: (mounted: {
+    readonly settled: Effect.Effect<void>;
+}) => (() => Promise<void>);
+export {};

package/dist/early-replay.js

@@ -0,0 +1,75 @@
+// What the page does with what the early-input shell kept (`early.ts`; Bet 14, decisions H3, H4, H6, H10): after hydration has adopted the server's nodes, in order and one at a time, waiting for each
+// command to settle. It dispatches ordinary events at the same nodes, so the PORT and the application see what they would have seen had the application been ready; neither knows. Development
+// and production alike.
+import { Effect } from "effect";
+/** At most this many events are replayed, and none older than this when it happens (H3). */
+export const EARLY_LIMIT = 20;
+export const EARLY_MAX_AGE_MS = 10_000;
+/** The shell the page's head started, if it did (a page served by something other than `vlx` has none). */
+export const shell = () => window.__vlx;
+/** Reads the fields whose text differs from the server's, and the caret, just before hydration writes the application's values over them (H4, H10). */
+export const snapEarly = () => window.__vlx?.snap?.();
+/** The WebAssembly module the shell compiled while the script downloaded, if it did and it worked; else nothing, and the runtime loads the module itself. */
+export const earlyModule = async () => {
+    const compiled = await window.__vlx?.wasm;
+    return compiled instanceof WebAssembly.Module ? compiled : undefined;
+};
+/**
+ * Replays what the shell kept, once. `adopted` is whether hydration kept the server's nodes: if it drew afresh the nodes are gone and nothing is replayed (H3). `settle` waits for the commands
+ * the last dispatch started.
+ */
+export const replayEarly = async (container, adopted, settle, now = Date.now) => {
+    const shell = window.__vlx;
+    if (shell === undefined) {
+        return { replayed: 0, dropped: 0 };
+    }
+    const queue = shell.q.splice(0);
+    const fields = shell.fields ?? [];
+    const alive = (node) => adopted && node.isConnected && container.contains(node);
+    let replayed = 0;
+    let dropped = 0;
+    shell.on = 0; // from here the page is listening itself
+    // The text first (H4): a field's value is part of what the next tap acts on.
+    for (const { n, x } of fields) {
+        if (!alive(n)) {
+            dropped += 1;
+            continue;
+        }
+        n.value = x;
+        n.dispatchEvent(new Event("input", { bubbles: true }));
+        await settle();
+        replayed += 1;
+    }
+    for (const entry of queue.slice(0, EARLY_LIMIT)) {
+        if (!alive(entry.n) || now() - entry.t > EARLY_MAX_AGE_MS) {
+            dropped += 1;
+            continue;
+        }
+        if (entry.k === "click") {
+            entry.n.click();
+        }
+        else {
+            entry.n.dispatchEvent(new KeyboardEvent("keydown", { key: entry.x ?? "", bubbles: true, cancelable: true }));
+        }
+        await settle();
+        replayed += 1;
+    }
+    dropped += Math.max(0, queue.length - EARLY_LIMIT);
+    const focus = shell.focus;
+    if (focus !== undefined && focus !== 0 && alive(focus.n)) {
+        focus.n.focus();
+        if (focus.s !== null && focus.e !== null) {
+            focus.n.setSelectionRange(focus.s, focus.e);
+        }
+    }
+    shell.busy.splice(0).forEach((node) => node.removeAttribute("aria-busy"));
+    shell.fields = [];
+    shell.done = { replayed, dropped };
+    return { replayed, dropped };
+};
+/** The page is ready, or has failed: it is no longer starting. */
+export const finishStarting = (container) => {
+    delete container.dataset["vlx"];
+    window.__vlx?.busy.splice(0).forEach((node) => node.removeAttribute("aria-busy"));
+};
+export const settleOf = (mounted) => () => Effect.runPromise(mounted.settled);

package/dist/early.d.ts

@@ -0,0 +1,8 @@
+/** The shell. Hand-minified; `earlyShellLimit` is its size budget (a test holds it). */
+export declare const earlyShell: string;
+/** The most bytes the shell may have: it is on the critical path of every page (Bet 3, `budgets.json`). */
+export declare const earlyShellLimit = 1500;
+/** The markup the server writes in the head: the shell, and, when the page's WebAssembly runtime is at `wasm`, the link the shell compiles it from. */
+export declare const earlyHead: (built: {
+    readonly wasm?: string | undefined;
+}) => string;

package/dist/early.js

@@ -0,0 +1,30 @@
+// The early-input shell (Bet 14; decisions H2 to H5, H9 to H11): a few hundred bytes of script written into every page's <head>, before the page's own script has arrived. For the second or so
+// between the server's HTML being painted and the application starting, a tap on a control does nothing, because nothing is listening yet (measured: 7 of 9 taps in that dead zone were lost). The
+// shell listens from the first byte and keeps what a person did, so the client can do it once the application is ready (`replayEarly`, below):
+//
+//   - a trusted click (a tap, a key press on a focused control) on a control inside the page, in order, at most 20 and none older than 10 seconds when they are replayed; never a link (the browser
+//     already navigates it) and never a control marked `earlyInput="drop"` (that one is dropped and shows the busy state: "Pay" and "Like" are both buttons, H9);
+//   - the keys Enter and Escape in a text field (H11);
+//   - the text of every field whose value differs from the server's, and the caret of the focused one (H4, H10): read once, when hydration begins.
+//
+// It also starts compiling the WebAssembly runtime as the document is parsed (`compileStreaming`, W11), when the page names it in `<link id="vlx-wasm">`, so the compile overlaps the download of the
+// page's script.
+//
+// The shell is the same bytes in every page, so a Content-Security-Policy can allow it by hash (`vlx build` computes it and writes it into `_headers`) without `'unsafe-inline'`. It decides nothing and has no configuration: PORTs do not
+// know it exists (H6), and replay is the composer's feature, done by dispatching ordinary events at the adopted nodes.
+/** The shell. Hand-minified; `earlyShellLimit` is its size budget (a test holds it). */
+export const earlyShell = `(function(d,w){var v=w.__vlx={q:[],busy:[],on:1,wasm:0},l=d.getElementById("vlx-wasm"),T="#app input:not([type=checkbox]):not([type=radio]),#app textarea";` +
+    `if(l&&w.WebAssembly&&WebAssembly.compileStreaming)v.wasm=WebAssembly.compileStreaming(fetch(l.href)).catch(function(){});` +
+    `function on(t,f){d.addEventListener(t,function(e){v.on&&e.isTrusted&&f(e)},!0)}` +
+    `function add(k,n,x){if(v.q.length<20)v.q.push({k:k,n:n,x:x,t:Date.now()})}` +
+    `on("click",function(e){var t=e.target.closest&&e.target.closest("a[href],button,[role=button],input,select,textarea,summary,label");` +
+    `if(t&&t.tagName=="LABEL")t=t.control;if(!t||t.closest("a[href]")||!t.closest("#app"))return;` +
+    `if(t.closest("[data-early-input=drop]")){t.setAttribute("aria-busy","true");v.busy.push(t);return}add("click",t)});` +
+    `on("keydown",function(e){var t=e.target;(e.key=="Enter"||e.key=="Escape")&&t.matches&&t.matches(T)&&add("key",t,e.key)});` +
+    `v.snap=function(){var f=[],a=d.activeElement;d.querySelectorAll(T).forEach(function(n){n.value!=n.defaultValue&&f.push({n:n,x:n.value})});` +
+    `v.fields=f;v.focus=a&&a.matches&&a.matches(T)?{n:a,s:a.selectionStart,e:a.selectionEnd}:0}` +
+    `})(document,window);`;
+/** The most bytes the shell may have: it is on the critical path of every page (Bet 3, `budgets.json`). */
+export const earlyShellLimit = 1500;
+/** The markup the server writes in the head: the shell, and, when the page's WebAssembly runtime is at `wasm`, the link the shell compiles it from. */
+export const earlyHead = (built) => `${built.wasm === undefined ? "" : `<link id="vlx-wasm" rel="preload" as="fetch" type="application/wasm" crossorigin href="${built.wasm}">`}<script>${earlyShell}</script>`;

package/dist/form.d.ts

@@ -0,0 +1,165 @@
+import { Schema } from "effect";
+import type { Derived, DeriveMaker, Field } from "./index.js";
+/** A mistake in the schema a form is made from, said at the declaration and naming the field. */
+export declare class FormError extends Error {
+    constructor(message: string);
+}
+/** What a field is, for choosing how to draw it: a line of text, a secret one, a number the person types as text, a yes or no, one of a closed set. */
+export type Kind = "text" | "password" | "number" | "boolean" | "choice";
+/** One field of the schema, as a screen needs to know it. Static: it is the same for every state. */
+export interface Descriptor {
+    /** Where the field is in the schema, joined with dots for a nested record: `address.zip`. */
+    readonly name: string;
+    readonly path: ReadonlyArray<string>;
+    /** The label: the schema's `title` annotation. */
+    readonly title: string;
+    readonly kind: Kind;
+    /** Whether a value must be given. A text field that is left empty is absent when the field is optional. */
+    readonly required: boolean;
+    /** The values of a closed set, in the schema's order. */
+    readonly choices: ReadonlyArray<string>;
+    /** The constraints the schema's refinements declare, as JSON Schema keywords: `minLength`, `maximum`, `pattern`, … */
+    readonly constraints: Readonly<Record<string, unknown>>;
+    /** Whether the value is a secret: it is never in a draft, and the default message never repeats it. */
+    readonly redacted: boolean;
+    /** Whether the schema gives its own message for the field's constraints. */
+    readonly hasMessage: boolean;
+}
+/** What the form keeps: all of it plain data, so it can be a field of the application's state. */
+export interface State {
+    /** The text each field holds (a yes or no for a boolean one), by field name. */
+    readonly values: Readonly<Record<string, string | boolean>>;
+    /** The fields the person has left. */
+    readonly touched: Readonly<Record<string, true>>;
+    /** How many times a submit has been tried, or a server has answered one with messages: the count a host watches to take the person to the first field in error (`ApplicationDefinition.focusFirstInvalid`). */
+    readonly attempts: number;
+    /** The messages a server gave, by field name; a field's is gone when it is edited. */
+    readonly remote: Readonly<Record<string, string>>;
+}
+/** What a template reads about one field. */
+export interface FieldView {
+    readonly name: string;
+    readonly title: string;
+    readonly kind: Kind;
+    /** The `kind` of a `textfield` that holds it: `password` for a secret, `text` otherwise. */
+    readonly input: string;
+    readonly required: boolean;
+    readonly choices: ReadonlyArray<string>;
+    readonly value: string;
+    readonly checked: boolean;
+    /** Whether an error is shown for the field now. */
+    readonly invalid: boolean;
+    /** The message to show, empty when none is shown. */
+    readonly error: string;
+    /** The address of the element that shows the message, always drawn (empty when there is no message): what the control's `describedby` names. */
+    readonly errorId: string;
+    readonly touched: boolean;
+    readonly dirty: boolean;
+}
+/** What a template reads about the form. */
+export interface View {
+    readonly fields: ReadonlyArray<FieldView>;
+    /** Whether the schema accepts what is typed (whatever is shown). */
+    readonly valid: boolean;
+    /** After a failed submit: how many fields need attention, for a live region. Empty otherwise. */
+    readonly message: string;
+    /** The first field with an error shown: where a failed submit takes the person. Empty when none. */
+    readonly first: string;
+    readonly submitted: boolean;
+}
+/** The type of `View`, for the derived value a template reads. */
+export declare const ViewSchema: Schema.Schema<View>;
+/** Messages by field name that a server (or any check the client cannot make) gives: a command that fails with this has the form show them as if the schema had said so. */
+export interface FieldErrors {
+    readonly _tag: "FieldErrors";
+    readonly errors: Readonly<Record<string, string>>;
+}
+export declare const fieldErrors: (errors: Readonly<Record<string, string>>) => FieldErrors;
+/** What a translation function is told about a leaf of the schema's own report, for a field that has no `message` of its own. */
+export interface Issue {
+    readonly path: ReadonlyArray<string>;
+    /** Which check failed: the schema id of a refinement (`minLength`, `int`, …) or the kind of the report (`Type`, `Missing`, …). */
+    readonly code: string;
+    /** The check's parameters, as JSON Schema keywords: `{ minLength: 2 }`. */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** What was typed. Absent for a secret field. */
+    readonly actual: unknown;
+}
+export interface Options<I> {
+    /** The text each field starts with. Absent: empty text, and `false` for a boolean. */
+    readonly initial?: Partial<I>;
+    /** The words for a field that has no `message` annotation. Absent: the schema's own text, which is for developers. */
+    readonly message?: (issue: Issue) => string | undefined;
+}
+/** The result of trying to submit. */
+export type Submitted<A> = {
+    readonly ok: true;
+    readonly value: A;
+    readonly state: State;
+} | {
+    readonly ok: false;
+    readonly state: State;
+};
+/** A form made from a schema. */
+export interface Form<A, I> {
+    /** The fields, in the schema's order. */
+    readonly fields: ReadonlyArray<Descriptor>;
+    /** The state a form starts in. */
+    readonly initial: State;
+    /** The schema, as the Standard Schema interface (`~standard`), for tools that take that. */
+    readonly standard: unknown;
+    /** Things in the schema worth a word to its author: a constraint with no message of its own. Empty when there are none. */
+    readonly warnings: ReadonlyArray<string>;
+    /** The form as a field of the application's state. */
+    readonly field: () => Field<State>;
+    /** What a template reads, for a state. */
+    readonly view: {
+        (state: State): View;
+        /** As a derived value of the application: `signup.view(derive, (state) => state.signup)`. */
+        <S>(derive: DeriveMaker<S>, from: (state: S) => State): Derived<View>;
+    };
+    readonly edit: (state: State, name: string, value: string) => State;
+    readonly check: (state: State, name: string, value: boolean) => State;
+    readonly blur: (state: State, name: string) => State;
+    /** Tries to submit: the decoded value when the schema accepts what is typed, and in any case the state with every field touched. */
+    readonly submit: (state: State) => Submitted<A>;
+    /** The messages of a failed command, shown on their fields. */
+    readonly reject: (state: State, errors: FieldErrors) => State;
+    /** What was typed, without secrets, to keep and give back: `initial` takes it. */
+    readonly draft: (state: State) => Draft;
+    /** The state a draft makes. */
+    readonly restore: (draft: Draft) => State;
+    /** The commands of the form on the application's state: `edit(name, text)`, `check(name, yes)`, `blur(name)` and `submit()`. */
+    readonly commands: <S>(command: CommandMaker<S>, how: Where<S, A>) => Commands;
+    /** The encoded type, for a caller that wants to name it. */
+    readonly encoded?: I;
+}
+/** What was typed, serializable. Never has a secret. */
+export interface Draft {
+    /** Which schema it is for: a draft of another shape is not restored. */
+    readonly version: string;
+    readonly values: Readonly<Record<string, string | boolean>>;
+}
+/** The commands a form adds to the application's table. */
+export interface Commands {
+    readonly edit: unknown;
+    readonly check: unknown;
+    readonly blur: unknown;
+    readonly submit: unknown;
+}
+/** Where the form is in the application's state, and what a submit that the schema accepts does. */
+export interface Where<S, A> {
+    /** The state field that holds the form (`state: { signup: signup.field() }` is `"signup"`): the usual way to say where it is. */
+    readonly field?: string;
+    /** Where the form is, when it is not simply a field of the state. */
+    readonly get?: (state: S) => State;
+    readonly set?: (state: S, form: State) => S;
+    /** The application's state after a submit that the schema accepted, from the decoded value. The form keeps what was typed. */
+    readonly submitted: (state: S, value: A) => S;
+}
+/** The part of `Valance.CommandMaker` the form uses, so this file imports no more of Valance than that. */
+export interface CommandMaker<S> {
+    <I>(input: Schema.Schema<I, any, never>, transition: (input: I, current: S) => S): unknown;
+    (transition: (current: S) => S): unknown;
+}
+export declare function make<A, I>(schema: Schema.Schema<A, I, never>, options?: Options<I>): Form<A, I>;