@pilotiq/pilotiq 0.8.2 → 0.9.0

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)
+}

package/src/react/fields/textDelta.test.ts

@@ -0,0 +1,141 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { computeDelta, preserveCursor } from './textDelta.js'
+
+describe('computeDelta — string-diff to TextDelta', () => {
+  it('returns null for identical strings', () => {
+    assert.equal(computeDelta('hello', 'hello'), null)
+    assert.equal(computeDelta('', ''),           null)
+  })
+
+  it('emits insert when text is appended', () => {
+    assert.deepEqual(
+      computeDelta('hello', 'hello!'),
+      { kind: 'insert', index: 5, text: '!' },
+    )
+  })
+
+  it('emits insert when text is prepended', () => {
+    assert.deepEqual(
+      computeDelta('world', 'hello world'),
+      { kind: 'insert', index: 0, text: 'hello ' },
+    )
+  })
+
+  it('emits insert when text is spliced mid-string', () => {
+    // Inserting an 'l' to make 'helo' → 'hello'. The longest common
+    // prefix is 'hel' (3 chars — before[2]='l' and after[2]='l' both
+    // match), so the insertion lands at index 3. Either interpretation
+    // (index 2 or index 3) produces the same CRDT result; the diff
+    // picks the rightmost feasible point deterministically.
+    assert.deepEqual(
+      computeDelta('helo', 'hello'),
+      { kind: 'insert', index: 3, text: 'l' },
+    )
+  })
+
+  it('emits delete when a trailing run is removed', () => {
+    assert.deepEqual(
+      computeDelta('hello!', 'hello'),
+      { kind: 'delete', index: 5, length: 1 },
+    )
+  })
+
+  it('emits delete when a leading run is removed', () => {
+    assert.deepEqual(
+      computeDelta('hello world', 'world'),
+      { kind: 'delete', index: 0, length: 6 },
+    )
+  })
+
+  it('emits delete when a mid-string run is removed', () => {
+    assert.deepEqual(
+      computeDelta('hello', 'hlo'),
+      { kind: 'delete', index: 1, length: 2 },
+    )
+  })
+
+  it('emits replace when a mid-string selection is swapped', () => {
+    assert.deepEqual(
+      computeDelta('hello world', 'hello pilot'),
+      { kind: 'replace', from: 6, to: 11, text: 'pilot' },
+    )
+  })
+
+  it('emits replace when the whole string is swapped', () => {
+    assert.deepEqual(
+      computeDelta('foo', 'bar'),
+      { kind: 'replace', from: 0, to: 3, text: 'bar' },
+    )
+  })
+
+  it('emits insert when growing from empty', () => {
+    assert.deepEqual(
+      computeDelta('', 'a'),
+      { kind: 'insert', index: 0, text: 'a' },
+    )
+  })
+
+  it('emits delete when shrinking to empty', () => {
+    assert.deepEqual(
+      computeDelta('abc', ''),
+      { kind: 'delete', index: 0, length: 3 },
+    )
+  })
+
+  it('handles repeated-char shrink without prefix/suffix overlap', () => {
+    // 'aaa' → 'aa' — the prefix walk could greedily eat all 2 chars from
+    // the after side; the suffix cap must stop suffix at 2 so beforeMid
+    // is 'a' (length 1) instead of '' (length 0, identity).
+    assert.deepEqual(
+      computeDelta('aaa', 'aa'),
+      { kind: 'delete', index: 2, length: 1 },
+    )
+  })
+})
+
+describe('preserveCursor — anchor across remote edits', () => {
+  it('returns input cursor when strings are identical', () => {
+    assert.equal(preserveCursor('hello', 'hello', 3), 3)
+  })
+
+  it('leaves cursor untouched when edit lands AFTER cursor', () => {
+    // Cursor at index 2 ('he|llo'); remote appends ' world'. Edit prefix
+    // length is 5, cursor 2 ≤ prefix → no shift.
+    assert.equal(preserveCursor('hello', 'hello world', 2), 2)
+  })
+
+  it('shifts cursor when edit lands BEFORE cursor', () => {
+    // Cursor at 5 ('hello|'); remote prepends 'XX '. The common prefix
+    // is empty, so cursor > prefix → shift by (8 − 5) = 3, landing at
+    // 8 (the end of the new string, same logical position as before).
+    assert.equal(preserveCursor('hello', 'XX hello', 5), 8)
+  })
+
+  it('lands at end-of-string for non-contiguous edits (heuristic limit)', () => {
+    // Both-sides insertion ('hello' → 'X hello world') flattens into a
+    // single full-string `replace` at the diff layer because the prefix
+    // and suffix walks find no common ground. Cursor lands at the end
+    // of the new string — imperfect for this case but harmless. A
+    // future v2 using Yjs `RelativePosition` would land it at 7
+    // (just after the original 'hello' substring).
+    assert.equal(preserveCursor('hello', 'X hello world', 5), 13)
+  })
+
+  it('clamps cursor when remote deletes around the cursor', () => {
+    // Cursor at 5 ('hello|world'); remote deletes 'hello'. Prefix is 0,
+    // delta is -5 → shifted to 0.
+    assert.equal(preserveCursor('helloworld', 'world', 5), 0)
+  })
+
+  it('never returns a negative cursor', () => {
+    assert.equal(preserveCursor('abcdef', '', 3), 0)
+  })
+
+  it('never returns a cursor past the new length', () => {
+    // Defensive — caller might pass a stale cursor longer than the new
+    // string. Clamp to new bounds.
+    assert.equal(preserveCursor('hello', 'hi', 10), 2)
+  })
+})

