@sanity/sdk 2.16.0 → 2.18.0

package/src/document/reducers.test.ts

@@ -497,6 +497,9 @@ describe('transitionAppliedTransactionsToOutgoing', () => {
     expect(docState?.unverifiedRevisions).toBeDefined()
     expect(docState?.unverifiedRevisions?.['txn7']).toBeDefined()
     expect(docState?.unverifiedRevisions?.['txn7']?.previousRev).toEqual('rev1')
+    // the transaction ID is also tracked durably for remote-patches origin
+    // labeling, surviving unverified-revision pruning
+    expect(docState?.recentOwnTransactionIds).toEqual(['txn7'])
   })
 })
 
@@ -693,6 +696,129 @@ describe('applyRemoteDocument', () => {
     expect(newDocState?.unverifiedRevisions?.['txn10']).toBeUndefined()
   })
 
+  describe('fast-forward convergence of local', () => {
+    const docId = getDraftId(DocumentId('doc1'))
+    const otherDocId = getDraftId(DocumentId('doc2'))
+
+    const makeApplied = (overrides: Partial<AppliedTransaction>): AppliedTransaction => ({
+      transactionId: 'txnPending',
+      actions: [],
+      working: {},
+      previous: {},
+      base: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:06:30.000Z',
+      outgoingActions: [],
+      outgoingMutations: [],
+      ...overrides,
+    })
+
+    const makeState = (applied: AppliedTransaction[]): SyncTransactionState => ({
+      queued: [],
+      applied,
+      outgoing: undefined,
+      grants,
+      documentStates: {
+        [docId]: {
+          id: docId,
+          subscriptions: ['sub1'],
+          local: {...exampleDoc, _id: docId, foo: 'optimistic'},
+          remote: {...exampleDoc, _id: docId, foo: 'old'},
+          unverifiedRevisions: {
+            txn10: {
+              transactionId: 'txn10',
+              documentId: docId,
+              previousRev: 'revOld',
+              timestamp: '2025-02-06T00:06:00.000Z',
+            },
+          },
+        },
+      },
+    })
+
+    const remote: RemoteDocument = {
+      type: 'sync',
+      documentId: docId,
+      document: {...exampleDoc, _id: docId, foo: 'server-truth'},
+      revision: 'txn10',
+      previousRev: 'revOld',
+      timestamp: '2025-02-06T00:07:00.000Z',
+    }
+
+    it('converges local to the server document when nothing else is pending', () => {
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('converges local when pending work modifies only other documents', () => {
+      // a pending applied transaction on doc2 must not block convergence of
+      // doc1: nothing would ever revisit doc1's local otherwise
+      const otherDoc = {...exampleDoc, _id: otherDocId}
+      const pendingOnOtherDoc = makeApplied({
+        working: {[otherDocId]: {...otherDoc, _rev: 'txnPending'}},
+        previous: {[otherDocId]: otherDoc},
+        base: {[otherDocId]: otherDoc},
+        previousRevs: {[otherDocId]: 'txn0'},
+      })
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([pendingOnOtherDoc]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('converges local when pending work carries this document unmodified', () => {
+      // a draft edit carries the published document in its working set
+      // without changing it; presence alone must not block convergence
+      const thisDoc = {...exampleDoc, _id: docId}
+      const pendingCarryingUnmodified = makeApplied({
+        working: {
+          [docId]: thisDoc,
+          [otherDocId]: {...exampleDoc, _id: otherDocId, _rev: 'txnPending'},
+        },
+        previous: {[docId]: thisDoc, [otherDocId]: {...exampleDoc, _id: otherDocId}},
+        base: {[docId]: thisDoc, [otherDocId]: {...exampleDoc, _id: otherDocId}},
+        previousRevs: {[docId]: thisDoc._rev, [otherDocId]: 'txn0'},
+      })
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([pendingCarryingUnmodified]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('keeps the optimistic local when pending work modifies this document', () => {
+      const optimistic = {...exampleDoc, _id: docId, _rev: 'txnPending', foo: 'optimistic'}
+      const pendingOnThisDoc = makeApplied({
+        working: {[docId]: optimistic},
+        previous: {[docId]: {...exampleDoc, _id: docId}},
+        base: {[docId]: {...exampleDoc, _id: docId}},
+        previousRevs: {[docId]: 'txn0'},
+      })
+      const state = makeState([pendingOnThisDoc])
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(state, remote, events)
+      expect(newState.documentStates[docId]?.local).toBe(state.documentStates[docId]?.local)
+      expect(newState.documentStates[docId]?.remote).toEqual(remote.document)
+    })
+
+    it('keeps the optimistic local when a different in-flight transaction modifies this document', () => {
+      const optimistic = {...exampleDoc, _id: docId, _rev: 'txnOutgoing', foo: 'optimistic'}
+      const outgoing = {
+        ...makeApplied({
+          transactionId: 'txnOutgoing',
+          working: {[docId]: optimistic},
+          previous: {[docId]: {...exampleDoc, _id: docId}},
+          base: {[docId]: {...exampleDoc, _id: docId}},
+          previousRevs: {[docId]: 'txn0'},
+        }),
+        disableBatching: false,
+        batchedTransactionIds: ['txnOutgoing'],
+      }
+      const state = {...makeState([]), outgoing}
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(state, remote, events)
+      expect(newState.documentStates[docId]?.local).toBe(state.documentStates[docId]?.local)
+    })
+  })
+
   it('rebases local changes when no matching unverified revision is found', () => {
     // In this branch we simply let processActions rebase so that the local becomes the remote.
     const docId = getDraftId(DocumentId('doc1'))
@@ -794,6 +920,399 @@ describe('applyRemoteDocument', () => {
     expect(newDocState?.remote).toEqual(remote.document)
     expect(newDocState?.remoteRev).toBe('currentRev')
   })
+
+  describe('remote-patches events', () => {
+    const docId = getDraftId(DocumentId('doc1'))
+
+    function createInitialState(
+      unverifiedRevisions: NonNullable<
+        SyncTransactionState['documentStates'][string]
+      >['unverifiedRevisions'] = {},
+      recentOwnTransactionIds?: string[],
+    ): SyncTransactionState {
+      return {
+        queued: [],
+        applied: [],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: {...exampleDoc, _id: docId, foo: 'old'},
+            remote: {...exampleDoc, _id: docId, foo: 'old'},
+            unverifiedRevisions,
+            ...(recentOwnTransactionIds && {recentOwnTransactionIds}),
+          },
+        },
+      }
+    }
+
+    it('emits a remote-patches event with origin "remote" for foreign transactions', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnForeign',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:12:00.000Z',
+        mutations: [
+          {
+            patch: {
+              id: docId,
+              unset: ['blocks[_key=="a"].children[_key=="b"].marks[0]'],
+            },
+          },
+          {
+            patch: {
+              id: docId,
+              insert: {after: 'blocks[_key=="a"].markDefs[-1]', items: [{_key: 'link1'}]},
+            },
+          },
+        ],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+
+      expect(received).toEqual([
+        {
+          type: 'remote-patches',
+          documentId: docId,
+          transactionId: 'txnForeign',
+          previousRev: 'txn0',
+          timestamp: '2025-02-06T00:12:00.000Z',
+          origin: 'remote',
+          patches: [
+            {unset: ['blocks[_key=="a"].children[_key=="b"].marks[0]']},
+            {insert: {after: 'blocks[_key=="a"].markDefs[-1]', items: [{_key: 'link1'}]}},
+          ],
+        },
+      ])
+    })
+
+    it('emits origin "local" when the transaction is one of our own unverified revisions', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnOwn',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:13:00.000Z',
+        mutations: [{patch: {id: docId, set: {foo: 'new'}}}],
+      }
+
+      applyRemoteDocument(
+        createInitialState({
+          txnOwn: {
+            transactionId: 'txnOwn',
+            documentId: docId,
+            previousRev: 'txn0',
+            timestamp: '2025-02-06T00:13:00.000Z',
+          },
+        }),
+        remote,
+        events,
+      )
+
+      expect(received).toEqual([
+        {
+          type: 'remote-patches',
+          documentId: docId,
+          transactionId: 'txnOwn',
+          previousRev: 'txn0',
+          timestamp: '2025-02-06T00:13:00.000Z',
+          origin: 'local',
+          patches: [{set: {foo: 'new'}}],
+        },
+      ])
+    })
+
+    it('does not emit for sync events', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'sync',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'revSync',
+        timestamp: '2025-02-06T00:14:00.000Z',
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+      expect(received).toEqual([])
+    })
+
+    it('does not emit when the mutations contain no patches', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnCreate',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:15:00.000Z',
+        mutations: [{createOrReplace: {...exampleDoc, _id: docId, foo: 'new'}}],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+      expect(received).toEqual([])
+    })
+
+    it('excludes patches addressed to other documents in the same transaction', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnMulti',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:20:00.000Z',
+        mutations: [
+          {patch: {id: docId, set: {foo: 'new'}}},
+          {patch: {id: 'some-other-doc', set: {foo: 'other'}}},
+          {patch: {query: '*[_type == "author"]', set: {foo: 'queried'}}},
+        ],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+
+      expect(received).toHaveLength(1)
+      expect((received[0] as {patches: unknown}).patches).toEqual([{set: {foo: 'new'}}])
+    })
+
+    it('labels origin "local" via recentOwnTransactionIds when the unverified revision was pruned', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnPruned',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:21:00.000Z',
+        mutations: [{patch: {id: docId, set: {foo: 'new'}}}],
+      }
+
+      // a sync event racing the listener echo pruned the unverified revision,
+      // but the transaction ID is still tracked as one of our own
+      applyRemoteDocument(createInitialState({}, ['txnPruned']), remote, events)
+
+      expect(received).toHaveLength(1)
+      expect(received[0]).toMatchObject({
+        type: 'remote-patches',
+        transactionId: 'txnPruned',
+        origin: 'local',
+      })
+    })
+  })
+
+  describe('rebase with preserved operations', () => {
+    it('skips a preserved-operations transaction that fails to re-apply and emits rebase-error', () => {
+      const docId = getDraftId(DocumentId('doc1'))
+      const originalDoc: SanityDocument = {
+        ...exampleDoc,
+        _id: docId,
+        _rev: 'rev1',
+        title: 'The quick brown fox',
+      }
+      const locallyEditedDoc: SanityDocument = {
+        ...originalDoc,
+        title: 'The quick brown cat',
+        _rev: 'txnLocal',
+      }
+
+      const appliedTransaction: AppliedTransaction = {
+        transactionId: 'txnLocal',
+        actions: [
+          {
+            type: 'document.edit',
+            documentId: 'doc1',
+            documentType: 'author',
+            patches: [{diffMatchPatch: {title: '@@ -13,7 +13,7 @@\n own \n-fox\n+cat\n'}}],
+            preserveOperations: true,
+          },
+        ],
+        previous: {[docId]: originalDoc},
+        base: {[docId]: originalDoc},
+        working: {[docId]: locallyEditedDoc},
+        previousRevs: {[docId]: 'rev1'},
+        timestamp: '2025-02-06T00:16:00.000Z',
+        outgoingActions: [],
+        outgoingMutations: [],
+      }
+
+      const initialState: SyncTransactionState = {
+        queued: [],
+        applied: [appliedTransaction],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: locallyEditedDoc,
+            remote: originalDoc,
+            unverifiedRevisions: {},
+          },
+        },
+      }
+
+      // a foreign transaction replaced the title with a non-string, so our
+      // diffMatchPatch can no longer re-apply during the rebase
+      const remoteDoc: SanityDocument = {
+        ...originalDoc,
+        title: 42 as unknown as string,
+        _rev: 'txnForeign',
+      }
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: remoteDoc,
+        revision: 'txnForeign',
+        previousRev: 'rev1',
+        timestamp: '2025-02-06T00:17:00.000Z',
+        mutations: [{patch: {id: docId, set: {title: 42}}}],
+      }
+
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const newState = applyRemoteDocument(initialState, remote, events)
+
+      const rebaseErrors = received.filter((e) => e.type === 'rebase-error')
+      expect(rebaseErrors).toHaveLength(1)
+      expect(rebaseErrors[0]).toMatchObject({
+        type: 'rebase-error',
+        transactionId: 'txnLocal',
+        documentId: 'doc1',
+        message: expect.stringMatching(/Failed to apply patches to the working document/),
+      })
+
+      // the failing transaction is dropped and local converges to remote
+      expect(newState.applied).toEqual([])
+      expect(newState.documentStates[docId]?.local).toEqual(remoteDoc)
+      expect(newState.documentStates[docId]?.remote).toEqual(remoteDoc)
+    })
+
+    it('re-applies preserved keyed patches onto a diverged remote document', () => {
+      const docId = getDraftId(DocumentId('doc1'))
+      const originalDoc: SanityDocument = {
+        ...exampleDoc,
+        _id: docId,
+        _rev: 'rev1',
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'b', value: 'second'},
+        ],
+      }
+      const locallyEditedDoc: SanityDocument = {
+        ...originalDoc,
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'c', value: 'in between'},
+          {_key: 'b', value: 'second'},
+        ],
+        _rev: 'txnLocal',
+      }
+
+      const appliedTransaction: AppliedTransaction = {
+        transactionId: 'txnLocal',
+        actions: [
+          {
+            type: 'document.edit',
+            documentId: 'doc1',
+            documentType: 'author',
+            patches: [
+              {insert: {after: 'items[_key=="a"]', items: [{_key: 'c', value: 'in between'}]}},
+            ],
+            preserveOperations: true,
+          },
+        ],
+        previous: {[docId]: originalDoc},
+        base: {[docId]: originalDoc},
+        working: {[docId]: locallyEditedDoc},
+        previousRevs: {[docId]: 'rev1'},
+        timestamp: '2025-02-06T00:18:00.000Z',
+        outgoingActions: [],
+        outgoingMutations: [],
+      }
+
+      const initialState: SyncTransactionState = {
+        queued: [],
+        applied: [appliedTransaction],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: locallyEditedDoc,
+            remote: originalDoc,
+            unverifiedRevisions: {},
+          },
+        },
+      }
+
+      // a foreign transaction appended a new item concurrently
+      const remoteDoc: SanityDocument = {
+        ...originalDoc,
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'b', value: 'second'},
+          {_key: 'd', value: 'appended remotely'},
+        ],
+        _rev: 'txnForeign',
+      }
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: remoteDoc,
+        revision: 'txnForeign',
+        previousRev: 'rev1',
+        timestamp: '2025-02-06T00:19:00.000Z',
+        mutations: [
+          {
+            patch: {
+              id: docId,
+              insert: {after: 'items[-1]', items: [{_key: 'd', value: 'appended remotely'}]},
+            },
+          },
+        ],
+      }
+
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(initialState, remote, events)
+
+      // both edits survive: our keyed insert re-anchors after item "a" while
+      // the remote append is preserved
+      expect(newState.documentStates[docId]?.local?.['items']).toEqual([
+        {_key: 'a', value: 'first'},
+        {_key: 'c', value: 'in between'},
+        {_key: 'b', value: 'second'},
+        {_key: 'd', value: 'appended remotely'},
+      ])
+      expect(newState.applied).toHaveLength(1)
+    })
+  })
 })
 
 describe('addSubscriptionIdToDocument', () => {

package/src/document/reducers.ts

@@ -5,7 +5,7 @@ import {type DocumentHandle} from '../config/sanityConfig'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
-import {omitProperty} from '../utils/object'
+import {isDeepEqual, omitProperty} from '../utils/object'
 import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {type Action} from './actions'
 import {DOCUMENT_STATE_CLEAR_DELAY} from './documentConstants'
@@ -17,6 +17,13 @@ import {type DocumentSet} from './processMutations'
 
 const EMPTY_REVISIONS: NonNullable<Required<DocumentState['unverifiedRevisions']>> = {}
 
+/**
+ * How many of this client's own transaction IDs to remember per document for
+ * `remote-patches` origin labeling. Sized to comfortably outlast the window
+ * between submitting a transaction and observing its listener echo.
+ */
+const MAX_RECENT_OWN_TRANSACTION_IDS = 50
+
 export type SyncTransactionState = Pick<
   DocumentStoreState,
   'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants' | 'identity'
@@ -364,6 +371,15 @@ export function transitionAppliedTransactionsToOutgoing(
             // add unverified revision
             [transactionId]: {documentId, previousRev, transactionId, timestamp},
           },
+          // also track the transaction ID durably (unverified revisions can be
+          // pruned by sync events before the listener echo arrives) so
+          // `remote-patches` events label our own transactions correctly
+          recentOwnTransactionIds: [
+            ...(documentState.recentOwnTransactionIds ?? []).slice(
+              -(MAX_RECENT_OWN_TRANSACTION_IDS - 1),
+            ),
+            transactionId,
+          ],
         }
 
         return acc
@@ -433,9 +449,29 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
   }
 }
 
