@pilotiq/pilotiq 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/pilotiq",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "View-based admin panel for RudderJS",
   "license": "MIT",
   "repository": {
@@ -81,10 +81,10 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1",
-    "@rudderjs/contracts": "^1.3.0",
-    "@rudderjs/core": "^1.1.2",
-    "@rudderjs/router": "^1.1.2",
-    "@rudderjs/view": "^1.0.1",
+    "@rudderjs/contracts": "^1.6.0",
+    "@rudderjs/core": "^1.1.4",
+    "@rudderjs/router": "^1.2.0",
+    "@rudderjs/view": "^1.1.0",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/sanitize-html": "^2.16.1",

package/src/react/AppShell.tsx

@@ -16,6 +16,7 @@ import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta
 import type { RenderHookMap } from '../RenderHook.js'
 import { RenderHookSlot } from './RenderHookSlot.js'
 import type { ComponentSlotRegistry } from './component-slots.js'
+import { CurrentUserProvider } from './CurrentUserContext.js'
 
 export interface AppShellProps {
   panel: {
@@ -180,7 +181,16 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
     props.basePath,
   )
 
-  return wrapped
+  // `CurrentUserProvider` sits OUTSIDE the layout-provider chain so
+  // plugin-registered providers (e.g. `@pilotiq-pro/collab`'s
+  // CollabProvider, which threads the user into CollaborationCaret
+  // presence labels) can read the active user via `useCurrentUser()`.
+  // Value source mirrors what the top-right user dropdown renders.
+  return (
+    <CurrentUserProvider value={props.panel.userMenu?.user ?? null}>
+      {wrapped}
+    </CurrentUserProvider>
+  )
 }
 
 /**

package/src/react/CollabTextRendererRegistry.ts

@@ -0,0 +1,84 @@
+import type { ComponentType } from 'react'
+
+/**
+ * Module-level registry slot for the collab-aware plain-text editor renderer.
+ *
+ * Wiring posture (mirrors `CollabExtensionFactoryRegistry` /
+ * `FormCollabBindingRegistry`):
+ *   - `@pilotiq/tiptap`'s `registerTiptap(...)` calls `registerCollabTextRenderer(...)`
+ *     once at boot. The registered component closes over `@tiptap/*` imports so
+ *     pilotiq core stays free of any tiptap peer dep — same posture as the
+ *     existing rich-text renderer registry.
+ *   - `TextLikeInput` checks for the registered component when a `<RecordCollabRoom>`
+ *     is mounted up-tree AND the field hasn't opted out via `.collab(false)` AND
+ *     the field has no `.mask()`. If present, the legacy `BoundTextInput`
+ *     (Y.Text + `computeDelta` + heuristic `preserveCursor`) is bypassed in
+ *     favour of a y-prosemirror-backed Tiptap editor that anchors selections to
+ *     `Yjs.RelativePosition` — the architectural fix for the cursor-jump and
+ *     two-peer concurrent-insert races documented in
+ *     `docs/plans/text-fields-tiptap-backed-collab.md`.
+ *
+ * Wire props are deliberately framework-agnostic — the renderer doesn't take a
+ * `binding` since it consumes the room's `ydoc` directly via the existing
+ * `useCollabRoom()` + `getCollabExtensions()` plumbing on its own side. Core
+ * keeps the seam narrow: handler callbacks + DOM chrome only.
+ */
+export interface CollabTextRendererProps {
+  /** Field name — drives the `Y.XmlFragment` selector inside the collab adapter. */
+  name: string
+  /** `true` for textarea-like (multiple paragraphs); `false` for input-like. */
+  multiline: boolean
+  /**
+   * Server-rendered default value. The renderer is expected to seed the
+   * `Y.XmlFragment` from this on first connect when the room has no
+   * persisted state for this field (i.e. brand-new record).
+   */
+  defaultValue: string
+  /** Optional placeholder hint. */
+  placeholder?: string
+  /** Disabled / read-only state. */
+  disabled?: boolean
+  /** Fired on every editor `update` with the editor's current plain text. */
+  onChange: (text: string) => void
+  /** Fired on editor blur — host wires this to live-onBlur trigger semantics. */
+  onBlur: () => void
+  /**
+   * Single-line submit — fired when `multiline: false` AND the user presses
+   * Enter. The renderer is expected to blur the editor after invoking this.
+   * Multiline mode ignores it (Enter inserts a paragraph instead).
+   */
+  onSubmit?: () => void
+  /**
+   * Tailwind className applied to the editor's contenteditable wrapper so the
+   * rendered editor matches the native `<input>` / `<textarea>` chrome it
+   * replaces. The host owns the styling — the adapter just forwards.
+   */
+  className?: string
+  /**
+   * Additional DOM attributes for the editor's contenteditable wrapper —
+   * typically `id`, `aria-*`, `autocomplete`, etc.
+   */
+  editorAttributes?: Record<string, string>
+}
+
+export type CollabTextRenderer = ComponentType<CollabTextRendererProps>
+
+let _renderer: CollabTextRenderer | null = null
+
+/**
+ * Register the collab plain-text editor component. Called once at boot by
+ * `@pilotiq/tiptap`'s `registerTiptap()` (or directly by an app that imports
+ * the renderer). Calling with `null` clears the registry — useful for tests.
+ *
+ * No-op behaviour when no renderer is registered: `TextLikeInput` falls back
+ * to the legacy `BoundTextInput` path (or the plain controlled / uncontrolled
+ * input when no collab room is mounted).
+ */
+export function registerCollabTextRenderer(component: CollabTextRenderer | null): void {
+  _renderer = component
+}
+
+/** Returns the registered component, or `null` when no adapter is installed. */
+export function getCollabTextRenderer(): CollabTextRenderer | null {
+  return _renderer
+}

package/src/react/CurrentUserContext.tsx

@@ -0,0 +1,50 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+/**
+ * Resolved identity of the user driving the current page. Mirrors the
+ * `UserMenuMeta.user` shape that `panelInfo()` ships to the renderer —
+ * whichever fields the `Pilotiq.user(req => …)` resolver populated.
+ *
+ * `null` is the no-user state: either the panel never wired a resolver,
+ * or the resolver returned `null` for this request. Consumers should
+ * gracefully fall back (no avatar, no presence label, etc.) rather than
+ * treating absence as an error.
+ */
+export interface CurrentUser {
+  name?:   string
+  email?:  string
+  avatar?: string
+}
+
+const CurrentUserContext = createContext<CurrentUser | null>(null)
+
+/**
+ * Mounted by `AppShell` around the layout-provider chain so plugins
+ * (collab user presence, audit-trail attribution, analytics
+ * client-side opt-outs, …) can read the active user via
+ * `useCurrentUser()` without prop-drilling through `panel`.
+ *
+ * Value source is `viewProps.panel.userMenu?.user` — the same shape the
+ * top-right dropdown renders. The provider sits OUTSIDE
+ * `layoutProviderRegistry` so plugin-registered layout providers can
+ * subscribe.
+ */
+export function CurrentUserProvider({
+  value,
+  children,
+}: {
+  value: CurrentUser | null
+  children: ReactNode
+}): ReactNode {
+  return <CurrentUserContext.Provider value={value}>{children}</CurrentUserContext.Provider>
+}
+
+/**
+ * Read the active user inside any descendant of `<AppShell>`. Returns
+ * `null` outside an `AppShell` mount (defensive — keeps storybook /
+ * isolated-render tests from throwing) and when no user resolved for
+ * the request.
+ */
+export function useCurrentUser(): CurrentUser | null {
+  return useContext(CurrentUserContext)
+}

package/src/react/FormCollabBindingRegistry.ts

@@ -1,44 +1,6 @@
 import type { ElementMeta } from '../schema/Element.js'
 import type { CollabRoom } from './CollabRoomContext.js'
 
-/**
- * Phase F.6 — character-level edit op emitted by `TextLikeInput` and
- * applied through `TextBinding.applyDelta`. `replace` covers IME / paste
- * / multi-char selections; `insert` and `delete` cover the single-key
- * common path. Pilotiq core stays Yjs-free — the binding impl in
- * `@pilotiq-pro/collab` translates these into `Y.Text.insert / delete`
- * inside a transaction.
- */
-export type TextDelta =
-  | { kind: 'insert',  index: number,  text: string }
-  | { kind: 'delete',  index: number,  length: number }
-  | { kind: 'replace', from:  number,  to: number, text: string }
-
-/**
- * Phase F.6 — per-field character-level CRDT handle. Issued by
- * `FormCollabBinding.getTextBinding(name)` for text-shaped fields
- * (`TextField / TextareaField / EmailField / SlugField / MarkdownField`);
- * returns `null` for non-text fields or text fields opted out via
- * `.collab(false)`. The surface stays intentionally narrow so pilotiq
- * core never touches Yjs directly — same posture as `FormCollabBinding`.
- *
- *   - `read()` returns the current full string. `TextLikeInput` calls
- *     this once on mount to seed its controlled value.
- *   - `applyDelta(delta)` is called from `onInput` events with a single
- *     `insert / delete / replace` op derived from the input's selection.
- *   - `observe(fn)` registers a remote-change listener; `fn(next)`
- *     receives the post-change string. Returns an unsubscribe function.
- *   - `destroy()` cleans up everything the handle holds. The owning
- *     `FormCollabBinding.destroy()` is expected to cascade — consumers
- *     don't need to call this directly.
- */
-export interface TextBinding {
-  read():     string
-  applyDelta(delta: TextDelta): void
-  observe(fn: (next: string) => void): () => void
-  destroy():  void
-}
-
 /**
  * Binding contract that a collab plugin returns from
  * `registerFormCollabBinding` — wraps a single form's value map in a
@@ -55,14 +17,14 @@ 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.
  *   - `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.
+ *     remove its CRDT observer.
+ *
+ * Text-field character-level CRDT lives in `@pilotiq/tiptap`'s
+ * `CollabTextRenderer` (`Y.XmlFragment` per field, keyed by bare name
+ * for top-level + `${arrayName}.${rowId}.${fieldName}` composite for
+ * row leaves) — pilotiq core no longer mediates per-field text CRDT,
+ * so this binding only handles non-text values + row lifecycle.
  *
  * `unknown` payloads keep pilotiq core Yjs-free; the binding owns its
  * own type knowledge. Same posture as `CollabExtensionFactory`.
@@ -74,12 +36,6 @@ 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). */
-  getTextBinding?(name: string): TextBinding | null
   /** Cleanup hook called when the form unmounts. */
   destroy():    void
 
@@ -125,11 +81,10 @@ export interface FormCollabBinding {
   /**
    * 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.
+   * Non-text row fields land on the row's scalar field-map under LWW;
+   * text row fields don't flow through here — the Tiptap renderer
+   * writes them directly to a `Y.XmlFragment` at the doc root keyed by
+   * `${arrayName}.${rowId}.${fieldName}`.
    *
    * `FormStateProvider` calls this on every local edit when both a
    * dotted-path name is being written AND `setRow` is implemented;
@@ -137,19 +92,6 @@ export interface FormCollabBinding {
    */
   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
@@ -232,14 +174,12 @@ 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).
+   * Initial form meta from the server. The binding walks this once at
+   * construction to index Repeater / Builder array names for row-level
+   * CRDT. Text fields (top-level and row leaves alike) don't need to be
+   * partitioned here — the Tiptap renderer owns their `Y.XmlFragment`s
+   * at the doc root. The meta is captured at mount; later structural
+   * changes from `live()` re-resolves aren't re-walked.
    */
   formMeta: ElementMeta
 }

