fix: transform points through text-preserving children replacements

When the sync machine receives a block whose children share no keys
with the local ones (a remote mark toggle that split spans without
preserving keys), it replaces the children array wholesale with one
`set` op. `transformPoint`'s `set` case only handled `_key` renames
and `text` clamps, so points inside the replaced children kept
referencing dead keys and the selection clamped to the block start.
The reported symptom is the local caret jumping, but every
key-addressed position flowing through the op stream was equally
stranded: `rangeRefs`, `pointRefs`, remote presence selections, range
decorations.

`transformPoint` now remaps such points through their text offset
within the node: the offset into the old children (the op's `inverse`,
which the `_key` branch already reads) locates the same textual
position in the new children, via the shared walks in
`util.child-text-offset.ts`. The mapping is gated on the old and new
children carrying identical concatenated span text, the condition
that makes it lossless; a remote mark toggle preserves text by
definition. Points whose span key survives the replacement keep their
identity untouched; raw block-offset points and points deeper than a
direct child pass through untransformed; text-changing replacements
keep the previous behavior, offset mapping would be guesswork there.
Spans are detected structurally (`text` being a string) because
`transformPoint` is deliberately schema-free; a container's array
field may also be named `children` and hold blocks, which the text
requirement turns into a no-op by construction.

Fixing at the transform layer rather than around the sync machine's
`set` call (the approach explored in the earlier draft) means all
point consumers are covered by the same code and the correctness
precondition is enforced where the mapping happens. The sync machine
is untouched.

The browser scenario (ported from the earlier draft, verified failing
before the fix) pins the end-to-end behavior along with a guard
scenario for text-changing replacements; unit tests pin the
mechanics, mid-span remaps, boundary offsets, inline objects,
identity over offset, container-depth remaps, container blocks in
`children`-named fields, raw block-offset points, and the no-inverse
and foreign-block no-ops.

Author: christianhg

.changeset/remote-children-replacement-selection.md

@@ -0,0 +1,12 @@
+---
+'@portabletext/editor': patch
+---
+
+fix: preserve selections through remote children replacements that keep the text
+
+When a remote change replaces a block's children with re-keyed spans
+(a collaborator toggling a mark that splits spans), the local cursor
+and any other tracked selection no longer jump to the start of the
+block. As long as the block's text is unchanged, selections keep
+their exact textual position; replacements that change the text keep
+the previous behavior.

packages/editor/src/engine/point/transform-point.test.ts

@@ -217,4 +217,309 @@ describe(transformPoint.name, () => {
       offset: 0,
     })
   })
