@pilotiq/pilotiq 0.8.1 → 0.9.0

package/src/react/FormStateContext.tsx

@@ -18,7 +18,11 @@ import {
 import { runJsHandler } from './fieldJsHandler.js'
 import { useToast } from './Toaster.js'
 import { useCollabRoom } from './CollabRoomContext.js'
-import { getFormCollabBinding, type FormCollabBinding } from './FormCollabBindingRegistry.js'
+import {
+  getFormCollabBinding,
+  type FormCollabBinding,
+  type TextBinding,
+} from './FormCollabBindingRegistry.js'
 
 export type FieldStatus = 'idle' | 'pending'
 
@@ -40,6 +44,13 @@ 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
 }
 
 const FormStateContext = createContext<FormStateApi | null>(null)
@@ -93,6 +104,15 @@ 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
 }
 
 /** Per-field accessor. Inside a `FormStateProvider` it returns the controlled
@@ -108,6 +128,7 @@ export function useFieldState(name: string): UseFieldStateResult {
       triggerLive: () => {},
       pending:     false,
       errors:      [],
+      textBinding: null,
     }
   }
   // Dotted-path fields (inner Repeater rows) always render uncontrolled
@@ -120,6 +141,11 @@ 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),
   }
 }
 
@@ -170,6 +196,13 @@ 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)
 
   const { notify } = useToast()
 
@@ -215,7 +248,12 @@ export function FormStateProvider({
   useEffect(() => {
     if (!collabRoom || !bindingFactory || !formId) return
 
-    const binding = bindingFactory({ room: collabRoom, formId, initial: valuesRef.current })
+    const binding = bindingFactory({
+      room:     collabRoom,
+      formId,
+      initial:  valuesRef.current,
+      formMeta: formMetaRef.current,
+    })
     bindingRef.current = binding
 
     // Lift any state already in the room (subsequent joiners — first
@@ -228,6 +266,25 @@ 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)
+    }
+
     // 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.
@@ -249,6 +306,7 @@ export function FormStateProvider({
       unsubscribe()
       binding.destroy()
       bindingRef.current = null
+      setTextBindings(null)
     }
     // `valuesRef.current` is intentionally read once at mount — initial
     // values seed the binding; subsequent edits flow through `setValue`
@@ -479,7 +537,8 @@ export function FormStateProvider({
     formMeta,
     inFlight,
     fieldStatus,
-  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus])
+    textBindings,
+  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, textBindings])
 
   return (
     <FormStateContext.Provider value={api}>

package/src/react/RecordWrapperGate.tsx

@@ -1,37 +1,55 @@
 import { type ReactNode } from 'react'
 import { getRecordWrapper } from './RecordWrapperRegistry.js'
-import { parseRecordEditUrl } from './parseRecordEditUrl.js'
+import { parseRecordPageUrl } from './parseRecordEditUrl.js'
+import type { ResourceCollabConfig } from '../Resource.js'
+
+/** Per-resource collab opt-in keyed by URL slug (`R.getSlug()` for
+ * non-clustered, `${cluster.slug}/${R.getSlug()}` for clustered). Built
+ * server-side by `panelInfo()` as `recordCollab`. */
+export type RecordCollabMap = Record<string, ResourceCollabConfig>
 
 export interface RecordWrapperGateProps {
   currentPath?: string
   basePath:     string
+  /** Resource opt-in map. Absent means no resource opted in (or the
+   *  panel has no resources) — gate always passes through. */
+  recordCollab?: RecordCollabMap
   children:     ReactNode
 }
 
 /**
  * Conditionally wraps the page tree with the plugin-registered
- * `RecordWrapper` when the current URL resolves to a record-bound edit
- * page. Pass-through in every other case:
+ * `RecordWrapper` when the current URL resolves to a record-bound page
+ * AND the underlying resource has opted into collab on that page role.
+ * Pass-through in every other case:
  *
  *   - no plugin registered a wrapper (`getRecordWrapper() === null`)
- *   - the URL isn't a record-edit URL (list / create / view / dashboard / …)
+ *   - the URL isn't a record edit/view page
  *   - `currentPath` not yet known on the very first SSR render
+ *   - the resource has not opted in via `static collab` (or has opted in
+ *     but excluded the current page role)
  *
  * Mounted once inside `AppShell` around the page content area so
  * record-scoped plugins (collab room, audit trail, …) get one
  * lifetimed mount per record-view-or-edit without each plugin having
  * to thread URL parsing into its own provider.
  *
- * Scope limited to `/edit` URLs in v1; view-page support (read-only
- * collab cursors on `ViewPage`) is a follow-up.
+ * v1 caveat: nested-relation edit URLs (`/articles/:parentId/comments/:childId/edit`)
+ * have a dynamic-id segment baked into the URL slug, so they don't match
+ * the resource-keyed `recordCollab` map and fall through to no-collab.
+ * Collab on nested-relation edits is a follow-up.
  */
