@orkestrel/form 0.0.4 → 0.0.6

package/dist/src/core/index.d.ts

@@ -1,14 +1,14 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { JSONRecord } from '@orkestrel/contract';
-import { Result } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { JSONRecord } from '@orkestrel/contract';
+import type { Result } from '@orkestrel/contract';
 
-/** One or more ASCII letters or digits. */
+/** Matches one or more ASCII letters or digits. */
 export declare const ALPHANUMERIC_PATTERN: Readonly<RegExp>;
 
 /**
- * Check whether a named rule applies to one field control.
+ * Checks whether a named rule applies to one field control.
  *
  * @remarks
  * The runtime control-membership check keeps this boundary total for JavaScript callers that
@@ -16,12 +16,12 @@ export declare const ALPHANUMERIC_PATTERN: Readonly<RegExp>;
  *
  * @param control - The field control to inspect.
  * @param rule - The named rule to inspect.
- * @returns Whether the control evaluates that rule.
+ * @returns True if the control evaluates that rule; false otherwise.
  */
 export declare function appliesRule(control: FieldControl, rule: FieldRuleName): boolean;
 
 /**
- * Audit a structurally valid schema for domain invariants.
+ * Audits a structurally valid schema for domain invariants.
  *
  * @param schema - The form schema to audit.
  * @returns Human-readable invariant violations, or an empty list when the schema is sound.
@@ -29,7 +29,7 @@ export declare function appliesRule(control: FieldControl, rule: FieldRuleName):
 export declare function auditSchema(schema: FormSchema): readonly string[];
 
 /**
- * Any number of choices out of a list, holding the checked values.
+ * Represents any number of choices out of a list, holding the checked values.
  *
  * @remarks
  * A field offering one box that means yes or no is a {@link ConfirmField}, not a one-choice
@@ -41,11 +41,11 @@ export declare interface CheckboxField extends FieldBase {
     readonly default?: readonly string[];
 }
 
-/** The maximum number of choices one `select` or `checkbox` field may offer. */
+/** Caps the number of choices one `select` or `checkbox` field may offer, at 1024. */
 export declare const CHOICE_LIMIT = 1024;
 
 /**
- * Clone a field's choices into an owned frozen snapshot.
+ * Clones a field's choices into an owned frozen snapshot.
  *
  * @param choices - The choices to own.
  * @returns A frozen list of frozen choice records.
@@ -53,7 +53,7 @@ export declare const CHOICE_LIMIT = 1024;
 export declare function cloneChoices(choices: readonly FieldChoice[]): readonly FieldChoice[];
 
 /**
- * Clone one form field into an owned frozen snapshot.
+ * Clones one form field into an owned frozen snapshot.
  *
  * @param field - The field to own.
  * @returns A frozen field with every nested collection owned.
@@ -62,7 +62,7 @@ export declare function cloneChoices(choices: readonly FieldChoice[]): readonly
 export declare function cloneFormField(field: FormField): FormField;
 
 /**
- * Clone a form schema into an owned frozen snapshot.
+ * Clones a form schema into an owned frozen snapshot.
  *
  * @param schema - The schema to own.
  * @returns A frozen schema with every nested record and list owned.
@@ -70,7 +70,7 @@ export declare function cloneFormField(field: FormField): FormField;
 export declare function cloneFormSchema(schema: FormSchema): FormSchema;
 
 /**
- * Clone one form value into an owned frozen snapshot.
+ * Clones one form value into an owned frozen snapshot.
  *
  * @param value - The field value to own.
  * @returns The scalar unchanged, or a frozen copy of the list.
@@ -79,31 +79,57 @@ export declare function cloneValue(value: readonly string[]): readonly string[];
 
 export declare function cloneValue(value: FieldValue): FieldValue;
 
-/** A six-digit hexadecimal color string. */
+/** Matches a six-digit hexadecimal color string. */
 export declare const COLOR_PATTERN: Readonly<RegExp>;
 
-/** A color, held as the control's own string. */
+/** Represents a color, held as the control's own six-digit `#rrggbb` string. */
 export declare interface ColorField extends FieldBase {
     readonly control: 'color';
     readonly default?: string;
 }
 
 /**
- * Compute the values explicitly seeded by a schema.
+ * Computes the values explicitly seeded by a schema.
+ *
+ * @remarks
+ * `password` and `file` declare no default, so a field of either control never appears in the
+ * result.
  *
  * @param schema - The schema whose defaults to collect.
  * @returns A value record containing only fields with defaults.
  */
 export declare function computeDefaults(schema: FormSchema): FormValues;
 
