@pilotiq/pilotiq 0.8.2 → 0.10.0

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

package/src/react/parseRecordEditUrl.ts

@@ -1,12 +1,13 @@
 /**
- * Parses a pilotiq URL into a record-edit identity, or returns `null`
- * for any URL that isn't a record-bound edit page.
+ * URL → record-page identity parser. Used by `RecordWrapperGate` (and any
+ * plugin that wants to reason about record-bound URLs) to decide whether
+ * the current page is a record-edit or record-view route.
  *
  * A URL matches when:
  *   1. it starts with the panel's `basePath`
- *   2. after stripping the prefix it ends with `/edit`
+ *   2. after stripping the prefix it ends with `/edit` or `/view`
  *   3. there are at least three remaining segments (resource slug,
- *      record id, `edit`)
+ *      record id, terminal token)
  *
  * The `resourceSlug` is the slash-joined chain of every segment up to
  * the record id — this gives clustered resources (`${base}/blog/articles/123/edit`)
@@ -14,22 +15,40 @@
  * distinct slugs so two URLs that target different records always
  * produce different room names downstream.
  *
- *   `/admin/articles/123/edit`                      → { resourceSlug: 'articles',                 recordId: '123' }
- *   `/admin/blog/articles/123/edit`                 → { resourceSlug: 'blog/articles',            recordId: '123' }
- *   `/admin/articles/123/comments/456/edit`         → { resourceSlug: 'articles/123/comments',    recordId: '456' }
- *   `/admin/articles/123/comments`                  → null  (no trailing /edit)
- *   `/admin/articles/123/comments/create`           → null  (no record id)
+ *   `/admin/articles/123/edit`                      → { slug: 'articles',              id: '123', role: 'edit' }
+ *   `/admin/articles/123/view`                      → { slug: 'articles',              id: '123', role: 'view' }
+ *   `/admin/blog/articles/123/edit`                 → { slug: 'blog/articles',         id: '123', role: 'edit' }
+ *   `/admin/articles/123/comments/456/edit`         → { slug: 'articles/123/comments', id: '456', role: 'edit' }
+ *   `/admin/articles/123/comments`                  → null  (no trailing /edit or /view)
+ *   `/admin/articles/123/comments/create`           → null  (terminal token isn't edit|view)
  *   `/site/articles/123/edit`                       → null  (basePath mismatch when basePath='/admin')
  */
-export interface RecordEditIdentity {
+
+/** Page roles `parseRecordPageUrl` recognizes. `'edit'` and `'view'`
+ * are the two record-scoped page roles where collab and other
+ * record-bound plugins want to mount their per-record wrapper. */
+export type RecordPageRole = 'edit' | 'view'
+
+export interface RecordPageIdentity {
   resourceSlug: string
   recordId:     string
+  /** Which terminal URL segment matched — `'edit'` for the writable edit
+   * page, `'view'` for the read-only view page. Lets the gate decide per
+   * resource whether collab activates on this role (defaults to `'edit'`
+   * only; resources opt into `'view'` for presence-only experiences). */
+  role:         RecordPageRole
 }
 
-export function parseRecordEditUrl(
+const RECOGNIZED_ROLES: ReadonlyArray<RecordPageRole> = ['edit', 'view']
+
+/**
+ * Parse a pilotiq URL into a `{ slug, id, role }` identity. Returns
+ * `null` for any URL that isn't a record-edit or record-view page.
+ */
+export function parseRecordPageUrl(
   currentPath: string,
   basePath:    string,
-): RecordEditIdentity | null {
+): RecordPageIdentity | null {
   if (!currentPath) return null
   // Normalise — trailing slashes on the URL or trailing slashes on
   // basePath would otherwise reject perfectly valid matches.
@@ -42,7 +61,8 @@ export function parseRecordEditUrl(
   const parts = tail.split('/').filter(Boolean)
 
   if (parts.length < 3) return null
-  if (parts[parts.length - 1] !== 'edit') return null
+  const terminal = parts[parts.length - 1]!
+  if (!RECOGNIZED_ROLES.includes(terminal as RecordPageRole)) return null
 
   const recordId    = parts[parts.length - 2]!
   const slugParts   = parts.slice(0, parts.length - 2)
@@ -51,5 +71,24 @@ export function parseRecordEditUrl(
   return {
     resourceSlug: slugParts.join('/'),
     recordId,
+    role:         terminal as RecordPageRole,
   }
 }
+
+/** Legacy alias: parse a URL into an edit-only identity. Returns `null`
+ * for view URLs (and any non-edit URL). Kept for back-compat with the
+ * pre-`parseRecordPageUrl` public API; new code should call
+ * `parseRecordPageUrl` and branch on `role`. */
+export interface RecordEditIdentity {
+  resourceSlug: string
+  recordId:     string
+}
+
+export function parseRecordEditUrl(
+  currentPath: string,
+  basePath:    string,
+): RecordEditIdentity | null {
+  const identity = parseRecordPageUrl(currentPath, basePath)
+  if (!identity || identity.role !== 'edit') return null
+  return { resourceSlug: identity.resourceSlug, recordId: identity.recordId }
+}