@pilotiq/pilotiq 0.12.0 → 0.13.1

package/src/react/fields/TextLikeInput.tsx

@@ -1,12 +1,12 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
 import type { ElementMeta } from '../../schema/Element.js'
-import type { TextBinding } from '../FormCollabBindingRegistry.js'
 import { useFieldState } from '../FormStateContext.js'
 import { useCollabRoom } from '../CollabRoomContext.js'
 import { getCollabTextRenderer, type CollabTextRenderer } from '../CollabTextRendererRegistry.js'
+import { useRowCoords } from '../RowCoordsContext.js'
+import { parseRowFieldPath } from '../formStateHelpers.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
@@ -15,15 +15,17 @@ import { computeDelta, preserveCursor } from './textDelta.js'
  * 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).
+ * **Collab branch — Tiptap-backed `Y.XmlFragment`.** When a
+ * `<RecordCollabRoom>` is mounted up-tree AND `@pilotiq/tiptap`'s
+ * `registerTiptap()` registered a collab text renderer, the input
+ * mounts the Tiptap-backed editor against a `Y.XmlFragment` keyed by
+ * either the bare field name (top-level) or
+ * `${arrayName}.${rowId}.${fieldName}` (Repeater / Builder row leaves
+ * via `useRowCoords()`). Selections anchor to `Y.RelativePosition` via
+ * y-prosemirror, so cursors survive both mid-word remote edits and
+ * concurrent inserts. Masked fields fall through to the legacy
+ * whole-string LWW path (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,
@@ -42,6 +44,7 @@ export function TextLikeInput({
   const fs = useFieldState(name)
   const room = useCollabRoom()
   const collabRenderer = getCollabTextRenderer()
+  const rowCoords = useRowCoords()
   const liveCfg = el['live']
   const liveOpts = (typeof liveCfg === 'object' && liveCfg !== null
     ? liveCfg as { onBlur?: boolean; debounce?: number }
@@ -49,35 +52,48 @@ 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.
+  // 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'
 
-  // Phase B — Tiptap-backed plain-text editor for collab text fields.
-  // When a `<RecordCollabRoom>` is mounted up-tree AND `@pilotiq/tiptap`'s
-  // `registerTiptap()` registered a collab text renderer, take the new path:
-  // the editor anchors selections to Yjs `RelativePosition` (via y-prosemirror)
-  // instead of integer string offsets, fixing the cursor-jump + two-peer
-  // concurrent-insert races that the legacy `Y.Text` + `computeDelta` path
-  // can't resolve. Dotted-path row leaves (Repeater / Builder) stay on the
-  // legacy `fs.textBinding` path — per-row collab editor support is a
-  // separate follow-up.
+  // Collab branch — Tiptap-backed plain-text editor. Top-level fields
+  // use the bare `name` as the fragment-key; Repeater / Builder row
+  // leaves compose `${arrayName}.${rowId}.${fieldName}` from
+  // `useRowCoords()` so the Y.XmlFragment survives row reorders (keyed
+  // by the stable rowId, not the array index). The hidden FormData
+  // input keeps the original dotted path so submission lands on the
+  // server at the right slot.
+  //
+  // Dotted paths that don't match a row shape (no rowCoords OR
+  // `parseRowFieldPath` returns null — nested row arrays, malformed
+  // names) skip the collab path and fall through to the controlled /
+  // uncontrolled branches below.
   const fieldCollab = el['collab'] as boolean | undefined
+  const fragmentKey: string | null = (() => {
+    if (!name.includes('.')) return name
+    if (!rowCoords) return null
+    const parsed = parseRowFieldPath(name)
+    if (!parsed) return null
+    if (parsed.arrayName !== rowCoords.arrayName) return null
+    if (parsed.index     !== rowCoords.rowIndex)  return null
+    return `${rowCoords.arrayName}.${rowCoords.rowId}.${parsed.fieldName}`
+  })()
   if (
     room &&
     collabRenderer &&
     fieldCollab !== false &&
     !hasMask &&
-    !name.includes('.')
+    fragmentKey !== null
   ) {
     return (
       <CollabTextField
         Renderer={collabRenderer}
-        name={name}
+        fragmentKey={fragmentKey}
+        hiddenInputName={name}
         multiline={multiline}
         defaultValue={stringValue(common['defaultValue'])}
         {...(common['placeholder'] !== undefined ? { placeholder: String(common['placeholder']) } : {})}
@@ -90,21 +106,6 @@ export function TextLikeInput({
     )
   }
 
-  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 => {
@@ -144,174 +145,7 @@ export function TextLikeInput({
 }
 
 /**
- * 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
-    // Pre-stamp `valueRef.current = after` BEFORE `applyDelta`. Y.Text's
-    // observe fires synchronously inside `applyDelta` for our own write,
-    // so without this the observer would see `prev=before, next=after`
-    // and run `preserveCursor` — which is designed for *remote* edits
-    // and clobbers the user's caret on local typing (typed '1' at pos 0
-    // would jump cursor forward by delta-length and the next keystroke
-    // would insert at the wrong index, producing scrambled output).
-    // With `valueRef` already at `after`, the observer's `next === prev`
-    // short-circuit fires and the cursor is left alone for local echoes.
-    valueRef.current = after
-    binding.applyDelta(delta)
-    setValueLocal(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} />
-}
-
-/**
- * Phase B — wrapper around the registered Tiptap-backed collab editor.
+ * Wrapper around the registered Tiptap-backed collab editor.
  * Owns the local text mirror so the hidden `<input>` always carries the
  * editor's current value for FormData submission. When `FormStateProvider`
  * is mounted up-tree, also mirrors every update into the values map via
@@ -322,21 +156,29 @@ function BoundTextInput({
  * editor handles composition natively and y-prosemirror anchors selections
  * to `Yjs.RelativePosition`, so the cursor survives concurrent + mid-word
  * remote edits without any client-side bookkeeping.
+ *
+ * `fragmentKey` and `hiddenInputName` diverge for row-text leaves (Phase
+ * 1 of collab-row-text-tiptap-backed.md): the renderer's Y.XmlFragment is
+ * keyed by `${arrayName}.${rowId}.${fieldName}` so it survives row
+ * reorders, while the hidden FormData input keeps the dotted path
+ * (`items.0.title`) so submission lands at the right server-side slot.
+ * For top-level fields the two are identical.
  */
 function CollabTextField({
-  Renderer, name, multiline, defaultValue, placeholder, disabled,
+  Renderer, fragmentKey, hiddenInputName, multiline, defaultValue, placeholder, disabled,
   triggerLive, setValue, controlled, onBlurMode,
 }: {
-  Renderer:     CollabTextRenderer
-  name:         string
-  multiline:    boolean
-  defaultValue: string
-  placeholder?: string
-  disabled:     boolean
-  triggerLive:  (valueOverride?: unknown) => void
-  setValue:     (v: unknown) => void
-  controlled:   boolean
-  onBlurMode:   boolean
+  Renderer:        CollabTextRenderer
+  fragmentKey:     string
+  hiddenInputName: string
+  multiline:       boolean
+  defaultValue:    string
+  placeholder?:    string
+  disabled:        boolean
+  triggerLive:     (valueOverride?: unknown) => void
+  setValue:        (v: unknown) => void
+  controlled:      boolean
+  onBlurMode:      boolean
 }): React.ReactElement {
   const [text, setText] = useState<string>(defaultValue)
   const textRef = useRef(text)
@@ -376,9 +218,9 @@ function CollabTextField({
 
   return (
     <>
-      <input type="hidden" name={name} value={text} />
+      <input type="hidden" name={hiddenInputName} value={text} />
       <Renderer
-        name={name}
+        name={fragmentKey}
         multiline={multiline}
         defaultValue={defaultValue}
         {...(placeholder !== undefined ? { placeholder } : {})}

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

@@ -0,0 +1,114 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  computeReconcilePlan,
+  markSubmitForReconcile,
+  consumeReconcileFlag,
+} from './repeaterReconcile.js'
+
+describe('computeReconcilePlan', () => {
+  it('returns empty plan when current and authoritative match', () => {
+    const plan = computeReconcilePlan({
+      current:       ['a', 'b', 'c'],
+      authoritative: ['a', 'b', 'c'],
+    })
+    assert.deepEqual(plan.toRemove, [])
+    assert.deepEqual(plan.toAdd,    [])
+  })
+
+  it('flags orphan CRDT rows as toRemove (PK-switch happy path)', () => {
+    // Submitting tab reloaded — server returned the new DB PK; CRDT
+    // still carries the renderer-minted UUID from the just-saved row.
+    const plan = computeReconcilePlan({
+      current:       ['uuid-foo', '42'],
+      authoritative: ['42'],
+    })
+    assert.deepEqual(plan.toRemove, ['uuid-foo'])
+    assert.deepEqual(plan.toAdd,    [])
+  })
+
+  it('flags missing CRDT rows as toAdd (raw-SQL-seeded record)', () => {
+    // First peer to open a record whose DB rows weren't seeded into the
+    // Y.Doc (no `seedRowArraysFromRecord` coverage for relationship-
+    // backed fields). Reconciler ensures CRDT mirrors initialRows.
+    const plan = computeReconcilePlan({
+      current:       [],
+      authoritative: ['42', '43'],
+    })
+    assert.deepEqual(plan.toRemove, [])
+    assert.deepEqual(plan.toAdd,    ['42', '43'])
+  })
+
+  it('handles both directions in a single pass', () => {
+    const plan = computeReconcilePlan({
+      current:       ['uuid-foo', 'uuid-bar', '42'],
+      authoritative: ['42', '43'],
+    })
+    assert.deepEqual(plan.toRemove, ['uuid-foo', 'uuid-bar'])
+    assert.deepEqual(plan.toAdd,    ['43'])
+  })
+
+  it('preserves order from inputs in toRemove / toAdd', () => {
+    const plan = computeReconcilePlan({
+      current:       ['z', 'a', 'm'],
+      authoritative: ['a', 'b', 'c'],
+    })
+    // toRemove walks current in order; toAdd walks authoritative in order.
+    // Order-stability matters because reconciler applies them sequentially
+    // and we want deterministic test snapshots.
+    assert.deepEqual(plan.toRemove, ['z', 'm'])
+    assert.deepEqual(plan.toAdd,    ['b', 'c'])
+  })
+})
+
+describe('markSubmitForReconcile / consumeReconcileFlag', () => {
+  // Minimal in-memory sessionStorage stub — Node lacks one, and we
+  // want to avoid bringing in jsdom for a flag-roundtrip test.
+  const realSessionStorage = (globalThis as { sessionStorage?: Storage }).sessionStorage
+  const store: Map<string, string> = new Map()
+
+  before(() => {
+    ;(globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      get length() { return store.size },
+      key:        (i: number) => Array.from(store.keys())[i] ?? null,
+      getItem:    (k: string) => store.has(k) ? store.get(k)! : null,
+      setItem:    (k: string, v: string) => { store.set(k, v) },
+      removeItem: (k: string) => { store.delete(k) },
+      clear:      () => { store.clear() },
+    } as Storage
+  })
+
+  after(() => {
+    if (realSessionStorage === undefined) {
+      delete (globalThis as { sessionStorage?: Storage }).sessionStorage
+    } else {
+      (globalThis as { sessionStorage?: Storage }).sessionStorage = realSessionStorage
+    }
+  })
+
+  beforeEach(() => { store.clear() })
+
+  it('returns false when no flag has been set', () => {
+    assert.equal(consumeReconcileFlag('form-1'), false)
+  })
+
+  it('round-trips a flag and clears on first consume', () => {
+    markSubmitForReconcile('form-1')
+    assert.equal(consumeReconcileFlag('form-1'), true)
+    // Second read: flag was cleared on the first consume.
+    assert.equal(consumeReconcileFlag('form-1'), false)
+  })
+
+  it('scopes the flag per formId', () => {
+    markSubmitForReconcile('form-1')
+    assert.equal(consumeReconcileFlag('form-2'), false)
+    assert.equal(consumeReconcileFlag('form-1'), true)
+  })
+
+  it('no-ops on empty formId (mark and consume both)', () => {
+    markSubmitForReconcile('')
+    assert.equal(store.size, 0)
+    assert.equal(consumeReconcileFlag(''), false)
+  })
+})

package/src/react/fields/repeaterReconcile.ts

@@ -0,0 +1,104 @@
+/**
+ * Phase A of the `Repeater.relationship` PK-switch reconciliation
+ * (see `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`).
+ *
+ * When a parent form submit creates new relationship-backed rows, the
+ * server assigns each child a DB primary key — but the row's `__id` in
+ * the row CRDT is still the renderer-minted UUID from the local session.
+ * After redirect, the submitting tab's pageData carries `__id = String(pk)`
+ * while CRDT still has the UUID, so the renderer ends up showing the
+ * same row twice (DB PK from initialRows + orphan UUID from CRDT).
+ *
+ * Phase A fix: the submitting tab marks itself for a one-shot CRDT
+ * reconcile on the next mount via a per-formId sessionStorage flag.
+ * `RepeaterInput` / `BuilderInput` read the flag on mount and, when set,
+ * snapshot the row CRDT after a short settle (waiting for WS sync) and
+ * reconcile against `initialRows` — removing orphan CRDT rows not in
+ * the form's authoritative data, and adding missing CRDT rows (rare,
+ * happens when the row was DB-seeded outside the collab session).
+ *
+ * The flag is scoped per-tab via sessionStorage, so other peers' tabs
+ * never run the reconciler — preserving their in-flight edits.
+ *
+ * Phase B (server-side rename via the @rudderjs/sync Y.Doc seam) will
+ * extend this to other peers without requiring them to reload.
+ */
+
+const STORAGE_PREFIX = 'pilotiq.repeaterReconcile.'
+
+function storageKey(formId: string): string {
+  return STORAGE_PREFIX + formId
+}
+
+/**
+ * Called by `FormRenderer` on submit success. Records that this tab
+ * has just persisted the form, so the next mount of any Repeater /
+ * Builder under the same form runs the PK-switch reconciler. No-op
+ * when `formId` is empty or `sessionStorage` is unavailable (SSR).
+ */
+export function markSubmitForReconcile(formId: string): void {
+  if (!formId) return
+  if (typeof sessionStorage === 'undefined') return
+  try {
+    sessionStorage.setItem(storageKey(formId), '1')
+  } catch {
+    // Quota exceeded / disabled — silently skip. Reconciliation is
+    // an optimization, not a correctness requirement.
+  }
+}
+
+/**
+ * Called by `RepeaterInput` / `BuilderInput` on mount. Returns `true`
+ * iff the form was just submitted in this tab AND clears the flag so
+ * subsequent mounts no-op. Idempotent across multiple Repeater/Builder
+ * fields on the same form — the FIRST reader clears the flag, so
+ * siblings see `false`. To avoid that, both fields call this helper at
+ * the same mount tick — for v1 we accept the limitation: only the first
+ * Repeater on the form runs the reconciler; siblings don't.
+ *
+ * If a future need surfaces (multiple relationship-backed Repeaters on
+ * the same form), switch to a per-field flag keyed by `formId.fieldName`
+ * or have the FormRenderer dispatch a custom event instead.
+ */
+export function consumeReconcileFlag(formId: string): boolean {
+  if (!formId) return false
+  if (typeof sessionStorage === 'undefined') return false
+  try {
+    const v = sessionStorage.getItem(storageKey(formId))
+    if (v !== '1') return false
+    sessionStorage.removeItem(storageKey(formId))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export interface ReconcileInputs {
+  /** Current CRDT row id order (post-WS-sync). */
+  current:        readonly string[]
+  /** Authoritative row id list from server-rendered initialRows. */
+  authoritative:  readonly string[]
+}
+
+export interface ReconcilePlan {
+  /** Row ids present in CRDT but not in initialRows — orphan UUIDs. */
+  toRemove: string[]
+  /** Row ids present in initialRows but not in CRDT — DB rows not yet
+   *  in the room (rare; only happens when DB was seeded outside collab). */
+  toAdd:    string[]
+}
+
+/**
+ * Pure helper: compute the symmetric difference. Exported separately so
+ * unit tests don't need a DOM / sessionStorage shim to verify the
+ * reconciliation arithmetic.
+ */
+export function computeReconcilePlan({ current, authoritative }: ReconcileInputs): ReconcilePlan {
+  const currentSet = new Set(current)
+  const authSet    = new Set(authoritative)
+  const toRemove: string[] = []
+  const toAdd:    string[] = []
+  for (const id of current)       if (!authSet.has(id))    toRemove.push(id)
+  for (const id of authoritative) if (!currentSet.has(id)) toAdd.push(id)
+  return { toRemove, toAdd }
+}