+/**
+ * Extracts the patch operations addressed to the given document from a set of
+ * raw listener mutations, stripping the mutation-level `id` addressing so the
+ * patches are rooted at the document. A transaction can carry mutations for
+ * other documents, so anything not explicitly id-addressed to this document
+ * (including query-addressed patches) is dropped.
+ */
+function extractPatchOperations(
+  mutations: Mutation[] | undefined,
+  documentId: string,
+): PatchOperations[] {
+  if (!mutations) return []
+  return mutations.flatMap((mutation) => {
+    if (!('patch' in mutation) || !mutation.patch) return []
+    const {id, ...operations} = mutation.patch as PatchOperations & {id?: string}
+    if (id !== documentId) return []
+    return [operations]
+  })
+}
+
 export function applyRemoteDocument(
   prev: SyncTransactionState,
-  {document, documentId, previousRev, revision, timestamp, type}: RemoteDocument,
+  {document, documentId, previousRev, revision, timestamp, type, mutations}: RemoteDocument,
   events: DocumentStoreState['events'],
 ): SyncTransactionState {
   if (!prev.grants) return prev
@@ -455,6 +491,31 @@ export function applyRemoteDocument(
     unverifiedRevisions = omitProperty(prevUnverifiedRevisions, revision)
   }
 
+  // surface the operational patches from this transaction before they are
+  // collapsed into the whole-document snapshot below. consumers that keep
+  // their own state (e.g. collaborative text editors) rely on these to apply
+  // remote changes without re-diffing document snapshots
+  if (type === 'mutation' && revision) {
+    const patches = extractPatchOperations(mutations, documentId)
+    if (patches.length) {
+      // `unverifiedRevisions` alone isn't a reliable origin marker: a sync
+      // event can prune an in-flight transaction's entry before its listener
+      // echo arrives. `recentOwnTransactionIds` survives that race
+      const isOwnTransaction =
+        Boolean(revisionToVerify) ||
+        (prevDocState.recentOwnTransactionIds?.includes(revision) ?? false)
+      events.next({
+        type: 'remote-patches',
+        documentId,
+        transactionId: revision,
+        previousRev,
+        timestamp,
+        patches,
+        origin: isOwnTransaction ? 'local' : 'remote',
+      })
+    }
+  }
+
   // if this remote document is from a `'sync'` event (meaning that the whole
   // thing was just fetched and not re-created from mutations)
   if (type === 'sync') {
@@ -473,6 +534,34 @@ export function applyRemoteDocument(
   // matches the previous revision we expected, we can "fast-forward" and skip
   // rebasing local changes on top of this new base
   if (revisionToVerify && revisionToVerify.previousRev === previousRev) {
+    // even on a clean fast-forward, the server's result can differ from our
+    // optimistic prediction: a publish derives the published content from the
+    // server's copy of the draft, which may carry concurrent edits our
+    // prediction never saw. once nothing else is pending locally for this
+    // document (no applied transaction and no in-flight transaction, other
+    // than the one this event just confirmed, modifies it), converge `local`
+    // to the server's document. while local work that modifies this document
+    // is pending, keep the optimistic `local` so those changes stay visible;
+    // that work's own echo (or rebase) recomputes `local` later.
+    //
+    // "modifies" matters: pending work on other documents must not block
+    // convergence here (nothing would ever revisit this document's `local`),
+    // and a pending draft edit carries the published document in its working
+    // set without changing it, so a presence check would block published-doc
+    // convergence whenever a draft edit is pending. this is the same
+    // modified-test `transitionAppliedTransactionsToOutgoing` uses
+    const modifiesDocument = (transaction: AppliedTransaction) =>
+      transaction.working[documentId]?._rev !== transaction.previousRevs[documentId]
+    const nothingElsePending =
+      !prev.applied.some(modifiesDocument) &&
+      (!prev.outgoing ||
+        prev.outgoing.transactionId === revision ||
+        !modifiesDocument(prev.outgoing))
+    const local =
+      nothingElsePending && !isDeepEqual(prevDocState.local, document)
+        ? document
+        : prevDocState.local
+
     return {
       ...prev,
       documentStates: {
@@ -481,6 +570,7 @@ export function applyRemoteDocument(
           ...prevDocState,
           remote: document,
           remoteRev: revision,
+          local,
           unverifiedRevisions,
         },
       },
@@ -531,6 +621,12 @@ export function applyRemoteDocument(
     }
   }
 
+  // when the recompute lands on a value deep-equal to the current local
+  // (the common case for echoes of our own transactions), keep the previous
+  // reference so subscribers don't re-render for an identical value
+  const nextLocal = working[documentId]
+  const local = isDeepEqual(prevDocState.local, nextLocal) ? prevDocState.local : nextLocal
+
   return {
     ...prev,
     applied: nextApplied,
@@ -540,7 +636,7 @@ export function applyRemoteDocument(
         ...prevDocState,
         remote: document,
         remoteRev: revision,
-        local: working[documentId],
+        local,
         unverifiedRevisions,
       },
     },