npm - @voltro/client - Versions diffs - 0.51.0 → 0.53.0 - Mend

@voltro/client 0.51.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md +356 -0
package/THIRD-PARTY-NOTICES.md +169 -1
package/dist/form.d.ts +228 -0
package/dist/form.js +2 -0
package/dist/formData-BO7zkG_F.js +386 -0
package/dist/index.d.ts +526 -16
package/dist/index.js +1527 -1261
package/package.json +10 -3

package/dist/index.d.ts CHANGED Viewed

@@ -6,6 +6,8 @@ import { Effect } from 'effect';
 import { EventDescriptor as EventDescriptor_2 } from '@voltro/protocol';
 import { Fiber } from 'effect';
 import { ManagedRuntime } from 'effect';
+import { ParseResult } from 'effect';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { Rpc } from '@effect/rpc';
 import { RpcClient } from '@effect/rpc';
@@ -215,6 +217,23 @@ export declare interface ApiHooks<P extends ProcedureTypeMap> {
         }): SubscriptionState<QueryData<P, Tag>> | SubscriptionIdle;
     };
     readonly useMutation: <Tag extends MutationTag<P>>(tag: Tag) => MutationBuilder<ProcedureInput<P[Tag]>, ProcedureOutput<P[Tag]>>;
+    /** Schema-driven form bound to one mutation — tag as a literal, `values` /
+     *  `defaults` / the submit output all inferred from the descriptor. The
+     *  input schema still resolves from the mounted client descriptor at
+     *  runtime, exactly like the untyped hook.
+     *
+     *  Two shapes: without `toInput` the form values ARE the mutation input.
+     *  WITH `toInput` the form has its OWN `Values` shape (inferred from
+     *  `defaults` / the mapper) and `toInput` must produce the mutation's
+     *  input — checked by the compiler, not asserted. */
+    readonly useFormBinding: {
+        <Tag extends MutationTag<P>>(tag: Tag, options?: UseFormBindingOptions<FormInput<P, Tag>> & {
+            readonly toInput?: undefined;
+        }): FormBinding<FormInput<P, Tag>, ProcedureOutput<P[Tag]>>;
+        <Tag extends MutationTag<P>, Values extends Record<string, unknown>>(tag: Tag, options: UseFormBindingOptions<Values> & {
+            readonly toInput: (values: Partial<Values>) => ProcedureInput<P[Tag]>;
+        }): FormBinding<Values, ProcedureOutput<P[Tag]>>;
+    };
     readonly useAction: <Tag extends ActionTag<P>>(tag: Tag) => ActionState<ProcedureInput<P[Tag]>, ProcedureOutput<P[Tag]>>;
 }
