@typed/ui 1.0.0-beta.6 → 1.0.0-beta.7

package/dist/Form.d.ts

@@ -1,148 +1,174 @@
+/**
+ * Schema-bound native controls, decoded values, field errors, and submit lifetime.
+ * Start with make for application forms; explicit-state controls support library boundaries.
+ * Browser FormData conversion and structured input codecs are separate APIs.
+ *
+ * Read the [Form guide](/explore/ui-form) for a complete example.
+ *
+ * [Platform reference](https://html.spec.whatwg.org/multipage/forms.html#the-form-element).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
 import * as Effect from "effect/Effect";
 import * as Context from "effect/Context";
 import * as Schema from "effect/Schema";
 import { RefSubject } from "@typed/fx";
-import type * as Scope from "effect/Scope";
+import * as Scope from "effect/Scope";
 import type { Fx } from "@typed/fx/Fx";
 import { EventHandler, type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
 import * as Dom from "./Dom.js";
 import type { HostResult } from "./Dom/Types.js";
 /**
- * Interaction metadata tracked for one form field.
+ * Metadata updated after a successful field mutation.
  *
  * @remarks
- * ## Why
- * Dirty and touched state belong to renderer-independent form state so they can
- * be tested without mounting UI and consumed by any host.
- *
- * ## Ownership and lifetime
- * Stored inside `FormState`; updates are owned by that RefSubject's Scope and
- * survive replacement of individual rendered controls.
- *
+ * dirty compares the new field value with defaultValues using !==, so object and array
+ * comparisons are by identity. touched becomes true for both user and programmatic updates; it
+ * is not specifically a blur flag.
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export interface FieldMeta {
-    /** Stored mutation flag for the field; update operations decide when it becomes true. */
+    /**
+     * Whether the updated value differs from its default under !== comparison.
+     */
     readonly dirty: boolean;
-    /** Whether user or programmatic field mutation has occurred. */
+    /**
+     * Whether user or programmatic field mutation has occurred.
+     */
     readonly touched: boolean;
 }
 /**
  * Serializable renderer-independent state of a form.
  *
  * @remarks
- * ## Why
  * Values, defaults, validation messages, interaction metadata, and submission
  * state can be inspected and tested without rendering a component.
  *
- * ## Ownership and lifetime
  * A `FormState` RefSubject owns this value. Renderers subscribe to it; they do
  * not contain or become the source of truth.
- *
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export interface State<Values extends object = object> {
-    /** Current decoded field values. */
+    /**
+     * Current decoded field values.
+     */
     readonly values: Values;
-    /** Exact baseline reference used by reset and retained independently from current values. */
+    /**
+     * Exact baseline reference used by reset and retained independently from current values.
+     */
     readonly defaultValues: Values;
-    /** Current validation messages keyed by field name. */
+    /**
+     * Current validation messages keyed by field name.
+     */
     readonly errors: Partial<Record<keyof Values & string, string>>;
-    /** Dirty/touched metadata keyed by field name. */
+    /**
+     * Dirty/touched metadata keyed by field name.
+     */
     readonly meta: Partial<Record<keyof Values & string, FieldMeta>>;
-    /** Whether a valid-submit Effect is currently running. */
+    /**
+     * Whether validation or the returned submit Effect is running.
+     */
     readonly submitting: boolean;
 }
 /**
  * Input used to construct a hydrated form state.
  *
  * @remarks
- * ## Why
  * Defaults make the common case concise while allowing SSR callers to provide
  * deterministic identity and server-known validation state.
  *
- * ## Ownership and lifetime
  * `values` and an explicit `defaultValues` are retained by reference, including
  * their nested objects. When `defaultValues` is omitted, both state fields
  * initially reference the exact `values` object. Subsequent helpers replace the
  * top-level `values` record but do not deep-clone nested values.
- *
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export interface InitialState<Values extends object> {
-    /** Stable relationship/hydration id; provide it for deterministic SSR. */
+    /**
+     * Stable relationship/hydration id; provide it for deterministic SSR.
+     */
     readonly id?: string;
-    /** Initial decoded values. */
+    /**
+     * Initial decoded values.
+     */
     readonly values: Values;
-    /** Exact reset-baseline reference; defaults to the same object as `values`. */
+    /**
+     * Exact reset-baseline reference; defaults to the same object as `values`.
+     */
     readonly defaultValues?: Values;
-    /** Optional initial validation messages. */
+    /**
+     * Optional initial validation messages.
+     */
     readonly errors?: Partial<Record<keyof Values & string, string>>;
-    /** Optional initial field metadata. */
+    /**
+     * Optional initial field metadata.
+     */
     readonly meta?: Partial<Record<keyof Values & string, FieldMeta>>;
-    /** Optional initial submission state. */
+    /**
+     * Whether validation or the returned submit Effect is running.
+     */
     readonly submitting?: boolean;
 }
 /**
  * Hydrated RefSubject carrying form state plus runtime schema metadata.
  *
  * @remarks
- * ## Why
  * State is serializable across SSR while codecs and field validators stay as
  * runtime capabilities. This keeps validation type-safe without trying to
  * serialize executable schemas.
  *
- * ## Ownership and lifetime
  * The surrounding Effect Scope owns the hydrated RefSubject and its subscribers.
  * On the server, serializable state is emitted for hydration; on the client it
  * must be restored before mounted controls begin producing updates.
- *
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export type FormState<Values extends object> = RefSubject.HydratedRefSubject<State<Values>, Schema.SchemaError> & {
-    /** Runtime identity used to scope field/error relationships. Pass an id for deterministic SSR. */
+    /**
+     * Runtime identity used to scope field/error relationships. Pass an id for deterministic SSR.
+     */
     readonly id: string;
-    /** Runtime-only validation codec; it is deliberately absent from hydration state. */
+    /**
+     * Runtime-only validation codec; it is deliberately absent from hydration state.
+     */
     readonly codec: Schema.Codec<Values, unknown>;