package/src/react/FormStateContext.tsx

@@ -11,13 +11,10 @@ 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'
@@ -27,7 +24,6 @@ import {
   getFormCollabBinding,
   type FormCollabBinding,
   type RowBindingApi,
-  type TextBinding,
 } from './FormCollabBindingRegistry.js'
 
 export type FieldStatus = 'idle' | 'pending'
@@ -50,36 +46,11 @@ export interface FormStateApi {
   formMeta:      ElementMeta
   inFlight:      boolean
   fieldStatus:   (name: string) => FieldStatus
-  /** Phase F.6 — per-field text-CRDT handles stashed at collab-room mount.
-   *  `null` outside a room or before the binding effect has populated the
-   *  map. The text/non-text allowlist lives in the binding impl —
-   *  `FormStateProvider` asks for every top-level field and only stashes
-   *  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)
@@ -120,15 +91,6 @@ export interface UseFieldStateResult {
   /** True while a live re-resolve POST is in flight for this field. */
   pending:     boolean
   errors:      string[]
-  /** Phase F.6 — character-level CRDT handle for text-shaped fields when
-   *  a collab room is mounted up-tree AND the binding strategy applies
-   *  (allowlist + `.collab() !== false`). Null in every other case —
-   *  outside a `FormStateProvider`, outside a `<RecordCollabRoom>`, on
-   *  non-text fields, on dotted-path inner-Repeater rows (deferred to
-   *  F.5), and on text fields opted out via `.collab(false)`. Text input
-   *  renderers branch on this: non-null → character-level path with
-   *  `applyDelta + observe`; null → today's whole-string LWW path. */
-  textBinding: TextBinding | null
 }
 
 /**
@@ -164,7 +126,6 @@ export function useFieldState(name: string): UseFieldStateResult {
       triggerLive: () => {},
       pending:     false,
       errors:      [],
-      textBinding: null,
     }
   }
   // Dotted-path fields (inner Repeater rows) always render uncontrolled
@@ -177,35 +138,9 @@ 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 — 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
@@ -253,22 +188,11 @@ export function FormStateProvider({
   const [errors,   setErrors] = useState<Record<string, string[]>>(initialErrors)
   const [pendingNames, setPendingNames] = useState<Set<string>>(() => new Set())
   const [inFlight, setInFlight] = useState(false)
-  // Phase F.6 — per-field text-CRDT stash. `null` until the collab effect
-  // populates it; stays `null` outside a collab room. Stored in state (not
-  // a ref) so consumers of `useFieldState` re-render once the bindings
-  // land. One extra render after collab-mount; acceptable since the
-  // 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.
+  // Phase F.5 — per-Repeater/Builder row-array stash. Populated on
+  // collab mount when the binding implements F.5 row methods, cleared
+  // on unmount. Stored in state (not a ref) so consumers of
+  // `useRowBinding` re-render once the bindings land.
   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()
 
@@ -332,25 +256,6 @@ export function FormStateProvider({
       setValuesState((prev) => ({ ...prev, ...synced }))
     }
 
-    // Phase F.6 — ask the binding for a `TextBinding` on every top-level
-    // field name. The text/non-text allowlist lives in the binding impl,
-    // not in core: the binding returns `null` for non-text fields and
-    // text fields opted out via `.collab(false)`. `getTextBinding` is
-    // optional on the contract — F1-era plugins that haven't implemented
-    // it short-circuit the whole stash and every text field stays on the
-    // LWW path. We stash only the non-null answers. Cleanup is owned by
-    // `binding.destroy()` (expected to cascade into every issued
-    // `TextBinding`).
-    if (binding.getTextBinding) {
-      const textStash = new Map<string, TextBinding>()
-      for (const fieldName of Object.keys(valuesRef.current)) {
-        if (fieldName.includes('.')) continue
-        const tb = binding.getTextBinding(fieldName)
-        if (tb) textStash.set(fieldName, tb)
-      }
-      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
@@ -358,8 +263,7 @@ export function FormStateProvider({
     // 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.
+    // contract says all three or nothing.
     if (binding.addRow && binding.removeRow && binding.reorderRows) {
       const { addRow, removeRow, reorderRows, subscribeRows } = binding
       const arrayNames = collectRowArrayFieldNames(formMetaRef.current)
@@ -383,23 +287,6 @@ export function FormStateProvider({
       }
     }
 
-    // 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.
@@ -421,10 +308,7 @@ export function FormStateProvider({
       unsubscribe()
       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`
@@ -657,11 +541,8 @@ export function FormStateProvider({
     formMeta,
     inFlight,
     fieldStatus,
-    textBindings,
     rowBindings,
-    rowTextLeaves,
-    getRowTextBinding,
-  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, textBindings, rowBindings, rowTextLeaves, getRowTextBinding])
+  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, rowBindings])
 
   return (
     <FormStateContext.Provider value={api}>

package/src/react/RowCoordsContext.tsx

@@ -0,0 +1,23 @@
+import React, { createContext, useContext } from 'react'
+
+/**
+ * Phase 1 — row-text Tiptap-backed collab plan
+ * (`pilotiq-pro/docs/plans/collab-row-text-tiptap-backed.md`).
+ *
+ * Each Repeater / Builder row mounts a `<RowCoordsContext.Provider>`
+ * around its children so dotted-path text leaves can compose a
+ * fragment-key that includes the stable `rowId` (survives reorders).
+ * Top-level fields see `null` and fall through to bare-name fragment
+ * routing.
+ */
+export interface RowCoords {
+  arrayName: string
+  rowIndex:  number
+  rowId:     string
+}
+
+export const RowCoordsContext = createContext<RowCoords | null>(null)
+
+export function useRowCoords(): RowCoords | null {
+  return useContext(RowCoordsContext)
+}

