@cosmicdrift/kumiko-headless 0.1.0

package/src/form/form-controller.ts

@@ -0,0 +1,333 @@
+import type { FieldIssue } from "../dispatcher";
+import { createStore } from "../store";
+import type {
+  FieldConditions,
+  FieldConditionValue,
+  FieldState,
+  FormController,
+  FormControllerOptions,
+  FormSnapshot,
+  FormValues,
+  SubmitResult,
+} from "./types";
+import { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge";
+
+// Resolve one condition-value (boolean | predicate) against current values + ctx.
+// `undefined` means "condition not declared"; the caller substitutes the
+// field-default (visible:true, readonly:false, required:false).
+function evalCondition<TValues extends FormValues, TCtx>(
+  condition: FieldConditionValue<TValues, TCtx> | undefined,
+  fallback: boolean,
+  values: TValues,
+  ctx: TCtx,
+): boolean {
+  if (condition === undefined) return fallback;
+  if (typeof condition === "boolean") return condition;
+  return condition(values, ctx);
+}
+
+function computeFieldStates<TValues extends FormValues, TCtx>(
+  rules: Readonly<Record<string, FieldConditions<TValues, TCtx>>> | undefined,
+  values: TValues,
+  ctx: TCtx,
+): Record<string, FieldState> {
+  if (!rules) return {};
+  const out: Record<string, FieldState> = {};
+  for (const [fieldKey, rule] of Object.entries(rules)) {
+    out[fieldKey] = {
+      visible: evalCondition(rule.visible, true, values, ctx),
+      readonly: evalCondition(rule.readonly, false, values, ctx),
+      required: evalCondition(rule.required, false, values, ctx),
+    };
+  }
+  return out;
+}
+
+// Reference equality only. For primitive-valued fields this is exact; for
+// object/array fields it treats "same reference" as "unchanged" — callers
+// who mutate in place instead of swapping references (which is bad form
+// anyway, but common in ad-hoc tests) would miss a change. Kumiko's
+// form-controller contract is that mutators build new references.
+// Object.is is chosen over === so NaN !== NaN doesn't mark a field dirty
+// after you re-type the same number back in.
+function valuesDiff<TValues extends FormValues>(
+  current: TValues,
+  initial: TValues,
+): Partial<TValues> {
+  const out: Partial<TValues> = {};
+  // Iterate over BOTH sides — a field that existed on initial but was
+  // deleted from current (via `setValues({ foo: undefined })`) still
+  // counts as a change.
+  // FormValues<T> erlaubt kein keyof-T-Iteration (T ist generic). Cast
+  // zu Record<string, unknown> für dynamic-key-Inspection.
+  const cur = current as Record<string, unknown>; // @cast-boundary form-values
+  const ini = initial as Record<string, unknown>; // @cast-boundary form-values
+  const o = out as Record<string, unknown>; // @cast-boundary form-values
+  const keys = new Set<string>([...Object.keys(cur), ...Object.keys(ini)]);
+  for (const key of keys) {
+    const a = cur[key];
+    const b = ini[key];
+    if (!Object.is(a, b)) {
+      o[key] = a;
+    }
+  }
+  return out;
+}
+
+// Shallow-freeze so accidental mutations on the snapshot (e.g. a test
+// writing `snapshot.values.title = "x"`) throw in strict mode instead of
+// silently diverging from the controller's internal state. Deep-freeze
+// would be safer but expensive — keeping it shallow matches React's own
+// immutability expectations and leaves room for sub-controllers to manage
+// their own sub-trees without double-frozen parents blocking them.
+function freezeSnapshot<TValues extends FormValues>(
+  snapshot: FormSnapshot<TValues>,
+): FormSnapshot<TValues> {
+  return Object.freeze(snapshot);
+}
+
+export function createFormController<TValues extends FormValues, TCtx = unknown>(
+  options: FormControllerOptions<TValues, TCtx>,
+): FormController<TValues> {
+  // Shallow copy so mutating the input after creation doesn't bleed into
+  // the controller's internal state. `initial` stays fixed across the
+  // controller's lifetime unless rebase() replaces it.
+  let values: TValues = { ...options.initial };
+  let initial: TValues = { ...options.initial };
+  let errors: Readonly<Record<string, readonly FieldIssue[]>> = Object.freeze({});
+  // ctx is cast-held as TCtx; `undefined` is valid when callers don't
+  // declare conditional predicates that depend on it.
+  let ctx: TCtx = (options.ctx as TCtx) ?? (undefined as TCtx);
+
+  // Snapshot lives in a Store — same reference across getSnapshot() calls
+  // until a mutator invalidates it via setState. React's useSyncExternalStore
+  // compares snapshot identity to decide on a re-render; the Store holds the
+  // identity stable until invalidate() swaps it for a fresh build.
+  const snapshotStore = createStore<FormSnapshot<TValues>>(buildSnapshot());
+
+  // In-flight submit tracker. When a submit() is pending, a second call
+  // awaits the same promise instead of firing a parallel write — avoids
+  // double-submission on double-click and keeps the rebase semantics
+  // coherent (rebasing twice in quick succession would mis-align the
+  // baseline with what the server actually saw).
+  let submitInFlight: Promise<unknown> | null = null;
+
+  function buildSnapshot(): FormSnapshot<TValues> {
+    const changes = valuesDiff(values, initial);
+    const isDirty = Object.keys(changes).length > 0;
+    const fields = Object.freeze(computeFieldStates(options.fields, values, ctx));
+    return freezeSnapshot({
+      values,
+      initial,
+      changes,
+      isDirty,
+      isUnchanged: !isDirty,
+      errors,
+      fields,
+    });
+  }
+
+  function invalidate() {
+    snapshotStore.setState(buildSnapshot());
+  }
+
+  // Local shared implementations so submit() can call validate/rebase
+  // without the this-in-object-literal dance. Both also expose themselves
+  // as methods on the returned controller.
+  function runValidate(): boolean {
+    if (!options.schema) {
+      if (Object.keys(errors).length > 0) {
+        errors = Object.freeze({});
+        invalidate();
+      }
+      return true;
+    }
+    const fieldStates = computeFieldStates(options.fields, values, ctx);
+    const parsed = options.schema.safeParse(values);
+    if (parsed.success) {
+      if (Object.keys(errors).length > 0) {
+        errors = Object.freeze({});
+        invalidate();
+      }
+      return true;
+    }
+    const hiddenFields = new Set<string>();
+    for (const [fieldKey, state] of Object.entries(fieldStates)) {
+      if (!state.visible) hiddenFields.add(fieldKey);
+    }
+    const allIssues = zodErrorToFieldIssues(parsed.error);
+    const relevantIssues = allIssues.filter((issue) => {
+      const rootField = issue.path.split(".")[0] ?? "";
+      return !hiddenFields.has(rootField);
+    });
+    if (relevantIssues.length === 0) {
+      if (Object.keys(errors).length > 0) {
+        errors = Object.freeze({});
+        invalidate();
+      }
+      return true;
+    }
+    errors = Object.freeze(groupIssuesByPath(relevantIssues));
+    invalidate();
+    return false;
+  }
+
+  function runRebase(): void {
+    initial = { ...values };
+    if (Object.keys(errors).length > 0) errors = Object.freeze({});
+    invalidate();
+  }
+
+  // Stale-submit-safe rebase. Difference to runRebase: the baseline is
+  // taken from the values that were actually SENT to the server, not
+  // from `values` at the moment the server replied. If the user typed
+  // into a field while the submit was in flight, those edits stay as
+  // dirty changes after the call — they never made it to the server, so
+  // pretending they did (via `initial = { ...values }`) would mask unsaved
+  // input. The race shows up as "user edits a field during a 2s save, sees
+  // it as saved, closes the tab — the edit is lost". This path keeps
+  // `values` untouched; only `initial` shifts to the submitted snapshot.
+  function runRebaseToSnapshot(snapped: TValues): void {
+    initial = { ...snapped };
+    if (Object.keys(errors).length > 0) errors = Object.freeze({});
+    invalidate();
+  }
+
+  return {
+    getSnapshot: snapshotStore.getSnapshot,
+    subscribe: snapshotStore.subscribe,
+    setField(key, value) {
+      // Skip work when the new value is identical to the current one —
+      // avoids a notify + re-render for "setField with same value" which
+      // happens a lot in controlled inputs on every keystroke of an
+      // untouched field.
+      if (Object.is(values[key], value)) return;
+      values = { ...values, [key]: value };
+      invalidate();
+    },
+    setValues(partial) {
+      // Detect any effective change before rebuilding — setValues with a
+      // partial that matches current values shouldn't fire listeners.
+      let changed = false;
+      const v = values as Record<string, unknown>; // @cast-boundary form-values
+      const p = partial as Record<string, unknown>; // @cast-boundary form-values
+      for (const k of Object.keys(p)) {
+        if (!Object.is(v[k], p[k])) {
+          changed = true;
+          break;
+        }
+      }
+      if (!changed) return;
+      values = { ...values, ...partial };
+      invalidate();
+    },
+    clearErrors(path) {
+      if (path === undefined) {
+        if (Object.keys(errors).length === 0) return;
+        errors = Object.freeze({});
+      } else {
+        if (!(path in errors)) return;
+        const next: Record<string, readonly FieldIssue[]> = { ...errors };
+        delete next[path];
+        errors = Object.freeze(next);
+      }
+      invalidate();
+    },
+    setErrors(nextErrors) {
+      errors = Object.freeze({ ...nextErrors });
+      invalidate();
+    },
+    validate: runValidate,
+    reset() {
+      // Cheap no-op when already at baseline and no errors to clear.
+      const alreadyClean = !snapshotStore.getSnapshot().isDirty && Object.keys(errors).length === 0;
+      if (alreadyClean) return;
+      values = { ...initial };
+      errors = Object.freeze({});
+      invalidate();
+    },
+    rebase: runRebase,
+    setCtx(nextCtx) {
+      // Cast back to TCtx: setCtx's public signature takes unknown so
+      // callers don't need to plumb generics. If conditions depend on ctx
+      // and callers pass the wrong shape, the predicate throws at
+      // evaluation time — which is the same fail mode as any other
+      // callback contract violation.
+      ctx = nextCtx as TCtx;
+      invalidate();
+    },
+    async submit<TData = unknown>(): Promise<SubmitResult<TData>> {
+      const submitCfg = options.submit;
+      if (!submitCfg) {
+        throw new Error(
+          "createFormController: submit() called without a `submit` config. Configure `{ dispatcher, type }` on the controller or drive dispatching manually.",
+        );
+      }
+
+      // Concurrent-submit guard: a double-click (two invocations before
+      // the first network call returned) would otherwise fire two writes
+      // AND rebase twice — compounding with the stale-submit race below.
+      // Serialize: subsequent calls await the in-flight promise. Same
+      // pattern the server-side event-dispatcher uses (passInFlight).
+      if (submitInFlight) return submitInFlight as Promise<SubmitResult<TData>>;
+
+      if (!runValidate()) {
+        return { validationBlocked: true, isSuccess: false };
+      }
+
+      const payloadMode = submitCfg.payloadMode ?? "values";
+      // Capture the whole snapshot AT submit-time. The user may keep
+      // typing while the network call is in flight; on success we rebase
+      // ONLY to the values that were actually sent, leaving any
+      // subsequent edits as a fresh dirty delta. Without this, an edit
+      // during the await would be swallowed into the new baseline and
+      // the user would see it as "saved" despite the server never seeing
+      // it. Same snapshot is fed to buildPayload — a custom transformer
+      // (nested-write case) sees exactly what submit() sees.
+      const submittedSnapshot = snapshotStore.getSnapshot();
+      const submittedValues = submittedSnapshot.values;
+
+      // buildPayload wins over payloadMode when both are set.
+      let payload: unknown;
+      if (submitCfg.buildPayload) {
+        payload = submitCfg.buildPayload(submittedSnapshot);
+      } else if (payloadMode === "changes") {
+        if (submittedSnapshot.isUnchanged) {
+          return {
+            validationBlocked: false,
+            isSuccess: true,
+            data: submittedValues as unknown as TData,
+          };
+        }
+        payload = submittedSnapshot.changes;
+      } else {
+        payload = submittedValues;
+      }
+
+      const runWrite = async (): Promise<SubmitResult<TData>> => {
+        const result = await submitCfg.dispatcher.write<TData>(submitCfg.type, payload);
+
+        if (result.isSuccess) {
+          // Rebase to the SNAPSHOT, not to the current values — see
+          // runRebaseToSnapshot comment for why.
+          runRebaseToSnapshot(submittedValues);
+          return { validationBlocked: false, isSuccess: true, data: result.data };
+        }
+
+        const serverFields = result.error.details?.fields;
+        if (serverFields && serverFields.length > 0) {
+          errors = Object.freeze(groupIssuesByPath(serverFields));
+          invalidate();
+        }
+        return { validationBlocked: false, isSuccess: false, error: result.error };
+      };
+
+      submitInFlight = runWrite();
+      try {
+        return await (submitInFlight as Promise<SubmitResult<TData>>);
+      } finally {
+        submitInFlight = null;
+      }
+    },
+  };
+}

package/src/form/index.ts

@@ -0,0 +1,15 @@
+export { createFormController } from "./form-controller";
+export type {
+  FieldConditionPredicate,
+  FieldConditions,
+  FieldConditionValue,
+  FieldState,
+  FormController,
+  FormControllerOptions,
+  FormSnapshot,
+  FormValues,
+  SubmitConfig,
+  SubmitPayloadMode,
+  SubmitResult,
+} from "./types";
+export { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge";

package/src/form/types.ts

@@ -0,0 +1,264 @@
+import type { ZodType } from "zod";
+import type { Dispatcher, FieldIssue, WriteResult } from "../dispatcher";
+
+// Form-Controller contract.
+//
+// One controller per edit/create screen. Wraps a mutable "values" record
+// plus derived state (changes vs initial, per-field errors) and exposes a
+// subscribe API shaped for React's `useSyncExternalStore`. The framework's
+// renderer-react wraps this in a thin `useForm` hook; the mobile renderer
+// will do the same with the same controller.
+//
+// Why not just Zustand / a state library?
+// Form state has a small, well-defined shape — values, initial, changes,
+// errors, per-field meta. Building it on raw subscribe/emit keeps the
+// runtime deps at zero (this package imports nothing but types from
+// @cosmicdrift/kumiko-framework and zod), and leaves renderer-specific decisions
+// (batching, suspense) to the host framework.
+//
+// Snapshot identity: `getSnapshot()` returns the SAME reference until a
+// mutator (setField / setValues / reset / ...) runs. React compares by
+// identity when deciding whether to re-render — recomputing the snapshot
+// on every call would re-render on every tick. Mutators rebuild the
+// snapshot once, then notify listeners.
+
+export type FormValues = Record<string, unknown>;
+
+// Per-field conditional rules (Kumiko's "visible/readonly/required as
+// functions" decision, 2026-03-30). A rule is either a static boolean or a
+// predicate `(values, ctx) => boolean`. The controller evaluates them on
+// every snapshot rebuild and exposes the resolved booleans as
+// FieldState — renderers read `snapshot.fields[key].visible` and never
+// re-evaluate the predicate themselves.
+//
+// Why here and not on the framework's FieldDefinition: conditions are
+// UI-layer concerns (visibility depends on form state, not entity state)
+// and shouldn't couple the server-side schema. The App wires them up per
+// screen via the screen-def / form-controller options. The framework's
+// own `field.required` is mirrored here when present, so feature authors
+// can still declare "always required" once at the entity level.
+export type FieldConditionPredicate<TValues extends FormValues, TCtx> = (
+  values: TValues,
+  ctx: TCtx,
+) => boolean;
+
+export type FieldConditionValue<TValues extends FormValues, TCtx> =
+  | boolean
+  | FieldConditionPredicate<TValues, TCtx>;
+
+export type FieldConditions<TValues extends FormValues, TCtx = unknown> = {
+  readonly visible?: FieldConditionValue<TValues, TCtx>;
+  readonly readonly?: FieldConditionValue<TValues, TCtx>;
+  readonly required?: FieldConditionValue<TValues, TCtx>;
+};
+
+// Resolved per-field state, keyed by field name, surfaced on the snapshot.
+// Defaults (when no condition is declared): visible=true, readonly=false,
+// required=false — renderer treats a field with no rules as a normal
+// always-shown-always-editable field.
+export type FieldState = {
+  readonly visible: boolean;
+  readonly readonly: boolean;
+  readonly required: boolean;
+};
+
+// Immutable view handed to renderers. Every mutator call produces a fresh
+// snapshot; previous snapshot references stay valid for `useSyncExternalStore`'s
+// identity compare.
+export type FormSnapshot<TValues extends FormValues> = {
+  // Current values — the user's in-progress edit.
+  readonly values: TValues;
+  // Pristine values at mount / last `reset()`. Needed for:
+  //   - diffing `changes` (see below)
+  //   - the "discard changes?" prompt when the user navigates away dirty
+  //   - re-hydrating the form after an optimistic-update rollback
+  readonly initial: TValues;
+  // Changes-only: keys whose current value differs from initial, with the
+  // NEW value. The server uses this directly as the `payload` of an
+  // entity-level update command (Kumiko writes carry changes, not full
+  // objects) — see `docs/plans/architecture/event-sourcing-pivot.md`.
+  readonly changes: Partial<TValues>;
+  // True iff `changes` is non-empty. Convenience for the submit-button's
+  // disabled state and the unsaved-changes guard.
+  readonly isDirty: boolean;
+  // True iff no field was touched, kept separate from `isDirty` so UI code
+  // reads the right one without negation (= `!isDirty`). Form consumers
+  // will reach for both — they're not symmetric in intent (one is "can I
+  // submit?" and the other is "can I safely close?").
+  readonly isUnchanged: boolean;
+  // Per-field errors keyed by dotted path (`title`, `address.city`,
+  // `tasks.2.title`). Empty when the form is valid, populated after
+  // `validate()` or a failed submit. The dotted convention matches the
+  // server's ValidationError.fields[].path — a failed dispatcher call
+  // pushes its field issues here without any translation.
+  readonly errors: Readonly<Record<string, readonly FieldIssue[]>>;
+  // Resolved per-field state from FieldConditions. Renderers read this to
+  // decide whether to show the field, whether the input is disabled, and
+  // whether to show the required-marker. Fields without declared
+  // conditions default to `{ visible: true, readonly: false, required: false }`.
+  readonly fields: Readonly<Record<string, FieldState>>;
+};
+
+export type FormController<TValues extends FormValues> = {
+  // --- Subscribe surface (for useSyncExternalStore) ---
+
+  // Returns the current snapshot. SAME reference across calls until a
+  // mutator runs — callers rely on identity compare.
+  getSnapshot(): FormSnapshot<TValues>;
+
+  // Registers a listener that fires whenever the snapshot changes. Returns
+  // an unsubscribe function. Matches the `subscribe(listener) => unsubscribe`
+  // shape required by `useSyncExternalStore`.
+  subscribe(listener: () => void): () => void;
+
+  // --- Value mutators ---
+
+  // Sets one field. For scalar fields, `value` is the new value; for
+  // nested paths (lines/sub-forms) you'd use a sub-controller (Block 2b.4)
+  // instead of poking this with a dotted path.
+  setField<K extends keyof TValues>(key: K, value: TValues[K]): void;
+
+  // Bulk-update multiple fields at once. One snapshot rebuild + one
+  // notify, so a 5-field form-reset from a remote fetch doesn't cascade 5
+  // re-renders.
+  setValues(partial: Partial<TValues>): void;
+
+  // Clears field-level errors, keyed by dotted path. Used when the user
+  // starts typing again in a field that had a server-side failure —
+  // the UX hint should go away immediately, before the next validate()
+  // run. Pass no arguments to clear ALL errors.
+  clearErrors(path?: string): void;
+
+  // Replaces all errors (overwrite, not merge). Used by submit() to
+  // surface server-side validation failures and by external callers
+  // that want to project custom error state (e.g. a parent controller
+  // pushing down cross-field errors onto its children).
+  setErrors(errors: Readonly<Record<string, readonly FieldIssue[]>>): void;
+
+  // --- Validation ---
+
+  // Runs the controller's zod schema (if configured) against current
+  // values. Populates errors and returns true iff valid. Noop-returns
+  // `true` when no schema was wired — a controller without a schema
+  // relies entirely on server-side validation via the submit() path.
+  validate(): boolean;
+
+  // Reverts values to `initial`, clears errors. Doesn't fire a new
+  // "initial" baseline — to adopt the current values as the new baseline
+  // (e.g. after a successful submit), use `rebase()`.
+  reset(): void;
+
+  // Promotes the current values to the new `initial`, clears errors.
+  // After a successful submit the user should no longer see "unsaved
+  // changes" — rebase() is what the submit path calls internally to
+  // achieve that.
+  rebase(): void;
+
+  // Swap the external context threaded into field-condition predicates.
+  // Rare — most conditionals depend on values, not ctx — but needed when
+  // e.g. the user switches tenant mid-form and visibility rules key off
+  // tenant-scoped config.
+  setCtx(ctx: unknown): void;
+
+  // --- Submit ---
+  //
+  // Runs validate() first; if it fails, returns `{ validationBlocked: true,
+  // isSuccess: false }` WITHOUT a network call (the caller knows it's a
+  // user-level failure — show the errors, let them retry).
+  //
+  // If validation passes, dispatches to the configured submit.type with
+  // values or changes per submit.payloadMode. On server-side
+  // ValidationError, the error's field issues are pushed onto the form
+  // via setErrors so the UI reacts identically to local and remote
+  // validation failures. On success, rebase() — the form becomes "clean"
+  // and the data returned by the handler flows back via the result.
+  //
+  // Throws (not returns a failure) if `submit` config wasn't provided —
+  // a controller without submit-wiring has no destination, and guessing
+  // one would hide an integration bug.
+  submit<TData = unknown>(): Promise<SubmitResult<TData>>;
+};
+
+export type FormControllerOptions<TValues extends FormValues, TCtx = unknown> = {
+  readonly initial: TValues;
+  // Optional zod schema used by `validate()`. When present, validate()
+  // runs schema.safeParse(values) and populates the snapshot's errors
+  // map. When absent, validate() is a no-op that returns true — the
+  // controller defers entirely to server-side validation on submit.
+  //
+  // Typed as `ZodType` (not `ZodType<TValues>`) because a feature's
+  // input schema often narrows a subset of the form's surface (e.g.
+  // "changes-only" update-schemas) and re-exporting that precise type
+  // all the way through would chain generics across every layer. The
+  // runtime contract is that schema accepts the form's `values` shape.
+  readonly schema?: ZodType;
+  // Per-field conditional rules. Keyed by field name; unlisted fields
+  // get the default {visible:true, readonly:false, required:false}.
+  // See FieldConditions for the predicate signature.
+  readonly fields?: Readonly<Record<string, FieldConditions<TValues, TCtx>>>;
+  // External context passed to every field-condition predicate. Host app
+  // picks the shape — typically `{ user, tenant, config, featureToggles }`.
+  // Captured once; a ctx change without a corresponding setField/validate
+  // won't re-evaluate predicates. Use setCtx() to trigger re-evaluation
+  // when the ctx itself changes (rare in practice — most conditionals
+  // depend on values, not ctx).
+  readonly ctx?: TCtx;
+  // Optional submit wiring. When configured, `controller.submit()` runs
+  // local validate() then dispatches to the configured type with the
+  // selected payload, maps server-side field errors back onto the form,
+  // and — on success — rebases so "unsaved changes" goes quiet.
+  //
+  // Omitted when the caller drives dispatching manually (custom-screen
+  // cases, or when a multi-step wizard needs finer control). In that
+  // case submit() throws rather than guessing a destination.
+  readonly submit?: SubmitConfig<TValues>;
+};
+
+// How the form's payload is derived when submit() runs. Kumiko's write
+// convention says commands carry CHANGES (delta since initial), not full
+// objects — but that assumes an update flow. For creates, `changes ===
+// values` in practice because initial is empty.
+//
+//   - "values"  — send the full current `values` object. Right for create
+//                 handlers whose schema expects a full entity payload.
+//   - "changes" — send only the `changes` delta. Right for update
+//                 handlers; noop when the form is un-dirty (submit
+//                 short-circuits into a no-network success).
+//
+// Default is "values" — the common M1 case is a create-screen wiring
+// straight through. Update-screens opt in with "changes".
+export type SubmitPayloadMode = "values" | "changes";
+
+export type SubmitConfig<TValues extends FormValues = FormValues> = {
+  readonly dispatcher: Dispatcher;
+  // Qualified write-handler name (e.g. "orders:write:order:create").
+  readonly type: string;
+  readonly payloadMode?: SubmitPayloadMode;
+  // Optional payload transformer — overrides payloadMode. Used for
+  // nested-writes: the submit path calls buildPayload(snapshot) once at
+  // submit-time and sends the result. The snapshot is the one captured
+  // before the network call, so in-flight edits during the await don't
+  // leak into the payload.
+  //
+  // Typical shape for a parent form with hasMany child controllers:
+  //
+  //   buildPayload: (snap) => ({
+  //     ...snap.values,
+  //     lines: lineControllers.map(c => c.getSnapshot().values),
+  //   })
+  //
+  // When both buildPayload and payloadMode are set, buildPayload wins.
+  // That's intentional: a caller choosing to write a transformer is
+  // making an explicit statement about payload shape.
+  readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+};
+
+// What submit() returns. Mirrors WriteResult so a failed submit can
+// carry the structured DispatcherError unchanged — callers log or toast
+// based on error.code without the form-controller guessing UX intent.
+// `validationBlocked: true` signals a LOCAL (pre-dispatch) validate()
+// failure — no network call happened; caller doesn't need to retry the
+// network, the user needs to fix fields.
+export type SubmitResult<TData = unknown> =
+  | ({ readonly validationBlocked: false } & WriteResult<TData>)
+  | { readonly validationBlocked: true; readonly isSuccess: false };