-/** A single on/off box, holding a boolean. */
+/** Represents a single on/off box, holding a boolean. */
 export declare interface ConfirmField extends FieldBase {
     readonly control: 'confirm';
     readonly default?: boolean;
 }
 
 /**
- * Open a form against a schema.
+ * Creates one named-rule failure against a field.
+ *
+ * @param field - The field the rule failed on.
+ * @param rule - The named rule that failed.
+ * @param limit - The rule's operand, substituted for `{limit}`, or absence when it carries none.
+ * @param messages - Optional rule-specific message replacements.
+ * @returns A frozen {@link FieldError} carrying the field's name, the resolved text, and the rule.
+ *
+ * @remarks
+ * A `custom` validator and the form's `invalidate` method both report a message of their own
+ * under no rule name, so neither builds its failure here.
+ *
+ * @example
+ * ```ts
+ * const field: FormField = { control: 'text', name: 'nickname', rule: { minimum: 3 } }
+ * const error = createFieldError(field, 'minimum', 3)
+ * error.message // 'Must be at least 3'
+ * ```
+ */
+export declare function createFieldError(field: FormField, rule: FieldRuleName, limit: number | string | undefined, messages?: Readonly<Partial<Record<FieldRuleName, string>>>): FieldError;
+
+/**
+ * Opens a form against a schema.
  *
  * @param schema - The form to ask. It is copied, and the copy is what the form asks.
  * @param options - The form's settings.
@@ -114,8 +140,10 @@ export declare interface ConfirmField extends FieldBase {
  * @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
  *   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded value
  *   is one its field's control cannot hold.
- * @example
+ * @example Open a form, answer it, and settle it
  * ```ts
+ * import { createForm } from '@orkestrel/form'
+ *
  * const form = createForm({
  * 	label: 'Sign up',
  * 	fields: [
@@ -125,64 +153,89 @@ export declare interface ConfirmField extends FieldBase {
  * })
  *
  * form.fill({ email: 'ada@example.com', terms: true })
- * form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+ * const result = form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+ * const answers = await form.answer // { email: 'ada@example.com', terms: true }
  * ```
  */
 export declare function createForm(schema: FormSchema, options?: FormOptions): FormInterface;
 
-/** An ISO calendar date string in `YYYY-MM-DD` form. */
+/** Matches an ISO calendar date string in `YYYY-MM-DD` form. */
 export declare const DATE_PATTERN: Readonly<RegExp>;
 
-/** A calendar date, held as the control's own string. */
+/** Represents a calendar date, held as the control's own `YYYY-MM-DD` string. */
 export declare interface DateField extends FieldBase {
     readonly control: 'date';
     readonly default?: string;
 }
 
-/** An ISO local date and time string with optional seconds. */
+/** Matches an ISO local date and time string with optional seconds. */
 export declare const DATETIME_PATTERN: Readonly<RegExp>;
 
-/** A date and a time of day together, with no zone, held as the control's own string. */
+/** Represents a date and a time of day together, with no zone, held as the control's own string. */
 export declare interface DatetimeField extends FieldBase {
     readonly control: 'datetime';
     readonly default?: string;
 }
 
-/** Text over many lines. */
+/**
+ * Writes one own enumerable data property onto a record.
+ *
+ * @param target - The record to write into.
+ * @param name - The property name to write.
+ * @param value - The value to store.
+ *
+ * @remarks
+ * Plain assignment runs an inherited setter, so writing a `__proto__` key that way reaches
+ * `Object.prototype` and leaves the record without the entry. Defining the property writes the
+ * record itself, whatever the prototype chain declares. The entry stays writable and configurable.
+ *
+ * @example
+ * ```ts
+ * const values: Record<string, number> = {}
+ * defineEntry(values, '__proto__', 1)
+ * Object.hasOwn(values, '__proto__') // true
+ * ```
+ */
+export declare function defineEntry<T>(target: Record<string, T>, name: string, value: T): void;
+
+/** Represents text over many lines. */
 export declare interface EditorField extends FieldBase {
     readonly control: 'editor';
     readonly default?: string;
     readonly placeholder?: string;
 }
 
-/** A practical whole-address email shape. */
+/** Matches a practical whole-address email shape. */
 export declare const EMAIL_PATTERN: Readonly<RegExp>;
 
 /**
- * Evaluate one field rule against its current value.
+ * Evaluates one field rule against its current value.
  *
  * @param field - The field and rule to evaluate.
  * @param value - The current value, or absence.
  * @param values - Every value available to a custom rule.
  * @param messages - Optional rule-specific message replacements.
  * @returns Every failure in rule order.
+ * @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+ *   its own value escapes unchanged, because this helper adds no boundary around it.
  */
 export declare function evaluateField(field: FormField, value: FieldValue | undefined, values: FormValues, messages?: Readonly<Partial<Record<FieldRuleName, string>>>): readonly FieldError[];
 
 /**
- * Evaluate every active field in schema order.
+ * Evaluates every active field in schema order.
  *
  * @param schema - The form schema to evaluate.
  * @param values - The values keyed by field name.
  * @param options - Optional message replacements and the effective disabled field set.
  * @returns Every field failure in schema and rule order.
+ * @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+ *   its own value escapes unchanged, because this helper adds no boundary around it.
  */
 export declare function evaluateForm(schema: FormSchema, values: FormValues, options?: EvaluationOptions): readonly FieldError[];
 
 /**
- * How to check a schema against a set of answers.
+ * Describes how to check a schema against a set of answers.
  *
- * @param options - The evaluation's settings.
  * @remarks
  * `messages` replaces the default message of a rule, keyed by {@link FieldRuleName}.
  *
@@ -205,40 +258,49 @@ export declare interface EvaluationOptions {
 }
 
 /**
- * Extract the names whose answers differ between two form value records.
+ * Extracts the names whose answers differ between two form value records.
  *
  * @remarks
  * Presence is compared in both directions before present values are compared through
  * {@link matchesValue}. The returned set is a new snapshot, exposed as readonly because later
  * changes to either input never alter its membership.
  *
- * @param current - The values held now.
+ * @param current - The values the form holds.
  * @param opened - The values held when the form opened.
  * @returns A readonly snapshot of changed field names.
  */
 export declare function extractChanges(current: FormValues, opened: FormValues): ReadonlySet<string>;
 
 /**
- * Select referenced groups in first-reference field order.
+ * Selects referenced groups in first-reference field order.
  *
  * @param schema - The schema whose group references to resolve.
  * @returns The referenced schema groups without duplicates.
  */
 export declare function extractGroups(schema: FormSchema): readonly FormGroup[];
 
