fix(plugin-sdk-value): guard keyed markDefs unsets against store-referenced definitions

An upcoming editor change emits normalization's unused-definition
prunes as item-keyed `unset` patches instead of whole-array sets.
`toMergeableMarkDefsPatches` only decomposes whole-array sets, so
those unsets would pass through without the referenced-keys guard: a
diverged client (its span `marks` overwritten by the other client's
flush, its own definition now locally unused) would prune a definition
the store's spans still reference, orphaning the other client's
annotation at the server.

Keyed `markDefs` unsets now go through the same store-side
referenced-keys check as decomposed sets and are dropped while the
store's spans reference the definition. A dropped prune leaves an
unused definition behind at worst; normalization in a later converged
session removes it for real. Against the current editor's emission
(whole-array sets only) the guard is inert; it ships ahead so a
consumer upgrading the editor without upgrading this plugin is never
exposed.

Author: christianhg

.changeset/guard-keyed-markdefs-unsets.md

@@ -0,0 +1,7 @@
+---
+'@portabletext/plugin-sdk-value': patch
+---
+
+fix: guard outgoing keyed `markDefs` unsets against store-referenced definitions
+
+An upcoming `@portabletext/editor` release prunes unused annotation definitions as item-keyed `unset` patches instead of whole-array sets. A client that has diverged from the store can prune a definition the store's spans still reference, which would orphan another client's annotation. Outgoing keyed `markDefs` unsets are now dropped while the store's spans reference the definition, mirroring the existing guard on decomposed whole-array sets; at worst an unused definition lingers until a later converged session prunes it. Against current editor releases the guard is inert.

packages/plugin-sdk-value/src/plugin.sdk-value.test.ts

@@ -326,6 +326,39 @@ describe(toMergeableMarkDefsPatches.name, () => {
     },
   ] as unknown as PortableTextBlock[]
 
+  test('keyed unsets of store-referenced definitions are dropped', () => {
+    expect(
+      toMergeableMarkDefsPatches(
+        [
+          {
+            type: 'unset',
+            path: [{_key: 'b1'}, 'markDefs', {_key: 'm1'}],
+          },
+        ],
+        () => storeValue,
+      ),
+    ).toEqual([])
+  })
+
+  test('keyed unsets of unreferenced definitions pass through', () => {
+    expect(
+      toMergeableMarkDefsPatches(
+        [
+          {
+            type: 'unset',
+            path: [{_key: 'b1'}, 'markDefs', {_key: 'm2'}],
+          },
+        ],
+        () => storeValue,
+      ),
+    ).toEqual([
+      {
+        type: 'unset',
+        path: [{_key: 'b1'}, 'markDefs', {_key: 'm2'}],
+      },
+    ])
+  })
+
   test('new definitions become inserts', () => {
     expect(
       toMergeableMarkDefsPatches(

packages/plugin-sdk-value/src/plugin.sdk-value.tsx

@@ -399,6 +399,51 @@ export function toMergeableMarkDefsPatches(
   getCurrentValue: () => PortableTextBlock[] | null | undefined,
 ): PtePatch[] {
   return patches.flatMap((patch): PtePatch[] => {
+    if (
+      patch.type === 'unset' &&
+      patch.path.length >= 2 &&
+      patch.path.at(-2) === 'markDefs'
+    ) {
+      // The editor emits item-keyed `markDefs` unsets (normalization
+      // pruning definitions its spans no longer reference). The same
+      // referenced-keys guard as below applies: a diverged client prunes
+      // definitions the store's spans still reference, which would
+      // orphan the other client's marks. Dropping the unset leaves an
+      // unused definition behind at worst; normalization on a later
+      // converged session prunes it for real.
+      const keySegment = patch.path.at(-1)
+      const definitionKey =
+        typeof keySegment === 'object' &&
+        keySegment !== null &&
+        '_key' in keySegment
+          ? keySegment._key
+          : undefined
+
+      if (definitionKey !== undefined) {
+        const currentValue = getCurrentValue()
+        const storeBlock = currentValue
+          ? getValueAtPath(
+              currentValue as unknown as JSONValue,
+              patch.path.slice(0, -2),
+            )
+          : undefined
+
+        if (typeof storeBlock === 'object' && storeBlock !== null) {
+          const referencedKeys = new Set(
+            (
+              (storeBlock as {children?: Array<{marks?: string[]}>}).children ??
+              []
+            ).flatMap((child) => child.marks ?? []),
+          )
+          if (referencedKeys.has(definitionKey)) {
+            return []
+          }
+        }
+      }
+
+      return [patch]
+    }
+
     if (
       patch.type !== 'set' ||
       patch.path.at(-1) !== 'markDefs' ||