@@ -751,6 +770,13 @@ export declare interface DataTableState<Row> {
  */
 export declare const decideAccess: (guards: ReadonlyArray<ManifestGuard> | undefined, subjectScopes: ReadonlyArray<string>) => AccessDecision;
+/**
+ * Walk a ParseError's issue tree into structured, PATH-PRESERVING issues.
+ * Every leaf keeps its full path (`address.city`, `entries.0.startsAt`) —
+ * nothing collapses to the top-level segment.
+ */
+export declare const decodeFieldIssues: (error: ParseResult.ParseError) => ReadonlyArray<FieldIssue>;
 /** All defined stores, in definition order. */
 export declare const definedStores: () => ReadonlyArray<StoreHandle<never>>;
@@ -792,6 +818,10 @@ export declare const defineTracking: <P = Record<string, unknown>>(name: string,
  */
 export declare const deriveEntityAdmins: (manifest: CapabilityManifest) => ReadonlyArray<EntityAdminSpec>;
+/** The document's locale per the framework contract (`<html lang>`); `'en'`
+ *  outside a browser. Primary subtag only (`de-AT` → `de`). */
+export declare const documentLocale: () => string;
 export declare const enqueueEntry: (queue: Outbox, id: string, tag: string, input: unknown) => Outbox;
 /**
@@ -936,17 +966,56 @@ export declare interface FieldDescriptor {
     /** The resolved JSON-Schema node — carries `maxLength` / `pattern` /
      *  `minimum` / `format` / `description` for widgets + validation hints. */
     readonly jsonSchema: Readonly<Record<string, unknown>>;
+    /** Dotted parent path for a nested-struct member (`'address'` for
+     *  `address.city`) — the SECTION a renderer groups it under. Top-level
+     *  fields carry none. Overridable via `formField({ section })`. */
+    readonly section?: string;
+    /** Human label for the section (humanised path tail). */
+    readonly sectionLabel?: string;
+    /** Help text — the Schema `description` annotation. */
+    readonly description?: string;
+    /** Declared ordering (`formField({ order })`); fields sort by it, stable
+     *  against declaration order. */
+    readonly order?: number;
+    /** For `widget: 'array'` (array of structs): the ITEM's field descriptors,
+     *  names relative to one item (`startsAt`, not `entries.0.startsAt`). */
+    readonly item?: ReadonlyArray<FieldDescriptor>;
+    /** For `widget: 'reference'`: the referenced TABLE — a renderer binds a
+     *  query-backed picker to it; the VALUE stays the id (or id list). Comes
+     *  from `formField({ reference: 'stores' })`. */
+    readonly reference?: string;
 }
 export declare interface FieldErrors {
     readonly [field: string]: string;
 }
+/** One structured validation issue. `path` is the dotted field path
+ *  (`'email'`, `'address.city'`, `'entries.0.startsAt'`); `id` is the stable
+ *  message id (`'validation.minLength'`); `params` feed its template;
+ *  `fallback` is a rendered English default so an unknown id still shows a
+ *  sentence, never a bare key. */
+export declare interface FieldIssue {
+    readonly path: string;
+    readonly id: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+    readonly fallback: string;
+}
 export declare interface FieldOption {
     readonly value: string;
     readonly label: string;
 }
+/** One display section of a form: `name` is the section path (`'address'`),
+ *  `undefined` for the top-level run of unsectioned fields. Contiguous in
+ *  display order, so a renderer can walk sections top to bottom. */
+export declare interface FieldSection {
+    readonly name: string | undefined;
+    readonly label: string | undefined;
+    readonly fields: ReadonlyArray<FieldDescriptor>;
+}
 export declare interface FilterDescriptor {
     readonly name: string;
     readonly label: string;
@@ -961,24 +1030,220 @@ export declare type FilterKind = 'text' | 'select' | 'multi-select' | 'number-ra
  *  input field → one FilterDescriptor. Pure. */
 export declare const filtersFromSchema: (schema: Schema.Schema.Any) => ReadonlyArray<FilterDescriptor>;
+/** DOM id of the JSON script the 422 re-render embeds (survives the
+ *  `interactive:'none'` strip — it is neither `type="module"` nor `src`). */
+export declare const FORM_FLASH_SCRIPT_ID = "__voltro_form_flash__";
+/** Hidden field carrying the form's instance key (multi-form pages). */
+export declare const FORM_KEY_FIELD = "__voltro_form";
+/** URL prefix the web listener mounts the no-JS endpoint under. */
+export declare const FORM_PATH_PREFIX = "/form/";
+/** Hidden field carrying the declared success-redirect path. */
+export declare const FORM_REDIRECT_FIELD = "__voltro_redirect";
+/** The path a native `<AutoForm>` POST goes to. */
+export declare const formActionPath: (mutationTag: string) => string;
+/** A field ARRAY (`entries[]`): items + structural operations + per-item
+ *  field handles (`array('entries').field(0, 'startsAt')`). */
+export declare interface FormArrayHandle {
+    readonly items: ReadonlyArray<unknown>;
+    readonly push: (item: unknown) => void;
+    readonly insert: (index: number, item: unknown) => void;
+    readonly remove: (index: number) => void;
+    readonly move: (from: number, to: number) => void;
+    readonly swap: (a: number, b: number) => void;
+    readonly field: (index: number, name: string) => FormFieldHandle;
+}
 export declare interface FormBinding<Input, Output> {
-    /** Ordered, render-agnostic field list derived from the input schema. */
+    /** Ordered, render-agnostic field list derived from the input schema —
+     *  nested structs flattened into sections, arrays carrying item
+     *  descriptors (see `schemaToFields`). */
     readonly fields: ReadonlyArray<FieldDescriptor>;
     readonly values: Partial<Input>;
-    /** First error per field — populated on submit. */
+    /** First VISIBLE error per field PATH (full dotted path — `'address.city'`,
+     *  not its top segment), display text in the resolved locale: gated schema
+     *  issues, blocked async checks, and routed server field errors. */
     readonly errors: FieldErrors;
+    /** Every current schema issue, structured `{ path, id, params, fallback }`
+     *  — ungated, for widget kits that translate themselves. */
+    readonly issues: ReadonlyArray<FieldIssue>;
     /** True when the CURRENT values decode against the schema. */
     readonly isValid: boolean;
     readonly pending: boolean;
-    /** The mutation's typed failure, if the last submit threw. */
+    /** The mutation's typed failure, if the last submit threw — MINUS anything
+     *  field-routable, which lands in `errors` instead. */
     readonly submitError: unknown | undefined;
+    /** A form-level (non-field) error carried in from a failed no-JS POST —
+     *  the RPC refused after valid input. Cleared by the next submit/reset. */
+    readonly formError: string | undefined;
     readonly data: Output | undefined;
     readonly setValue: (name: string, value: unknown) => void;
     readonly setValues: (patch: Partial<Input>) => void;
-    readonly reset: () => void;
-    /** Validate; if valid, run the mutation. Returns the output, or `undefined`
-     *  when validation blocked the submit. */
+    /** Reset to the initial defaults — or to NEW defaults (switching the edited
+     *  record without a remount). */
+    readonly reset: (nextDefaults?: Partial<Input>) => void;
+    /** Validate (incl. async checks); if valid, map (`toInput`), run the
+     *  mutation (or `onSubmit`), route server field errors. Returns the output,
+     *  or `undefined` when anything blocked the submit. */
     readonly submit: () => Promise<Output | undefined>;
+    /** One field, bound — see {@link FormFieldHandle}. */
+    readonly field: (path: string) => FormFieldHandle;
+    /** A field array — see {@link FormArrayHandle}. */
+    readonly array: (path: string) => FormArrayHandle;
+    /** The descriptors of one section (`section('address')`). */
+    readonly section: (name: string) => ReadonlyArray<FieldDescriptor>;
+    readonly state: FormStateSnapshot;
+    /** Move focus to the first field with a visible error (display order). */
+    readonly focusFirstInvalid: () => void;
+}
+/**
+ * Convert posted form entries into the input object the mutation's schema
+ * decodes — the shape `validateFields` (and the RPC payload) expects.
+ *
+ * Mapping rules (the documented contract):
+ * - **checkbox/switch**: present → `true`, absent → `false`. A native POST
+ *   omits an unchecked checkbox entirely, so absence is data, not a gap.
+ * - **number**: `Number(raw)`; `''` → the field is omitted (`undefined`), so
+ *   an optional number stays absent and a required one reports "missing"
+ *   instead of silently becoming `0`.
+ * - **date/datetime**: the string passes through (the schema's encoded side);
+ *   `''` → omitted, same reasoning as number.
+ * - **arrays** (multi-select): `getAll` semantics — every entry under the key,
+ *   items converted per the array's item type (number items → `Number`).
+ * - **unknown keys are dropped**: only names the schema declares are mapped,
+ *   so protocol fields (`__voltro_form`, …) never reach the input object —
+ *   the server rejects undeclared fields, and a hidden bookkeeping field must
+ *   not turn every no-JS submit into a validation error.
+ */
+export declare const formDataToInput: (schema: Schema.Schema.Any, entries: Iterable<FormEntry>) => Record<string, unknown>;
+/** One posted entry. File entries must be filtered out by the caller —
+ *  uploads are a declared limit of the no-JS path. */
+export declare type FormEntry = readonly [name: string, value: string];
+/** UI metadata for one schema field, as an annotations object:
+ *
+ *     Schema.String.annotations(formField({ section: 'contact', order: 2 }))
+ *
+ * Rides the JSON-Schema annotation (merged, not replaced — verified), so it
+ * survives the same normalisation every other descriptor fact does. */
+export declare const formField: (meta: {
+    readonly label?: string;
+    readonly section?: string;
+    readonly order?: number;
+    readonly widget?: WidgetKind;
+    /** Mark the field a REFERENCE to a table: `formField({ reference: 'stores' })`
+     *  → `widget: 'reference'` carrying the target, value = the id (or id
+     *  list, for a multi-reference feeding a target's `relations:`). */
+    readonly reference?: string;
+}) => {
+    readonly jsonSchema: {
+        readonly "x-voltro": typeof meta;
+    };
+};
+/** One field, bound: value + change/blur wiring + gated error + descriptor
+ *  facts + a11y props a widget kit spreads onto its input. */
+export declare interface FormFieldHandle {
+    readonly value: unknown;
+    readonly setValue: (value: unknown) => void;
+    readonly onBlur: () => void;
+    /** The VISIBLE error (display-gated schema error, server error, or async
+     *  verdict) — `undefined` while hidden or absent. */
+    readonly error: string | undefined;
+    /** The routed server error for this field, if any (also part of `error`). */
+    readonly serverError: string | undefined;
+    readonly touched: boolean;
+    readonly blurred: boolean;
+    readonly dirty: boolean;
+    readonly required: boolean;
+    readonly label: string;
+    readonly widget: string;
+    readonly options: ReadonlyArray<FieldOption> | undefined;
+    readonly description: string | undefined;
+    /** `'idle' | 'checking' | 'valid' | 'invalid'` — mirrors the entry passed
+     *  under this path in `asyncFields`. */
+    readonly asyncStatus: AsyncValidationResult['status'];
+    readonly a11y: {
+        readonly id: string;
+        readonly 'aria-invalid': true | undefined;
+        readonly 'aria-required': true | undefined;
+        readonly 'aria-describedby': string | undefined;
+    };
+}
+/**
+ * The error/values payload a failed no-JS form POST carries back into the
+ * 422 re-render. Keyed by `formKey` so a page with several forms re-fills
+ * only the one that was submitted. The SSR render passes it through the
+ * server-request context; the client reads the same payload back off the
+ * `#__voltro_form_flash__` JSON script, so a late-hydrating page shows the
+ * identical state (no mismatch, no vanished errors).
+ */
+export declare interface FormFlashPayload {
+    /** The submitted form's key — `<AutoForm formKey>` or its mutation tag. */
+    readonly formKey: string;
+    /** The mapped input values as posted (pre-decode), to re-fill the fields. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** First error per field — the `validateFields` shape. */
+    readonly errors: Readonly<Record<string, string>>;
+    /** A non-field error (the RPC refused after valid input: guard, server). */
+    readonly formError?: string;
+}
+/** A mutation's input as the form binding's value shape. A struct input is its
+ *  own shape; the (theoretical) non-object input degrades to the untyped map
+ *  rather than failing the whole binding. */
+declare type FormInput<P extends ProcedureTypeMap, Tag extends keyof P> = ProcedureInput<P[Tag]> extends Record<string, unknown> ? ProcedureInput<P[Tag]> : Record<string, unknown>;
+/**
+ * Group an ordered field list into contiguous sections — the structure a
+ * form (or its skeleton — the placeholder must have the SHAPE of the real
+ * thing, title rows included) renders. Pure; feeds `<FormSkeleton>`,
+ * `<AutoForm>` layouts and `form.section(...)` alike.
+ */
+export declare const formSections: (fields: ReadonlyArray<FieldDescriptor>) => ReadonlyArray<FieldSection>;
+/** The full form state, engine + mutation, in ONE place — a save button reads
+ *  `canSubmit`/`pending`, a dialog closes on `isSubmitSuccessful`, a banner
+ *  listens to `submitError`. */
+export declare interface FormStateSnapshot {
+    readonly isDirty: boolean;
+    readonly isPristine: boolean;
+    readonly isTouched: boolean;
+    /** The CURRENT values decode (display gating does not apply here). */
+    readonly isValid: boolean;
+    /** An async field check is in flight. */
+    readonly isValidating: boolean;
+    readonly canSubmit: boolean;
+    readonly isSubmitting: boolean;
+    readonly isSubmitted: boolean;
+    readonly isSubmitSuccessful: boolean;
+    readonly submissionAttempts: number;
+    /** VISIBLE errors right now (post-gating). */
+    readonly errorCount: number;
+    readonly firstInvalidPath: string | undefined;
+    /** The mutation is on the wire — can outlast `isSubmitting` under
+     *  auto-optimistic. */
+    readonly pending: boolean;
+    readonly isLoading: boolean;
+    readonly submitError: unknown | undefined;
+    readonly data: unknown;
+}
+export declare interface FormValidateOptions {
+    /** When a field's error becomes VISIBLE while editing. `'afterTouched'`
+     *  (default): after that field blurred once, or after the first submit
+     *  attempt — a form never opens with errors. `'always'`: live from the
+     *  first keystroke. `'never'`: only after a submit attempt. */
+    readonly onChange?: 'always' | 'afterTouched' | 'never';
+    /** Reveal a field's error when it blurs (default true). */
+    readonly onBlur?: boolean;
 }
 export declare interface FrameworkRuntimes {
@@ -1010,6 +1275,32 @@ export declare const getMutationNotifier: () => MutationNotifier | undefined;
 /** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
 export declare const getMutations: () => ReadonlyArray<MutationEvent>;
+/**
+ * A process-wide singleton React context, pinned on the global symbol registry.
+ *
+ * WHY this exists: the SSG prerender (`voltro build`) loads the framework
+ * through TWO separate module instances — the renderer comes in via Vite's
+ * `ssrLoadModule('@voltro/web/ssr')` (Vite-transformed) while a page's own
+ * framework import is externalised to Node — so a plain `createContext()`
+ * in a shared module is evaluated twice and yields two DISTINCT context
+ * objects. The `<Router>` provider then holds one while the page's
+ * `useLocation()` reads the other, which throws "Router hooks must be used
+ * inside <Router>." The same duplicate-instance hazard shows up wherever a
+ * deployment ends up with two copies of a package (the classic dual-package
+ * hazard, monorepo hoisting quirks, separate SSR vs client bundles).
+ *
+ * Resolving every context through `Symbol.for(...)` on `globalThis` makes all
+ * module copies share ONE instance, so provider and consumer can never diverge.
+ * A duplicated copy of THIS helper is harmless — both copies hit the same
+ * global registry entry.
+ *
+ * Lives in @voltro/client (the lowest React-carrying package) so both
+ * @voltro/web and @voltro/ui reach it without a cycle; the key prefix keeps
+ * its historical spelling on purpose — a mixed dist/src world must resolve
+ * to the same registry entries.
+ */
+export declare const globalContext: <T>(key: string, initial: T) => Context<T>;
 /** Is this the framework's `Unauthenticated`? Matched on `_tag`, the wire
  *  contract, rather than on an instance — the error crosses a package boundary
  *  and may be re-created by the decoder. */
@@ -1263,6 +1554,9 @@ export declare interface OutboxControls {
     readonly online: boolean;
     readonly pending: number;
     readonly conflicts: ReadonlyArray<OutboxEntry>;
+    /** Resolve a conflicted entry with a new input (see {@link resolveConflictEntry})
+     *  and replay immediately when online. */
+    readonly resolveConflict: (id: string, input: unknown) => void;
 }
 export declare interface OutboxEntry {
@@ -1274,6 +1568,22 @@ export declare interface OutboxEntry {
     readonly error?: unknown;
 }
+/**
+ * Durability seam for the outbox queue. `load` runs once on mount and returns
+ * the surviving entries (oldest first); `save` is called after every queue
+ * transition with the entries worth keeping (`sent` entries are compacted away
+ * before the call — a delivered write needs no durability).
+ *
+ * The one real implementation is `outboxPersistence()` in
+ * `@voltro/local-first`, which stores the entries through the same
+ * `PersistenceAdapter` the sync engine uses — ONE durable queue for a device,
+ * whichever surface enqueued the write.
+ */
+export declare interface OutboxPersistence {
+    readonly load: () => Promise<Outbox>;
+    readonly save: (queue: Outbox) => Promise<void>;
+}
 export declare type OutboxStatus = 'pending' | 'sent' | 'failed' | 'conflict';
 /** Provide the current subject's scopes to `useCan`. Mount it once high in the
@@ -1575,6 +1885,14 @@ export declare type ResolvableHeaders = Readonly<Record<string, string>> | (() =
 export declare const resolveByTag: (client: unknown, tag: string) => unknown;
+/** Resolve a conflicted entry: replace its input with the RESOLVED value and
+ *  return it to `pending`, so the next replay sends the resolution and the
+ *  entries it was blocking become replayable again. The resolved input
+ *  typically comes from a conflict policy (`@voltro/local-first`'s
+ *  `resolveWithPolicy` — CRDT fields merge, scalars resolve deterministically);
+ *  a caller may equally pass a hand-picked value. */
+export declare const resolveConflictEntry: (queue: Outbox, id: string, input: unknown) => Outbox;
 export declare interface ResolvedClient {
     readonly runtime: AnyRuntime;
     readonly cache: SubscriptionCache;
@@ -1587,6 +1905,13 @@ export declare const resolveStoreStorage: (area: StoreStorageArea) => StoreStora
 /** Resolve one map entry against the props. Pure. */
 export declare const resolveTrackingEvent: <P>(entry: TrackingEntry<P> | undefined, props: P) => TrackingEvent | null;
+/**
+ * Render one issue id to display text: app resolver first (its `undefined`
+ * falls through), then the built-in catalog for the locale's primary subtag,
+ * then English, then the issue's own fallback sentence.
+ */
+export declare const resolveValidationMessage: (issue: Pick<FieldIssue, "id" | "params" | "fallback">, options?: ValidateOptions) => string;
 export declare interface ResourceCanInput {
     /** The action being gated (e.g. `'read'`, `'write'`, `'delete'`). */
     readonly action: string;
@@ -1832,6 +2157,29 @@ export declare type SequenceResult<Ctx> = {
     }>;
 };
+export declare const ServerRequestContext: Context<ServerRequestContextValue | null>;
+export declare interface ServerRequestContextValue {
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw request URL as it came off the wire (path + query). Useful
+     *  for SSR pages that need to read `?q=…` style search params
+     *  without touching anything client-only. Empty string for build-
+     *  time SSG renders where there is no incoming request. */
+    readonly url: string;
+    /** Present ONLY on the 422 re-render of a failed no-JS form POST:
+     *  the submitted values + field errors, keyed by formKey. Travels on
+     *  the EXISTING request context deliberately — a dedicated provider
+     *  would add a fiber fork the client boot does not have, and every
+     *  ancestor arity difference shifts every useId in the app. */
+    readonly formFlash?: FormFlashPayload;
+}
+export declare const ServerRequestProvider: ({ value, children, }: {
+    readonly value: ServerRequestContextValue;
+    readonly children: ReactNode;
+}) => ReactNode;
 /** Register (or clear) the app-wide notifier that `notify:` routes to. Call once
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
@@ -2168,6 +2516,8 @@ export declare class SubscriptionCache {
     private readonly inactiveTtlMs;
     private readonly onChangeHook;
     private readonly errorBus;
+    private readonly mirror;
+    private readonly mergeCell;
     constructor(options?: SubscriptionCacheOptions);
     /**
      * Register a subscriber. The cache forks the underlying fiber on the
@@ -2383,6 +2733,17 @@ export declare class SubscriptionCache {
 }
 export declare interface SubscriptionCacheOptions {
+    /** Durable local mirror (see {@link SubscriptionMirror}). */
+    readonly mirror?: SubscriptionMirror;
+    /**
+     * CRDT cell merger for the downstream lane (plan 18): folds a
+     * `mergeCells` delta op's incremental update into the held cell. The one
+     * real implementation is `crdtMergeCell` from `@voltro/local-first` (this
+     * package stays CRDT-library-free). Absent → a mergeCells op replaces the
+     * cell (the producer only emits them when the app declares CRDT tables,
+     * so an app without the binding never sees one).
+     */
+    readonly mergeCell?: (column: string, prevValue: unknown, update: unknown) => unknown;
     /** Milliseconds to keep an entry alive after the last subscriber leaves.
      *  Lets back-button / quick remount reuse the warm subscription. */
     readonly inactiveTtlMs?: number;
@@ -2476,6 +2837,29 @@ export declare interface SubscriptionMeta {
     readonly pendingPatches: number;
 }
+/**
+ * Durable local mirror seam (plan 02 — local-first). `save` fires after every
+ * server event that moved an entry's base (snapshot or delta) with the rows
+ * AND the revision; `load` runs once for a COLD entry (no server data yet)
+ * and, when it resolves first, seeds the entry so the UI renders mirrored
+ * rows offline — and the NEXT (re)subscribe presents the mirrored revision as
+ * `voltro-resume-from`, composing with delta-resume. The implementation
+ * (`@voltro/local-first`'s query mirror) owns partitioning, encrypted-column
+ * stripping and which tags mirror at all — the cache calls it for every
+ * entry and a foreign tag is the mirror's no-op.
+ */
+export declare interface SubscriptionMirror {
+    readonly load: (key: string) => Promise<{
+        readonly data: unknown;
+        readonly revision: number;
+    } | undefined>;
+    readonly save: (key: string, snap: {
+        readonly tag: string | undefined;
+        readonly data: unknown;
+        readonly revision: number;
+    }) => Promise<void>;
+}
 /**
  * Subscribe to a streaming rpc by tag.
  *
@@ -3048,8 +3432,107 @@ export declare interface UseFormBindingOptions<Input> {
     readonly schema?: Schema.Schema.Any;
     /** Initial field values. */
     readonly defaults?: Partial<Input>;
+    /** The failed no-JS POST's payload for THIS form (`useFormFlash` from
+     *  @voltro/web resolves it, SSR and client alike). When present it seeds
+     *  the initial values + field errors, so the 422 re-render shows the
+     *  submitted state server-side and hydrates to the identical state. */
+    readonly flash?: FormFlashPayload | undefined;
+    /** Locale for the built-in validation messages (en/de shipped). Default:
+     *  the document's `<html lang>` — the framework's locale contract. */
+    readonly locale?: string;
+    /** App override for message-id resolution — wire your i18n catalog in one
+     *  line: `messages: (id, params) => t(id, params)`. Return `undefined` to
+     *  fall through to the built-in defaults. Resolves BOTH schema-validation
+     *  ids (`validation.minLength`) and server ids (`validation.emailTaken`
+     *  from `ctx.validation.fail`). */
+    readonly messages?: ValidationMessageResolver;
+    /** Error-visibility timing — see {@link FormValidateOptions}. */
+    readonly validate?: FormValidateOptions;
+    /**
+     * Form values ≠ mutation input — the mapping seam. Runs BEFORE validation:
+     * the INPUT is validated against the schema, and its error paths map back
+     * to form fields via {@link UseFormBindingOptions.errorPath} (same-name
+     * fields map automatically).
+     *
+     *     toInput: (values) => ({ id: employee.id, ...employeePatch(values) })
+     */
+    readonly toInput?: (values: Partial<Input>) => unknown;
+    /** Input-path → form-path mapping for `toInput` error routing, e.g.
+     *  `{ firstName: 'name' }`. Same-name paths need no entry. */
+    readonly errorPath?: Readonly<Record<string, string>>;
+    /**
+     * Own the save: runs INSTEAD of the plain `mutate(input)`, with the mutation
+     * handle in hand — for composed writes (mutation + links + follow-ups).
+     * Server field errors thrown here still route to their fields.
+     *
+     *     onSubmit: async ({ input, mutate, values }) => {
+     *       const row = await mutate(input)
+     *       await setLinks(values.assignedStores)
+     *       return row
+     *     }
+     */
+    readonly onSubmit?: (args: {
+        readonly input: unknown;
+        readonly values: Partial<Input>;
+        readonly mutate: (input: unknown) => Promise<unknown>;
+    }) => Promise<unknown>;
+    /** Ran after a successful submit with the mutation's output. */
+    readonly onSuccess?: (output: unknown) => void;
+    /**
+     * Async field checks `submit` must wait for. Pass each field's
+     * `useAsyncValidation` result under its field path:
+     *
+     *     const email = useAsyncValidation('app', 'users.emailAvailable', values.email ?? '', { … })
+     *     const form = useFormBinding('app', 'users.create', { asyncFields: { email } })
+     *
+     * On submit, in-flight checks are awaited (bounded by `asyncTimeoutMs`),
+     * an `'invalid'` verdict blocks the submit with the error on ITS field.
+     */
+    readonly asyncFields?: Readonly<Record<string, AsyncValidationResult>>;
+    /** Upper bound for waiting on `asyncFields` (ms, default 5000). On timeout
+     *  the still-checking field blocks the submit with `validation.checking`. */
+    readonly asyncTimeoutMs?: number;
+    /** The defaults hang on a subscription that has not delivered yet. While
+     *  true the form suppresses `dirty` and every error — render the skeleton,
+     *  not an empty form scolding the user. */
+    readonly isLoading?: boolean;
+    /** Re-render scope of THIS hook. `'all'` (default): re-render on every
+     *  engine change — simplest, correct everywhere. `'fields'`: the hook only
+     *  re-renders on submission-level changes; field components subscribe
+     *  narrowly via `useFormField(form, path)` so a keystroke re-renders one
+     *  field, not the page. In that mode `values`/`errors` on the binding are
+     *  the state as of the LAST binding render. */
+    readonly subscribe?: 'all' | 'fields';
 }
+/**
+ * Narrow per-field subscription — the render-performance half of the engine.
+ *
+ * `useFormBinding` with `subscribe: 'fields'` re-renders only on
+ * submission-level changes; each field COMPONENT calls this with the binding
+ * and its path, and a keystroke re-renders that field alone:
+ *
+ *     const Field = ({ form, path }: { form: FormBinding<I, O>; path: string }) => {
+ *       const f = useFormField(form, path)
+ *       return <input id={f.a11y.id} value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} />
+ *     }
+ */
+export declare const useFormField: (binding: FormBinding<never, never> | FormBinding<Record<string, unknown>, unknown>, path: string) => FormFieldHandle;
+/**
+ * The failed-no-JS-POST payload for ONE form, or `undefined`.
+ *
+ * On the server (the 422 re-render) it comes off the request context; on the
+ * client it is read back from the `#__voltro_form_flash__` JSON script the
+ * same response embedded. Both carry the SAME payload, so a page that loads
+ * its bundle after a native submit hydrates to exactly the server-rendered
+ * state — errors visible, values filled, no mismatch.
+ *
+ * Keyed: only the form whose `formKey` was submitted receives the payload —
+ * two `<AutoForm>`s on one page re-fill only the one that POSTed.
+ */
+export declare const useFormFlash: (formKey: string) => FormFlashPayload | undefined;
 /** The field shape a `<AutoForm mutation=…>` will render — from the mutation's
  *  input Schema. Use it to render a matching skeleton while anything the form
  *  depends on is still loading. */
@@ -3074,6 +3557,8 @@ export declare const useOutbox: (options: UseOutboxOptions) => OutboxControls;
 export declare interface UseOutboxOptions {
     /** Perform one queued write (the real mutation). Throw to fail. */
     readonly send: (entry: OutboxEntry) => Promise<void>;
+    /** Durable backing (see {@link OutboxPersistence}). Omitted → in-memory only. */
+    readonly persistence?: OutboxPersistence;
     /** Online override (defaults to navigator.onLine + online/offline events). */
     readonly online?: boolean;
     /** Classify a send error as a conflict (blocks replay) vs a transient
@@ -3198,6 +3683,8 @@ export declare interface UseSequenceResult {
     readonly failedStep: string | undefined;
 }
+export declare const useServerRequest: () => ServerRequestContextValue | null;
 export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input: Readonly<Record<string, unknown>>, options: SubscriptionOptions<T> & {
     readonly initialSnapshot: T;
 }): SubscriptionStateWithFallback<T>;
@@ -3245,6 +3732,10 @@ export declare interface UseUndoOptions {
  */
 export declare const useUpload: (apiName: string, hookOpts?: UploadOptions) => UploadHandle;
+/** The app-wide resolver, if a provider is mounted. Consumed by the form
+ *  binding; exported for widget kits that resolve ids themselves. */
+export declare const useValidationMessages: () => ValidationMessageResolver | undefined;
 export declare const useWindowedSubscription: <Row = Record<string, unknown>>(apiName: string, queryTag: string, options: UseWindowedSubscriptionOptions) => WindowedSubscriptionState<Row>;
 export declare interface UseWindowedSubscriptionOptions {
@@ -3288,20 +3779,39 @@ export declare const useWorkflowUpdate: (apiName: string) => WorkflowUpdateState
 export declare const validateEventPayload: (descriptor: EventDescriptor<string, unknown>, payload: unknown) => EventValidation;
 /**
- * Validate `values` against an input `schema`, returning the first error per
- * top-level field (`{ [field]: message }`) — the shape `<AutoForm>` and custom
- * widgets render inline. Uses the same `decodeUnknownEither` + `ArrayFormatter`
- * path the store's `.validate(...)` uses, so client and server speak ONE
- * schema. `{ errors: 'all' }` collects every field's error in one pass.
- *
- * Client-side validation is non-authoritative UX — the server re-validates the
- * same schema on the mutation; this just gives instant inline feedback.
+ * Validate `values` against an input `schema`. Uses the same
+ * `decodeUnknownEither` path the store's `.validate(...)` uses, so client and
+ * server speak ONE schema; `{ errors: 'all' }` collects every field in one
+ * pass. Client-side validation is non-authoritative UX — the server
+ * re-validates the same schema on the mutation.
  */
-export declare const validateFields: (schema: Schema.Schema.Any, values: unknown) => ValidationResult;
+export declare const validateFields: (schema: Schema.Schema.Any, values: unknown, options?: ValidateOptions) => ValidationResult;
+export declare interface ValidateOptions {
+    /** BCP-47-ish tag; only the primary subtag is read. Default: the document's
+     *  `<html lang>`, else `'en'`. */
+    readonly locale?: string;
+    readonly messages?: ValidationMessageResolver;
+}
+/** Resolve one message id to display text. Return `undefined` to fall through
+ *  to the built-in en/de defaults — so a resolver only has to know the ids it
+ *  overrides. Wire it to `@voltro/i18n` in one line:
+ *  `messages: (id, params) => t(id, params)`. */
+export declare type ValidationMessageResolver = (id: string, params: Readonly<Record<string, unknown>> | undefined, fallback: string) => string | undefined;
+export declare const ValidationMessagesProvider: (props: {
+    readonly messages: ValidationMessageResolver;
+    readonly children?: ReactNode;
+}) => ReactElement;
 export declare interface ValidationResult {
     readonly valid: boolean;
+    /** Display text per field path — what `<AutoForm>` and custom widgets
+     *  render inline. First issue per field wins. */
     readonly errors: FieldErrors;
+    /** Every issue, structured — for widget kits that translate themselves. */
+    readonly issues: ReadonlyArray<FieldIssue>;
 }
 export declare type ValidationStatus = 'idle' | 'checking' | 'valid' | 'invalid';
@@ -3325,7 +3835,7 @@ export declare const validationStatus: (args: {
 /** The default widget kinds the framework can render from a schema. `'custom'`
  *  means "no default widget" — the field needs a render-prop (a nested object,
  *  an array of objects, or a multi-branch union). Mirrors innovation/01's set. */
-export declare type WidgetKind = 'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'custom';
+export declare type WidgetKind = 'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'array' | 'reference' | 'custom';
 export declare interface WindowedSubscriptionState<Row> {
     /** The in-window rows (live). */