-export function RecordWrapperGate({ currentPath, basePath, children }: RecordWrapperGateProps) {
+export function RecordWrapperGate({ currentPath, basePath, recordCollab, children }: RecordWrapperGateProps) {
   const Wrapper = getRecordWrapper()
   if (!Wrapper || !currentPath) return <>{children}</>
 
-  const identity = parseRecordEditUrl(currentPath, basePath)
+  const identity = parseRecordPageUrl(currentPath, basePath)
   if (!identity) return <>{children}</>
 
+  const cfg = recordCollab?.[identity.resourceSlug]
+  if (!cfg) return <>{children}</>
+  if (!cfg.pages.includes(identity.role)) return <>{children}</>
+
   return (
     <Wrapper resourceSlug={identity.resourceSlug} recordId={identity.recordId}>
       {children}

package/src/react/fields/FieldShell.tsx

@@ -5,6 +5,8 @@ import { usePendingSuggestions, usePendingSuggestionsForField, type PendingSugge
 import { getPendingSuggestionOverlay } from '../PendingSuggestionOverlayRegistry.js'
 import { registerPendingSuggestionApplier, type PendingSuggestionApplier } from '../PendingSuggestionApplierRegistry.js'
 import { FormIdContext, useFieldState } from '../FormStateContext.js'
+import { getFieldPresenceComponent } from '../FieldPresenceRegistry.js'
+import { getFieldFocusReporter } from '../FieldFocusReporterRegistry.js'
 
 /**
  * Field types whose visible state is driven by React (not by a matching
@@ -140,10 +142,25 @@ export function FieldShell({ el, name, label, required, children, before, after,
   const labelClass = hiddenLabel
     ? 'sr-only'
     : 'text-sm font-medium leading-none'
+  // Phase F4 — presence chip + focus reporter slots. The chip mounts
+  // alongside the label so remote-focus indicators don't shift the
+  // input geometry; the focus reporter sits on the outer wrapper using
+  // capture-phase listeners so any inner-input focus event flows
+  // through. Both slots are gated on `meta.collab !== false` (Q3 from
+  // the F-plan — opted-out fields are fully invisible to the collab
+  // layer) AND on the field having a stable top-level name (dotted-path
+  // Repeater rows skip presence in v1 — Phase F.5).
+  const collabOptedOut = (el as { collab?: boolean })['collab'] === false
+  const dottedName     = name.includes('.')
+  const presenceSlotEligible = !collabOptedOut && !dottedName
+  const PresenceChip = presenceSlotEligible ? getFieldPresenceComponent() : null
+  const focusReporter = presenceSlotEligible ? getFieldFocusReporter() : null
+
   const labelEl = label !== '' ? (
     <label htmlFor={name} className={labelClass}>
       {label}{required && <span className="text-destructive ml-0.5">*</span>}
       {labelSlot}
+      {PresenceChip && <PresenceChip fieldName={name} formId={formId ?? ''} />}
     </label>
   ) : null
 
@@ -177,9 +194,24 @@ export function FieldShell({ el, name, label, required, children, before, after,
     </>
   )
 
+  // Capture-phase focus / blur dispatch — runs even when the inner
+  // input is wrapped in custom NodeViews (Select / Date / Slider). One
+  // wrapper-level handler covers every controlled input in the tree.
+  const onFocusCapture = focusReporter
+    ? () => focusReporter.onFocus({ fieldName: name, formId: formId ?? '' })
+    : undefined
+  const onBlurCapture = focusReporter
+    ? () => focusReporter.onBlur({ fieldName: name, formId: formId ?? '' })
+    : undefined
+
   if (inline) {
     return (
-      <div className="flex items-baseline gap-3" {...wrapperAttrs}>
+      <div
+        className="flex items-baseline gap-3"
+        {...wrapperAttrs}
+        {...(onFocusCapture ? { onFocusCapture } : {})}
+        {...(onBlurCapture  ? { onBlurCapture  } : {})}
+      >
         {labelEl && <div className="min-w-32 pt-2">{labelEl}</div>}
         <div className="min-w-0 flex-1">
           {inputBlock}
@@ -192,7 +224,12 @@ export function FieldShell({ el, name, label, required, children, before, after,
   }
 
   return (
-    <div className="flex flex-col gap-1.5" {...wrapperAttrs}>
+    <div
+      className="flex flex-col gap-1.5"
+      {...wrapperAttrs}
+      {...(onFocusCapture ? { onFocusCapture } : {})}
+      {...(onBlurCapture  ? { onBlurCapture  } : {})}
+    >
       {labelEl}
       {inputBlock}
       {helperText && (

package/src/react/fields/MarkdownInput.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo, useRef, useState } from 'react'
+import React, { useEffect, useMemo, useRef, useState } from 'react'
 import { marked } from 'marked'
 import {
   BoldIcon, ItalicIcon, StrikethroughIcon, LinkIcon,
@@ -8,6 +8,7 @@ import {
 import { useFieldState } from '../FormStateContext.js'
 import { useToast } from '../Toaster.js'
 import { Button } from '../ui/button.js'
+import { computeDelta, preserveCursor } from './textDelta.js'
 
 type ToolbarButton =
   | 'bold' | 'italic' | 'strike' | 'link'
@@ -47,14 +48,90 @@ export function MarkdownInput({
   const fs = useFieldState(name)
   const { notify } = useToast()
   const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+  // Phase F.6 — IME composition gate. Set between `compositionstart` /
+  // `compositionend`; the textarea's onChange skips `applyDelta` while
+  // composing so intermediate chars don't emit ops. Lives at the
+  // component scope so the onChange and composition handlers share it.
+  const isComposingRef = useRef<boolean>(false)
 
   const initial = useMemo(() => stringValue(defaultValue), [])
   const [localValue, setLocalValue] = useState<string>(initial)
   const [tab, setTab] = useState<'write' | 'preview'>('write')
   const [busy, setBusy] = useState(false)
 
-  const value = fs.controlled ? stringValue(fs.value) : localValue
+  // Phase F.6 — when a `<RecordCollabRoom>` is mounted and the field has
+  // a `TextBinding`, the textarea is bound to a `Y.Text` and edits emit
+  // `TextDelta`s. Mirrors the architecture in `TextLikeInput.tsx` but
+  // wired in-line because MarkdownInput has its own toolbar + Preview
+  // tab that also need to flow through the binding.
+  const binding = fs.textBinding
+  const [boundValue, setBoundValue] = useState<string>(() => binding?.read() ?? initial)
+  const boundValueRef = useRef<string>(boundValue)
+  useEffect(() => { boundValueRef.current = boundValue }, [boundValue])
+
+  // On binding swap: read current Y.Text state. If non-empty, lift it
+  // into local + form-map state. If empty (no peer has typed yet), leave
+  // the SSR-default-derived `boundValue` showing — first edit will
+  // emit a replace-from-empty delta that atomically populates Y.Text.
+  // No client-side seed: Y.Text isn't safe to seed under concurrent
+  // first-mounters (see @pilotiq-pro/collab `formCollabBinding.ts`).
+  useEffect(() => {
+    if (!binding) return
+    const next = binding.read()
+    if (next.length > 0) {
+      setBoundValue(next)
+      boundValueRef.current = next
+      fs.setValue(next)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [binding])
+
+  // Subscribe to remote changes. Local-echoes are filtered by the
+  // `next === prev` guard. Cursor preserved via the same heuristic
+  // used in `TextLikeInput.BoundTextInput`.
+  useEffect(() => {
+    if (!binding) return
+    return binding.observe((next) => {
+      const prev = boundValueRef.current
+      if (next === prev) return
+      const ta = textareaRef.current
+      const cursor = ta?.selectionStart ?? next.length
+      const restored = preserveCursor(prev, next, cursor)
+      setBoundValue(next)
+      boundValueRef.current = next
+      fs.setValue(next)
+      requestAnimationFrame(() => {
+        if (!ta) return
+        if (document.activeElement !== ta) return
+        try { ta.setSelectionRange(restored, restored) } catch { /* defensive */ }
+      })
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [binding])
+
+  const value = binding
+    ? boundValue
+    : (fs.controlled ? stringValue(fs.value) : localValue)
+
   const setValue = (next: string): void => {
+    if (binding) {
+      // Compute against current Y.Text contents (not the local ref) so:
+      //  - first edit against empty Y.Text → `insert@0 <whole>` atomic
+      //    populate (no separate seed op needed);
+      //  - after a remote-applied update or server-resolve replace, the
+      //    delta reflects the actual current shared state, not stale
+      //    local bookkeeping.
+      const before = binding.read()
+      if (next !== before) {
+        const delta = computeDelta(before, next)
+        if (delta) binding.applyDelta(delta)
+        setBoundValue(next)
+        boundValueRef.current = next
+      }
+      fs.setValue(next)
+      fs.triggerLive(next)
+      return
+    }
     if (fs.controlled) { fs.setValue(next); fs.triggerLive(next) }
     else                { setLocalValue(next); fs.triggerLive(next) }
   }