-    /** Runtime field codecs used for field-level validation. */
+    /**
+     * Runtime field codecs used for field-level validation.
+     */
     readonly fields: Readonly<Record<keyof Values & string, Schema.Codec<any, any>>>;
 };
 /**
  * Context service exposed to schema-bound descendant controls.
  *
  * @remarks
- * ## Why
  * A bound form can share its state through Effect context without a component tree.
  *
- * ## Ownership and lifetime
  * The root form provides the service only for its rendered Fx lifetime; it does
  * not own the underlying state beyond that state's Scope.
- *
  * @since 1.0.0
- * @category services
+ * @category Form context
  */
 export interface FormService<Values extends object> {
-    /** Form state visible to bound descendants. */
+    /**
+     * Form state visible to bound descendants.
+     */
     readonly state: FormState<Values>;
 }
 /**
  * Effect context service used by schema-bound form controls.
  *
  * @remarks
- * ## Why
  * Bound controls avoid threading `state` through every call while their
  * service requirement remains visible in the Fx type.
  *
- * ## Ownership and lifetime
  * `Form` provides the service for its child render lifetime; use outside that
  * boundary fails with the ordinary Effect missing-service defect.
- *
  * @since 1.0.0
- * @category services
+ * @category Form context
  */
 export declare const CurrentForm: Context.Service<FormService<any>, FormService<any>>;
 declare const FieldMetaSchema: Schema.Struct<{
@@ -153,14 +179,11 @@ declare const FieldMetaSchema: Schema.Struct<{
  * Schema field map accepted by the schema-bound form factory.
  *
  * @remarks
- * ## Why
  * A Struct's individual codecs drive field-name inference and field-level decoding.
  *
- * ## Ownership and lifetime
  * Codecs are runtime values retained by the created form API; they are not hydrated.
- *
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export type FormFields = Readonly<Record<string, Schema.Codec<any, any>>>;
 type OptionalFields<Fields extends FormFields, Value extends Schema.Constraint> = {
@@ -178,10 +201,8 @@ type InitialStateFor<Fields extends FormFields> = {
  * Builds the serializable schema for a form's hydrated state.
  *
  * @remarks
- * ## Why
  * The hydration payload needs validation independent from runtime-only field codecs.
  *
- * ## Ownership and lifetime
  * Pure schema construction; the returned Schema acquires no Scope or subscription.
  *
  * @example
@@ -192,9 +213,8 @@ type InitialStateFor<Fields extends FormFields> = {
  * const codec = Schema.Struct({ email: Schema.String })
  * const stateCodec = StateSchema(codec)
  * ```
- *
  * @since 1.0.0
- * @category schemas
+ * @category Hydration schemas
  */
 export declare function StateSchema<const Fields extends FormFields>(codec: Schema.Struct<Fields>): Schema.Struct<{
     readonly values: Schema.Struct<Fields>;
@@ -210,11 +230,9 @@ export declare function StateSchema<const Fields extends FormFields>(codec: Sche
  * Creates a Scope-owned hydrated form RefSubject from a Struct codec.
  *
  * @remarks
- * ## Why
  * One constructor establishes values, defaults, validation state, field codecs,
  * and hydration identity consistently.
  *
- * ## Ownership and lifetime
  * Requires `Scope.Scope`. Provide an explicit `id` during SSR; the counter-based
  * fallback is process/order dependent. Only state data hydrates—`codec` and
  * `fields` are reattached from the live Struct on each runtime.
@@ -230,9 +248,8 @@ export declare function StateSchema<const Fields extends FormFields>(codec: Sche
  *   return state
  * })
  * ```
- *
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export declare function makeState<const Fields extends FormFields>(codec: Schema.Struct<Fields>, initial: InitialStateFor<Fields>): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly values: Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>;
@@ -276,14 +293,9 @@ export declare function makeState<const Fields extends FormFields>(codec: Schema
  * Field names whose decoded value is assignable to `Value`.
  *
  * @remarks
- * ## Why
  * Control options reject incompatible fields at compile time.
- *
- * ## Ownership and lifetime
- * Type-only and resource-free.
- *
  * @since 1.0.0
- * @category type-level
+ * @category Field types
  */
 export type FieldNameFor<Values extends object, Value> = {
     [Key in keyof Values & string]: Values[Key] extends Value ? Key : never;
@@ -292,242 +304,242 @@ export type FieldNameFor<Values extends object, Value> = {
  * Struct field names matching both decoded and encoded control value types.
  *
  * @remarks
- * ## Why
  * Schema-bound controls require an encoded form compatible with the native element.
- *
- * ## Ownership and lifetime
- * Type-only and resource-free.
- *
  * @since 1.0.0
- * @category type-level
+ * @category Field types
  */
 export type SchemaFieldNameFor<Fields extends FormFields, Value, Encoded> = {
     [Key in keyof Fields & string]: Fields[Key]["Type"] extends Value ? Fields[Key]["Encoded"] extends Encoded ? Key : never : never;
 }[keyof Fields & string];
 /**
- * Options shared by state-explicit native input components.
+ * State-explicit native input binding with a compatible field name and optional string codec.
  *
  * @remarks
- * ## Why
- * Controls bind a typed field directly to renderer-independent state while
- * leaving every ordinary input prop and native event available.
- *
- * ## Ownership and lifetime
- * The rendered control subscribes within its Scope. `state` remains independently
- * owned and may outlive that control; custom codecs are retained for that host.
- *
+ * Successful native input decoding updates values and metadata; failure records an error while
+ * retaining the last decoded value. Rendering encodes the retained value into .value, so
+ * arbitrary invalid draft text is not guaranteed to remain visible. Native constraints and codec
+ * validation are separate boundaries.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface InputOptions<Values extends object, Value> extends Dom.HostOptions<HTMLInputElement> {
-    /** Renderer-independent form state to read and update. */
+    /**
+     * Renderer-independent form state to read and update.
+     */
     readonly state: FormState<Values>;
-    /** Type-compatible field name. */
+    /**
+     * Type-compatible field name.
+     */
     readonly name: FieldNameFor<Values, Value>;
-    /** Optional string codec overriding the input type's default codec. */
+    /**
+     * Optional string codec overriding the input type's default codec.
+     */
     readonly codec?: Schema.Codec<Value, string>;
 }
 /**
  * String-valued native input options.
  * @remarks
- * ## Why
  * Names are restricted to fields a text-like control can represent without an incompatible cast.
- * ## Ownership and lifetime
  * The control Scope owns DOM work; the referenced state and optional codec are borrowed.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export type TextInputOptions<Values extends object> = InputOptions<Values, string>;
 /**
  * Finite-number native input options.
  * @remarks
- * ## Why
  * Names are restricted to numeric fields compatible with number/range decoding.
- * ## Ownership and lifetime
  * The control Scope owns DOM work; the referenced state and optional codec are borrowed.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export type NumberInputOptions<Values extends object> = InputOptions<Values, number>;
 /**
  * Date-valued native input options.
  * @remarks
- * ## Why
  * Names are restricted to Date fields compatible with native date-string decoding.
- * ## Ownership and lifetime
  * The control Scope owns DOM work; the referenced state and optional codec are borrowed.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export type DateInputOptions<Values extends object> = InputOptions<Values, Date>;
-declare function inputProps<Values extends object, Value>(options: InputOptions<Values, Value>, type: string, codec: Schema.Codec<Value, string>): () => {
+declare function inputProps<Values extends object, Value>(options: InputOptions<Values, Value>, type: string, codec: Schema.Codec<Value, string>): (() => {
     readonly type: string;
     readonly name: FieldNameFor<Values, Value>;
     readonly "aria-describedby": RefSubject.Computed<string | undefined, Schema.SchemaError, never>;
     readonly "aria-invalid": RefSubject.Computed<true | undefined, Schema.SchemaError, never>;
     readonly ".value": RefSubject.Computed<string, Schema.SchemaError, never>;
     readonly oninput: EventHandler.EventHandler<Event, Schema.SchemaError, never>;
-};
+}) | (() => {
+    readonly type: string;
+    readonly name: FieldNameFor<Values, Value>;
+    readonly "aria-describedby": RefSubject.Computed<string | undefined, Schema.SchemaError, never>;
+    readonly "aria-invalid": RefSubject.Computed<true | undefined, Schema.SchemaError, never>;
+    readonly ".value": Effect.Effect<string, Schema.SchemaError, never>;
+    readonly ref: (element: HTMLInputElement) => Effect.Effect<void, Schema.SchemaError, Scope.Scope>;
+    readonly onbeforeinput: EventHandler.EventHandler<InputEvent, Schema.SchemaError, never>;
+    readonly oninput: EventHandler.EventHandler<InputEvent, Schema.SchemaError, never>;
+    readonly oncompositionstart: EventHandler.EventHandler<Event, never, never>;
+    readonly oncompositionend: EventHandler.EventHandler<CompositionEvent, Schema.SchemaError, never>;
+});
 type InputProps<Values extends object, Value> = ReturnType<ReturnType<typeof inputProps<Values, Value>>>;
 type RenderableComponentOptions<Options> = Pick<Options, Extract<keyof Options, "props" | "ref" | "content" | Dom.EventHandlerProperty>>;
 /**
  * Options for a schema-bound native input.
  *
  * @remarks
- * ## Why
  * The factory's Struct infers compatible field names, so callers need not pass state or a codec.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the control's Scope owns its DOM subscription.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundInputOptions<Fields extends FormFields, Value> extends Dom.HostOptions<HTMLInputElement> {
-    /** Struct field whose decoded type matches `Value` and whose encoded type is string. */
+    /**
+     * Struct field whose decoded type matches `Value` and whose encoded type is string.
+     */
     readonly name: SchemaFieldNameFor<Fields, Value, string>;
 }
 /**
  * Options for a schema-bound masked text input.
  *
  * @remarks
- * ## Why
  * Any field with a string encoding can use the Struct field codec as its mask codec.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the control Scope owns DOM work.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundMaskedInputOptions<Fields extends FormFields> extends Dom.HostOptions<HTMLInputElement> {
-    /** Struct field whose codec accepts the input's string representation. */
+    /**
+     * Struct field whose codec accepts the input's string representation.
+     */
     readonly name: SchemaFieldNameFor<Fields, unknown, string>;
 }
 /**
  * Options for a schema-bound boolean checkbox.
  *
  * @remarks
- * ## Why
  * Field-name inference limits the native checked binding to boolean fields.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the control Scope owns DOM work.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundCheckboxOptions<Values extends object> extends Dom.HostOptions<HTMLInputElement> {
-    /** Boolean field controlled by the checkbox. */
+    /**
+     * Boolean field controlled by the checkbox.
+     */
     readonly name: BooleanFieldName<Values>;
 }
 /**
  * Options for a schema-bound native select.
  *
  * @remarks
- * ## Why
  * Native option markup remains caller-authored while selection binds to a string field.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; rendered content is owned by the control Scope.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundSelectOptions<Values extends object> extends Dom.HostOptions<HTMLSelectElement> {
-    /** String field controlled by the select. */
+    /**
+     * String field controlled by the select.
+     */
     readonly name: FieldNameFor<Values, string>;
-    /** Native option/optgroup renderable content. */
+    /**
+     * Native option/optgroup renderable content.
+     */
     readonly content: Renderable.Any;
 }
 /**
  * Options for a schema-bound field-error region.
  *
  * @remarks
- * ## Why
  * Error text and ARIA relationships derive from the same form identity and field name.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the error host Scope owns its subscription.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundErrorOptions<Values extends object> extends Dom.HostOptions<HTMLDivElement> {
-    /** Field whose current validation message is rendered. */
+    /**
+     * Field whose current validation message is rendered.
+     */
     readonly name: keyof Values & string;
 }
 /**
  * Options for a schema-bound reset button.
  *
  * @remarks
- * ## Why
  * The button can use native semantics without receiving state explicitly.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; button content is Scope-owned renderable work.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundResetOptions extends Dom.HostOptions<HTMLButtonElement> {
-    /** Reset button label/content. */
+    /**
+     * Reset button label/content.
+     */
     readonly content: Renderable.Any;
 }
 /**
  * Options for a schema-bound array append button.
  *
  * @remarks
- * ## Why
  * Array field and element types are inferred from the form schema.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the click Effect and content share the host Scope.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundPushOptions<Values extends object, Name extends ArrayFieldName<Values>> extends Dom.HostOptions<HTMLButtonElement> {
-    /** Array-valued field to append to. */
+    /**
+     * Array-valued field to append to.
+     */
     readonly name: Name;
-    /** Type-compatible item appended on activation. */
+    /**
+     * Type-compatible item appended on activation.
+     */
     readonly value: ArrayFieldValue<Values, Name>;
-    /** Button label/content. */
+    /**
+     * Button label/content.
+     */
     readonly content: Renderable.Any;
 }
 /**
  * Options for a schema-bound array removal button.
  *
  * @remarks
- * ## Why
  * The field is constrained to arrays and the index remains an explicit local operation.
  *
- * ## Ownership and lifetime
  * State is borrowed from `CurrentForm`; the click Effect and content share the host Scope.
- *
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SchemaBoundRemoveOptions<Values extends object, Name extends ArrayFieldName<Values>> extends Dom.HostOptions<HTMLButtonElement> {
-    /** Array-valued field to remove from. */
+    /**
+     * Array-valued field to remove from.
+     */
     readonly name: Name;