+
+  test('set children: remaps a point through a text-preserving replacement', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's1'}],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [
+        {_type: 'span', _key: 'n1', text: 'foo', marks: []},
+        {_type: 'span', _key: 'n2', text: 'bar', marks: ['strong']},
+        {_type: 'span', _key: 'n3', text: 'baz', marks: []},
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toEqual({
+      path: [{_key: 'b1'}, 'children', {_key: 'n2'}],
+      offset: 2,
+    })
+  })
+
+  test('set children: a boundary offset lands at the end of the earlier span', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's1'}],
+      offset: 3,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [
+        {_type: 'span', _key: 'n1', text: 'foo', marks: []},
+        {_type: 'span', _key: 'n2', text: 'barbaz', marks: []},
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toEqual({
+      path: [{_key: 'b1'}, 'children', {_key: 'n1'}],
+      offset: 3,
+    })
+  })
+
+  test('set children: inline objects occupy no text offset on either side', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's2'}],
+      offset: 1,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [
+        {_type: 'span', _key: 'n1', text: 'foo', marks: []},
+        {_type: 'stock-ticker', _key: 'n2'},
+        {_type: 'span', _key: 'n3', text: 'bar', marks: []},
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [
+          {_type: 'span', _key: 's1', text: 'foo', marks: []},
+          {_type: 'stock-ticker', _key: 'o1'},
+          {_type: 'span', _key: 's2', text: 'bar', marks: []},
+        ],
+      },
+    }
+    expect(transformPoint(point, op)).toEqual({
+      path: [{_key: 'b1'}, 'children', {_key: 'n3'}],
+      offset: 1,
+    })
+  })
+
+  test('set children: a surviving span keeps its identity over offset mapping', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's1'}],
+      offset: 2,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [
+        {_type: 'span', _key: 'n1', text: 'bar', marks: []},
+        {_type: 'span', _key: 's1', text: 'foo', marks: []},
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [
+          {_type: 'span', _key: 's1', text: 'foo', marks: []},
+          {_type: 'span', _key: 'o2', text: 'bar', marks: []},
+        ],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: a text-changing replacement leaves the point untransformed', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's1'}],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [{_type: 'span', _key: 'n1', text: 'hello', marks: []}],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: no inverse leaves the point untransformed', () => {
+    const point = {
+      path: [{_key: 'b1'}, 'children', {_key: 's1'}],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [{_type: 'span', _key: 'n1', text: 'foobarbaz', marks: []}],
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: a point in another block is untouched', () => {
+    const point = {
+      path: [{_key: 'b2'}, 'children', {_key: 's9'}],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [{_type: 'span', _key: 'n1', text: 'foobarbaz', marks: []}],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: container blocks in a field named `children` are not offset-mapped', () => {
+    // A container's array field may be named `children` and hold
+    // blocks. Blocks carry no `text`, so a point addressing a replaced
+    // block keeps the untransformed-point behavior.
+    const point = {
+      path: [{_key: 'callout1'}, 'children', {_key: 'block1'}],
+      offset: 0,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'callout1'}, 'children'],
+      value: [
+        {
+          _type: 'block',
+          _key: 'newBlock1',
+          children: [{_type: 'span', _key: 'n1', text: 'foo', marks: []}],
+        },
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'callout1'}, 'children'],
+        value: [
+          {
+            _type: 'block',
+            _key: 'block1',
+            children: [{_type: 'span', _key: 's1', text: 'foo', marks: []}],
+          },
+        ],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: a point deeper inside replaced container blocks is untouched', () => {
+    const point = {
+      path: [
+        {_key: 'callout1'},
+        'children',
+        {_key: 'block1'},
+        'children',
+        {_key: 's1'},
+      ],
+      offset: 2,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'callout1'}, 'children'],
+      value: [
+        {
+          _type: 'block',
+          _key: 'newBlock1',
+          children: [{_type: 'span', _key: 'n1', text: 'foo', marks: []}],
+        },
+      ],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'callout1'}, 'children'],
+        value: [
+          {
+            _type: 'block',
+            _key: 'block1',
+            children: [{_type: 'span', _key: 's1', text: 'foo', marks: []}],
+          },
+        ],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
+
+  test('set children: remaps span points of a text block nested in a container', () => {
+    const point = {
+      path: [
+        {_key: 'table1'},
+        'rows',
+        {_key: 'row1'},
+        'cells',
+        {_key: 'cell1'},
+        'content',
+        {_key: 'block1'},
+        'children',
+        {_key: 's1'},
+      ],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [
+        {_key: 'table1'},
+        'rows',
+        {_key: 'row1'},
+        'cells',
+        {_key: 'cell1'},
+        'content',
+        {_key: 'block1'},
+        'children',
+      ],
+      value: [
+        {_type: 'span', _key: 'n1', text: 'foo', marks: []},
+        {_type: 'span', _key: 'n2', text: 'bar', marks: ['strong']},
+        {_type: 'span', _key: 'n3', text: 'baz', marks: []},
+      ],
+      inverse: {
+        type: 'set',
+        path: [
+          {_key: 'table1'},
+          'rows',
+          {_key: 'row1'},
+          'cells',
+          {_key: 'cell1'},
+          'content',
+          {_key: 'block1'},
+          'children',
+        ],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toEqual({
+      path: [
+        {_key: 'table1'},
+        'rows',
+        {_key: 'row1'},
+        'cells',
+        {_key: 'cell1'},
+        'content',
+        {_key: 'block1'},
+        'children',
+        {_key: 'n2'},
+      ],
+      offset: 2,
+    })
+  })
+
+  test('set children: a raw block-offset point is never offset-mapped', () => {
+    // Selections can carry raw block-offset points ({path: [block],
+    // offset: N}) that resolve lazily. The children remap only applies
+    // to points addressing a direct child of the replaced array, so
+    // block-path points pass through untouched.
+    const point = {
+      path: [{_key: 'b1'}],
+      offset: 5,
+    }
+    const op: EngineOperation = {
+      type: 'set',
+      path: [{_key: 'b1'}, 'children'],
+      value: [{_type: 'span', _key: 'n1', text: 'foobarbaz', marks: []}],
+      inverse: {
+        type: 'set',
+        path: [{_key: 'b1'}, 'children'],
+        value: [{_type: 'span', _key: 's1', text: 'foobarbaz', marks: []}],
+      },
+    }
+    expect(transformPoint(point, op)).toBe(point)
+  })
 })