-/** Every field control, in the order declared by the public contract. */
+/** Lists the members every field declares, whatever its control. */
+export declare const FIELD_BASE_KEYS: readonly string[];
+
+/** Lists every field control, in the order declared by the public contract. */
 export declare const FIELD_CONTROLS: readonly FieldControl[];
 
-/** The maximum number of fields one schema may declare. */
+/**
+ * Lists every member one field control permits, composed from {@link FIELD_BASE_KEYS} and the
+ * members the control's own interface adds.
+ */
+export declare const FIELD_KEYS: Readonly<Record<FieldControl, readonly string[]>>;
+
+/** Caps the number of fields one schema may declare, at 512. */
 export declare const FIELD_LIMIT = 512;
 
 /**
- * What every field carries, whatever its control.
+ * Declares what every field carries, whatever its control.
  *
  * @remarks
  * `name` keys the field in {@link FormValues} and `group` names a {@link FormGroup}.
  *
- * The three visibility switches differ in what they remove. `hidden` keeps the field out of
+ * `hidden`, `locked`, and `disabled` differ in what they remove. `hidden` keeps the field out of
  * the rendered form, `locked` renders it unwritable, and both are still validated and still
  * submitted. `disabled` takes the field out of the form entirely: it is neither validated nor
  * submitted. It is the field's declared, opening state; {@link FormInterface.disabled} is the
@@ -261,7 +323,7 @@ export declare interface FieldBase {
 }
 
 /**
- * One option a `select` or `checkbox` field offers.
+ * Represents one option a `select` or `checkbox` field offers.
  *
  * @remarks
  * `value` is what the form stores and `label` is what the person reads. `help` explains the
@@ -276,16 +338,16 @@ export declare interface FieldChoice {
 }
 
 /**
- * The control a field presents to the person answering it.
+ * Names the control a field presents to the person answering it.
  *
  * @remarks
  * The control is the discriminant of every {@link FormField} variant, so choosing it fixes
  * which options that field accepts and which {@link FieldValue} it holds.
  *
- * Three members need saying out loud. `confirm` is a single on/off box holding a boolean, so
- * a lone browser checkbox is a `confirm`. `checkbox` is the multi-choice group holding the
- * checked values as a list, never a single box. `datetime` is the browser's `datetime-local`:
- * a wall-clock date and time carrying no zone.
+ * The `confirm`, `checkbox`, and `datetime` members need saying out loud. `confirm` is a single
+ * on/off box holding a boolean, so a lone browser checkbox is a `confirm`. `checkbox` is the
+ * multi-choice group holding the checked values as a list, never a single box. `datetime` is the
+ * browser's `datetime-local`: a wall-clock date and time carrying no zone.
  *
  * @example
  * ```ts
@@ -295,7 +357,7 @@ export declare interface FieldChoice {
 export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'file';
 
 /**
- * One failed check against one field.
+ * Represents one failed check against one field.
  *
  * @remarks
  * `rule` names the constraint that failed. It is absent when the message came from a
@@ -309,7 +371,7 @@ export declare interface FieldError {
 }
 
 /**
- * The constraints one field's value must satisfy.
+ * Represents the constraints one field's value must satisfy.
  *
  * @remarks
  * `minimum` and `maximum` measure whatever the control makes countable: characters for
@@ -340,7 +402,7 @@ export declare interface FieldRule {
 }
 
 /**
- * Every rule that reports its failure by name.
+ * Lists every rule that reports its failure by name.
  *
  * @remarks
  * `custom` is excluded because it supplies its own message, so nothing keyed by a rule name
@@ -349,20 +411,21 @@ export declare interface FieldRule {
 export declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
 
 /**
- * Check one value against the whole form.
+ * Checks one value against the whole form.
  *
  * @remarks
  * It runs after every named rule, and it runs on an absent value as well as a present one. That
  * is what makes a rule such as "required once the sibling says yes" expressible, and it means an
  * unanswered field can carry both a `required` message and this validator's own.
  *
- * @param value - The value the field currently holds, or `undefined` when nobody has answered it.
+ * @param value - The value the field holds, or `undefined` when nobody has answered it.
  * @param values - Every answer the form holds, so a rule can read its siblings.
  * @returns `true` when the value passes, or the message explaining why it failed.
- * @throws The validator's own thrown value escapes the mutation call unchanged. When a form
- *   mutation has already changed state, the throw leaves those changes beside the error list
- *   from before that mutation. An invalidation can therefore be recorded without appearing in
- *   `errors`, and a clear can reset state without emitting `clear`. Form-owned refusals use
+ * @throws Thrown when a {@link FieldValidator} throws; its own thrown value escapes the mutation
+ *   call unchanged. When a form mutation has already changed state, the throw leaves those
+ *   changes beside the error list from before that mutation. An invalidation can therefore be
+ *   recorded without appearing in `errors`, and a clear can reset state without emitting `clear`.
+ *   Form-owned refusals use
  *   {@link FormError} instead.
  * @example
  * ```ts
@@ -373,7 +436,7 @@ export declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
 export declare type FieldValidator = (value: FieldValue | undefined, values: FormValues) => true | string;
 
 /**
- * Every value a field can hold.
+ * Represents every value a field can hold.
  *
  * @remarks
  * The variant follows the control: text-like controls hold a `string`, `number` holds a
@@ -383,11 +446,11 @@ export declare type FieldValidator = (value: FieldValue | undefined, values: For
 export declare type FieldValue = string | number | boolean | readonly string[];
 
 /**
- * One or more files.
+ * Represents one or more files, by name.
  *
  * @remarks
- * `accept` lists the media types and extensions the control offers, in the form the host
- * expects.
+ * A value is the names alone: bytes never enter the document. `accept` lists the media types
+ * and extensions the control offers, in the form the host expects.
  */
 export declare interface FileField extends FieldBase {
     readonly control: 'file';
@@ -396,7 +459,8 @@ export declare interface FileField extends FieldBase {
 }
 
 /**
- * A form: a schema, the answers given against it, and the errors they carry.
+ * Implements `FormInterface` exactly, over an owned schema, the answers given against it, and the
+ * errors they carry.
  *
  * @remarks
  * The form owns its schema, so a later edit to the schema the caller passed changes nothing here.
@@ -423,7 +487,7 @@ export declare interface FileField extends FieldBase {
 export declare class Form implements FormInterface {
     #private;
     /**
-     * Open a form against a schema.
+     * Opens a form against a schema.
      *
      * @param schema - The form to ask. It is copied, and the copy is what the form asks.
      * @param options - The form's settings.
@@ -432,28 +496,28 @@ export declare class Form implements FormInterface {
      *   value is one its field's control cannot hold.
      */
     constructor(schema: FormSchema, options?: FormOptions);
-    /** The form's event emitter. */
+    /** Holds the form's event emitter. */
     get emitter(): EmitterInterface<FormEventMap>;
-    /** The schema this form asks, owned and frozen. */
+    /** Holds the schema this form asks, owned and frozen. */
     get schema(): FormSchema;
-    /** The answers held right now. */
+    /** Reports the answers the form holds. */
     get values(): FormValues;
-    /** The answers the form opened with. */
+    /** Holds the answers the form opened with. */
     get baseline(): FormValues;
-    /** Every error the last completed evaluation produced. */
+    /** Holds every error the last completed evaluation produced. */
     get errors(): readonly FieldError[];
-    /** The names of the fields somebody has visited. */
+    /** Lists the names of the fields somebody has visited. */
     get touched(): ReadonlySet<string>;
-    /** The names of the fields currently out of the form. */
+    /** Lists the names of the fields that are out of the form. */
     get disabled(): ReadonlySet<string>;
-    /** Where the form sits in its life. */
+    /** Reports where the form sits in its life. */
     get status(): FormStatus;
-    /** Whether the last completed evaluation found no error. */
+    /** Reports whether the last completed evaluation found no error. */
     get valid(): boolean;
-    /** Whether any answer has moved since the form opened. */
+    /** Reports whether any answer has moved since the form opened. */
     get dirty(): boolean;
     /**
-     * The answers, once the form settles.
+     * Holds the answers after the form settles.
      *
      * @remarks
      * It resolves with the submitted values on the first valid submit, and rejects with a
@@ -461,27 +525,27 @@ export declare class Form implements FormInterface {
      */
     get answer(): Promise<FormValues>;
     /**
-     * Find one field by name.
+     * Finds one field by name.
      *
      * @param name - The field's name.
      * @returns The field, or `undefined` when the schema declares no such name.
      */
     field(name: string): FormField | undefined;
     /**
-     * Answer several fields at once.
+     * Answers several fields at once.
      *
      * @param values - The answers to write, each keyed by its field name.
      */
     fill(values: FormValues): void;
     /**
-     * Answer one field.
+     * Answers one field.
      *
      * @param name - The field's name.
      * @param value - The answer to write, or `undefined` to clear it.
      */
     fill(name: string, value: FieldValue | undefined): void;
     /**
-     * Record that somebody has visited a field.
+     * Records that somebody has visited a field.
      *
      * @param name - The field's name.
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -489,7 +553,7 @@ export declare class Form implements FormInterface {
      */
     touch(name: string): void;
     /**
-     * Fail a field from outside, for what the rules cannot see.
+     * Fails a field from outside, for what the rules cannot see.
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
@@ -500,36 +564,36 @@ export declare class Form implements FormInterface {
      *   `FIELD` when the schema declares no such name.
      */
     invalidate(name: string, message: string): void;
-    /** Take every field out of the form. */
+    /** Takes every field out of the form. */
     disable(): void;
     /**
-     * Take one field out of the form.
+     * Takes one field out of the form.
      *
      * @param name - The field's name.
      */
     disable(name: string): void;
     /**
-     * Take several fields out of the form.
+     * Takes several fields out of the form.
      *
      * @param names - The field names.
      */
     disable(names: readonly string[]): void;
-    /** Put every field back into the form. */
+    /** Puts every field back into the form. */
     enable(): void;
     /**
-     * Put one field back into the form.
+     * Puts one field back into the form.
      *
      * @param name - The field's name.
      */
     enable(name: string): void;
     /**
-     * Put several fields back into the form.
+     * Puts several fields back into the form.
      *
      * @param names - The field names.
      */
     enable(names: readonly string[]): void;
     /**
-     * Check every answer and settle the form when they all pass.
+     * Checks every answer and settles the form when they all pass.
      *
      * @returns The values on success, or every error that stopped them.
      * @remarks
@@ -546,14 +610,14 @@ export declare class Form implements FormInterface {
      */
     submit(): FormResult;
     /**
-     * Return every answer to the ones the form opened with: the schema's defaults, overlaid with
+     * Returns every answer to the ones the form opened with: the schema's defaults, overlaid with
      * any seeded `values`. Reset the runtime disabled state to the schema's declarations.
      *
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
      */
     clear(): void;
     /**
-     * Tear the form down, abandoning it when it has not settled.
+     * Tears the form down, abandoning it when it has not settled.
      *
      * @remarks
      * Destroying twice does nothing the second time. A settled form keeps its `settled` status and
@@ -564,11 +628,15 @@ export declare class Form implements FormInterface {
     destroy(): void;
 }
 
-/** Every form lifecycle status. */
+/** Lists every form lifecycle status. */
 export declare const FORM_STATUSES: readonly FormStatus[];
 
 /**
- * Resolve and interpolate one rule message.
+ * Resolves and interpolates one rule message.
+ *
+ * @remarks
+ * A replacement in `messages` is read first and {@link RULE_MESSAGES} supplies the copy otherwise,
+ * and `{limit}` in whichever text wins is replaced with the rule's operand.
  *
  * @param rule - The rule whose message to resolve.
  * @param limit - The optional operand substituted for `{limit}`.
@@ -577,14 +645,26 @@ export declare const FORM_STATUSES: readonly FormStatus[];
  */
 export declare function formatMessage(rule: FieldRuleName, limit?: number | string, messages?: Readonly<Partial<Record<FieldRuleName, string>>>): string;
 
-/** An error raised by the form domain. */
+/**
+ * Represents an error raised by the form domain.
+ *
+ * @example
+ * ```ts
+ * const error = new FormError('FIELD', 'The schema declares no field named "nickname"', {
+ * 	field: 'nickname',
+ * })
+ *
+ * error.code // 'FIELD'
+ * error.context // { field: 'nickname' }
+ * ```
+ */
 export declare class FormError extends Error {
-    /** The machine-readable reason for this failure. */
+    /** Holds the machine-readable reason for this failure. */
     readonly code: FormErrorCode;
-    /** Structured values that locate or explain this failure. */
+    /** Holds structured values that locate or explain this failure. */
     readonly context?: JSONRecord;
     /**
-     * Create a form error.
+     * Creates a form error.
      *
      * @param code - The machine-readable reason.
      * @param message - The human-readable failure text.
@@ -594,7 +674,7 @@ export declare class FormError extends Error {
 }
 
 /**
- * The machine-readable code a form error carries.
+ * Names the machine-readable code a form error carries.
  *
  * @remarks
  * `SCHEMA` rejects a malformed schema. `FIELD` names a field the schema does not declare.
@@ -604,7 +684,7 @@ export declare class FormError extends Error {
 export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED';
 
 /**
- * Everything a form announces.
+ * Lists everything a form announces.
  *
  * @remarks
  * `fill` carries the field that changed and its new value, where `undefined` is the value
@@ -624,7 +704,7 @@ export declare type FormEventMap = {
 };
 
 /**
- * Any field a schema can declare.
+ * Represents any field a schema can declare.
  *
  * @remarks
  * The union discriminates on `control`, so narrowing on that member reaches each variant's
@@ -640,7 +720,7 @@ export declare type FormEventMap = {
 export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
 
 /**
- * A named section of a form.
+ * Represents a named section of a form.
  *
  * @remarks
  * A field joins a group through {@link FieldBase.group}. Grouping arranges the form and
@@ -653,7 +733,7 @@ export declare interface FormGroup {
 }
 
 /**
- * A form: a schema, the answers given against it, and the errors they carry.
+ * Declares the contract a form exposes: the state it holds and the calls that move it.
  *
  * @remarks
  * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
@@ -670,26 +750,26 @@ export declare interface FormGroup {
  * ```
  */
 export declare interface FormInterface {
-    /** The form's event emitter. */
+    /** Holds the form's event emitter. */
     readonly emitter: EmitterInterface<FormEventMap>;
-    /** The schema this form asks. */
+    /** Holds the schema this form asks. */
     readonly schema: FormSchema;
-    /** The answers held right now. */
+    /** Reports the answers the form holds. */
     readonly values: FormValues;
     /**
-     * The answers the form opened with: the schema's defaults, overlaid with any seeded values.
+     * Holds the answers the form opened with: the schema's defaults, overlaid with any seeded values.
      *
      * @remarks
      * It is fixed when the form opens and never moves again, so it is what `dirty` measures
      * against and what {@link FormInterface.clear} returns to.
      */
     readonly baseline: FormValues;
-    /** Every error the last check produced. */
+    /** Holds every error the last check produced. */
     readonly errors: readonly FieldError[];
-    /** The names of the fields somebody has visited. */
+    /** Lists the names of the fields somebody has visited. */
     readonly touched: ReadonlySet<string>;
     /**
-     * The names of the fields currently out of the form.
+     * Lists the names of the fields that are out of the form.
      *
      * @remarks
      * It opens as the set the schema declares through {@link FieldBase.disabled} and moves with
@@ -697,14 +777,14 @@ export declare interface FormInterface {
      * holds the declaration and this holds the current fact.
      */
     readonly disabled: ReadonlySet<string>;
-    /** Where the form sits in its life. */
+    /** Reports where the form sits in its life. */
     readonly status: FormStatus;
-    /** Whether the last completed evaluation found no error. */
+    /** Reports whether the last completed evaluation found no error. */
     readonly valid: boolean;
-    /** Whether any answer has moved since the form opened. */
+    /** Reports whether any answer has moved since the form opened. */
     readonly dirty: boolean;
     /**
-     * The answers, once the form settles.
+     * Holds the answers after the form settles.
      *
      * @remarks
      * It resolves with the submitted values on the first valid submit, and rejects when teardown
@@ -712,40 +792,44 @@ export declare interface FormInterface {
      */
     readonly answer: Promise<FormValues>;
     /**
-     * Find one field by name.
+     * Finds one field by name.
      *
      * @param name - The field's name.
      * @returns The field, or `undefined` when the schema declares no such name.
      */
     field(name: string): FormField | undefined;
     /**
-     * Answer several fields at once.
+     * Answers one field, or several at once.
      *
      * @param values - The answers to write, each keyed by its field name.
      */
     fill(values: FormValues): void;
     /**
-     * Answer one field.
+     * Answers one field.
      *
      * @param name - The field's name.
      * @param value - The answer to write, or `undefined` to clear it.
      */
     fill(name: string, value: FieldValue | undefined): void;
     /**
-     * Record that somebody has visited a field.
+     * Records that somebody has visited a field.
      *
      * @param name - The field's name.
      */
     touch(name: string): void;
     /**
-     * Fail a field from outside, for what the rules cannot see.
+     * Fails a field from outside, for what the rules cannot see.
+     *
+     * @remarks
+     * One field holds one external failure, so a second call replaces the first, and the failure
+     * lasts until that field is filled again or the form is cleared.
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
      */
     invalidate(name: string, message: string): void;
     /**
-     * Take every field out of the form.
+     * Takes one field, several fields, or every field out of the form.
      *
      * @remarks
      * A disabled field is neither evaluated nor submitted. Its answer is kept, and so is any
@@ -756,14 +840,14 @@ export declare interface FormInterface {
      */
     disable(): void;
     /**
-     * Take one field out of the form.
+     * Takes one field out of the form.
      *
      * @param name - The field's name.
      * @throws A {@link FormError} coded `FIELD` when the schema declares no such name.
      */
     disable(name: string): void;
     /**
-     * Take several fields out of the form.
+     * Takes several fields out of the form.
      *
      * @param names - The field names.
      * @throws A {@link FormError} coded `FIELD` when the schema declares no such name. Every name
@@ -771,7 +855,7 @@ export declare interface FormInterface {
      */
     disable(names: readonly string[]): void;
     /**
-     * Put every field back into the form.
+     * Puts one field, several fields, or every field back into the form.
      *
      * @remarks
      * An enabled field is evaluated and submitted again, and any invalidation held while it was
@@ -780,14 +864,14 @@ export declare interface FormInterface {
      */
     enable(): void;
     /**
-     * Put one field back into the form.
+     * Puts one field back into the form.
      *
      * @param name - The field's name.
      * @throws A {@link FormError} coded `FIELD` when the schema declares no such name.
      */
     enable(name: string): void;
     /**
-     * Put several fields back into the form.
+     * Puts several fields back into the form.
      *
      * @param names - The field names.
      * @throws A {@link FormError} coded `FIELD` when the schema declares no such name. Every name
@@ -795,33 +879,33 @@ export declare interface FormInterface {
      */
     enable(names: readonly string[]): void;
     /**
-     * Check every answer and settle the form when they all pass.
+     * Checks every answer and settles the form when they all pass.
      *
      * @returns The values on success, or every error that stopped them.
      */
     submit(): FormResult;
     /**
-     * Return every answer to {@link FormInterface.baseline}, the answers the form opened with.
+     * Returns every answer to the ones the form opened with.
      *
      * @remarks
-     * The runtime disabled overlay resets with them, so {@link FormInterface.disabled} reads the
-     * schema's declarations again.
+     * Those answers are {@link FormInterface.baseline}. The runtime disabled overlay resets with
+     * them, so {@link FormInterface.disabled} reads the schema's declarations again.
      */
     clear(): void;
     /**
-     * Tear the form down, abandoning it when it has not settled.
+     * Tears the form down, abandoning it when it has not settled.
      *
      * @remarks
-     * A request from inside a listener defers teardown until the outermost mutation batch closes,
-     * so an in-flight settlement can win and leave the form `settled` rather than `abandoned`.
+     * Tearing down twice does nothing the second time. A request from inside a listener defers
+     * teardown until the outermost mutation batch closes, so an in-flight settlement can win and
+     * leave the form `settled` rather than `abandoned`.
      */
     destroy(): void;
 }
 
 /**
- * How to open a form.
+ * Describes how to open a form.
  *
- * @param options - The form's settings.
  * @remarks
  * `on` wires listeners at construction and `error` receives any throw from one of them.
  * `values` seeds the answers, overriding each field's declared default. `messages` replaces
@@ -844,7 +928,7 @@ export declare interface FormOptions {
 }
 
 /**
- * What a submit answers with: the values, or every error that stopped them.
+ * Reports what a submit answers with: the values, or every error that stopped them.
  *
  * @example
  * ```ts
@@ -855,7 +939,7 @@ export declare interface FormOptions {
 export declare type FormResult = Result<FormValues, readonly FieldError[]>;
 
 /**
- * Everything a form asks.
+ * Describes everything a form asks.
  *
  * @remarks
  * `fields` is the schema's only required member, and the order it declares is the order the
@@ -881,7 +965,7 @@ export declare interface FormSchema {
 }
 
 /**
- * Where a form sits in its life.
+ * Represents where a form sits in its life.
  *
  * @remarks
  * A form opens `editing`, turns `settled` on its first valid submit, and turns `abandoned`
@@ -895,7 +979,7 @@ export declare interface FormSchema {
 export declare type FormStatus = 'editing' | 'settled' | 'abandoned';
 
 /**
- * A form's answers, keyed by field name.
+ * Represents a form's answers, keyed by field name.
  *
  * @remarks
  * A name with no key is a field nobody has answered. A disabled field's value may appear so a
@@ -908,62 +992,86 @@ export declare type FormStatus = 'editing' | 'settled' | 'abandoned';
  */
 export declare type FormValues = Readonly<Record<string, FieldValue>>;
 
-/** The maximum number of groups one schema may declare. */
+/**
+ * Writes one own enumerable data property that cannot be rewritten or removed.
+ *
+ * @param target - The record to write into.
+ * @param name - The property name to write.
+ * @param value - The value to store.
+ *
+ * @remarks
+ * The prototype-safe write of {@link defineEntry}, frozen: the entry is neither writable nor
+ * configurable, so the record a parser hands back cannot be edited through the key it filled.
+ *
+ * @example
+ * ```ts
+ * const values: Record<string, number> = {}
+ * freezeEntry(values, '__proto__', 1)
+ * Object.getOwnPropertyDescriptor(values, '__proto__')?.writable // false
+ * ```
+ */
+export declare function freezeEntry<T>(target: Record<string, T>, name: string, value: T): void;
+
+/** Caps the number of groups one schema may declare, at 64. */
 export declare const GROUP_LIMIT = 64;
 
-/** A signed or unsigned base-ten integer string. */
+/** Matches a signed or unsigned base-ten integer string. */
 export declare const INTEGER_PATTERN: Readonly<RegExp>;
 
 /**
- * Determine whether an unknown value is one exact field choice record.
+ * Determines whether an unknown value is one exact field choice record.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a field choice.
+ * @returns True if the value is a field choice; false otherwise.
  */
 export declare function isFieldChoice(input: unknown): input is FieldChoice;
 
 /**
- * Determine whether an unknown value is a declared field control.
+ * Determines whether an unknown value is a declared field control.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a field control.
+ * @returns True if the value is a field control; false otherwise.
  */
 export declare function isFieldControl(input: unknown): input is FieldControl;
 
 /**
- * Determine whether an unknown value is one exact field error record.
+ * Determines whether an unknown value is one exact field error record.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a field error.
+ * @returns True if the value is a field error; false otherwise.
  */
 export declare function isFieldError(input: unknown): input is FieldError;
 
 /**
- * Determine whether an unknown value is one exact field rule record.
+ * Determines whether an unknown value is one exact field rule record.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a structurally valid field rule.
+ * @returns True if the value is a structurally valid field rule; false otherwise.
  */
 export declare function isFieldRule(input: unknown): input is FieldRule;
 
 /**
- * Determine whether an unknown value has a form field value shape.
+ * Determines whether an unknown value has a form field value shape.
+ *
+ * @remarks
+ * A string, a finite number, a boolean, and a list of strings each qualify. A number that is not
+ * finite does not, so `NaN` and `Infinity` are refused.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a field value.
+ * @returns True if the value is a field value; false otherwise.
  */
 export declare function isFieldValue(input: unknown): input is FieldValue;
 
 /**
- * Determine whether an unknown value is a form error.
+ * Determines whether an unknown value is a form error.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a {@link FormError} instance.
+ * @returns True if the value is a {@link FormError} instance; false otherwise.
  */
 export declare function isFormError(input: unknown): input is FormError;
 
 /**
- * Determine whether an unknown value is one exact discriminated form field.
+ * Determines whether an unknown value is one exact discriminated form field.
  *
  * @remarks
  * Metadata is admitted structurally as bounded JSON. An accessor-bearing metadata record is
@@ -971,47 +1079,51 @@ export declare function isFormError(input: unknown): input is FormError;
  * data properties only.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a structurally valid form field.
+ * @returns True if the value is a structurally valid form field; false otherwise.
  */
 export declare function isFormField(input: unknown): input is FormField;
 
 /**
- * Determine whether an unknown value is one exact form group record.
+ * Determines whether an unknown value is one exact form group record.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a form group.
+ * @returns True if the value is a form group; false otherwise.
  */
 export declare function isFormGroup(input: unknown): input is FormGroup;
 
 /**
- * Determine whether an unknown value is one exact structural form schema.
+ * Determines whether an unknown value is one exact structural form schema.
+ *
+ * @remarks
+ * Structure alone is read. Domain soundness — a duplicate name, a bound no answer satisfies, a
+ * breached budget — is {@link auditSchema}'s question.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a structurally valid form schema.
+ * @returns True if the value is a structurally valid form schema; false otherwise.
  */
 export declare function isFormSchema(input: unknown): input is FormSchema;
 
 /**
- * Determine whether an unknown value is a form lifecycle status.
+ * Determines whether an unknown value is a form lifecycle status.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a form status.
+ * @returns True if the value is a form status; false otherwise.
  */
 export declare function isFormStatus(input: unknown): input is FormStatus;
 
 /**
- * Determine whether an unknown value is a record of field values.
+ * Determines whether an unknown value is a record of field values.
  *
  * @param input - The value to inspect.
- * @returns Whether the value is a form values record.
+ * @returns True if the value is a form values record; false otherwise.
  */
 export declare function isFormValues(input: unknown): input is FormValues;
 
-/** The maximum number of entries one list-valued answer may hold. */
+/** Caps the number of entries one list-valued answer may hold, at 1024. */
 export declare const LIST_LIMIT = 1024;
 
 /**
- * Decide whether a raw binding value projects to an answered field.
+ * Decides whether a raw binding value projects to an answered field.
  *
  * @remarks
  * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
@@ -1020,44 +1132,48 @@ export declare const LIST_LIMIT = 1024;
  * its `required` rule remains presence-only.
  *
  * @param value - The raw field value, or absence.
- * @returns Whether the binding should preserve the value as an answer.
+ * @returns True if the binding preserves the value as an answer; false otherwise.
  */
 export declare function matchesAnswer(value: FieldValue | undefined): boolean;
 
 /**
- * Check whether a value has the shape required by one field control.
+ * Checks whether a value has the shape required by one field control.
+ *
+ * @remarks
+ * Every write and every seeded value passes through this gate, and it reads `STRING_LIMIT` and
+ * `LIST_LIMIT` before it consults the control, so no regular expression sees an over-long value.
  *
  * @param field - The field that owns the value.
  * @param value - The unknown value to inspect.
- * @returns Whether the control can hold the value.
+ * @returns True if the control can hold the value; false otherwise.
  */
 export declare function matchesField(field: FormField, value: unknown): value is FieldValue;
 
 /**
- * Compare two field values by scalar identity or ordered list content.
+ * Compares two field values by scalar identity or ordered list content.
  *
  * @param a - The first field value.
  * @param b - The second field value.
- * @returns Whether both values contain the same answer.
+ * @returns True if both values contain the same answer; false otherwise.
  */
 export declare function matchesValue(a: FieldValue, b: FieldValue): boolean;
 
 /**
- * Compare two form value records by keys and value content.
+ * Compares two form value records by keys and value content.
  *
  * @param a - The first value record.
  * @param b - The second value record.
- * @returns Whether both records contain the same answers.
+ * @returns True if both records contain the same answers; false otherwise.
  */
 export declare function matchesValues(a: FormValues, b: FormValues): boolean;
 
-/** The maximum length, in UTF-16 code units, of a schema, group, or field name. */
+/** Caps the length, in UTF-16 code units, of a schema, group, or field name, at 128. */
 export declare const NAME_LIMIT = 128;
 
-/** The maximum total number of records, arrays, and leaves one schema retains. */
+/** Caps the total number of records, arrays, and leaves one schema retains, at 16384. */
 export declare const NODE_LIMIT = 16384;
 
-/** A number. */
+/** Represents a number. */
 export declare interface NumberField extends FieldBase {
     readonly control: 'number';
     readonly default?: number;
@@ -1065,7 +1181,7 @@ export declare interface NumberField extends FieldBase {
 }
 
 /**
- * Parse unknown wire data into an owned, semantically sound form schema.
+ * Parses unknown wire data into an owned, semantically sound form schema.
  *
  * @param input - The unknown schema value to parse.
  * @returns An owned schema with custom rules removed, or `undefined` on refusal.
@@ -1073,7 +1189,11 @@ export declare interface NumberField extends FieldBase {
 export declare function parseForm(input: unknown): FormSchema | undefined;
 
 /**
- * Parse one answer against its field control.
+ * Parses one answer against its field control.
+ *
+ * @remarks
+ * A numeric string coerces to a number for a `number` field, and `'true'` and `'false'` coerce to
+ * a boolean for a `confirm` field. Every other value must already have its control's shape.
  *
  * @param field - The field that defines the accepted value.
  * @param input - The unknown value to parse.
@@ -1082,7 +1202,7 @@ export declare function parseForm(input: unknown): FormSchema | undefined;
 export declare function parseValue(field: FormField, input: unknown): FieldValue | undefined;
 
 /**
- * Parse a strict answer record against the fields declared by a schema.
+ * Parses a strict answer record against the fields declared by a schema.
  *
  * @param schema - The schema that owns the accepted field names and controls.
  * @param input - The unknown answer record to parse.
@@ -1091,7 +1211,7 @@ export declare function parseValue(field: FormField, input: unknown): FieldValue
 export declare function parseValues(schema: FormSchema, input: unknown): FormValues | undefined;
 
 /**
- * A secret, obscured as it is typed.
+ * Represents a secret, obscured as it is typed.
  *
  * @remarks
  * It carries no `default` deliberately: a seeded secret is a secret written down. `mask` is
@@ -1102,14 +1222,14 @@ export declare interface PasswordField extends FieldBase {
     readonly mask?: string;
 }
 
-/** The maximum accepted source length for an authored regular expression. */
+/** Caps the accepted source length for an authored regular expression, at 256. */
 export declare const PATTERN_LIMIT = 256;
 
-/** Default failure copy for every named field rule. */
+/** Holds the default failure copy for every named field rule. */
 export declare const RULE_MESSAGES: Readonly<Record<FieldRuleName, string>>;
 
 /**
- * One choice out of a list.
+ * Represents one choice out of a list.
  *
  * @remarks
  * `open` admits a value the list does not offer, which is what turns a closed menu into a
@@ -1123,7 +1243,7 @@ export declare interface SelectField extends FieldBase {
 }
 
 /**
- * Project a schema into JSON while removing custom validators and absent values.
+ * Projects a schema into JSON while removing custom validators and absent values.
  *
  * @param schema - The schema to project.
  * @returns A deep JSON copy of the serializable schema.
@@ -1132,29 +1252,29 @@ export declare interface SelectField extends FieldBase {
  */
 export declare function serializeForm(schema: FormSchema): JSONRecord;
 
-/** The maximum length, in UTF-16 code units, of any single retained string. */
+/** Caps the length, in UTF-16 code units, of any single retained string, at 65536. */
 export declare const STRING_LIMIT = 65536;
 
-/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+/** Caps the total length, in UTF-16 code units, of every string one schema retains, at 1048576. */
 export declare const TEXT_LIMIT = 1048576;
 
-/** A single line of text. */
+/** Represents a single line of text. */
 export declare interface TextField extends FieldBase {
     readonly control: 'text';
     readonly default?: string;
     readonly placeholder?: string;
 }
 
-/** A 24-hour time string with optional seconds. */
+/** Matches a 24-hour time string with optional seconds. */
 export declare const TIME_PATTERN: Readonly<RegExp>;
 
-/** A time of day, held as the control's own string. */
+/** Represents a time of day, held as the control's own `HH:MM` string, with seconds optional. */
 export declare interface TimeField extends FieldBase {
     readonly control: 'time';
     readonly default?: string;
 }
 
-/** An absolute HTTP or HTTPS URL shape. */
+/** Matches an absolute HTTP or HTTPS URL shape. */
 export declare const URL_PATTERN: Readonly<RegExp>;
 
 export { }