-    /** Zero-based item index removed on activation. */
+    /**
+     * Zero-based item index removed on activation.
+     */
     readonly index: number;
-    /** Button label/content. */
+    /**
+     * Button label/content.
+     */
     readonly content: Renderable.Any;
 }
 /**
  * Public component contract shared by state-explicit native input factories.
  *
  * @remarks
- * ## Why
- *
  * Text-like, numeric, range, and date controls differ in their default codec while preserving one
  * field-inference, host-override, error, and service contract. Naming that contract keeps emitted
  * declarations readable without hiding any generic channel behind a private compiler alias.
  *
- * ## Ownership and lifetime
- *
  * Calling an input component starts no work. The returned Fx requires the Scope and RenderTemplate
  * that own DOM rendering; the supplied FormState remains independently owned and may outlive it.
  *
@@ -545,20 +557,17 @@ export interface SchemaBoundRemoveOptions<Values extends object, Name extends Ar
  *   return Text({ state, name: "name" }, (props) => html`<input ...${props} />`)
  * })
  * ```
- *
  * @since 1.0.0
- * @category models
+ * @category Native controls
  */
 export type InputComponent<Value> = <const Values extends object, const Options extends InputOptions<Values, Value>, const Host extends HostResult = never>(options: Options & Pick<InputOptions<Values, Value>, "state" | "name">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, InputProps<Values, Value>>, "", Host>) => Fx<RenderEvent, Schema.SchemaError | Renderable.Error<RenderableComponentOptions<Options> | Host>, Renderable.Services<RenderableComponentOptions<Options> | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Binds a native `input[type=text]` to a string field.
  *
  * @remarks
- * ## Why
  * The control uses the browser's real input event and a Schema codec while
  * keeping state independently testable.
  *
- * ## Ownership and lifetime
  * The control Scope owns DOM listeners/subscriptions; the supplied `FormState`
  * may outlive the rendered input. A custom host must apply all merged props.
  *
