@pilotiq/pilotiq 0.8.2 → 0.10.0

package/src/pageData.test.ts

@@ -5,6 +5,7 @@ import { Form } from './elements/Form.js'
 import { ListTab } from './Tab.js'
 import { ListTabs } from './elements/ListTabs.js'
 import {
+  applyEditPageHydrators,
   applyFillPipeline,
   formCreateOptionData,
   formStateData,
@@ -1202,3 +1203,139 @@ describe('tagRichTextMentionUrls — nested Repeater + Builder rows', () => {
     assert.equal(inner.stamped, '/admin/_form/art/mentions')
   })
 })
+
+describe('applyEditPageHydrators (Pilotiq.editPageHydrator)', () => {
+  class Posts extends Resource { static override label = 'Posts' }
+  const ctx = (currentValues: Record<string, unknown> = {}) => ({
+    resource:      Posts,
+    recordId:      '42',
+    currentValues,
+  })
+
+  it('empty hydrators array → empty overlay', async () => {
+    const overlay = await applyEditPageHydrators([], ctx())
+    assert.deepEqual(overlay, {})
+  })
+
+  it('hydrator returning null → empty overlay', async () => {
+    const overlay = await applyEditPageHydrators([
+      async () => null,
+    ], ctx())
+    assert.deepEqual(overlay, {})
+  })
+
+  it('hydrator returning a partial → overlay carries the keys', async () => {
+    const overlay = await applyEditPageHydrators([
+      async () => ({ title: 'Y-Title', body: 'Y-Body' }),
+    ], ctx({ title: 'DB-Title', body: 'DB-Body', author: 'DB-Author' }))
+    assert.deepEqual(overlay, { title: 'Y-Title', body: 'Y-Body' })
+  })
+
+  it('two hydrators merge in registration order (later wins on conflict)', async () => {
+    const overlay = await applyEditPageHydrators([
+      async () => ({ title: 'first',  shared: 'first-shared' }),
+      async () => ({ body:  'second', shared: 'second-shared' }),
+    ], ctx())
+    assert.deepEqual(overlay, {
+      title:  'first',
+      body:   'second',
+      shared: 'second-shared',
+    })
+  })
+
+  it('hydrator that throws is swallowed; siblings still contribute', async () => {
+    // Stub console.warn so the test output stays clean; restore after.
+    const originalWarn = console.warn
+    let warned = false
+    console.warn = (..._args: unknown[]) => { warned = true }
+    try {
+      const overlay = await applyEditPageHydrators([
+        async () => { throw new Error('boom') },
+        async () => ({ title: 'sibling-survived' }),
+      ], ctx())
+      assert.deepEqual(overlay, { title: 'sibling-survived' })
+      assert.equal(warned, true, 'console.warn should fire for thrown hydrators')
+    } finally {
+      console.warn = originalWarn
+    }
+  })
+
+  it('hydrator returning a non-object is skipped', async () => {
+    const overlay = await applyEditPageHydrators([
+      // @ts-expect-error — deliberately exercising the runtime guard
+      async () => 'not-an-object',
+      async () => ({ title: 'real-result' }),
+    ], ctx())
+    assert.deepEqual(overlay, { title: 'real-result' })
+  })
+
+  it('hydrator receives current fill-pipeline values via ctx.currentValues', async () => {
+    let seen: Record<string, unknown> | undefined
+    await applyEditPageHydrators([
+      async (ctx) => { seen = ctx.currentValues; return null },
+    ], ctx({ title: 'DB-Title', body: 'DB-Body' }))
+    assert.deepEqual(seen, { title: 'DB-Title', body: 'DB-Body' })
+  })
+
+  it('hydrator receives resource class + recordId in ctx', async () => {
+    let seenResource: unknown
+    let seenRecordId: unknown
+    await applyEditPageHydrators([
+      async (ctx) => { seenResource = ctx.resource; seenRecordId = ctx.recordId; return null },
+    ], ctx())
+    assert.equal(seenResource, Posts)
+    assert.equal(seenRecordId, '42')
+  })
+})
+
+describe('Pilotiq.editPageHydrator builder method', () => {
+  it('stores hydrators on the config in registration order', () => {
+    const fn1 = async () => ({ a: 1 })
+    const fn2 = async () => ({ b: 2 })
+    const panel = Pilotiq.make('Admin')
+      .editPageHydrator(fn1)
+      .editPageHydrator(fn2)
+    assert.deepEqual(panel.getConfig().editPageHydrators, [fn1, fn2])
+  })
+
+  it('absent when no hydrator registered', () => {
+    const panel = Pilotiq.make('Admin')
+    assert.equal(panel.getConfig().editPageHydrators, undefined)
+  })
+})
+
+describe('panelInfo — recordCollab map (resource collab opt-in)', () => {
+  it('absent when no resource opts in', async () => {
+    class Posts extends Resource { static override label = 'Posts' }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts]))
+    assert.equal((info as { recordCollab?: unknown }).recordCollab, undefined)
+  })
+
+  it('emits an entry for each opted-in resource keyed by URL slug', async () => {
+    class Posts extends Resource {
+      static override label  = 'Posts'
+      static override collab = true as const
+    }
+    class Users extends Resource {
+      static override label  = 'Users'
+      // No collab — should NOT appear in the map.
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts, Users]))
+    const map = (info as { recordCollab?: Record<string, unknown> }).recordCollab
+    assert.deepEqual(map, {
+      posts: { pages: ['edit'], presence: true },
+    })
+  })
+
+  it('honors object form of static collab (pages + presence override defaults)', async () => {
+    class Posts extends Resource {
+      static override label  = 'Posts'
+      static override collab = { pages: ['edit', 'view'] as const, presence: false }
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts]))
+    const map = (info as { recordCollab?: Record<string, unknown> }).recordCollab
+    assert.deepEqual(map, {
+      posts: { pages: ['edit', 'view'], presence: false },
+    })
+  })
+})

