@pilotiq/pilotiq 0.8.1 → 0.9.0

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,7 +49,20 @@ export {
   type FormCollabBinding,
   type FormCollabBindingFactory,
   type FormCollabBindingFactoryArgs,
+  type TextBinding,
+  type TextDelta,
 } from './FormCollabBindingRegistry.js'
+export {
+  registerFieldPresenceComponent,
+  getFieldPresenceComponent,
+  type FieldPresenceProps,
+} from './FieldPresenceRegistry.js'
+export {
+  registerFieldFocusReporter,
+  getFieldFocusReporter,
+  type FieldFocusReporter,
+  type FieldFocusEvent,
+} from './FieldFocusReporterRegistry.js'
 export {
   registerRecordWrapper,
   getRecordWrapper,
@@ -59,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 }
+}