@@ -573,195 +582,142 @@ export type InputComponent<Value> = <const Values extends object, const Options
  *   return TextInput({ state, name: "name" })
  * })
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const TextInput: InputComponent<string>;
 /**
  * Binds a native search input to a string field.
  * @remarks
- * ## Why
  * Preserves the platform's search-input semantics while sharing Typed validation.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const SearchInput: InputComponent<string>;
 /**
  * Binds a native email input to a string field.
  * @remarks
- * ## Why
  * Keeps browser email affordances and constraints available alongside Schema validation.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const EmailInput: InputComponent<string>;
 /**
  * Binds a native URL input to a string field.
  * @remarks
- * ## Why
  * Keeps browser URL affordances while the schema remains the decoded state contract.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const UrlInput: InputComponent<string>;
 /**
  * Binds a native telephone input to a string field.
  * @remarks
- * ## Why
  * Preserves platform telephone keyboards and autocomplete behavior.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const TelInput: InputComponent<string>;
 /**
  * Binds a native password input to a string field.
  * @remarks
- * ## Why
  * Uses browser password handling instead of recreating sensitive-input behavior.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const PasswordInput: InputComponent<string>;
 /**
  * Binds a native hidden input to a string field.
  * @remarks
- * ## Why
  * Allows standards-based form serialization for non-visible values.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const HiddenInput: InputComponent<string>;
 /**
  * Binds a native color input to a string field.
  * @remarks
- * ## Why
  * Retains the browser's color picker while state receives its string value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const ColorInput: InputComponent<string>;
 /**
  * Binds a native time input to a string field.
  * @remarks
- * ## Why
  * Preserves browser locale and time-entry behavior without inventing a picker.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const TimeInput: InputComponent<string>;
 /**
  * Binds a native local date-time input to a string field.
  * @remarks
- * ## Why
  * Keeps the platform's local date-time UI and its standard encoded value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const DateTimeLocalInput: InputComponent<string>;
 /**
  * Binds a native month input to a string field.
  * @remarks
- * ## Why
  * Preserves the browser month picker and standardized string encoding.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const MonthInput: InputComponent<string>;
 /**
  * Binds a native week input to a string field.
  * @remarks
- * ## Why
  * Preserves platform week-entry behavior and standardized string encoding.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const WeekInput: InputComponent<string>;
 /**
  * Binds a native number input to a finite number field.
  * @remarks
- * ## Why
  * `FiniteFromString` makes the browser's string value an explicit typed decode.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const NumberInput: InputComponent<number>;
 /**
  * Binds a native range input to a finite number field.
  * @remarks
- * ## Why
  * Retains native slider interaction while exposing a decoded numeric value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const RangeInput: InputComponent<number>;
 /**
  * Binds a native date input to a `Date` field.
  * @remarks
- * ## Why
  * `DateFromString` makes the native encoded value's conversion explicit and fallible.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare const DateInput: InputComponent<Date>;
 /**
  * Native value emitted by `FormData`.
  * @remarks
- * ## Why
  * Browser serialization produces strings and Files; the union states that boundary exactly.
- * ## Ownership and lifetime
  * Files remain browser-owned objects referenced by the converted record.
  * @since 1.0.0
- * @category models
+ * @category Browser form data
  */
 export type FormDataValue = string | File;
 /**
  * Object representation of native FormData, preserving repeated names as arrays.
  * @remarks
- * ## Why
  * A plain record is directly consumable by Effect Schema without losing repeats.
- * ## Ownership and lifetime
  * Conversion allocates arrays/record entries but retains original File objects.
  * @since 1.0.0
- * @category models
+ * @category Browser form data
  */
 export type FormDataRecord = Readonly<Record<string, FormDataValue | ReadonlyArray<FormDataValue>>>;
 /**
- * Converts native FormData to a record and preserves repeated fields as arrays.
- * @remarks
- * ## Why
- * `Object.fromEntries` silently loses repeated names, which breaks checkbox,
- * multiselect, and multi-file submissions.
- * ## Ownership and lifetime
- * The function is synchronous and resource-free; File values are not cloned.
+ * Converts native form data to a record, preserving repeated names as arrays.
  * @example
  * ```ts
  * import { formDataToRecord } from "@typed/ui/Form"
@@ -772,16 +728,14 @@ export type FormDataRecord = Readonly<Record<string, FormDataValue | ReadonlyArr
  * const record = formDataToRecord(data)
  * ```
  * @since 1.0.0
- * @category conversions
+ * @category Browser form data
  */
 export declare function formDataToRecord(data: FormData): FormDataRecord;
 /**
  * Decodes native FormData through an Effect Schema codec.
  * @remarks
- * ## Why
  * Browser serialization, repeated values, Files, and typed validation meet at
  * one explicit fallible boundary.
- * ## Ownership and lifetime
  * The returned Effect is lazy and owns no browser resource; it references File
  * objects present in the supplied FormData.
  * @example
@@ -792,63 +746,62 @@ export declare function formDataToRecord(data: FormData): FormDataRecord;
  * const decode = decodeFormData(Schema.Struct({ name: Schema.String }), new FormData())
  * ```
  * @since 1.0.0
- * @category conversions
+ * @category Browser form data
  */
 export declare function decodeFormData<Values extends object, Codec extends Schema.Codec<Values, unknown>>(codec: Codec, data: FormData): Effect.Effect<Codec["Type"], Schema.SchemaError, Codec["DecodingServices"]>;
 /**
- * Validates current form values and synchronizes decoded values or field errors.
+ * Checks retained decoded values against the form codec Type.
+ *
  * @remarks
- * ## Why
- * Submission needs one whole-form schema check in addition to incremental field decoding.
- * ## Ownership and lifetime
- * The returned Effect updates the supplied state when run. On success it clears
- * errors; on failure it records messages and re-fails with `SchemaError`.
+ * Success replaces values and clears errors. Failure copies the aggregate schema message across
+ * fields and re-fails with SchemaError; this is not per-field issue-path mapping. A prior input
+ * decode error does not independently block success when the retained decoded value still
+ * validates.
  * @since 1.0.0
- * @category validation
+ * @category Validation
  */
 export declare function validate<Values extends object>(state: FormState<Values>): Effect.Effect<Values, Schema.SchemaError, never>;
 /**
  * Named decoded segment in a bidirectional text mask.
  * @remarks
- * ## Why
- * Slots make structured display strings type-safe and Schema-driven rather than cursor heuristics.
- * ## Ownership and lifetime
- * A slot retains its codec and optional validation constraints; it acquires no Scope.
+ * The codec preserves the slot's domain type. Supply a fixed length and charset
+ * when the input should insert unambiguous surrounding literals while editing.
+ * Use string codecs for identifiers such as phone segments that may start with zero.
  * @since 1.0.0
- * @category models
+ * @category Input codecs
  */
 export interface MaskSlot<Name extends string = string, Value = unknown> {
-    /** Discriminant used to distinguish slots from literal mask parts. */
+    /**
+     * Discriminant used to distinguish slots from literal mask parts.
+     */
     readonly _tag: "MaskSlot";
-    /** Property name written into the decoded mask object. */
+    /**
+     * Property name written into the decoded mask object.
+     */
     readonly name: Name;
-    /** Bidirectional conversion between this slot's string segment and decoded value. */
+    /**
+     * Bidirectional conversion between this slot's string segment and decoded value.
+     */
     readonly codec: Schema.Codec<Value, string>;
-    /** Exact encoded character count, when fixed-width. */
+    /**
+     * Exact encoded character count, when fixed-width.
+     */
     readonly length?: number;
-    /** Per-character acceptance test applied before Schema decoding. */
+    /**
+     * Per-character acceptance test applied before Schema decoding.
+     */
     readonly charset?: RegExp | ((character: string) => boolean);
 }
 /**
  * Literal or decoded segment of a mask.
  * @remarks
- * ## Why
  * The tuple order completely specifies parsing and formatting.
- * ## Ownership and lifetime
  * Immutable description data with no runtime ownership.
  * @since 1.0.0
- * @category models
+ * @category Input codecs
  */
 export type MaskPart = string | MaskSlot;
 /**
- * Decoded object inferred from the named slots in a mask tuple.
- * @remarks
- * ## Why
- * Slot names and codecs become a precise form-field value type.
- * ## Ownership and lifetime
- * Type-only and resource-free.
- * @since 1.0.0
- * @category type-level
  */
 export type MaskValue<Parts extends ReadonlyArray<MaskPart>> = {
     readonly [Part in Parts[number] as Part extends MaskSlot<infer Name> ? Name : never]: Part extends MaskSlot<string, infer Value> ? Value : never;
@@ -856,9 +809,7 @@ export type MaskValue<Parts extends ReadonlyArray<MaskPart>> = {
 /**
  * Creates a named, Schema-decoded mask slot.
  * @remarks
- * ## Why
  * Length and character constraints are expressed beside the codec that owns conversion.
- * ## Ownership and lifetime
  * Pure constructor; the returned descriptor retains the codec but acquires no Scope.
  * @example
  * ```ts
@@ -868,17 +819,17 @@ export type MaskValue<Parts extends ReadonlyArray<MaskPart>> = {
  * const areaCode = slot("area", Schema.String, { length: 3, charset: /[0-9]/ })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Input codecs
  */
 export declare function slot<Name extends string, Value>(name: Name, codec: Schema.Codec<Value, string>, options?: Omit<MaskSlot<Name, Value>, "_tag" | "name" | "codec">): MaskSlot<Name, Value>;
 /**
  * Builds a bidirectional Schema codec from literal text and named slots.
  * @remarks
- * ## Why
- * Display formatting and decoding share one ordered specification and produce
- * ordinary Schema issues on invalid length, characters, literals, or slot values.
- * ## Ownership and lifetime
- * Pure codec construction. Decode/encode Effects are lazy and Scope-free.
+ * Strict encoding and decoding share the same parts and reject invalid length,
+ * characters, literals, or slot values. MaskedInput also uses these parts to
+ * retain drafts and format fixed-width slots with explicit charsets. Literal
+ * characters must be distinguishable from editable characters for auto-formatting;
+ * ambiguous or variable-width masks retain ordinary strict text entry.
  * @example
  * ```ts
  * import { mask, slot } from "@typed/ui/Form"
@@ -888,50 +839,53 @@ export declare function slot<Name extends string, Value>(name: Name, codec: Sche
  *   slot("number", Schema.String, { length: 7 }))
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Input codecs
  */
 export declare function mask<const Parts extends ReadonlyArray<MaskPart>>(...parts: Parts): Schema.Codec<MaskValue<Parts>, string>;
 /**
  * Options for an input decoded through a structured mask codec.
  * @remarks
- * ## Why
  * A normal text input can expose a structured typed value without hiding native events or props.
- * ## Ownership and lifetime
  * The control Scope owns DOM work; form state and the mask codec remain independently owned.
  * @since 1.0.0
- * @category component-options
+ * @category Input codecs
  */
 export interface MaskedInputOptions<Values extends object, Parts extends ReadonlyArray<MaskPart>> extends InputOptions<Values, MaskValue<Parts>> {
-    /** Bidirectional mask codec used for display and input decoding. */
+    /**
+     * Bidirectional mask codec used for display and input decoding.
+     */
     readonly mask: Schema.Codec<MaskValue<Parts>, string>;
 }
 /**
  * Binds a native text input to a structured mask value.
  * @remarks
- * ## Why
- * The supplied Schema codec controls both display encoding and input decoding;
- * failed edits update field errors rather than corrupting decoded state.
- * ## Ownership and lifetime
- * DOM listeners and reactive value binding live in the control Scope. The
- * supplied state can be tested and retained without mounting this control.
+ * A codec created by mask supplies the editable format. Fixed-width slots with
+ * explicit charsets receive literal insertion and caret-aware deletion; other
+ * codecs retain strict text entry. Incomplete drafts remain visible while decoded
+ * state keeps its previous value. Native custom validity and field error text
+ * prevent native submission of an incomplete mask. Composition is committed only
+ * after compositionend. New edits and resets supersede pending slot decoders.
+ * Each mounted input owns its draft observer and reset registration in Scope.
  * @since 1.0.0
- * @category components
+ * @category Input codecs
  */
 export declare function MaskedInput<const Values extends object, const Parts extends ReadonlyArray<MaskPart>, const Options extends MaskedInputOptions<Values, Parts>, const Host extends HostResult = never>(options: Options & Pick<MaskedInputOptions<Values, Parts>, "state" | "name" | "mask">, host?: Dom.HostOverride<Dom.RenderHostProps<Omit<Options, "mask">, InputProps<Values, MaskValue<Parts>>>, "", Host>): Fx<RenderEvent, Schema.SchemaError | Renderable.Error<RenderableComponentOptions<Omit<Options, "mask">> | Host>, Renderable.Services<RenderableComponentOptions<Omit<Options, "mask">> | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Options for a state-explicit native checkbox.
  * @remarks
- * ## Why
  * Boolean field inference and live `checked` binding preserve native checkbox behavior.
- * ## Ownership and lifetime
  * The control Scope owns the listener/binding; form state may outlive the element.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface CheckboxOptions<Values extends object> extends Dom.HostOptions<HTMLInputElement> {
-    /** Renderer-independent state read and updated by the checkbox. */
+    /**
+     * Renderer-independent state read and updated by the checkbox.
+     */
     readonly state: FormState<Values>;
-    /** Boolean field controlled by the checkbox. */
+    /**
+     * Boolean field controlled by the checkbox.
+     */
     readonly name: BooleanFieldName<Values>;
 }
 declare function checkboxProps<Values extends object>(options: CheckboxOptions<Values>): () => {
@@ -947,32 +901,34 @@ type CheckboxProps<Values extends object> = ReturnType<ReturnType<typeof checkbo
 /**
  * Binds a native checkbox to a boolean form field.
  * @remarks
- * ## Why
  * Both the checked attribute and live property follow state, while the browser's
  * real change event is decoded through the field codec.
- * ## Ownership and lifetime
  * The rendered Scope owns the input, listener, and subscriptions. A custom host
  * must apply merged name, ARIA, checked, and change props.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare function Checkbox<const Values extends object, const Options extends CheckboxOptions<Values>, const Host extends HostResult = never>(options: Options & Pick<CheckboxOptions<Values>, "state" | "name">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, CheckboxProps<Values>>, "", Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for a state-explicit native select.
  * @remarks
- * ## Why
  * Callers author ordinary option markup while the selected value binds to typed state.
- * ## Ownership and lifetime
  * The control Scope owns content, listener, and binding; form state may outlive it.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SelectOptions<Values extends object> extends Dom.HostOptions<HTMLSelectElement> {
-    /** Renderer-independent state read and updated by the select. */
+    /**
+     * Renderer-independent state read and updated by the select.
+     */
     readonly state: FormState<Values>;
-    /** String field controlled by the select. */
+    /**
+     * String field controlled by the select.
+     */
     readonly name: FieldNameFor<Values, string>;
-    /** Native option/optgroup renderable content. */
+    /**
+     * Native option/optgroup renderable content.
+     */
     readonly content: Renderable.Any;
 }
 declare function selectProps<Values extends object>(options: SelectOptions<Values>): () => {
@@ -986,29 +942,29 @@ type SelectProps<Values extends object> = ReturnType<ReturnType<typeof selectPro
 /**
  * Binds a native select element to a string form field.
  * @remarks
- * ## Why
  * Native keyboard, accessibility, option, and form semantics remain browser-owned.
- * ## Ownership and lifetime
  * The rendered Scope owns the select/content subscriptions. A custom host must
  * preserve supplied name, ARIA, value, and change props.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare function Select<const Values extends object, const Options extends SelectOptions<Values>, const Host extends HostResult = never>(options: Options & Pick<SelectOptions<Values>, "state" | "name" | "content">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, SelectProps<Values>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for a native form label.
  * @remarks
- * ## Why
  * Explicit `for` linkage keeps accessible naming in browser-standard markup.
- * ## Ownership and lifetime
  * The label Scope owns rendered content only; it does not own the referenced control.
  * @since 1.0.0
- * @category component-options
+ * @category Field relationships
  */
 export interface LabelOptions extends Dom.HostOptions<HTMLLabelElement> {
-    /** ID of the native control labeled by this element. */
+    /**
+     * ID of the native control labeled by this element.
+     */
     readonly for: string;
-    /** Human-readable label content. */
+    /**
+     * Human-readable label content.
+     */
     readonly content: Renderable.Any;
 }
 declare function labelProps<const Options extends LabelOptions>(options: Options): () => {
@@ -1018,55 +974,54 @@ type LabelProps<Options extends LabelOptions> = ReturnType<ReturnType<typeof lab
 /**
  * Renders a native label with an explicit control relationship.
  * @remarks
- * ## Why
  * The browser supplies click-to-focus and accessible-name behavior with no synthetic layer.
- * ## Ownership and lifetime
  * The Scope owns label output/content; the referenced element remains separately owned.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export declare function Label<const Options extends LabelOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, LabelProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Options for descriptive form content.
  * @remarks
- * ## Why
  * Provides a host-overrideable descriptive region without inventing text semantics.
- * ## Ownership and lifetime
  * The host Scope owns the rendered content.
  * @since 1.0.0
- * @category component-options
+ * @category Field relationships
  */
 export interface DescriptionOptions extends Dom.HostOptions<HTMLDivElement> {
-    /** Descriptive renderable content. */
+    /**
+     * Descriptive renderable content.
+     */
     readonly content: Renderable.Any;
 }
 declare function descriptionProps(): () => {};
 type DescriptionProps = ReturnType<ReturnType<typeof descriptionProps>>;
 /**
- * Renders form description content in a neutral native div by default.
+ * Renders visible explanatory content in a neutral div.
+ *
  * @remarks
- * ## Why
- * Consumers can connect the resulting element with ordinary ARIA props where needed.
- * ## Ownership and lifetime
- * The Scope owns the description host/content and no external control.
+ * No control relationship is created automatically. The current input binding owns its generated
+ * error aria-describedby; do not assume consumer description IDs are merged into it.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export declare function Description<const Options extends DescriptionOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, DescriptionProps>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for a field validation alert.
  * @remarks
- * ## Why
  * Error identity derives from form and field IDs so controls can reference it reliably.
- * ## Ownership and lifetime
  * The error host subscribes within its Scope; form state remains independently owned.
  * @since 1.0.0
- * @category component-options
+ * @category Field relationships
  */
 export interface ErrorOptions<Values extends object> extends Dom.HostOptions<HTMLDivElement> {
-    /** Renderer-independent state supplying validation errors. */
+    /**
+     * Renderer-independent state supplying validation errors.
+     */
     readonly state: FormState<Values>;
-    /** Field whose current message is rendered. */
+    /**
+     * Field whose current message is rendered.
+     */
     readonly name: keyof Values & string;
 }
 declare function errorProps<Values extends object>(options: ErrorOptions<Values>): () => {
@@ -1075,29 +1030,28 @@ declare function errorProps<Values extends object>(options: ErrorOptions<Values>
 };
 type ErrorProps<Values extends object> = ReturnType<ReturnType<typeof errorProps<Values>>>;
 /**
- * Renders the current field error as a native ARIA alert region.
+ * Renders the named field message with a generated ID and alert role.
+ *
  * @remarks
- * ## Why
- * The same derived ID is placed on the error and in the control's
- * `aria-describedby`, keeping validation messaging coherent.
- * ## Ownership and lifetime
- * The Scope owns the alert and state subscription; removing it does not remove form state.
+ * Bound inputs refer to this ID through aria-describedby and expose aria-invalid when an error
+ * exists. Keep the form ID stable and render one matching error host per field. Alert timing
+ * still depends on the browser and assistive technology; this is not an announcement queue.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export declare function Error<const Values extends object, const Options extends ErrorOptions<Values>, const Host extends HostResult = never>(options: Options & Pick<ErrorOptions<Values>, "state" | "name">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ErrorProps<Values>>, Renderable.Any, Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for a native submit button.
  * @remarks
- * ## Why
  * Uses ordinary form submission semantics while exposing all button props/events.
- * ## Ownership and lifetime
  * The button Scope owns rendered content and listeners.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface SubmitOptions extends Dom.HostOptions<HTMLButtonElement> {
-    /** Submit button label/content. */
+    /**
+     * Submit button label/content.
+     */
     readonly content: Renderable.Any;
 }
 declare function submitProps(): () => {
@@ -1107,28 +1061,28 @@ type SubmitProps = ReturnType<ReturnType<typeof submitProps>>;
 /**
  * Renders a native `type=submit` button.
  * @remarks
- * ## Why
  * Keyboard activation, form association, and accessibility stay browser-standard.
- * ## Ownership and lifetime
  * The Scope owns the button/content; the surrounding Form owns submission sequencing.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export declare function Submit<const Options extends SubmitOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, SubmitProps>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for a state-explicit reset button.
  * @remarks
- * ## Why
  * Native reset activation can restore renderer-independent Typed state deterministically.
- * ## Ownership and lifetime
  * The click Effect runs in the button Scope; state may outlive the button.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface ResetOptions<Values extends object> extends Dom.HostOptions<HTMLButtonElement> {
-    /** Renderer-independent state restored on activation. */
+    /**
+     * Renderer-independent state restored on activation.
+     */
     readonly state: FormState<Values>;
-    /** Reset button label/content. */
+    /**
+     * Reset button label/content.
+     */
     readonly content: Renderable.Any;
 }
 declare function resetProps<Values extends object>(options: ResetOptions<Values>): () => {
@@ -1139,29 +1093,29 @@ type ResetProps<Values extends object> = ReturnType<ReturnType<typeof resetProps
 /**
  * Renders a native reset button that restores Typed form defaults.
  * @remarks
- * ## Why
  * It prevents the browser's independent control mutation and resets the single
  * RefSubject source of truth, clearing errors, metadata, and submitting state.
- * ## Ownership and lifetime
  * The Scope owns the click handler/content. The supplied form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export declare function Reset<const Values extends object, const Options extends ResetOptions<Values>, const Host extends HostResult = never>(options: Options & Pick<ResetOptions<Values>, "state" | "content">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ResetProps<Values>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for an accessible group of form controls.
  * @remarks
- * ## Why
  * Provides a native host with `role=group` and optional accessible label.
- * ## Ownership and lifetime
  * The group Scope owns child renderables but not their independent form state.
  * @since 1.0.0
- * @category component-options
+ * @category Field relationships
  */
 export interface GroupOptions extends Dom.HostOptions<HTMLDivElement> {
-    /** Controls or other renderable members of the group. */
+    /**
+     * Controls or other renderable members of the group.
+     */
     readonly content: Renderable.Any;
-    /** Optional accessible name applied through `aria-label`. */
+    /**
+     * Optional accessible name applied through `aria-label`.
+     */
     readonly label?: string;
 }
 declare function groupProps<const Options extends GroupOptions>(options: Options): () => {
@@ -1172,32 +1126,36 @@ type GroupProps<Options extends GroupOptions> = ReturnType<ReturnType<typeof gro
 /**
  * Renders an ARIA group with an optional accessible name.
  * @remarks
- * ## Why
  * Related controls can expose their relationship without a framework-specific wrapper.
- * ## Ownership and lifetime
  * The Scope owns host/content; child controls retain their own DOM/state contracts.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export declare function Group<const Options extends GroupOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, GroupProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for an array-field append button.
  * @remarks
- * ## Why
  * The field name and appended item are derived from the form value type.
- * ## Ownership and lifetime
  * The click Effect runs in the button Scope; form state remains independently owned.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface PushOptions<Values extends object, Name extends ArrayFieldName<Values>> extends Dom.HostOptions<HTMLButtonElement> {
-    /** Renderer-independent state updated on activation. */
+    /**
+     * Renderer-independent state updated on activation.
+     */
     readonly state: FormState<Values>;
-    /** Array-valued field to append to. */
+    /**
+     * Array-valued field to append to.
+     */
     readonly name: Name;
-    /** Type-compatible item appended to the field. */
+    /**
+     * Type-compatible item appended to the field.
+     */
     readonly value: ArrayFieldValue<Values, Name>;
-    /** Button label/content. */
+    /**
+     * Button label/content.
+     */
     readonly content: Renderable.Any;
 }
 declare function pushProps<Values extends object, Name extends ArrayFieldName<Values>>(options: PushOptions<Values, Name>): () => {
@@ -1208,32 +1166,36 @@ type PushProps<Values extends object, Name extends ArrayFieldName<Values>> = Ret
 /**
  * Renders a button that appends one item to an array field.
  * @remarks
- * ## Why
  * Array mutation is immutable, typed, and marks the field dirty/touched.
- * ## Ownership and lifetime
  * The Scope owns the button handler/content; state may outlive the button.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export declare function Push<const Values extends object, const Name extends ArrayFieldName<Values>, const Options extends PushOptions<Values, Name>, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, PushProps<Values, Name>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
  * Options for an array-field removal button.
  * @remarks
- * ## Why
  * The array field is type-checked and the local index is explicit.
- * ## Ownership and lifetime
  * The click Effect runs in the button Scope; form state remains independently owned.
  * @since 1.0.0
- * @category component-options
+ * @category Component options
  */
 export interface RemoveOptions<Values extends object, Name extends ArrayFieldName<Values>> extends Dom.HostOptions<HTMLButtonElement> {
-    /** Renderer-independent state updated on activation. */
+    /**
+     * Renderer-independent state updated on activation.
+     */
     readonly state: FormState<Values>;
-    /** Array-valued field to remove from. */
+    /**
+     * Array-valued field to remove from.
+     */
     readonly name: Name;
-    /** Zero-based item index removed from the field. */
+    /**
+     * Zero-based item index removed from the field.
+     */
     readonly index: number;
-    /** Button label/content. */
+    /**
+     * Button label/content.
+     */
     readonly content: Renderable.Any;
 }
 declare function removeProps<Values extends object, Name extends ArrayFieldName<Values>>(options: RemoveOptions<Values, Name>): () => {
@@ -1244,123 +1206,93 @@ type RemoveProps<Values extends object, Name extends ArrayFieldName<Values>> = R
 /**
  * Renders a button that removes one array item by index.
  * @remarks
- * ## Why
  * Array mutation is immutable, typed, and marks the field dirty/touched.
- * ## Ownership and lifetime
  * The Scope owns the button handler/content; state may outlive the button.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export declare function Remove<const Values extends object, const Name extends ArrayFieldName<Values>, const Options extends RemoveOptions<Values, Name>, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RemoveProps<Values, Name>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 /**
- * Sets one decoded field value and updates dirty/touched metadata.
+ * Assigns one decoded field value and updates dirty/touched metadata.
+ *
  * @remarks
- * ## Why
- * Programmatic updates use the same renderer-independent state transition as controls.
- * ## Ownership and lifetime
- * The returned Effect mutates only the supplied RefSubject when run.
+ * The helper does not decode or validate the supplied value and does not clear an existing field
+ * error. Use validate for an explicit whole-form check. Dirty tracking compares against the
+ * default field with !==; updates replace the top-level values record.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function setValue<Values extends object, Key extends keyof Values & string, E, R>(state: RefSubject.RefSubject<State<Values>, E, R>, key: Key, value: Values[Key]): Effect.Effect<State<Values>, E, R>;
 /**
- * Restores default values and clears errors, interaction metadata, and submission state.
+ * Restores default values and clears errors, metadata, and submitting.
+ *
  * @remarks
- * ## Why
- * Resetting the RefSubject, rather than only DOM controls, keeps every renderer
- * and test observer consistent with the source of truth.
- * ## Ownership and lifetime
- * The returned Effect performs one update when run and requires the same services as `state`.
+ * The defaultValues object is reused rather than deep-cloned. This state operation does not
+ * cancel a running submission Effect or reset independently owned result state.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function reset<Values extends object, E, R>(state: RefSubject.RefSubject<State<Values>, E, R>): Effect.Effect<State<Values>, E, R>;
 /**
- * Names of boolean-valued fields.
- * @remarks
- * ## Why
- * Constrains checkbox bindings to values the control can represent exactly.
- * ## Ownership and lifetime
- * Type-only and resource-free.
- * @since 1.0.0
- * @category type-level
  */
 export type BooleanFieldName<Values extends object> = FieldNameFor<Values, boolean>;
 /**
- * Names of readonly-array-valued fields.
- * @remarks
- * ## Why
- * Constrains append/removal helpers to collection fields.
- * ## Ownership and lifetime
- * Type-only and resource-free.
- * @since 1.0.0
- * @category type-level
  */
 export type ArrayFieldName<Values extends object> = {
     [Key in keyof Values & string]: Values[Key] extends ReadonlyArray<unknown> ? Key : never;
 }[keyof Values & string];
 /**
- * Element type of a selected array field.
- * @remarks
- * ## Why
- * Append values are checked against the exact chosen field.
- * ## Ownership and lifetime
- * Type-only and resource-free.
- * @since 1.0.0
- * @category type-level
  */
 export type ArrayFieldValue<Values extends object, Name extends ArrayFieldName<Values>> = Values[Name] extends ReadonlyArray<infer Value> ? Value : never;
 /**
  * Appends one item to an array field and marks it dirty and touched.
  * @remarks
- * ## Why
  * The immutable state transition is usable in tests, commands, or any renderer.
- * ## Ownership and lifetime
  * The returned Effect performs one RefSubject update when run.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function pushValue<Values extends object, Name extends ArrayFieldName<Values>, E, R>(state: RefSubject.RefSubject<State<Values>, E, R>, name: Name, value: ArrayFieldValue<Values, Name>): Effect.Effect<State<Values>, E, R>;
 /**
  * Removes one item by index from an array field and marks it dirty and touched.
  * @remarks
- * ## Why
  * The transition is explicit and renderer-independent; an out-of-range index leaves values unchanged.
- * ## Ownership and lifetime
  * The returned Effect performs one RefSubject update when run.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function removeValue<Values extends object, Name extends ArrayFieldName<Values>, E, R>(state: RefSubject.RefSubject<State<Values>, E, R>, name: Name, index: number): Effect.Effect<State<Values>, E, R>;
 /**
  * Handler invoked only after whole-form Schema validation succeeds.
  * @remarks
- * ## Why
  * Callers receive decoded values and the real native SubmitEvent, and may return an Effect.
- * ## Ownership and lifetime
  * A returned Effect runs inside the form submit handler and completes before `submitting` resets.
  * @since 1.0.0
- * @category events
+ * @category Form roots
  */
 export type ValidSubmitHandler<Values extends object, E = never, R = never> = (values: Values, event: SubmitEvent) => void | Effect.Effect<unknown, E, R>;
 /**
  * Options for the state-explicit form root.
  * @remarks
- * ## Why
  * The form supplies native submit/reset behavior and Effect context while its
  * data remains in a standalone hydrated RefSubject.
- * ## Ownership and lifetime
  * The root Scope owns DOM handlers/content and provides `CurrentForm` to descendants.
  * It borrows `state`; submission Effects are finalized before `submitting` is cleared.
  * @since 1.0.0
- * @category component-options
+ * @category Form roots
  */
 export interface FormOptions<Values extends object, E = never, R = never> extends Dom.HostOptions<HTMLFormElement> {
-    /** Hydrated renderer-independent state owned outside the form renderer. */
+    /**
+     * Hydrated renderer-independent state owned outside the form renderer.
+     */
     readonly state: FormState<Values>;
-    /** Controls and other renderable form content. */
+    /**
+     * Controls and other renderable form content.
+     */
     readonly content: Renderable.Any;
-    /** Callback invoked with decoded values only after successful validation. */
+    /**
+     * Callback invoked with decoded values only after successful validation.
+     */
     readonly onValidSubmit?: ValidSubmitHandler<Values, E, R>;
 }
 declare function formProps<const Values extends object, E, R, const Options extends FormOptions<Values, E, R>>(options: Options): () => {
@@ -1370,16 +1302,14 @@ declare function formProps<const Values extends object, E, R, const Options exte
 };
 type FormProps<Values extends object, E, R, Options extends FormOptions<Values, E, R>> = ReturnType<ReturnType<typeof formProps<Values, E, R, Options>>>;
 /**
- * Renders a native form and provides its state to schema-bound descendants.
+ * Renders a native form and provides its state to bound descendants.
+ *
  * @remarks
- * ## Why
- * Native submission is intercepted once, whole-form Schema validation runs,
- * then `onValidSubmit` receives decoded values. Reset updates the RefSubject so
- * all renderers stay coherent.
- * ## Ownership and lifetime
- * The root Scope owns its listeners/content and `CurrentForm` service. A valid
- * submit Effect runs in that lifetime; `submitting` is cleared in finalization
- * even on failure or interruption. Hydration does not itself attach client UI.
+ * The submit listener synchronously prevents browser navigation, marks submitting, validates
+ * decoded state, and runs onValidSubmit on success. Finalization clears submitting. Native
+ * constraint validation can prevent submit dispatch before this handler runs. The root does not
+ * read FormData, serialize a request, cancel duplicate submissions, or infer server errors.
+ *
  * @example
  * ```ts
  * import { Form, Submit, TextInput, makeState } from "@typed/ui/Form"
@@ -1397,298 +1327,400 @@ type FormProps<Values extends object, E, R, Options extends FormOptions<Values,
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Form roots
  */
 export declare function Form<const Values extends object, E, R, const Options extends FormOptions<Values, E, R>, const Host extends HostResult = never>(options: Options & Pick<FormOptions<Values, E, R>, "state" | "content">, host?: Dom.HostOverride<Dom.RenderHostProps<Options, FormProps<Values, E, R, Options>>, Options["content"], Host>): SchemaBoundRootResult<Options, Host>;
 /**
  * Options accepted by a schema-bound form root.
  * @remarks
- * ## Why
  * The factory names the state `form` and supplies its schema/context automatically.
- * ## Ownership and lifetime
  * The root Scope borrows `form` and owns content, listeners, and submit Effects.
  * @since 1.0.0
- * @category component-options
+ * @category Form roots
  */
 export interface BoundFormOptions<Values extends object, E = never, R = never> extends Dom.HostOptions<HTMLFormElement> {
-    /** State previously created by the bound API's `state` constructor. */
+    /**
+     * State previously created by the bound API's `state` constructor.
+     */
     readonly form: FormState<Values>;
-    /** Schema-bound controls and other renderable form content. */
+    /**
+     * Schema-bound controls and other renderable form content.
+     */
     readonly content: Renderable.Any;
-    /** Callback invoked with decoded values only after successful validation. */
+    /**
+     * Callback invoked with decoded values only after successful validation.
+     */
     readonly onValidSubmit?: ValidSubmitHandler<Values, E, R>;
 }
 type CurrentFormIdentifier = Context.Service.Identifier<typeof CurrentForm>;
 /**
  * Fx result of a schema-bound descendant control.
  * @remarks
- * ## Why
- * Its type makes `CurrentForm`, render services, Schema errors, Scope, and custom-host requirements explicit.
- * ## Ownership and lifetime
+ * Its type makes `CurrentForm`, render services, Schema errors, Scope, and custom-host
+ * requirements explicit.
  * The parent form supplies `CurrentForm`; the running Scope owns DOM work.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export type SchemaBoundComponentResult<Options, Host> = Fx<RenderEvent, Schema.SchemaError | Renderable.Error<RenderableComponentOptions<Options> | Host>, Renderable.Services<RenderableComponentOptions<Options> | Host> | CurrentFormIdentifier | Scope.Scope | RenderTemplate>;
 /**
  * Fx result of a schema-bound root after it provides `CurrentForm` internally.
  * @remarks
- * ## Why
  * Consumers see only external render/host requirements, not the service supplied by the root itself.
- * ## Ownership and lifetime
  * The running Scope owns the service provision, listeners, and rendered range.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export type SchemaBoundRootResult<Options, Host> = Fx<RenderEvent, Schema.SchemaError | Renderable.Error<RenderableComponentOptions<Options> | Host>, Exclude<Renderable.Services<RenderableComponentOptions<Options> | Host>, CurrentFormIdentifier> | Scope.Scope | RenderTemplate>;
 /**
  * Callable schema-bound input constructor for fields with one decoded value type.
  * @remarks
- * ## Why
  * Struct field names, errors, and services remain inferred without passing state repeatedly.
- * ## Ownership and lifetime
  * Each call borrows `CurrentForm` and returns Scope-owned render work.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundInput<Fields extends FormFields, Value> {
-    /** Creates a bound native input and optionally delegates its merged props to a custom host. @since 1.0.0 @category constructors */
+    /**
+     * Creates a bound native input and optionally delegates its merged props to a custom host.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundInputOptions<Fields, Value> & Options, host?: Dom.HostOverride<Dom.HostProps<HTMLInputElement>, "", Host>): SchemaBoundComponentResult<Omit<Options, "name">, Host>;
 }
 /**
  * Callable schema-bound input using its selected field's string codec as a mask.
  * @remarks
- * ## Why
  * Structured string encodings stay declared once in the Struct schema.
- * ## Ownership and lifetime
  * Each call borrows `CurrentForm` and returns Scope-owned render work.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundMaskedInput<Fields extends FormFields> {
-    /** Creates a bound text input using the selected field's bidirectional string codec. @since 1.0.0 @category constructors */
+    /**
+     * Creates a bound text input using the selected field's bidirectional string codec.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundMaskedInputOptions<Fields> & Options, host?: Dom.HostOverride<Dom.HostProps<HTMLInputElement>, "", Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound checkbox constructor.
  * @remarks
- * ## Why
  * Only boolean field names are accepted and state comes from `CurrentForm`.
- * ## Ownership and lifetime
  * Each call returns Scope-owned DOM work and borrows the current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundCheckbox<Values extends object> {
-    /** Creates a bound native checkbox for a boolean field. @since 1.0.0 @category constructors */
+    /**
+     * Creates a bound native checkbox for a boolean field.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundCheckboxOptions<Values> & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, CheckboxProps<Values>>, "", Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound native select constructor.
  * @remarks
- * ## Why
  * String field names are inferred while option content remains caller-authored.
- * ## Ownership and lifetime
  * Each call returns Scope-owned DOM/content work and borrows current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundSelect<Values extends object> {
-    /** Creates a bound native select and preserves caller-authored option content. @since 1.0.0 @category constructors */
+    /**
+     * Creates a bound native select and preserves caller-authored option content.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundSelectOptions<Values> & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, SelectProps<Values>>, (SchemaBoundSelectOptions<Values> & Options)["content"], Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound field-error constructor.
  * @remarks
- * ## Why
  * Field error text and relationship IDs derive from the current form automatically.
- * ## Ownership and lifetime
  * Each call returns a Scope-owned subscription and borrows current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundError<Values extends object> {
-    /** Creates a bound alert region for one field's current error. @since 1.0.0 @category constructors */
+    /**
+     * Creates a bound alert region for one field's current error.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundErrorOptions<Values> & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ErrorProps<Values>>, Renderable.Any, Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound reset-button constructor.
  * @remarks
- * ## Why
  * Reset behavior can access the current form without a state argument.
- * ## Ownership and lifetime
  * Each call returns Scope-owned DOM work and borrows current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundReset {
-    /** Creates a reset button targeting the form provided by `CurrentForm`. @since 1.0.0 @category constructors */
+    /**
+     * Creates a reset button targeting the form provided by `CurrentForm`.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Options extends object, const Host extends HostResult = never>(options: SchemaBoundResetOptions & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ResetProps<object>>, (SchemaBoundResetOptions & Options)["content"], Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound array append-button constructor.
  * @remarks
- * ## Why
  * Field and item types are derived from the form value.
- * ## Ownership and lifetime
  * Each call returns Scope-owned DOM work and borrows current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundPush<Values extends object> {
-    /** Creates an append button for a type-compatible array field and item. @since 1.0.0 @category constructors */
+    /**
+     * Creates an append button for a type-compatible array field and item.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Name extends ArrayFieldName<Values>, const Options extends object, const Host extends HostResult = never>(options: SchemaBoundPushOptions<Values, Name> & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, PushProps<Values, Name>>, (SchemaBoundPushOptions<Values, Name> & Options)["content"], Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable schema-bound array removal-button constructor.
  * @remarks
- * ## Why
  * Array fields remain type-checked without passing state explicitly.
- * ## Ownership and lifetime
  * Each call returns Scope-owned DOM work and borrows current form state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundRemove<Values extends object> {
-    /** Creates a remove button for an array field and explicit item index. @since 1.0.0 @category constructors */
+    /**
+     * Creates a remove button for an array field and explicit item index.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <const Name extends ArrayFieldName<Values>, const Options extends object, const Host extends HostResult = never>(options: SchemaBoundRemoveOptions<Values, Name> & Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RemoveProps<Values, Name>>, (SchemaBoundRemoveOptions<Values, Name> & Options)["content"], Host>): SchemaBoundComponentResult<Options, Host>;
 }
 /**
  * Callable root constructor supplied by a schema-bound form API.
  * @remarks
- * ## Why
  * It connects one factory-created state to native form behavior and descendant context.
- * ## Ownership and lifetime
  * The returned Fx provides `CurrentForm` for its own Scope and borrows the state.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundRoot<Values extends object> {
-    /** Creates the native form root that provides its `form` state to bound descendants. @since 1.0.0 @category constructors */
+    /**
+     * Creates the native form root that provides its `form` state to bound descendants.
+     * @since 1.0.0
+     * @category Schema-bound components
+     */
     <E, R, const Options extends BoundFormOptions<Values, E, R>, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.HostProps<HTMLFormElement>, Options["content"], Host>): SchemaBoundRootResult<Options, Host>;
 }
 /**
  * Optional state metadata for `SchemaBoundForm.state`.
  * @remarks
- * ## Why
  * Callers may seed SSR identity, defaults, errors, and interaction/submission state.
- * ## Ownership and lifetime
  * Values/defaults and nested references are retained exactly; provide `id` for
  * deterministic SSR identity.
  * @since 1.0.0
- * @category models
+ * @category Component options
  */
 export interface SchemaBoundStateOptions<Values extends object> {
-    /** Stable hydration and accessibility relationship ID; required for deterministic SSR ordering. */
+    /**
+     * Stable hydration and accessibility relationship ID; required for deterministic SSR ordering.
+     */
     readonly id?: string;
-    /** Exact reset-baseline reference, defaulting to the same object passed as initial values. */
+    /**
+     * Exact reset-baseline reference, defaulting to the same object passed as initial values.
+     */
     readonly defaultValues?: Values;
-    /** Initial field validation messages. */
+    /**
+     * Initial field validation messages.
+     */
     readonly errors?: Partial<Record<keyof Values & string, string>>;
-    /** Initial dirty/touched metadata. */
+    /**
+     * Initial dirty/touched metadata.
+     */
     readonly meta?: Partial<Record<keyof Values & string, FieldMeta>>;
-    /** Initial in-flight submission flag. */
+    /**
+     * Whether validation or the returned submit Effect is running.
+     */
     readonly submitting?: boolean;
 }
 /**
  * Schema-specialized form API returned by `make`.
  * @remarks
- * ## Why
  * The Struct codec is declared once, then every state, field name, component,
  * error, and custom-host signature stays aligned with it.
- * ## Ownership and lifetime
  * The API retains the codec but acquires no Scope. Each `state` call creates a
  * Scope-owned hydrated RefSubject; each component call creates lazy Fx output.
  * @since 1.0.0
- * @category models
+ * @category Schema-bound components
  */
 export interface SchemaBoundForm<Fields extends FormFields> {
-    /** Struct codec shared by state construction and every bound field. */
+    /**
+     * Struct codec shared by state construction and every bound field.
+     */
     readonly codec: Schema.Struct<Fields>;
-    /** Creates a Scope-owned hydrated state from decoded initial values. */
+    /**
+     * Creates a Scope-owned hydrated state from decoded initial values.
+     */
     readonly state: (values: Schema.Struct.Type<Fields>, options?: SchemaBoundStateOptions<Schema.Struct.Type<Fields>>) => Effect.Effect<FormState<Schema.Struct.Type<Fields>>, Schema.SchemaError, Scope.Scope>;
-    /** Native form root that provides the current state to bound descendants. */
+    /**
+     * Native form root that provides the current state to bound descendants.
+     */
     readonly Root: SchemaBoundRoot<Schema.Struct.Type<Fields>>;
-    /** Bound native text input for string-encoded string fields. */
+    /**
+     * Bound native text input for string-encoded string fields.
+     */
     readonly TextInput: SchemaBoundInput<Fields, string>;
-    /** Bound native search input for string-encoded string fields. */
+    /**
+     * Bound native search input for string-encoded string fields.
+     */
     readonly SearchInput: SchemaBoundInput<Fields, string>;
-    /** Bound native email input for string-encoded string fields. */
+    /**
+     * Bound native email input for string-encoded string fields.
+     */
     readonly EmailInput: SchemaBoundInput<Fields, string>;
-    /** Bound native URL input for string-encoded string fields. */
+    /**
+     * Bound native URL input for string-encoded string fields.
+     */
     readonly UrlInput: SchemaBoundInput<Fields, string>;
-    /** Bound native telephone input for string-encoded string fields. */
+    /**
+     * Bound native telephone input for string-encoded string fields.
+     */
     readonly TelInput: SchemaBoundInput<Fields, string>;
-    /** Bound native password input for string-encoded string fields. */
+    /**
+     * Bound native password input for string-encoded string fields.
+     */
     readonly PasswordInput: SchemaBoundInput<Fields, string>;
-    /** Bound native hidden input for string-encoded string fields. */
+    /**
+     * Bound native hidden input for string-encoded string fields.
+     */
     readonly HiddenInput: SchemaBoundInput<Fields, string>;
-    /** Bound native color input for string-encoded string fields. */
+    /**
+     * Bound native color input for string-encoded string fields.
+     */
     readonly ColorInput: SchemaBoundInput<Fields, string>;
-    /** Bound native time input for string-encoded string fields. */
+    /**
+     * Bound native time input for string-encoded string fields.
+     */
     readonly TimeInput: SchemaBoundInput<Fields, string>;
-    /** Bound native local date-time input for string-encoded string fields. */
+    /**
+     * Bound native local date-time input for string-encoded string fields.
+     */
     readonly DateTimeLocalInput: SchemaBoundInput<Fields, string>;
-    /** Bound native month input for string-encoded string fields. */
+    /**
+     * Bound native month input for string-encoded string fields.
+     */
     readonly MonthInput: SchemaBoundInput<Fields, string>;
-    /** Bound native week input for string-encoded string fields. */
+    /**
+     * Bound native week input for string-encoded string fields.
+     */
     readonly WeekInput: SchemaBoundInput<Fields, string>;
-    /** Bound native number input for finite-number fields encoded as strings. */
+    /**
+     * Bound native number input for finite-number fields encoded as strings.
+     */
     readonly NumberInput: SchemaBoundInput<Fields, number>;
-    /** Bound native range input for finite-number fields encoded as strings. */
+    /**
+     * Bound native range input for finite-number fields encoded as strings.
+     */
     readonly RangeInput: SchemaBoundInput<Fields, number>;
-    /** Bound native date input for Date fields encoded as strings. */
+    /**
+     * Bound native date input for Date fields encoded as strings.
+     */
     readonly DateInput: SchemaBoundInput<Fields, Date>;
-    /** Bound text input using the selected field's own string codec. */
+    /**
+     * Bound text input using the selected field's own string codec.
+     */
     readonly MaskedInput: SchemaBoundMaskedInput<Fields>;
-    /** Bound native checkbox limited to boolean fields. */
+    /**
+     * Bound native checkbox limited to boolean fields.
+     */
     readonly Checkbox: SchemaBoundCheckbox<Schema.Struct.Type<Fields>>;
-    /** Bound native select limited to string fields. */
+    /**
+     * Bound native select limited to string fields.
+     */
     readonly Select: SchemaBoundSelect<Schema.Struct.Type<Fields>>;
-    /** Bound ARIA alert for a field's current validation message. */
+    /**
+     * Bound ARIA alert for a field's current validation message.
+     */
     readonly Error: SchemaBoundError<Schema.Struct.Type<Fields>>;
-    /** Bound reset button that restores the current form's defaults. */
+    /**
+     * Bound reset button that restores the current form's defaults.
+     */
     readonly Reset: SchemaBoundReset;
-    /** Bound button that appends to an array field. */
+    /**
+     * Bound button that appends to an array field.
+     */
     readonly Push: SchemaBoundPush<Schema.Struct.Type<Fields>>;
-    /** Bound button that removes an item from an array field. */
+    /**
+     * Bound button that removes an item from an array field.
+     */
     readonly Remove: SchemaBoundRemove<Schema.Struct.Type<Fields>>;
-    /** Native label component; callers provide the target control ID. */
+    /**
+     * Native label component; callers provide the target control ID.
+     */
     readonly Label: typeof Label;
-    /** Neutral description host for caller-linked explanatory content. */
+    /**
+     * Neutral description host for caller-linked explanatory content.
+     */
     readonly Description: typeof Description;
-    /** Native submit button. */
+    /**
+     * Native submit button.
+     */
     readonly Submit: typeof Submit;
-    /** Accessible group host for related controls. */
+    /**
+     * Accessible group host for related controls.
+     */
     readonly Group: typeof Group;
 }
 /**
- * Creates a schema-bound form component family from one Struct codec.
+ * Binds a native form component family to one Struct codec.
+ *
  * @remarks
- * ## Why
- * Defining the schema once removes repeated state/codec arguments and makes
- * incompatible field/component combinations compile-time errors.
- * ## Ownership and lifetime
- * Factory creation is pure and retains the codec. `state` requires Scope and
- * returns a hydrated RefSubject. `Root` provides that state through Effect
- * context only for its render lifetime; controls borrow it.
+ * state accepts decoded defaults and allocates a Scope-owned hydrated subject. Root provides
+ * that form through CurrentForm. Bound controls select compatible field names from both decoded
+ * and encoded schema types; their context requirement remains in the Fx until Root provides it.
+ * Use explicit stable IDs when server rendering and hydrating.
+ *
  * @example
  * ```ts
- * import { make } from "@typed/ui/Form"
- * import { Effect, Schema } from "effect"
- * import { html } from "@typed/template"
- *
- * const Signup = make(Schema.Struct({ email: Schema.String, accepted: Schema.Boolean }))
- * const view = Effect.gen(function* () {
- *   const form = yield* Signup.state({ email: "", accepted: false }, { id: "signup" })
- *   return Signup.Root({
+ * import { Schema } from "effect";
+ * import { html } from "@typed/template";
+ * import { RefSubject } from "@typed/fx";
+ * import { component } from "@typed/ui/Component";
+ * import * as Form from "@typed/ui/Form";
+ *
+ * const Order = Form.make(Schema.Struct({
+ *   copies: Schema.FiniteFromString.pipe(Schema.check(Schema.isGreaterThan(0))),
+ *   includeNotes: Schema.Boolean,
+ * }));
+ *
+ * export const PrintOrder = component(function* () {
+ *   const form = yield* Order.state({ copies: 1, includeNotes: false }, { id: "print-order" });
+ *   const submitting = RefSubject.map(form, (state) => state.submitting);
+ *   const preview = yield* RefSubject.make("No print request preview yet.");
+ *   return html`<section>${Order.Root({
  *     form,
- *     content: html`${Signup.EmailInput({ name: "email" })}${Signup.Checkbox({ name: "accepted" })}`
- *   })
- * })
+ *     content: [
+ *       Order.Label({ for: "order-copies", content: "Copies" }),
+ *       Order.NumberInput({ name: "copies", props: { id: "order-copies", min: 1, required: true } }),
+ *       Order.Error({ name: "copies" }),
+ *       Order.Checkbox({ name: "includeNotes", props: { id: "order-notes" } }),
+ *       Order.Label({ for: "order-notes", content: "Include speaker notes" }),
+ *       Order.Submit({ content: "Preview print request", props: { "?disabled": submitting } }),
+ *       Order.Reset({ content: "Restore defaults" }),
+ *     ],
+ *     onValidSubmit: (values) => RefSubject.set(
+ *       preview,
+ *       `${values.copies} copies; notes ${values.includeNotes ? "included" : "excluded"}.`,
+ *     ),
+ *   })}<p role="status">${preview}</p></section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Schema-bound components
  */
 export declare function make<const Fields extends FormFields>(codec: Schema.Struct<Fields>): SchemaBoundForm<Fields>;
 export {};