@kontsedal/olas-core 0.0.1 → 0.0.3

package/src/controller/types.ts

@@ -42,6 +42,10 @@ export interface AmbientDeps {
  * `ctx.field(initial, validators?)`. Spec §8, §20.7.
  */
 export type Field<T> = ReadSignal<T> & {
+  /**
+   * All errors currently surfaced on this field — validator errors first,
+   * server errors after. See `setErrors` for the server-error channel.
+   */
   errors: ReadSignal<string[]>
   isValid: ReadSignal<boolean>
   isDirty: ReadSignal<boolean>
@@ -59,6 +63,15 @@ export type Field<T> = ReadSignal<T> & {
   reset(): void
   markTouched(): void
   revalidate(): Promise<boolean>
+  /**
+   * Pin externally-sourced errors on the field — typically server-side
+   * validation results returned from a failed submit. These errors live in
+   * a separate channel from validator output, so a re-run of local
+   * validators (triggered by a new value or `revalidate()`) does NOT clear
+   * them. They're cleared automatically the next time the user writes to
+   * the field (via `set`), or explicitly via `setErrors([])` / `reset()`.
+   */
+  setErrors(errors: ReadonlyArray<string>): void
   /** Idempotent. Called by the owning controller's dispose. */
   dispose(): void
 }
@@ -79,6 +92,80 @@ export type CtrlProps<C> = C extends ControllerDef<infer P, unknown> ? P : never
 /** Extract a controller's Api type. */
 export type CtrlApi<C> = C extends ControllerDef<unknown, infer A> ? A : never
 
+/**
+ * The reactive surface returned by `ctx.collection(...)`. `items` is the
+ * canonical ordered view (source-order, with any construction-failed items
+ * filtered out); `size` mirrors `items.length`; `get` / `has` are
+ * imperative key lookups. SPEC §11.1.
+ */
+export type Collection<K, Api> = {
+  readonly items: ReadSignal<ReadonlyArray<{ readonly key: K; readonly api: Api }>>
+  readonly size: ReadSignal<number>
+  get(key: K): Api | undefined
+  has(key: K): boolean
+}
+
+/**
+ * Homogeneous form of `ctx.collection`: one controller def for every item,
+ * with `propsOf` projecting each item to the controller's `Props`. Construct
+ * happens once per new key — `propsOf` is **not** re-applied for unchanged
+ * keys.
+ */
+export type CollectionHomogeneousOptions<Item, K, Props, Api, TDeps = AmbientDeps> = {
+  readonly source: ReadSignal<readonly Item[]>
+  readonly keyOf: (item: Item) => K
+  readonly controller: ControllerDef<Props, Api>
+  readonly propsOf: (item: Item) => Props
+  readonly factory?: never
+  readonly propsFor?: never
+  readonly deps?: Partial<TDeps>
+}
+
+/**
+ * Heterogeneous form of `ctx.collection`: a single `factory` decides per-item
+ * which controller + props to construct. When a key's factory result picks a
+ * *different* controller than last time, the existing child is disposed and
+ * the new one constructed (type-discriminant rebuild).
+ *
+ * `R` is the factory's *return type* (typically inferred as the union of the
+ * branches' `{ controller, props }` shapes). `Api` is then projected out as
+ * the union of every branch's controller Api via `CollectionFactoryApi<R>` —
+ * unlike a single `Api` generic, the union doesn't collapse to the first
+ * branch.
+ */
+export type CollectionFactoryOptions<Item, K, R, TDeps = AmbientDeps> = {
+  readonly source: ReadSignal<readonly Item[]>
+  readonly keyOf: (item: Item) => K
+  readonly controller?: never
+  readonly propsOf?: never
+  readonly factory: (item: Item) => R
+  readonly deps?: Partial<TDeps>
+}
+
+/** Constraint for the factory form's return shape. */
+// biome-ignore lint/suspicious/noExplicitAny: per-branch types vary
+export type CollectionFactoryResult = { controller: ControllerDef<any, any>; props: any }
+
+/** Extract the union of every branch's controller Api. Distributes over R. */
+export type CollectionFactoryApi<R> = R extends {
+  // biome-ignore lint/suspicious/noExplicitAny: distributive infer across the union
+  controller: ControllerDef<any, infer A>
+}
+  ? A
+  : never
+
+/**
+ * Handle returned by `ctx.lazyChild(...)`. `status` walks `idle → loading →
+ * (ready | error)`; `api` becomes defined once `status === 'ready'`. SPEC §16.5.
+ */
+export type LazyChild<Api> = {
+  readonly status: ReadSignal<'idle' | 'loading' | 'ready' | 'error'>
+  readonly api: ReadSignal<Api | undefined>
+  readonly error: ReadSignal<unknown | undefined>
+  load(): Promise<Api>
+  dispose(): void
+}
+
 /**
  * `ctx` is the lifecycle-bound surface every controller factory receives.
  * Every primitive constructed through `ctx` is owned by the controller and
@@ -106,6 +193,13 @@ export type Ctx<TDeps = AmbientDeps> = {
     source: InfiniteQuery<Args, TPage, TItem>,
     keyOrOptions?: (() => Args) | UseOptions<Args>,
   ): InfiniteQuerySubscription<TPage, TItem>
+  // Overload — `select` projects T → U; the returned subscription's `data`
+  // is `U | undefined`. The required `select` field is the discriminator
+  // that picks this overload over the plain-key one above.
+  use<Args extends unknown[], T, U>(
+    source: Query<Args, T>,
+    options: { key?: () => Args; enabled?: () => boolean; select: (data: T) => U },
+  ): QuerySubscription<U>
 
   mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>
 
@@ -150,6 +244,63 @@ export type Ctx<TDeps = AmbientDeps> = {
     options?: { deps?: Partial<TDeps> },
   ): { api: Api; dispose: () => void; suspend: () => void; resume: () => void }
 
+  /**
+   * Ephemeral child controller bound to either (a) the explicit `dispose()`
+   * call returned in the tuple, or (b) the parent's disposal — whichever
+   * comes first. Same lifecycle semantics as `ctx.attach` minus suspend /
+   * resume (sessions are short-lived, not pause-able). Returns a `[api,
+   * dispose]` tuple so the api shape is exactly the controller's return
+   * type, with no wrapper to unpack.
+   *
+   * Use cases: modal forms, inline edit sessions, wizards, command palette.
+   * SPEC §11.1.
+   */
+  session<Props, Api>(
+    def: ControllerDef<Props, Api>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): readonly [api: Api, dispose: () => void]
+
+  /**
+   * Diff-by-key set of child controllers driven by a reactive `source`.
+   * On every change to `source`, the collection:
+   *   - **new keys** → construct a child via `controller` + `propsOf(item)`
+   *     (or `factory(item)` for the heterogeneous form);
+   *   - **removed keys** → dispose that child;
+   *   - **unchanged keys** → leave it alone (`propsOf` is NOT re-applied).
+   *
+   * For per-item type-discriminated children, use the `factory` form —
+   * type changes for an existing key dispose and reconstruct.
+   *
+   * Construction errors (factory or controller throw) are routed to
+   * `onError` with `kind: 'construction'` and the item is **skipped** —
+   * the collection's surface shows one fewer entry. The diff loop does
+   * not re-throw. SPEC §11.1, §12.1.6.
+   */
+  collection<Item, K, Props, Api>(
+    options: CollectionHomogeneousOptions<Item, K, Props, Api, TDeps>,
+  ): Collection<K, Api>
+  collection<Item, K, R extends CollectionFactoryResult>(
+    options: CollectionFactoryOptions<Item, K, R, TDeps>,
+  ): Collection<K, CollectionFactoryApi<R>>
+
+  /**
+   * Code-split child controller. The loader is invoked on `load()`
+   * (idempotent), then the controller is constructed with the supplied
+   * `props`. `status` / `api` / `error` are reactive signals; subscribe
+   * via `use(child.api)` in your view layer.
+   *
+   * Parent disposal disposes the loaded child (if any) and flags any
+   * in-flight load so its eventual settle is dropped on the floor.
+   * Construction or import failures route through `onError` with
+   * `kind: 'construction'`. SPEC §16.5.
+   */
+  lazyChild<Props, Api>(
+    loader: () => Promise<ControllerDef<Props, Api>>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): LazyChild<Api>
+
   effect(fn: () => void | (() => void)): void
 
   on<T>(emitter: Emitter<T>, handler: (value: T) => void): void

package/src/emitter.ts

@@ -20,17 +20,43 @@ export type Emitter<T> = {
 
 type AnyHandler = (value: unknown) => void
 
+/**
+ * Optional escape hatch for emit-time handler throws. If supplied, a thrown
+ * handler is reported here and emission continues with the remaining handlers
+ * (spec §20.6 — one throwing handler must not block the rest). If absent,
+ * the throw is logged via `console.error`.
+ */
+export type EmitterErrorReporter = (err: unknown) => void
+
 class EmitterImpl<T> {
   private handlers = new Set<AnyHandler>()
   private disposed = false
 
+  constructor(private onError?: EmitterErrorReporter) {}
+
   emit(value: T): void {
     if (this.disposed) return
     // Snapshot so a handler that unsubscribes itself (or another) doesn't
     // mutate the set mid-iteration.
     const snapshot = Array.from(this.handlers)
     for (const handler of snapshot) {
-      handler(value as unknown)
+      try {
+        handler(value as unknown)
+      } catch (err) {
+        // Spec §20.6: isolate handler throws so siblings still fire.
+        if (this.onError) {
+          try {
+            this.onError(err)
+          } catch {
+            // Reporter itself threw — last resort.
+            // eslint-disable-next-line no-console
+            console.error('[olas] emitter handler threw and reporter threw:', err)
+          }
+        } else {
+          // eslint-disable-next-line no-console
+          console.error('[olas] emitter handler threw:', err)
+        }
+      }
     }
   }
 
@@ -67,9 +93,14 @@ class EmitterImpl<T> {
  * (or the emitter is disposed). Use this for emitters that live outside any
  * single controller — typically in deps. Use `ctx.emitter()` for emitters that
  * should auto-clean with a controller.
+ *
+ * Pass `onError` to receive emit-time handler throws (spec §20.6 — one
+ * throwing handler must not block the rest of the fan-out). `ctx.emitter()`
+ * wires this to the root's `onError` so deps-level emitters get isolation
+ * by default when constructed via `ctx`.
  */
-export function createEmitter<T = void>(): Emitter<T> {
-  const impl = new EmitterImpl<T>()
+export function createEmitter<T = void>(options?: { onError?: EmitterErrorReporter }): Emitter<T> {
+  const impl = new EmitterImpl<T>(options?.onError)
   return {
     emit: ((value?: T) => impl.emit(value as T)) as Emitter<T>['emit'],
     on: (handler) => impl.on(handler),

package/src/forms/field.ts

@@ -36,7 +36,18 @@ export type ValidatorErrorReporter = (err: unknown) => void
 
 class FieldImpl<T> implements Field<T> {
   private readonly value$: Signal<T>
-  private readonly errors$: Signal<string[]>
+  /**
+   * Validator-produced errors. The public `errors` getter merges this with
+   * `serverErrors$` so consumers see a single flat array. Kept separate so a
+   * re-run of validators (after a new value) doesn't clobber server errors.
+   */
+  private readonly validatorErrors$: Signal<string[]>
+  /**
+   * Externally-injected errors — see `setErrors`. Cleared on the next user
+   * `set()`, on `reset()`, or via an explicit `setErrors([])`.
+   */
+  private readonly serverErrors$: Signal<string[]>
+  private readonly errors$: Computed<string[]>
   private readonly touched$: Signal<boolean>
   private readonly dirty$: Signal<boolean>
   private readonly validating$: Signal<boolean>
@@ -67,11 +78,19 @@ class FieldImpl<T> implements Field<T> {
     // post-construct hook so it can't catch the first run).
     this.onValidatorError = options?.onValidatorError ?? null
     this.value$ = signal(initial)
-    this.errors$ = signal<string[]>([])
+    this.validatorErrors$ = signal<string[]>([])
+    this.serverErrors$ = signal<string[]>([])
     this.touched$ = signal(false)
     this.dirty$ = signal(false)
     this.validating$ = signal(false)
     this.revalidateTrigger$ = signal(0)
+    this.errors$ = computed(() => {
+      const v = this.validatorErrors$.value
+      const s = this.serverErrors$.value
+      if (s.length === 0) return v
+      if (v.length === 0) return s
+      return [...v, ...s]
+    })
     this.isValid$ = computed(() => this.errors$.value.length === 0 && !this.validating$.value)
 
     if (validators.length > 0) {
@@ -126,8 +145,21 @@ class FieldImpl<T> implements Field<T> {
   // --- mutating methods ---
   set(value: T): void {
     if (this.disposed) return
-    this.value$.set(value)
-    this.dirty$.set(true)
+    batch(() => {
+      this.value$.set(value)
+      this.dirty$.set(true)
+      // Server errors are pinned externally and survive validator re-runs,
+      // but they MUST clear when the user edits the field — otherwise a
+      // server error like "username taken" would persist after the user
+      // typed a different username.
+      if (this.serverErrors$.peek().length > 0) this.serverErrors$.set([])
+    })
+  }
+
+  setErrors(errors: ReadonlyArray<string>): void {
+    if (this.disposed) return
+    const next = errors.length === 0 ? [] : [...errors]
+    this.serverErrors$.set(next)
   }
 
   /**
@@ -154,7 +186,8 @@ class FieldImpl<T> implements Field<T> {
       this.value$.set(this.initial)
       this.dirty$.set(false)
       this.touched$.set(false)
-      this.errors$.set([])
+      this.validatorErrors$.set([])
+      this.serverErrors$.set([])
       this.validating$.set(false)
     })
   }
@@ -262,7 +295,7 @@ class FieldImpl<T> implements Field<T> {
 
     if (syncErrors.length > 0) {
       batch(() => {
-        this.errors$.set(syncErrors)
+        this.validatorErrors$.set(syncErrors)
         this.validating$.set(false)
       })
       this.emitValidated(false, syncErrors)
@@ -271,7 +304,7 @@ class FieldImpl<T> implements Field<T> {
 
     if (asyncPromises.length === 0) {
       batch(() => {
-        this.errors$.set([])
+        this.validatorErrors$.set([])
         this.validating$.set(false)
       })
       this.emitValidated(true, [])
@@ -279,7 +312,7 @@ class FieldImpl<T> implements Field<T> {
     }
 
     batch(() => {
-      this.errors$.set([])
+      this.validatorErrors$.set([])
       this.validating$.set(true)
     })
 
@@ -295,7 +328,7 @@ class FieldImpl<T> implements Field<T> {
         }
       }
       batch(() => {
-        this.errors$.set(asyncErrors)
+        this.validatorErrors$.set(asyncErrors)
         this.validating$.set(false)
       })
       this.emitValidated(asyncErrors.length === 0, asyncErrors)

package/src/forms/form-types.ts

@@ -90,6 +90,22 @@ export type Form<S extends FormSchema> = {
   readonly touched: ReadSignal<boolean>
   readonly isValidating: ReadSignal<boolean>
 
+  /**
+   * `true` while a `submit(...)` is in flight. Clears when the handler
+   * resolves, throws, or pre-submit validation fails.
+   */
+  readonly isSubmitting: ReadSignal<boolean>
+  /** Number of times `submit(...)` has been called. Bumps before the handler runs. */
+  readonly submitCount: ReadSignal<number>
+  /**
+   * The thrown value from the most recent failed submission, if any.
+   * Cleared at the start of each new `submit(...)` call and on `reset()`.
+   * Note that a validation failure ("submit blocked because the form is
+   * invalid") is NOT a thrown error — `submitError` stays whatever it
+   * was, and the returned promise resolves with `{ ok: false }`.
+   */
+  readonly submitError: ReadSignal<unknown>
+
   /** Deep-merge a partial value into the form, batched. */
   set(partial: DeepPartial<FormValue<S>>): void
   /**
@@ -105,6 +121,27 @@ export type Form<S extends FormSchema> = {
   markAllTouched(): void
   /** Re-run every leaf's validators. Resolves with true if all leaves are valid. */
   validate(): Promise<boolean>
+  /**
+   * Run a submission. Pre-validates the form (unless `validateBeforeSubmit: false`),
+   * then calls `handler(value)`. Maintains `isSubmitting` / `submitCount` /
+   * `submitError`. Returns `{ ok, data?, error? }` — see `FormImpl.submit`
+   * for the full contract.
+   */
+  submit(
+    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+    options?: {
+      validateBeforeSubmit?: boolean
+      resetOnSuccess?: boolean
+      onError?: 'rethrow' | 'capture'
+    },
+  ): Promise<{ ok: boolean; data?: unknown; error?: unknown }>
+  /**
+   * Pin externally-sourced errors on specific fields. Keys are dot-separated
+   * paths through nested forms / field arrays (numeric segments are array
+   * indices). Errors land in each field's `serverErrors` channel — kept
+   * separate from validator output and auto-cleared on the next user write.
+   */
+  setErrors(errors: Record<string, ReadonlyArray<string>>): void
   /** Idempotent. Called by the owning controller's dispose. */
   dispose(): void
 }

package/src/forms/form.ts

@@ -51,6 +51,14 @@ class FormImpl<S extends FormSchema> implements Form<S> {
   readonly topLevelErrors: ReadSignal<string[]> = this.topLevelErrors$
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
 
+  // Submission lifecycle.
+  private readonly isSubmitting$: Signal<boolean> = signal(false)
+  private readonly submitCount$: Signal<number> = signal(0)
+  private readonly submitError$: Signal<unknown> = signal(undefined)
+  readonly isSubmitting: ReadSignal<boolean> = this.isSubmitting$
+  readonly submitCount: ReadSignal<number> = this.submitCount$
+  readonly submitError: ReadSignal<unknown> = this.submitError$
+
   private readonly validators: ReadonlyArray<FormValidator<S>>
   private readonly options: FormOptions<S> | undefined
   private validatorDispose: (() => void) | null = null
@@ -202,10 +210,42 @@ class FormImpl<S extends FormSchema> implements Form<S> {
         }
       } else if (isFieldArray(child)) {
         const arr = child
-        // Replace items: clear, then add each
-        arr.clear()
-        for (const itemVal of val as unknown[]) {
-          arr.add(itemVal as ItemInitial<Field<unknown>>)
+        const newValues = val as unknown[]
+        if (asInitial) {
+          // Reset-style application: replace items wholesale and re-anchor
+          // them as the new initial so a later `reset()` returns here.
+          arr.clear()
+          for (const itemVal of newValues) {
+            arr.add(itemVal as ItemInitial<Field<unknown>>)
+          }
+          // Internal: re-anchor the initialItems list. `replaceInitialItems`
+          // is only exposed for this exact use case.
+          ;(
+            arr as unknown as {
+              replaceInitialItems: (items: ReadonlyArray<unknown>) => void
+            }
+          ).replaceInitialItems(newValues)
+        } else {
+          // User-driven patch: preserve item identity where the lengths
+          // overlap so touched / dirty / in-flight validators on existing
+          // items survive. Tail diff handles grow / shrink.
+          const current = arr.items.peek() as ReadonlyArray<Field<unknown> | Form<FormSchema>>
+          const overlap = Math.min(current.length, newValues.length)
+          for (let i = 0; i < overlap; i++) {
+            const item = current[i]
+            const v = newValues[i]
+            if (isForm(item)) {
+              item.set(v as DeepPartial<FormValue<FormSchema>>)
+            } else {
+              ;(item as Field<unknown>).set(v)
+            }
+          }
+          for (let i = current.length; i < newValues.length; i++) {
+            arr.add(newValues[i] as ItemInitial<Field<unknown>>)
+          }
+          for (let i = current.length - 1; i >= newValues.length; i--) {
+            arr.remove(i)
+          }
         }
       } else {
         const f = child as Field<unknown>
@@ -281,6 +321,116 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     return this.isValid.peek()
   }
 
+  /**
+   * Run a submission against this form. Wraps `handler(value)` with:
+   * - `isSubmitting` set true while the handler is in flight.
+   * - `submitCount` incremented before the handler runs.
+   * - `submitError` set to the throw, if any.
+   * - Optional pre-submit `validate()` (default true). When invalid every
+   *   field is marked touched and the handler is skipped — the returned
+   *   promise resolves with `{ ok: false }` and `submitError` is left
+   *   untouched (validation failure is not a thrown error).
+   *
+   * The handler may return a value (synchronously or via Promise); it's
+   * captured in the resolved object's `data` field. Throws are captured
+   * unless `onError: 'rethrow'`. A `resetOnSuccess: true` option calls
+   * `reset()` after the handler resolves successfully.
+   */
+  async submit(
+    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+    options?: {
+      validateBeforeSubmit?: boolean
+      resetOnSuccess?: boolean
+      onError?: 'rethrow' | 'capture'
+    },
+  ): Promise<{ ok: boolean; data?: unknown; error?: unknown }> {
+    if (this.disposed) return { ok: false, error: new Error('form is disposed') }
+
+    // Double-submit guard — refusing to start a second submission while one
+    // is in flight matches RHF / TanStack-Form. Consumers wanting parallel
+    // submits should run them off the form directly.
+    if (this.isSubmitting$.peek()) {
+      return { ok: false, error: new Error('submit already in progress') }
+    }
+
+    const validateFirst = options?.validateBeforeSubmit ?? true
+    const onErrorMode = options?.onError ?? 'capture'
+
+    batch(() => {
+      this.submitCount$.update((n) => n + 1)
+      this.submitError$.set(undefined)
+      this.isSubmitting$.set(true)
+    })
+
+    try {
+      if (validateFirst) {
+        const ok = await this.validate()
+        if (!ok) {
+          this.markAllTouched()
+          this.isSubmitting$.set(false)
+          return { ok: false }
+        }
+      }
+      const result = await handler(this.value.peek())
+      if (options?.resetOnSuccess) this.reset()
+      this.isSubmitting$.set(false)
+      return { ok: true, data: result }
+    } catch (err) {
+      batch(() => {
+        this.submitError$.set(err)
+        this.isSubmitting$.set(false)
+      })
+      if (onErrorMode === 'rethrow') throw err
+      return { ok: false, error: err }
+    }
+  }
+
+  /**
+   * Pin externally-sourced errors on specific fields — typically server-side
+   * validation results from a failed submit. Paths are dot-separated and
+   * traverse nested `Form` / `FieldArray` children (numeric segments are
+   * array indices). Errors land in the field's `serverErrors` channel and
+   * clear automatically on the next user write to that field. Passing an
+   * empty array for a path clears that field's server errors immediately.
+   */
+  setErrors(errors: Record<string, ReadonlyArray<string>>): void {
+    if (this.disposed) return
+    batch(() => {
+      for (const [path, msgs] of Object.entries(errors)) {
+        const target = this.resolvePath(path)
+        if (target === undefined) continue
+        if ((target as { setErrors?: unknown }).setErrors === undefined) continue
+        ;(target as { setErrors: (e: ReadonlyArray<string>) => void }).setErrors(msgs)
+      }
+    })
+  }
+
+  private resolvePath(path: string): unknown {
+    if (path === '') return undefined
+    const segments = path.split('.')
+    let cursor: unknown = this
+    for (const seg of segments) {
+      if (cursor === undefined || cursor === null) return undefined
+      if (isForm(cursor)) {
+        cursor = (cursor.fields as Record<string, unknown>)[seg]
+        continue
+      }
+      if (isFieldArray(cursor)) {
+        const idx = Number(seg)
+        if (!Number.isInteger(idx) || idx < 0) return undefined
+        cursor = (cursor as { at(i: number): unknown }).at(idx)
+        continue
+      }
+      // Top-level dispatch — `this` is the FormImpl; walk via `fields`.
+      if (cursor === this) {
+        cursor = (this.fields as Record<string, unknown>)[seg]
+        continue
+      }
+      return undefined
+    }
+    return cursor
+  }
+
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
@@ -403,7 +553,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
 
   private readonly itemFactory: (initial?: ItemInitial<I>) => I
-  private readonly initialItems: Array<ItemInitial<I>> = []
+  private initialItems: Array<ItemInitial<I>> = []
   private readonly validators: ReadonlyArray<FieldArrayValidator<I>>
   private currentValidatorRun = 0
   private currentValidatorAbort: AbortController | null = null
@@ -528,6 +678,16 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     this.items$.set([])
   }
 
+  /**
+   * Internal — used by `Form.resetWithInitial` to re-anchor the array's
+   * initial items after a parent-driven `applyPartial(..., asInitial: true)`.
+   * Without this, a subsequent `reset()` would revert to the construction-
+   * time initials rather than the most-recently-applied ones.
+   */
+  replaceInitialItems(items: ReadonlyArray<ItemInitial<I>>): void {
+    this.initialItems = [...items]
+  }
+
   reset(): void {
     if (this.disposed) return
     batch(() => {

package/src/forms/index.ts

@@ -1,2 +1,13 @@
+export type { StandardSchemaV1 } from './standard-schema'
+export { isStandardSchema } from './standard-schema'
 export type { Validator } from './types'
-export { email, max, maxLength, min, minLength, pattern, required } from './validators'
+export {
+  email,
+  max,
+  maxLength,
+  min,
+  minLength,
+  pattern,
+  required,
+  validator,
+} from './validators'

package/src/forms/standard-schema.ts

@@ -0,0 +1,37 @@
+/**
+ * Standard Schema v1 — the cross-library validation contract adopted by
+ * Zod 4, Valibot 1, ArkType 2, and others. See https://standardschema.dev.
+ *
+ * We type-only-import the shape so consumers don't take a new runtime dep:
+ * any object with a `~standard.validate(value)` method conforming to this
+ * structure works.
+ */
+export type StandardSchemaV1Issue = {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+}
+
+export type StandardSchemaV1Result<O> =
+  | { readonly value: O; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<StandardSchemaV1Issue> }
+
+export type StandardSchemaV1<I = unknown, O = I> = {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: string
+    validate(value: unknown): StandardSchemaV1Result<O> | Promise<StandardSchemaV1Result<O>>
+    readonly types?: { readonly input: I; readonly output: O } | undefined
+  }
+}
+
+/**
+ * Heuristic: does `x` look like a Standard Schema?
+ */
+export function isStandardSchema(x: unknown): x is StandardSchemaV1<unknown, unknown> {
+  return (
+    x !== null &&
+    typeof x === 'object' &&
+    '~standard' in x &&
+    typeof (x as { '~standard': { validate?: unknown } })['~standard']?.validate === 'function'
+  )
+}