package/src/react/fields/textDelta.ts

@@ -0,0 +1,86 @@
+import type { TextDelta } from '../FormCollabBindingRegistry.js'
+
+/**
+ * Phase F.6 — derive a single character-level edit op from two strings.
+ *
+ * Strategy: find the longest common prefix and suffix between `before`
+ * and `after`; whatever's left in the middle is the changed region.
+ *
+ *   - middle-after empty + middle-before non-empty → `delete`
+ *   - middle-before empty + middle-after non-empty → `insert`
+ *   - both non-empty                              → `replace`
+ *   - both empty (identical strings)              → `null`
+ *
+ * This correctly handles the common edit shapes: single-key insert,
+ * single-key backspace, multi-char paste replacing a selection, IME
+ * commits, accent-key composition. It does NOT preserve user intent
+ * when the same character appears at multiple positions and the edit
+ * could be attributed to either occurrence — Yjs's per-character
+ * identity makes that distinction lossy at the string-diff layer
+ * (the `Y.Text` itself maintains item identity internally). For v1
+ * we accept the ambiguity; the CRDT semantics still converge.
+ */
+export function computeDelta(before: string, after: string): TextDelta | null {
+  if (before === after) return null
+
+  let prefix = 0
+  const minLen = Math.min(before.length, after.length)
+  while (prefix < minLen && before[prefix] === after[prefix]) prefix++
+
+  // Walk back from each end, capped so suffix can't overlap the prefix
+  // on either side. Without the cap, identical strings of repeated
+  // chars (e.g. 'aaa' → 'aa') would consume the same byte from both
+  // directions and produce an empty middle on both sides.
+  let suffix = 0
+  const maxSuffix = Math.min(before.length - prefix, after.length - prefix)
+  while (
+    suffix < maxSuffix &&
+    before[before.length - 1 - suffix] === after[after.length - 1 - suffix]
+  ) {
+    suffix++
+  }
+
+  const beforeMid = before.slice(prefix, before.length - suffix)
+  const afterMid  = after.slice(prefix, after.length - suffix)
+
+  if (beforeMid.length === 0 && afterMid.length > 0) {
+    return { kind: 'insert', index: prefix, text: afterMid }
+  }
+  if (afterMid.length === 0 && beforeMid.length > 0) {
+    return { kind: 'delete', index: prefix, length: beforeMid.length }
+  }
+  return { kind: 'replace', from: prefix, to: prefix + beforeMid.length, text: afterMid }
+}
+
+/**
+ * Phase F.6 — best-effort cursor anchor across a remote-applied edit.
+ *
+ *   - Edit landed AFTER cursor (cursor inside the common prefix) → keep
+ *     cursor where it is.
+ *   - Edit landed BEFORE cursor                                  → shift
+ *     cursor by `after.length − before.length` so its character-offset
+ *     into the post-edit string matches its pre-edit anchor.
+ *   - Edit landed OVERLAPPING the cursor                         → cursor
+ *     ends up at the boundary between the changed region and the
+ *     unchanged suffix (which `Math.max(0, cursor + delta)` produces
+ *     naturally and clamps to the new bounds).
+ *
+ * This is a heuristic, not a Yjs `RelativePosition`. Two peers typing
+ * at the exact same insertion point can still see a one-character cursor
+ * twitch on the remote-mirror side; v2 (in-input remote carets) would
+ * upgrade to relative positions if/when a consumer asks. Native input
+ * cursors are clamped to `[0, after.length]` by every browser, so this
+ * function does the same to avoid `setSelectionRange` throwing.
+ */
+export function preserveCursor(before: string, after: string, cursor: number): number {
+  if (before === after) return cursor
+
+  let prefix = 0
+  const minLen = Math.min(before.length, after.length)
+  while (prefix < minLen && before[prefix] === after[prefix]) prefix++
+
+  if (cursor <= prefix) return Math.min(cursor, after.length)
+
+  const delta = after.length - before.length
+  return Math.max(0, Math.min(after.length, cursor + delta))
+}