package/src/pageData.ts

@@ -22,6 +22,7 @@ export type { ServerDataMap } from './pageData/helpers.js'
 // Re-export the URL-tag helpers + fill pipeline + server-data resolver
 // for consumers that import them through `./pageData.js`.
 export {
+  applyEditPageHydrators,
   applyFillPipeline,
   applyRelationshipBuilderFill,
   applyRelationshipRepeaterFill,

package/src/react/AppShell.tsx

@@ -10,7 +10,7 @@ import type { RightPanelRegistry } from './right-panel-registry.js'
 import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
-import { RecordWrapperGate } from './RecordWrapperGate.js'
+import { RecordWrapperGate, type RecordCollabMap } from './RecordWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
@@ -34,6 +34,10 @@ export interface AppShellProps {
      *  `panelInfo()` only ships this when at least one contribution
      *  was registered AND passed the auth gate AND is non-hidden. */
     rightSidebar?: RightSidebarMeta
+    /** Per-resource collab opt-in map — read by `RecordWrapperGate` to
+     *  decide whether to mount the plugin-registered RecordWrapper on
+     *  a record edit/view URL. Absent when no resource opted in. */
+    recordCollab?: RecordCollabMap
     /** Pre-resolved render-hook slots for the panel chrome (body /
      *  topbar / sidebar / user-menu / footer / head). Sparse map —
      *  slots with no registered entries are absent. Built by
@@ -130,6 +134,7 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
       <RecordWrapperGate
         basePath={props.basePath}
         {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+        {...(props.panel.recordCollab !== undefined ? { recordCollab: props.panel.recordCollab } : {})}
       >
         {props.children}
       </RecordWrapperGate>

package/src/react/FormCollabBindingRegistry.ts

@@ -1,5 +1,44 @@
+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
@@ -16,8 +55,14 @@ import type { CollabRoom } from './CollabRoomContext.js'
  *   - `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.
+ *     remove its CRDT observer. Implementations are expected to cascade
+ *     into every `TextBinding` they issued.
  *
  * `unknown` payloads keep pilotiq core Yjs-free; the binding owns its
  * own type knowledge. Same posture as `CollabExtensionFactory`.
@@ -29,6 +74,12 @@ 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
 }
@@ -51,6 +102,17 @@ export interface FormCollabBindingFactoryArgs {
    * map already populated and skip.
    */
   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).
+   */
+  formMeta: ElementMeta
 }
 
 export type FormCollabBindingFactory = (args: FormCollabBindingFactoryArgs) => FormCollabBinding

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/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}