package/src/react/fields/BuilderInput.tsx

@@ -5,6 +5,7 @@ import { Button } from '../ui/button.js'
 import { SchemaRenderer } from '../SchemaRenderer.js'
 import { FormIdContext, useFormState, useRowBinding } from '../FormStateContext.js'
 import { findFieldMeta } from '../formStateHelpers.js'
+import { RowCoordsContext } from '../RowCoordsContext.js'
 import { useIconFor } from '../icon-context.js'
 import { reorderRows, ExtraActionStrip, buildGridContainer } from './RepeaterInput.js'
 import { syncRowGates } from './syncRowGates.js'
@@ -191,11 +192,9 @@ export function BuilderInput({
   // 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.
+  // Mirror row identities into the form's values map so dotted row-leaf
+  // consumers can resolve the row's `__id` via `rowIdAtIndex(ctx.values,
+  // name, i)`. Mirrors the same plumbing in RepeaterInput.
   const formStateForIds = useFormState()
   const ctxSetValue = formStateForIds?.setValue
   useEffect(() => {
@@ -870,6 +869,15 @@ function BuilderRow({
     () => row.children.map(c => prefixFieldNames(c, dataPrefix)),
     [row.children, dataPrefix],
   )
+  // Row coords for dotted-path text leaves under this row — composes
+  // fragment-key `${arrayName}.${rowId}.${fieldName}` (Phase 1 of
+  // collab-row-text-tiptap-backed.md). `parseRowFieldPath` strips the
+  // Builder-specific `data` segment, so the coords use the array name +
+  // the row's stable id without referencing the dialect.
+  const rowCoords = useMemo(
+    () => ({ arrayName: name, rowIndex: index, rowId: row.id }),
+    [name, index, row.id],
+  )
 
   const RowIcon = useIconFor(showIcons ? block?.icon : undefined)
   const blockLabel = block?.label ?? row.type ?? 'Block'
@@ -878,11 +886,13 @@ function BuilderRow({
 
   if (row.hidden) {
     return (
-      <div style={{ display: 'none' }} data-pilotiq-builder-row="hidden">
-        <input type="hidden" name={`${name}.${index}.__id`} value={row.id} readOnly />
-        <input type="hidden" name={`${name}.${index}.type`} value={row.type} readOnly />
-        <SchemaRenderer elements={namespaced} />
-      </div>
+      <RowCoordsContext.Provider value={rowCoords}>
+        <div style={{ display: 'none' }} data-pilotiq-builder-row="hidden">
+          <input type="hidden" name={`${name}.${index}.__id`} value={row.id} readOnly />
+          <input type="hidden" name={`${name}.${index}.type`} value={row.type} readOnly />
+          <SchemaRenderer elements={namespaced} />
+        </div>
+      </RowCoordsContext.Provider>
     )
   }
 
@@ -921,6 +931,7 @@ function BuilderRow({
   const innerColumns = block.columns && block.columns > 1 ? block.columns : 1
 
   return (
+    <RowCoordsContext.Provider value={rowCoords}>
     <div
       className={`rounded-md border bg-card transition-opacity ${isDragging ? 'opacity-50' : ''}`}
       data-pilotiq-builder-row=""
@@ -999,6 +1010,7 @@ function BuilderRow({
           : <SchemaRenderer elements={namespaced} />}
       </div>
     </div>
+    </RowCoordsContext.Provider>
   )
 }