package/src/react/index.ts

@@ -49,6 +49,8 @@ export {
   type FormCollabBinding,
   type FormCollabBindingFactory,
   type FormCollabBindingFactoryArgs,
+  type TextBinding,
+  type TextDelta,
 } from './FormCollabBindingRegistry.js'
 export {
   registerFieldPresenceComponent,
@@ -70,7 +72,13 @@ export {
   RecordWrapperGate,
   type RecordWrapperGateProps,
 } from './RecordWrapperGate.js'
-export { parseRecordEditUrl, type RecordEditIdentity } from './parseRecordEditUrl.js'
+export {
+  parseRecordPageUrl,
+  parseRecordEditUrl,
+  type RecordPageIdentity,
+  type RecordPageRole,
+  type RecordEditIdentity,
+} from './parseRecordEditUrl.js'
 export {
   registerWidgetRenderer,
   getWidgetRenderer,

package/src/react/parseRecordEditUrl.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { parseRecordEditUrl } from './parseRecordEditUrl.js'
+import { parseRecordEditUrl, parseRecordPageUrl } from './parseRecordEditUrl.js'
 
 test('parseRecordEditUrl: bare resource edit', () => {
   assert.deepEqual(
@@ -73,3 +73,50 @@ test('parseRecordEditUrl: slug-only edit (no record id) returns null', () => {
   // slice. Defensive: reject when slugParts is empty.
   assert.equal(parseRecordEditUrl('/admin/edit', '/admin'), null)
 })
+
+// ─── parseRecordPageUrl (role-aware) ─────────────────────────
+
+test('parseRecordPageUrl: edit URL returns role=edit', () => {
+  assert.deepEqual(
+    parseRecordPageUrl('/admin/articles/123/edit', '/admin'),
+    { resourceSlug: 'articles', recordId: '123', role: 'edit' },
+  )
+})
+
+test('parseRecordPageUrl: view URL returns role=view', () => {
+  assert.deepEqual(
+    parseRecordPageUrl('/admin/articles/123/view', '/admin'),
+    { resourceSlug: 'articles', recordId: '123', role: 'view' },
+  )
+})
+
+test('parseRecordPageUrl: cluster-prefixed view URL', () => {
+  assert.deepEqual(
+    parseRecordPageUrl('/admin/blog/articles/123/view', '/admin'),
+    { resourceSlug: 'blog/articles', recordId: '123', role: 'view' },
+  )
+})
+
+test('parseRecordPageUrl: terminal token other than edit|view returns null', () => {
+  // 'delete' / 'restore' / 'force-delete' are POST handlers, not pages.
+  assert.equal(parseRecordPageUrl('/admin/articles/123/delete', '/admin'), null)
+  assert.equal(parseRecordPageUrl('/admin/articles/123/restore', '/admin'), null)
+  // Custom record sub-pages also fall through here — they have their own
+  // gate path (not record-bound for collab purposes in v1).
+  assert.equal(parseRecordPageUrl('/admin/articles/123/history', '/admin'), null)
+})
+
+test('parseRecordPageUrl: view URL in nested-relation form', () => {
+  assert.deepEqual(
+    parseRecordPageUrl('/admin/articles/123/comments/456/view', '/admin'),
+    { resourceSlug: 'articles/123/comments', recordId: '456', role: 'view' },
+  )
+})
+
+// ─── Legacy alias: parseRecordEditUrl filters view URLs ──────
+
+test('parseRecordEditUrl: view URL returns null (back-compat: edit-only)', () => {
+  // A consumer still calling the legacy `parseRecordEditUrl` should
+  // continue to see view URLs filtered out — only edit URLs round-trip.
+  assert.equal(parseRecordEditUrl('/admin/articles/123/view', '/admin'), null)
+})