@@ -285,7 +362,27 @@ export function MarkdownInput({
           placeholder={placeholder}
           disabled={disabled}
           {...(fs.controlled
-            ? { value, onChange: (e) => setValue(e.target.value) }
+            ? {
+                value,
+                onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+                  // Phase F.6 — when the binding is active and the user
+                  // is mid-IME, paint locally and hold the delta until
+                  // compositionend so we never emit ops for the
+                  // intermediate composing chars.
+                  if (binding && isComposingRef.current) {
+                    setBoundValue(e.target.value)
+                    return
+                  }
+                  setValue(e.target.value)
+                },
+                ...(binding ? {
+                  onCompositionStart: () => { isComposingRef.current = true },
+                  onCompositionEnd:   (e: React.CompositionEvent<HTMLTextAreaElement>) => {
+                    isComposingRef.current = false
+                    setValue(e.currentTarget.value)
+                  },
+                } : {}),
+              }
             : { defaultValue: initial, onChange: (e) => setLocalValue(e.target.value) })}
           onPaste={onPaste}
           onKeyDown={onKeyDown}

package/src/react/fields/TextLikeInput.tsx

@@ -1,8 +1,10 @@
-import React from 'react'
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { ElementMeta } from '../../schema/Element.js'
+import type { TextBinding } from '../FormCollabBindingRegistry.js'
 import { useFieldState } from '../FormStateContext.js'
 import { Input } from '../ui/input.js'
 import { Textarea } from '../ui/textarea.js'
+import { computeDelta, preserveCursor } from './textDelta.js'
 
 /**
  * Bridge between controlled (FormStateProvider) and uncontrolled
@@ -10,6 +12,16 @@ import { Textarea } from '../ui/textarea.js'
  * `live()` fields, the input is bound to the context's values map and
  * fires the live trigger on change/blur according to the field's `live`
  * config. Outside a controlled form, falls back to plain `defaultValue`.
+ *
+ * **Phase F.6 — character-level CRDT branch.** When a `<RecordCollabRoom>`
+ * is mounted up-tree AND `@pilotiq-pro/collab`'s binding registered a
+ * `TextBinding` for this field (text-shaped fieldType + `.collab() !== false`),
+ * the input takes the `BoundTextInput` path: edits emit `TextDelta`s to
+ * the binding's `Y.Text`, remote changes flow back via `observe`, and
+ * cursor position survives both. The legacy whole-string LWW path
+ * still runs for non-text fields, non-collab forms, and masked inputs
+ * (mask + character-level CRDT is incompatible — peers would see raw
+ * keystrokes desynced from the rendered mask).
  */
 export function TextLikeInput({
   el, name, common, type, extraProps, multiline, applyMask,
@@ -33,6 +45,28 @@ export function TextLikeInput({
   const onBlurMode = liveOpts.onBlur === true
   const mask = applyMask ?? identity
 
+  // Phase F.6 — character-level CRDT path. Masking is mutually exclusive
+  // with character-level CRDT (peers would see raw keystrokes diverged
+  // from the local mask render); masked fields fall through to LWW.
+  // We read the mask from the field meta directly — `applyMask` is a
+  // `useCallback`-wrapped fn that's *always* defined (identity when no
+  // mask), so its truthiness can't gate the branch.
+  const hasMask = typeof el['mask'] === 'string'
+  if (fs.textBinding && !hasMask) {
+    return (
+      <BoundTextInput
+        binding={fs.textBinding}
+        name={name}
+        triggerLive={fs.triggerLive}
+        onBlurMode={onBlurMode}
+        common={common}
+        extraProps={extraProps}
+        type={type}
+        multiline={multiline}
+      />
+    )
+  }
+
   if (fs.controlled) {
     const ctxValue = fs.value !== undefined && fs.value !== null ? String(fs.value) : ''
     const onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>): void => {
@@ -71,4 +105,172 @@ export function TextLikeInput({
   return <Input {...(common as React.ComponentProps<typeof Input>)} type={type} {...extraProps} />
 }
 
+/**
+ * Phase F.6 — CRDT-bound text input. Owns its own controlled state
+ * because the binding's `Y.Text` is the source of truth (not the
+ * form's `values` map). Mirrors every committed value back into the
+ * form context via `fs.setValue` so submission / live re-resolve see
+ * the latest string.
+ *
+ * Lifecycle:
+ *   - Mount: seed local state from `binding.read()`; mirror it into
+ *     the form's `values` map.
+ *   - Local edit: compute a `TextDelta` (insert / delete / replace)
+ *     from the before/after strings and `applyDelta` to the binding.
+ *     Eagerly update local state in the same React render so the
+ *     controlled input doesn't lag the keystroke.
+ *   - Remote edit: `binding.observe` fires with the post-change
+ *     string; we replace local state and best-effort preserve the
+ *     local cursor via `preserveCursor`. The local-echo of our own
+ *     `applyDelta` is collapsed by the value-equality check.
+ *   - IME composition: `applyDelta` is deferred to `compositionend`
+ *     so the binding never sees intermediate composing chars (which
+ *     would emit one delta per keystroke and confuse downstream
+ *     observers).
+ */
+function BoundTextInput({
+  binding, name, triggerLive, onBlurMode, common, extraProps, type, multiline,
+}: {
+  binding:     TextBinding
+  name:        string
+  triggerLive: (valueOverride?: unknown) => void
+  onBlurMode:  boolean
+  common:      Record<string, unknown>
+  extraProps:  Record<string, unknown>
+  type:        string
+  multiline:   boolean
+}): React.ReactElement {
+  const fs = useFieldState(name)
+  // SSR-rendered default. Captured once at mount; used as display
+  // fallback while the room's `Y.Text` is still empty (the seed race
+  // for Y.Text isn't safe across concurrent first-mounters, so no peer
+  // populates it client-side — see `@pilotiq-pro/collab` for the
+  // rationale). First user edit emits a replace-from-empty delta that
+  // atomically lifts the displayed value into the CRDT.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const fallback    = useMemo(() => stringValue(fs.value), [])
+  const [value, setValueLocal] = useState<string>(() => binding.read() || fallback)
+  const valueRef    = useRef<string>(value)
+  const isComposing = useRef<boolean>(false)
+  const inputRef    = useRef<HTMLInputElement | HTMLTextAreaElement | null>(null)
+
+  useEffect(() => { valueRef.current = value }, [value])
+
+  // Stable ref to the form-mirror writer so the observer effect below
+  // doesn't tear down on every render (fs.setValue is a fresh arrow on
+  // every useFieldState call).
+  const mirrorRef = useRef<(v: string) => void>(() => {})
+  useEffect(() => {
+    mirrorRef.current = (v: string): void => { fs.setValue(v) }
+  })
+
+  // On mount / binding swap: read the binding's current state. If
+  // non-empty (i.e. someone else has already typed), display it and
+  // mirror into the form values map. If empty, leave the fallback
+  // showing — no client-side seed (see file-header comment).
+  useEffect(() => {
+    const initial = binding.read()
+    if (initial.length > 0) {
+      setValueLocal(initial)
+      valueRef.current = initial
+      mirrorRef.current(initial)
+    }
+  }, [binding])
+
+  // Subscribe to text-CRDT changes. Yjs fires this for BOTH local and
+  // remote transactions — local echoes are collapsed by the
+  // `next === prev` guard.
+  useEffect(() => {
+    const unsubscribe = binding.observe((next) => {
+      const prev = valueRef.current
+      if (next === prev) return
+      const el = inputRef.current
+      const cursor = el?.selectionStart ?? next.length
+      const restored = preserveCursor(prev, next, cursor)
+      setValueLocal(next)
+      valueRef.current = next
+      mirrorRef.current(next)
+      // Defer cursor restore until after React commits. Only reapply
+      // when the input is still focused — yanking the selection on a
+      // blurred field would steal focus across the page.
+      requestAnimationFrame(() => {
+        if (!el) return
+        if (document.activeElement !== el) return
+        try { el.setSelectionRange(restored, restored) } catch { /* setSelectionRange unsupported on some input types — defensive */ }
+      })
+    })
+    return unsubscribe
+  }, [binding])
+
+  const commitDelta = useCallback((after: string): void => {
+    // Compute the delta against the binding's *current* Y.Text contents
+    // — not the renderer's `before` ref. The two can diverge in three
+    // cases that all converge correctly under this approach:
+    //   1. First edit when Y.Text is empty: delta = `insert@0 <whole>`,
+    //      which atomically lifts the displayed fallback into the CRDT
+    //      without a separate seed op.
+    //   2. After a remote-applied update: Y.Text holds the peer's value;
+    //      computing against it avoids "ghost" deltas that re-emit ops
+    //      against a stale local ref.
+    //   3. After a server-resolve `triggerLive` replace: same as (2).
+    const before = binding.read()
+    if (after === before) return
+    const delta = computeDelta(before, after)
+    if (!delta) return
+    binding.applyDelta(delta)
+    // Eager local + form-map update so the controlled input doesn't
+    // wait on the observer echo to render the new keystroke. Observer
+    // will fire with the same string and short-circuit via the equality
+    // check above.
+    setValueLocal(after)
+    valueRef.current = after
+    mirrorRef.current(after)
+    if (!onBlurMode) triggerLive(after)
+  }, [binding, onBlurMode, triggerLive])
+
+  const onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>): void => {
+    if (isComposing.current) {
+      // IME mid-composition — paint locally, hold the delta until commit.
+      setValueLocal(e.target.value)
+      return
+    }
+    commitDelta(e.target.value)
+  }
+
+  const onCompositionStart = (): void => { isComposing.current = true }
+  const onCompositionEnd   = (e: React.CompositionEvent<HTMLInputElement | HTMLTextAreaElement>): void => {
+    isComposing.current = false
+    commitDelta(e.currentTarget.value)
+  }
+
+  const onBlur = (): void => {
+    if (onBlurMode) triggerLive(valueRef.current)
+  }
+
+  const setRef = (el: HTMLInputElement | HTMLTextAreaElement | null): void => {
+    inputRef.current = el
+  }
+
+  const props = {
+    ...common,
+    ...extraProps,
+    defaultValue: undefined,
+    value,
+    onChange,
+    onBlur,
+    onCompositionStart,
+    onCompositionEnd,
+    ref: setRef,
+  }
+
+  if (multiline) return <Textarea {...(props as React.ComponentProps<typeof Textarea>)} />
+  return <Input {...(props as React.ComponentProps<typeof Input>)} type={type} />
+}
+
 function identity(v: string): string { return v }
+
+function stringValue(v: unknown): string {
+  if (v === undefined || v === null) return ''
+  if (typeof v === 'string') return v
+  return String(v)
+}