@pilotiq/pilotiq 0.10.0 → 0.12.0

package/src/react/FormCollabBindingRegistry.ts

@@ -55,11 +55,18 @@ export interface TextBinding {
  *   - `subscribe(fn)` registers a listener that fires when REMOTE
  *     changes land; `fn(snapshot)` receives the full updated map.
  *     The provider re-applies this snapshot onto its React state.
- *   - `getTextBinding(name)` (Phase F.6) returns a `Y.Text`-backed
- *     handle for text-shaped fields, or `null` for non-text fields and
- *     text fields opted out via `.collab(false)`. The text/non-text
- *     allowlist lives in the binding impl — `FormStateProvider` asks
- *     for every field and routes per-field on the answer.
+ *   - `getTextBinding(name)` (Phase F.6) was the per-field `Y.Text`
+ *     handle for character-level CRDT on top-level text inputs. After
+ *     the Tiptap-backed text-collab swap (Phase D, 2026-05), bindings
+ *     are expected to return `null` for every top-level field —
+ *     character-level CRDT now lives in the Tiptap renderer's
+ *     `Collaboration` extension (`Y.XmlFragment` per field). Returning
+ *     a non-null `TextBinding` here is still supported for legacy
+ *     bindings, but the active `@pilotiq-pro/collab` impl no longer
+ *     allocates `Y.Text` for top-level fields. Row-text leaves under
+ *     Repeater / Builder continue to route through Y.Text via
+ *     `getRowTextBinding` — the Tiptap-backed renderer only handles
+ *     top-level (non-dotted-path) field names today.
  *   - `destroy()` is called on unmount — gives the plugin a chance to
  *     remove its CRDT observer. Implementations are expected to cascade
  *     into every `TextBinding` they issued.
@@ -74,16 +81,150 @@ export interface FormCollabBinding {
   set(name: string, value: unknown): void
   /** Subscribe to remote changes. Returns an unsubscribe function. */
   subscribe(fn: (snapshot: Record<string, unknown>) => void): () => void
-  /** Phase F.6 — per-field text-CRDT handle. Returns `null` for non-text
-   *  fields or text fields opted out via `.collab(false)`. Optional so
-   *  existing F1-era plugins keep type-checking without a no-op stub;
-   *  when absent, every text field stays on today's whole-string LWW
-   *  path (i.e. F.6 character-level CRDT is opt-in by impl). */
+  /** Phase F.6 / Phase D — per-field text-CRDT handle. Post Phase D,
+   *  `@pilotiq-pro/collab` returns `null` for every top-level text
+   *  field (character-level CRDT moved into `@pilotiq/tiptap`'s
+   *  `CollabTextRenderer`, which mounts its own `Y.XmlFragment` per
+   *  field via the `Collaboration` extension). The method is preserved
+   *  on the contract for legacy bindings and for the row-text leaves
+   *  routed through `getRowTextBinding` (under Repeater / Builder).
+   *  Optional so existing F1-era plugins keep type-checking without a
+   *  no-op stub; absent reads as "binding has no top-level text CRDT
+   *  surface," same as returning `null` for every field. */
   getTextBinding?(name: string): TextBinding | null
   /** Cleanup hook called when the form unmounts. */
   destroy():    void
+
+  // ── Phase F.5 — Repeater / Builder row-identity surface (all optional) ──
+
+  /**
+   * Add a row to a Repeater or Builder field. `rowId` is the stable
+   * `__id` the renderer already mints (UUID for new rows / DB PK for
+   * relationship-backed rows) — the binding indexes the row's CRDT
+   * surface by this id so concurrent inserts from peers both survive.
+   *
+   * Idempotent — calling with a `rowId` that already exists in the
+   * Repeater's array is a no-op. `initial` may carry pre-filled values
+   * for the new row (e.g. the inner fields' `default()` from schema
+   * resolution); the binding seeds them onto the row's storage under
+   * the same idempotent posture as top-level `set` (first writer wins
+   * across concurrent first-mounters).
+   *
+   * Renderer call sites: `RepeaterInput.addRow()` + `BuilderInput.addBlock()`.
+   * When absent, F.5 row-level CRDT degrades to v1 behaviour (whole-array
+   * LWW under the top-level Y.Map).
+   */
+  addRow?(arrayName: string, rowId: string, initial: Record<string, unknown>): void
+
+  /**
+   * Remove a row from a Repeater/Builder field by stable id. Idempotent
+   * — a missing `rowId` is a no-op. Triggered by the renderer's row
+   * delete button.
+   */
+  removeRow?(arrayName: string, rowId: string): void
+
+  /**
+   * Apply a new row order. `newOrder` is the full list of row ids in
+   * their final positions; the binding computes the minimal CRDT move
+   * sequence and applies it inside a single transaction (peers see one
+   * coalesced update, not N intermediate states).
+   *
+   * Called by drag-and-drop / up-down move handlers in
+   * `RepeaterInput` + `BuilderInput`.
+   */
+  reorderRows?(arrayName: string, newOrder: string[]): void
+
+  /**
+   * Write a single field on a row. Replaces the dotted-path `set` for
+   * row leaves (`tags.0.label` → `setRow('tags', rowId, 'label', value)`).
+   *
+   * Binding routes by allowlist same as top-level `set`: text-shaped
+   * fields go through the row's `TextBinding` when a `Y.Text` exists
+   * (see `getRowTextBinding`); non-text fields land on the row's
+   * scalar field-map under LWW.
+   *
+   * `FormStateProvider` calls this on every local edit when both a
+   * dotted-path name is being written AND `setRow` is implemented;
+   * otherwise the v1 skip-on-dot path runs.
+   */
+  setRow?(arrayName: string, rowId: string, fieldName: string, value: unknown): void
+
+  /**
+   * Per-row text-CRDT handle. Composes with F.6's `BoundTextInput`:
+   * the renderer asks for one of these when a row leaf is text-shaped
+   * AND not opted out via `.collab(false)`, then threads it through
+   * the existing `TextBinding` plumbing inside the row.
+   *
+   * Returns `null` for non-text fields, fields opted out via collab,
+   * rows not yet present in the binding's index (e.g. before
+   * `addRow` has propagated), or when the binding doesn't yet
+   * implement per-row text CRDT (deferred to F.5c).
+   */
+  getRowTextBinding?(arrayName: string, rowId: string, fieldName: string): TextBinding | null
+
+  /**
+   * Subscribe to row-lifecycle events for a Repeater/Builder array.
+   * Fires on remote add / remove / move; the renderer reconciles its
+   * `rows` state by `__id`. Local mutations fire too — the renderer
+   * deduplicates by checking whether the event's `rowId` matches one
+   * it just dispatched itself (the binding's roundtrip + the
+   * renderer's optimistic update converge).
+   */
+  subscribeRows?(arrayName: string, fn: (event: RowsEvent) => void): () => void
+}
+
+/**
+ * Phase F.5 — array-scoped imperative API exposed to Repeater / Builder
+ * renderers through `useRowBinding(arrayName)`. Each method's first arg
+ * (`arrayName`) is pre-bound by the hook so call sites read naturally.
+ *
+ * Returned by the hook only when the active binding implements all four
+ * F.5 row methods (`addRow + removeRow + reorderRows`); partial impls
+ * read as null so renderers can do a single existence check before
+ * proceeding. `setRow` is intentionally NOT exposed here — it's invoked
+ * implicitly via `FormStateProvider.setValue`'s dotted-path routing,
+ * so renderers never need to touch it directly.
+ */
+export interface RowBindingApi {
+  /** Register a new row in the array's CRDT surface. `initial` may
+   *  carry pre-seeded values (e.g. clone of a sibling); pass `{}` (or
+   *  omit) for empty rows. Idempotent under existing rowId. */
+  add(rowId: string, initial?: Record<string, unknown>): void
+  /** Remove the row with the given id. Idempotent for unknown ids. */
+  remove(rowId: string): void
+  /** Replace the array's row order. `newOrder` is the full list of row
+   *  ids in their post-reorder positions; the binding emits the minimal
+   *  CRDT move sequence in one transaction so peers observe a single
+   *  coalesced update. */
+  reorder(newOrder: string[]): void
+  /** Subscribe to remote row-lifecycle events on this array. Returns
+   *  an unsubscribe fn the renderer's `useEffect` cleanup hangs on.
+   *  Local mutations may also surface here (Yjs observers fire on
+   *  local transactions); the renderer is expected to dedupe by
+   *  rowId presence in its current state. Optional on the underlying
+   *  contract — `null` when the binding lacks `subscribeRows`. */
+  subscribe(fn: (event: RowsEvent) => void): () => void
 }
 
+/**
+ * Phase F.5 — row-lifecycle event surfaced through `subscribeRows`.
+ *
+ *   - `add`    — a new row was inserted at `index`. `values` carries
+ *                the row's seeded field values (mirrors `addRow.initial`).
+ *   - `remove` — a row was removed; `index` is its position at the
+ *                moment of removal.
+ *   - `move`   — a row shifted positions. `from` and `to` are 0-based
+ *                indices in the post-reorder layout (i.e. the row at
+ *                position `from` ended up at `to`).
+ *
+ * Pilotiq core stays Yjs-free — the binding impl in `@pilotiq-pro/collab`
+ * translates `Y.Array<Y.Map>` `observe` deltas into these events.
+ */
+export type RowsEvent =
+  | { kind: 'add';    rowId: string; index: number; values: Record<string, unknown> }
+  | { kind: 'remove'; rowId: string; index: number }
+  | { kind: 'move';   rowId: string; from: number; to: number }
+
 export interface FormCollabBindingFactoryArgs {
   /** Active collab room — provides `ydoc`, `provider`, `user`. Opaque to pilotiq core. */
   room:    CollabRoom
@@ -104,13 +245,15 @@ export interface FormCollabBindingFactoryArgs {
   initial: Record<string, unknown>
   /**
    * Phase F.6 — initial form meta from the server. The binding walks
-   * this once at construction to decide which fields are text-shaped
-   * (`fieldType ∈ { text, textarea, email, slug, markdown }`) and
-   * which have opted out via `.collab(false)`. Text fields get a
-   * dedicated `Y.Text` and route through `getTextBinding`; non-text
-   * fields stay on the `Y.Map`. The meta is captured at mount; later
-   * structural changes from `live()` re-resolves aren't re-walked
-   * (rare in practice — dynamic field add/remove is an F-followup).
+   * this once at construction to index Repeater / Builder array names
+   * for row-level CRDT and to identify which row leaves are text-shaped
+   * (`fieldType ∈ { text, textarea, email, slug, markdown }` and not
+   * `.collab(false)`). Post Phase D, top-level text fields no longer
+   * need to be partitioned here — their character-level CRDT lives in
+   * the Tiptap renderer's `Y.XmlFragment`, not in a binding-allocated
+   * `Y.Text`. The meta is captured at mount; later structural changes
+   * from `live()` re-resolves aren't re-walked (rare in practice —
+   * dynamic field add/remove is an F-followup).
    */
   formMeta: ElementMeta
 }

package/src/react/FormStateContext.tsx

@@ -10,9 +10,14 @@ import React, {
 import type { ElementMeta } from '../schema/Element.js'
 import {
   collectFieldDefaults,
+  collectRowArrayFieldNames,
+  collectRowTextLeavesByArray,
   findFieldMeta,
   parseFormDataToNested,
+  parseRowFieldPath,
   readNestedValue,
+  routeBindingWrite,
+  rowIdAtIndex,
   writeNestedValue,
 } from './formStateHelpers.js'
 import { runJsHandler } from './fieldJsHandler.js'
@@ -21,6 +26,7 @@ import { useCollabRoom } from './CollabRoomContext.js'
 import {
   getFormCollabBinding,
   type FormCollabBinding,
+  type RowBindingApi,
   type TextBinding,
 } from './FormCollabBindingRegistry.js'
 
@@ -51,6 +57,29 @@ export interface FormStateApi {
    *  non-null answers, so a `Map.get()` hit means the binding has opted
    *  this field into the character-level path. */
   textBindings:  ReadonlyMap<string, TextBinding> | null
+  /** Phase F.5 — per-Repeater/Builder row-array bindings. `null` outside a
+   *  collab room or when the binding doesn't implement F.5 row methods.
+   *  Each entry's API methods are pre-bound to the array name so renderers
+   *  call `.add(rowId, initial)` rather than `binding.addRow(name, …)`. */
+  rowBindings:   ReadonlyMap<string, RowBindingApi> | null
+  /**
+   * Phase F.5c — per-array set of inner-field names that should route
+   * through `Y.Text` (character-level CRDT) instead of row-level Y.Map
+   * LWW. Built from a single meta walk at binding mount. Read by
+   * `useFieldState(dottedName).textBinding` to decide whether to call
+   * `getRowTextBinding`. Sparse — only arrays with at least one
+   * text-shaped row leaf appear; absence on a key means "no text leaves
+   * in this Repeater/Builder".
+   */
+  rowTextLeaves: ReadonlyMap<string, ReadonlySet<string>> | null
+  /**
+   * Phase F.5c — resolve a per-row `TextBinding`. Pre-bound to the
+   * active F.5 binding so consumers don't reach for `bindingRef`
+   * directly. Returns `null` when no binding implements F.5c OR the
+   * row+field doesn't qualify (renderer caller should fall back to
+   * `defaultValue` like a non-collab form).
+   */
+  getRowTextBinding: ((arrayName: string, rowId: string, fieldName: string) => TextBinding | null) | null
 }
 
 const FormStateContext = createContext<FormStateApi | null>(null)
@@ -71,19 +100,6 @@ export function useFormState(): FormStateApi | null {
  */
 export const FormIdContext = createContext<string>('')
 
-/**
- * Phase F2 — returns `true` iff the named field has explicitly opted out
- * of realtime collab via `Field.collab(false)`. Sparse meta — absent =
- * inherit the panel default (collab on). Walks the form meta tree the
- * same way `findFieldMeta` does; cheap because it only runs on the
- * per-write path (already a hot path, but every check is one map
- * lookup + one boolean compare).
- */
-function fieldOptsOutOfCollab(formMeta: ElementMeta, name: string): boolean {
-  const meta = findFieldMeta(formMeta, name) as { collab?: boolean } | undefined
-  return meta?.collab === false
-}
-
 export interface UseFieldStateResult {
   /** True when the field is inside a controlled form (live fields enabled).
    *  Renderers should fall back to their `defaultValue` path when false.
@@ -115,6 +131,26 @@ export interface UseFieldStateResult {
   textBinding: TextBinding | null
 }
 
+/**
+ * Phase F.5 — return the row-array CRDT API for a Repeater/Builder field.
+ * Returns `null` when:
+ *
+ *   - No `FormStateProvider` is mounted (e.g. uncontrolled form path).
+ *   - No `<RecordCollabRoom>` is up-tree (no binding registered).
+ *   - The active binding doesn't implement F.5's row methods.
+ *   - The named field opted out via `.collab(false)` (skipped at meta walk).
+ *   - The named field isn't a Repeater/Builder.
+ *
+ * RepeaterInput + BuilderInput call this once per render and proceed
+ * with the v1 local-only behaviour when null. The returned API methods
+ * are pre-bound to the array name so consumers don't repeat it.
+ */
+export function useRowBinding(arrayName: string): RowBindingApi | null {
+  const ctx = useContext(FormStateContext)
+  if (!ctx?.rowBindings) return null
+  return ctx.rowBindings.get(arrayName) ?? null
+}
+
 /** Per-field accessor. Inside a `FormStateProvider` it returns the controlled
  *  value + setter + live trigger; outside, it returns sentinels and callers
  *  should fall back to `defaultValue` (uncontrolled inputs). */
@@ -141,14 +177,35 @@ export function useFieldState(name: string): UseFieldStateResult {
     triggerLive: (valueOverride?: unknown) => ctx.triggerLive(name, valueOverride),
     pending:     ctx.fieldStatus(name) === 'pending',
     errors:      ctx.errors[name] ?? [],
-    // Phase F.6 — dotted-path inner-Repeater rows skipped in v1 (deferred
-    // to F.5 alongside Y.Array row identity). Outside a collab room or
-    // for non-text fields, the stash returns null and the renderer falls
-    // back to today's whole-string LWW path.
-    textBinding: dotted ? null : (ctx.textBindings?.get(name) ?? null),
+    // Phase F.6 — top-level text fields resolve from the binding-mount
+    // text stash. Phase F.5c — dotted-path row leaves resolve through
+    // `getRowTextBinding` when the field is text-shaped AND the row's
+    // `__id` is already stamped in the values map. Outside a collab
+    // room, for non-text fields, or before `addRow` has settled the
+    // row's id, the lookup returns null and `BoundTextInput` falls
+    // back to today's uncontrolled-input path.
+    textBinding: dotted
+      ? resolveRowTextBinding(ctx, name)
+      : (ctx.textBindings?.get(name) ?? null),
   }
 }
 
+/**
+ * Phase F.5c — dotted-name `TextBinding` resolver. Returns `null`
+ * whenever any precondition fails so the caller's renderer can take a
+ * single branch on null vs non-null.
+ */
+function resolveRowTextBinding(ctx: FormStateApi, dottedName: string): TextBinding | null {
+  if (!ctx.rowTextLeaves || !ctx.getRowTextBinding) return null
+  const parsed = parseRowFieldPath(dottedName)
+  if (!parsed) return null
+  const set = ctx.rowTextLeaves.get(parsed.arrayName)
+  if (!set?.has(parsed.fieldName)) return null
+  const rowId = rowIdAtIndex(ctx.values, parsed.arrayName, parsed.index)
+  if (!rowId) return null
+  return ctx.getRowTextBinding(parsed.arrayName, rowId, parsed.fieldName)
+}
+
 /** Response shape from `POST {base}/.../_form/:formId/state`. */
 interface FormStateResponse {
   ok:    boolean
@@ -203,6 +260,15 @@ export function FormStateProvider({
   // existing `setValuesState` overlay below already triggers one when the
   // room has pre-existing state.
   const [textBindings, setTextBindings] = useState<ReadonlyMap<string, TextBinding> | null>(null)
+  // Phase F.5 — per-Repeater/Builder row-array stash. Same lifecycle as
+  // `textBindings`: populated on collab mount when the binding implements
+  // F.5 row methods, cleared on unmount.
+  const [rowBindings, setRowBindings] = useState<ReadonlyMap<string, RowBindingApi> | null>(null)
+  // Phase F.5c — per-array set of text-shaped row leaves + a pre-bound
+  // resolver. Both populated at binding mount when the active binding
+  // implements `getRowTextBinding`; cleared on unmount.
+  const [rowTextLeaves,     setRowTextLeaves]     = useState<ReadonlyMap<string, ReadonlySet<string>> | null>(null)
+  const [getRowTextBinding, setGetRowTextBinding] = useState<((arrayName: string, rowId: string, fieldName: string) => TextBinding | null) | null>(null)
 
   const { notify } = useToast()
 
@@ -285,6 +351,55 @@ export function FormStateProvider({
       if (textStash.size > 0) setTextBindings(textStash)
     }
 
+    // Phase F.5 — build a `RowBindingApi` per top-level Repeater/Builder
+    // field when the binding implements all three lifecycle methods. The
+    // walk reads from formMeta (structural — fields exist regardless of
+    // whether the form has any rows yet); the API is then pre-bound to
+    // the array name so `RepeaterInput` calls `rb.add(rowId, …)` rather
+    // than `binding.addRow(name, rowId, …)`. Partial F.5 impls (e.g. a
+    // binding that has addRow but not reorderRows) skip the stash — the
+    // contract says all three or nothing. F.5c's per-row text path is
+    // exposed separately via `getRowTextBinding` and stays optional.
+    if (binding.addRow && binding.removeRow && binding.reorderRows) {
+      const { addRow, removeRow, reorderRows, subscribeRows } = binding
+      const arrayNames = collectRowArrayFieldNames(formMetaRef.current)
+      if (arrayNames.length > 0) {
+        const rowStash = new Map<string, RowBindingApi>()
+        for (const arrayName of arrayNames) {
+          rowStash.set(arrayName, {
+            add:     (rowId, initial = {}) => addRow.call(binding, arrayName, rowId, initial),
+            remove:  (rowId)               => removeRow.call(binding, arrayName, rowId),
+            reorder: (newOrder)            => reorderRows.call(binding, arrayName, newOrder),
+            // Partial F.5 impl: a binding may ship add/remove/reorder
+            // without `subscribeRows` (e.g. tests). Substitute a no-op
+            // subscription so renderer code stays uniform — the cleanup
+            // fn is still called on unmount but no events ever arrive.
+            subscribe: subscribeRows
+              ? (fn) => subscribeRows.call(binding, arrayName, fn)
+              : () => () => {},
+          })
+        }
+        setRowBindings(rowStash)
+      }
+    }
+
+    // Phase F.5c — capture the per-array text-leaf allowlist + bind the
+    // row-text resolver to the active binding. `getRowTextBinding` may
+    // be absent on partial F.5 impls; we expose the resolver as null in
+    // that case so `useFieldState` short-circuits cleanly.
+    if (binding.getRowTextBinding) {
+      const leaves = collectRowTextLeavesByArray(formMetaRef.current)
+      if (leaves.size > 0) {
+        setRowTextLeaves(leaves)
+        const bound = binding.getRowTextBinding
+        // useState's functional-updater overload would invoke the
+        // stored function during set; wrapping in a fresh closure keeps
+        // React's setState path from confusing it for an updater fn.
+        setGetRowTextBinding(() => (arrayName: string, rowId: string, fieldName: string) =>
+          bound.call(binding, arrayName, rowId, fieldName))
+      }
+    }
+
     // Subscribe to remote changes. Local writes ALSO trigger this
     // (Yjs observers fire on local transactions too) — the per-key
     // Object.is short-circuit below collapses them into no-op renders.
@@ -307,6 +422,9 @@ export function FormStateProvider({
       binding.destroy()
       bindingRef.current = null
       setTextBindings(null)
+      setRowBindings(null)
+      setRowTextLeaves(null)
+      setGetRowTextBinding(null)
     }
     // `valuesRef.current` is intentionally read once at mount — initial
     // values seed the binding; subsequent edits flow through `setValue`
@@ -367,14 +485,13 @@ export function FormStateProvider({
       if (Object.is(prev[name], value)) return prev
       return { ...prev, [name]: value }
     })
-    // Phase F2 — proxy the write through the collab binding when active
-    // AND the field hasn't opted out via `.collab(false)`. Dotted-path
-    // names (Repeater / Builder row leaves) stay local-only in v1; their
-    // syncing belongs to Phase F.5 (`Y.Array<Y.Map>` row identity).
-    const binding = bindingRef.current
-    if (binding && !name.includes('.') && !fieldOptsOutOfCollab(formMetaRef.current, name)) {
-      binding.set(name, value)
-    }
+    // Phase F2 / F.5 — proxy the write through the collab binding when
+    // active AND the field hasn't opted out via `.collab(false)`. Top-level
+    // fields ride `binding.set`. Row leaves (dotted paths matching
+    // `parseRowFieldPath`) route through `binding.setRow` when the
+    // binding implements F.5 — otherwise stay local-only (same posture
+    // as pre-F.5).
+    routeBindingWrite(bindingRef.current, formMetaRef.current, valuesRef.current, name, value)
     // Fire the client-side JS hook synchronously after the state write.
     // Dotted-name fields don't go through here (their setter is a no-op
     // in `useFieldState`); they fire JS via `triggerLive` instead so we
@@ -448,16 +565,19 @@ export function FormStateProvider({
         const serverValues = (data.form as { values?: Record<string, unknown> }).values
         if (serverValues) {
           setValuesState((prev) => ({ ...prev, ...serverValues }))
-          // Phase F2 (Q2) — derived fields propagate to peers via the
-          // collab binding so every client sees the auto-`slug` / etc.
-          // without each peer roundtripping the server. Skip dotted-path
-          // names + fields that opted out.
+          // Phase F2 (Q2) / F.5 — derived fields propagate to peers via the
+          // collab binding so every client sees the auto-`slug` / etc. without
+          // each peer roundtripping the server. Row leaves route through
+          // `setRow` when the binding implements F.5; top-level fields ride
+          // `set`. The rowId lookup needs the freshest values — merge
+          // `valuesRef.current` with the server overlay so a row-id stamped
+          // by this very server-resolve response is visible to `rowIdAtIndex`.
           const binding = bindingRef.current
           if (binding) {
+            const lookupValues = { ...valuesRef.current, ...serverValues }
             for (const [k, v] of Object.entries(serverValues)) {
-              if (k.includes('.')) continue
-              if (fieldOptsOutOfCollab(data.form, k)) continue
-              binding.set(k, v)
+              // routeBindingWrite handles `.collab(false)` opt-out internally.
+              routeBindingWrite(binding, data.form, lookupValues, k, v)
             }
           }
         }
@@ -538,7 +658,10 @@ export function FormStateProvider({
     inFlight,
     fieldStatus,
     textBindings,
-  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, textBindings])
+    rowBindings,
+    rowTextLeaves,
+    getRowTextBinding,
+  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, textBindings, rowBindings, rowTextLeaves, getRowTextBinding])
 
   return (
     <FormStateContext.Provider value={api}>

package/src/react/fields/BuilderInput.tsx

@@ -3,7 +3,7 @@ import { ChevronDownIcon, PlusIcon } from 'lucide-react'
 import type { ElementMeta } from '../../schema/Element.js'
 import { Button } from '../ui/button.js'
 import { SchemaRenderer } from '../SchemaRenderer.js'
-import { FormIdContext, useFormState } from '../FormStateContext.js'
+import { FormIdContext, useFormState, useRowBinding } from '../FormStateContext.js'
 import { findFieldMeta } from '../formStateHelpers.js'
 import { useIconFor } from '../icon-context.js'
 import { reorderRows, ExtraActionStrip, buildGridContainer } from './RepeaterInput.js'
@@ -185,6 +185,74 @@ export function BuilderInput({
     if (!metaRows) return
     setRows(prev => syncRowGates(prev, metaRows))
   }, [metaRows])
+  // Phase F.5 — row-array CRDT binding (mirrors `RepeaterInput`). The
+  // initial-row payload that lands on `add()` carries the block's `type`
+  // alongside the empty field map so peers see the discriminator from
+  // the first event — without it, the picker dropdown choice doesn't
+  // propagate until the user makes their first inner-field edit.
+  const rowBinding = useRowBinding(name)
+  // Phase F.5c — mirror row identities into the form's values map so dotted
+  // row-leaf consumers (`useFieldState('${name}.${i}.data.text').textBinding`)
+  // can resolve the row's `__id` via `rowIdAtIndex(ctx.values, name, i)`.
+  // Without this stamp the F.5c per-row Y.Text path stays null on Builder
+  // and inner text fields never sync. Mirrors the same fix in RepeaterInput.
+  const formStateForIds = useFormState()
+  const ctxSetValue = formStateForIds?.setValue
+  useEffect(() => {
+    if (!ctxSetValue) return
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]
+      if (!row) continue
+      ctxSetValue(`${name}.${i}.__id`, row.id)
+    }
+  }, [rows, name, ctxSetValue])
+  // Phase F.5 — reconcile remote row events. Builder mirrors
+  // RepeaterInput but reads `event.values.type` to pick the block whose
+  // template seeds the new row's children. Falls back to the first
+  // registered block when the remote `type` doesn't match a known one;
+  // the row still mounts so the user sees the change rather than a
+  // silent drop (matches the server-side `unknownType` fallback).
+  useEffect(() => {
+    if (!rowBinding) return
+    return rowBinding.subscribe((event) => {
+      if (event.kind === 'add') {
+        setRows((prev) => {
+          if (prev.some(r => r.id === event.rowId)) return prev
+          const blockType = typeof event.values['type'] === 'string'
+            ? event.values['type'] as string
+            : (meta.blocks?.[0]?.name ?? '')
+          const block = blocksByName.get(blockType)
+          const incoming: RowState = {
+            id:       event.rowId,
+            type:     blockType,
+            children: block?.template ?? [],
+          }
+          const next = prev.slice()
+          const at = Math.max(0, Math.min(event.index, next.length))
+          next.splice(at, 0, incoming)
+          return next
+        })
+        return
+      }
+      if (event.kind === 'remove') {
+        setRows((prev) => {
+          if (!prev.some(r => r.id === event.rowId)) return prev
+          return prev.filter(r => r.id !== event.rowId)
+        })
+        return
+      }
+      setRows((prev) => {
+        const fromIdx = prev.findIndex(r => r.id === event.rowId)
+        if (fromIdx < 0) return prev
+        if (fromIdx === event.to) return prev
+        const next  = prev.slice()
+        const [moved] = next.splice(fromIdx, 1)
+        if (!moved) return prev
+        next.splice(event.to, 0, moved)
+        return next
+      })
+    })
+  }, [rowBinding, blocksByName, meta.blocks])
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() =>
     accordion ? {} : initSeedCollapsed(initialRows, formId, name, defaultCollapsed, collapsible),
   )
@@ -232,6 +300,9 @@ export function BuilderInput({
       const i = Math.max(0, Math.min(atIndex, prev.length))
       return [...prev.slice(0, i), newRow, ...prev.slice(i)]
     })
+    // F.5 — seed the new block's discriminator on the CRDT side so peers
+    // pick the right inner schema without waiting for the user's first edit.
+    rowBinding?.add(newRow.id, { type: block.name })
     if (accordion) {
       setAccordionOpenId(newRow.id)
       writeAccordionToStorage(formId, name, newRow.id)
@@ -246,6 +317,7 @@ export function BuilderInput({
   const removeRow = (id: string): void => {
     if (atMin) return
     setRows(prev => prev.filter(r => r.id !== id))
+    rowBinding?.remove(id)
     if (accordion) {
       if (accordionOpenId === id) {
         setAccordionOpenId(null)
@@ -262,6 +334,8 @@ export function BuilderInput({
 
   const cloneRow = (id: string): void => {
     if (atMax) return
+    let cloneId:   string | null = null
+    let cloneType: string | null = null
     setRows(prev => {
       const idx = prev.findIndex(r => r.id === id)
       if (idx < 0) return prev
@@ -270,8 +344,10 @@ export function BuilderInput({
       const block = blocksByName.get(source.type)
       const cap   = block?.maxItems
       if (cap !== undefined && (typeCounts.get(source.type) ?? 0) >= cap) return prev
+      cloneId   = generateRowId()
+      cloneType = source.type
       const clone: RowState = {
-        id:       generateRowId(),
+        id:       cloneId,
         type:     source.type,
         children: source.children,
         ...(source.itemLabel !== undefined ? { itemLabel: source.itemLabel } : {}),
@@ -280,23 +356,32 @@ export function BuilderInput({
       next.splice(idx + 1, 0, clone)
       return next
     })
+    if (cloneId !== null && cloneType !== null) {
+      rowBinding?.add(cloneId, { type: cloneType })
+    }
   }
 
   const moveRow = (id: string, dir: -1 | 1): void => {
+    let newOrder: string[] | null = null
     setRows(prev => {
       const idx = prev.findIndex(r => r.id === id)
       if (idx < 0) return prev
+      let next: RowState[]
       if (dir === -1) {
         let target = idx - 1
         while (target >= 0 && prev[target]?.hidden) target--
         if (target < 0) return prev
-        return reorderRows(prev, idx, target)
+        next = reorderRows(prev, idx, target)
+      } else {
+        let target = idx + 1
+        while (target < prev.length && prev[target]?.hidden) target++
+        if (target >= prev.length) return prev
+        next = reorderRows(prev, idx, target + 1)
       }
-      let target = idx + 1
-      while (target < prev.length && prev[target]?.hidden) target++
-      if (target >= prev.length) return prev
-      return reorderRows(prev, idx, target + 1)
+      if (next !== prev) newOrder = next.map(r => r.id)
+      return next
     })
+    if (newOrder !== null) rowBinding?.reorder(newOrder)
   }
 
   // ── DnD state (skipped when buttonsOnly) ────────────────
@@ -310,11 +395,15 @@ export function BuilderInput({
   } = useRowReorderDnd({
     enabled: dndEnabled,
     onDrop: (fromId, at) => {
+      let newOrder: string[] | null = null
       setRows(prev => {
         const fromIdx = prev.findIndex(r => r.id === fromId)
         if (fromIdx < 0) return prev
-        return reorderRows(prev, fromIdx, at)
+        const next = reorderRows(prev, fromIdx, at)
+        if (next !== prev) newOrder = next.map(r => r.id)
+        return next
       })
+      if (newOrder !== null) rowBinding?.reorder(newOrder)
     },
   })