@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.1

package/src/document/documentStore.test.ts

@@ -1,8 +1,10 @@
 import {
   type BaseActionOptions,
+  type BaseMutationOptions,
   type FilteredResponseQueryOptions,
   type ListenEvent,
   type MultipleActionResult,
+  type MultipleMutationResult,
   type MutationEvent,
   type RawQueryResponse,
   type ResponseQueryOptions,
@@ -12,6 +14,7 @@ import {
   type WelcomeEvent,
 } from '@sanity/client'
 import {diffValue} from '@sanity/diff-patch'
+import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
 import {type Mutation, type SanityDocument} from '@sanity/types'
 import {evaluate, parse} from 'groq-js'
 import {delay, first, firstValueFrom, from, Observable, of, ReplaySubject, Subject} from 'rxjs'
@@ -21,7 +24,6 @@ import {getClientState} from '../client/clientStore'
 import {createDocumentHandle} from '../config/handles'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getDraftId, getPublishedId} from '../utils/ids'
 import {
   createDocument,
   deleteDocument,
@@ -39,7 +41,12 @@ import {
   resolvePermissions,
   subscribeDocumentEvents,
 } from './documentStore'
-import {type ActionErrorEvent, type TransactionRevertedEvent} from './events'
+import {
+  type ActionErrorEvent,
+  type DocumentRemotePatchesEvent,
+  type TransactionRevertedEvent,
+} from './events'
+import {DEFAULT_MAX_BUFFER_SIZE} from './listen'
 import {type DatasetAcl} from './permissions'
 import {type DocumentSet, processMutations} from './processMutations'
 import {type HttpAction} from './reducers'
@@ -51,23 +58,42 @@ interface TestDocument extends SanityDocument {
   title?: string
 }
 
+// Scope the TestDocument type to the project/datasets used in tests
+type AllTestSchemaTypes = TestDocument
+
+// Augment the 'groq' module
+declare module 'groq' {
+  interface SanitySchemas {
+    default: AllTestSchemaTypes
+  }
+}
+
 let instance: SanityInstance
+let instance1: SanityInstance
+let instance2: SanityInstance
 
-// bindActionByResource should ensure docs from different resources are isolated
 const resource = {projectId: 'p', dataset: 'd'}
-const resource1 = {projectId: 'p', dataset: 'd1'}
-const resource2 = {projectId: 'p', dataset: 'd2'}
+const source1 = {projectId: 'p', dataset: 'd1'}
+const source2 = {projectId: 'p', dataset: 'd2'}
 
 beforeEach(() => {
-  instance = createSanityInstance()
+  instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  // test uses two instances that share the same in-memory dataset, but separate
+  // store instances. in real scenarios, this would be separate machines but with
+  // the same project + dataset
+  instance1 = createSanityInstance({projectId: 'p', dataset: 'd1'})
+  instance2 = createSanityInstance({projectId: 'p', dataset: 'd2'})
 })
 
 afterEach(() => {
   instance?.dispose()
+  instance1?.dispose()
+  instance2?.dispose()
 })
 
 it('creates, edits, and publishes a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-single', documentType: 'article', resource})
+  const documentId = DocumentId('doc-single')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   const documentState = getDocumentState<TestDocument>(instance, doc)
 
   // Initially the document is undefined
@@ -80,10 +106,10 @@ it('creates, edits, and publishes a document', async () => {
     actions: [createDocument(doc)],
     resource,
   })
-  expect(appeared).toContain(getDraftId(doc.documentId))
+  expect(appeared).toContain(getDraftId(documentId))
 
   let currentDoc = documentState.getCurrent()
-  expect(currentDoc?._id).toEqual(getDraftId(doc.documentId))
+  expect(currentDoc?._id).toEqual(getDraftId(documentId))
 
   // Edit the document – add a title
   await applyDocumentActions(instance, {
@@ -101,16 +127,13 @@ it('creates, edits, and publishes a document', async () => {
   await submitted()
   currentDoc = documentState.getCurrent()
 
-  expect(currentDoc).toMatchObject({_id: doc.documentId, _rev: transactionId})
+  expect(currentDoc).toMatchObject({_id: documentId, _rev: transactionId})
   unsubscribe()
 })
 
 it('creates a document with initial values', async () => {
-  const doc = createDocumentHandle({
-    documentId: 'doc-with-initial',
-    documentType: 'article',
-    resource,
-  })
+  const documentId = DocumentId('doc-with-initial')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   const documentState = getDocumentState<TestDocument>(instance, doc)
 
   expect(documentState.getCurrent()).toBeUndefined()
@@ -128,10 +151,10 @@ it('creates a document with initial values', async () => {
     ],
     resource,
   })
-  expect(appeared).toContain(getDraftId(doc.documentId))
+  expect(appeared).toContain(getDraftId(documentId))
 
   const currentDoc = documentState.getCurrent()
-  expect(currentDoc?._id).toEqual(getDraftId(doc.documentId))
+  expect(currentDoc?._id).toEqual(getDraftId(documentId))
   expect(currentDoc?.title).toEqual('Article with Initial Values')
   expect(currentDoc?.['author']).toEqual('Jane Doe')
   expect(currentDoc?.['count']).toEqual(42)
@@ -140,7 +163,8 @@ it('creates a document with initial values', async () => {
 })
 
 it('edits existing documents', async () => {
-  const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article', resource})
+  const documentId = DocumentId('existing-doc')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   const state = getDocumentState<TestDocument>(instance, doc)
 
   // not subscribed yet so the value is undefined
@@ -152,7 +176,7 @@ it('edits existing documents', async () => {
   await firstValueFrom(state.observable.pipe(first((i) => !!i)))
 
   expect(state.getCurrent()).toMatchObject({
-    _id: getDraftId(doc.documentId),
+    _id: getDraftId(documentId),
     title: 'existing doc',
   })
 
@@ -161,7 +185,7 @@ it('edits existing documents', async () => {
     resource,
   })
   expect(state.getCurrent()).toMatchObject({
-    _id: getDraftId(doc.documentId),
+    _id: getDraftId(documentId),
     title: 'updated title',
   })
 
@@ -169,33 +193,31 @@ it('edits existing documents', async () => {
 })
 
 it('sets optimistic changes synchronously', async () => {
-  const doc1 = createDocumentHandle({
-    documentId: 'optimistic',
+  const doc1 = {
+    documentId: DocumentId('optimistic'),
     documentType: 'article',
-    resource: resource1,
-  })
-  const doc2 = createDocumentHandle({
-    documentId: 'optimistic',
+  }
+  const doc2 = {
+    documentId: DocumentId('optimistic'),
     documentType: 'article',
-    resource: resource2,
-  })
+  }
 
-  const state1 = getDocumentState<TestDocument>(instance, doc1)
-  const state2 = getDocumentState<TestDocument>(instance, doc2)
+  const state1 = getDocumentState(instance1, doc1)
+  const state2 = getDocumentState(instance2, doc2)
 
   const unsubscribe1 = state1.subscribe()
   const unsubscribe2 = state2.subscribe()
 
   // wait until the value is primed in the store
-  await resolveDocument(instance, doc1)
+  await resolveDocument(instance1, doc1)
 
   // then the actions are synchronous
   expect(state1.getCurrent()).toBeNull()
-  applyDocumentActions(instance, {actions: [createDocument(doc1)], resource: resource1})
+  applyDocumentActions(instance1, {actions: [createDocument(doc1)], resource: source1})
   expect(state1.getCurrent()).toMatchObject({_id: getDraftId(doc1.documentId)})
-  const actionResult1Promise = applyDocumentActions(instance, {
+  const actionResult1Promise = applyDocumentActions(instance1, {
     actions: [editDocument(doc1, {set: {title: 'initial title'}})],
-    resource: resource1,
+    resource: source1,
   })
   expect(state1.getCurrent()?.title).toBe('initial title')
 
@@ -214,9 +236,9 @@ it('sets optimistic changes synchronously', async () => {
   expect(state2.getCurrent()?.title).toBe('initial title')
 
   // synchronous for state 2
-  const actionResult2Promise = applyDocumentActions(instance, {
+  const actionResult2Promise = applyDocumentActions(instance2, {
     actions: [editDocument(doc2, {set: {title: 'updated title'}})],
-    resource: resource2,
+    resource: source2,
   })
   expect(state2.getCurrent()?.title).toBe('updated title')
   // async for state 1
@@ -231,37 +253,27 @@ it('sets optimistic changes synchronously', async () => {
 })
 
 it('propagates changes between two instances', async () => {
-  const doc1 = createDocumentHandle({
-    documentId: 'doc-collab',
-    documentType: 'article',
-    resource: resource1,
-  })
-  const doc2 = createDocumentHandle({
-    documentId: 'doc-collab',
-    documentType: 'article',
-    resource: resource2,
-  })
-  const state1 = getDocumentState<TestDocument>(instance, doc1)
-  const state2 = getDocumentState<TestDocument>(instance, doc2)
+  const doc = createDocumentHandle({documentId: 'doc-collab', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
 
   const state1Unsubscribe = state1.subscribe()
   const state2Unsubscribe = state2.subscribe()
 
-  // Create the document from the store instance.
-  await applyDocumentActions(instance, {
-    actions: [createDocument(doc1)],
-    resource: resource1,
-  }).then((r) => r.submitted())
+  // Create the document from instance1.
+  await applyDocumentActions(instance1, {actions: [createDocument(doc)], resource: source1}).then(
+    (r) => r.submitted(),
+  )
 
-  const docState1 = state1.getCurrent()
-  const docState2 = state2.getCurrent()
-  expect(docState1?._id).toEqual(getDraftId(doc1.documentId))
-  expect(docState2?._id).toEqual(getDraftId(doc1.documentId))
+  const doc1 = state1.getCurrent()
+  const doc2 = state2.getCurrent()
+  expect(doc1?._id).toEqual(getDraftId(DocumentId(doc.documentId)))
+  expect(doc2?._id).toEqual(getDraftId(DocumentId(doc.documentId)))
 
-  // Now, edit the document from the other store instance.
-  await applyDocumentActions(instance, {
-    actions: [editDocument(doc2, {set: {title: 'Hello world!'}})],
-    resource: resource2,
+  // Now, edit the document from instance2.
+  await applyDocumentActions(instance2, {
+    actions: [editDocument(doc, {set: {title: 'Hello world!'}})],
+    resource: source2,
   }).then((r) => r.submitted())
 
   const updated1 = state1.getCurrent()
@@ -273,44 +285,95 @@ it('propagates changes between two instances', async () => {
   state2Unsubscribe()
 })
 
-it('handles concurrent edits and resolves conflicts', async () => {
-  const doc1 = createDocumentHandle({
-    documentId: 'doc-concurrent',
-    documentType: 'article',
-    resource: resource1,
+it('emits remote-patches events distinguishing own and foreign transactions', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-remote-patches', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
+
+  const state1Unsubscribe = state1.subscribe()
+  const state2Unsubscribe = state2.subscribe()
+
+  await applyDocumentActions(instance1, {actions: [createDocument(doc)], resource: source1}).then(
+    (r) => r.submitted(),
+  )
+
+  const events1: DocumentRemotePatchesEvent[] = []
+  const events2: DocumentRemotePatchesEvent[] = []
+  const unsubscribeEvents1 = subscribeDocumentEvents(instance1, {
+    resource: source1,
+    eventHandler: (e) => {
+      if (e.type === 'remote-patches') events1.push(e)
+    },
   })
-  const doc2 = createDocumentHandle({
-    documentId: 'doc-concurrent',
-    documentType: 'article',
-    resource: resource2,
+  const unsubscribeEvents2 = subscribeDocumentEvents(instance2, {
+    resource: source2,
+    eventHandler: (e) => {
+      if (e.type === 'remote-patches') events2.push(e)
+    },
   })
-  const state1 = getDocumentState<TestDocument>(instance, doc1)
-  const state2 = getDocumentState<TestDocument>(instance, doc2)
+
+  // edit from instance2: an own transaction for instance2, a foreign one for instance1
+  const result = await applyDocumentActions(instance2, {
+    actions: [editDocument(doc, {set: {title: 'Hello world!'}})],
+    resource: source2,
+  }).then((r) => r.submitted())
+
+  const draftId = getDraftId(DocumentId(doc.documentId))
+
+  expect(events1).toHaveLength(1)
+  expect(events1[0]).toMatchObject({
+    type: 'remote-patches',
+    documentId: draftId,
+    transactionId: result.transactionId,
+    origin: 'remote',
+  })
+  expect(events1[0].patches).toEqual(
+    expect.arrayContaining([{set: expect.objectContaining({title: 'Hello world!'})}]),
+  )
+
+  expect(events2).toHaveLength(1)
+  expect(events2[0]).toMatchObject({
+    type: 'remote-patches',
+    documentId: draftId,
+    transactionId: result.transactionId,
+    origin: 'local',
+  })
+
+  unsubscribeEvents1()
+  unsubscribeEvents2()
+  state1Unsubscribe()
+  state2Unsubscribe()
+})
+
+it('handles concurrent edits and resolves conflicts', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-concurrent', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
 
   const state1Unsubscribe = state1.subscribe()
   const state2Unsubscribe = state2.subscribe()
 
-  const oneOffInstance = createSanityInstance()
+  const oneOffInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
 
   // Create the initial document from a one-off instance.
   await applyDocumentActions(oneOffInstance, {
     actions: [
-      createDocument(doc1),
-      editDocument(doc1, {set: {title: 'The quick brown fox jumps over the lazy dog'}}),
+      createDocument(doc),
+      editDocument(doc, {set: {title: 'The quick brown fox jumps over the lazy dog'}}),
     ],
     resource,
   }).then((res) => res.submitted())
 
-  // Both store instances now issue an edit simultaneously.
-  const p1 = applyDocumentActions(instance, {
-    actions: [editDocument(doc1, {set: {title: 'The quick brown fox jumps over the lazy cat'}})],
-    resource: resource1,
+  // Both instances now issue an edit simultaneously.
+  const p1 = applyDocumentActions(instance1, {
+    actions: [editDocument(doc, {set: {title: 'The quick brown fox jumps over the lazy cat'}})],
+    resource: source1,
   }).then((r) => r.submitted())
-  const p2 = applyDocumentActions(instance, {
+  const p2 = applyDocumentActions(instance2, {
     actions: [
-      editDocument(doc2, {set: {title: 'The quick brown elephant jumps over the lazy dog'}}),
+      editDocument(doc, {set: {title: 'The quick brown elephant jumps over the lazy dog'}}),
     ],
-    resource: resource2,
+    resource: source2,
   }).then((r) => r.submitted())
 
   // Wait for both actions to complete (or reject).
@@ -326,8 +389,76 @@ it('handles concurrent edits and resolves conflicts', async () => {
   oneOffInstance.dispose()
 })
 
+it('interleaves concurrent keyed-array edits when operations are preserved', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-preserve-ops', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
+
+  const state1Unsubscribe = state1.subscribe()
+  const state2Unsubscribe = state2.subscribe()
+
+  const oneOffInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  await applyDocumentActions(oneOffInstance, {
+    actions: [
+      createDocument(doc),
+      editDocument(doc, {
+        set: {
+          items: [
+            {_key: 'a', value: 'first'},
+            {_key: 'b', value: 'second'},
+          ],
+        },
+      }),
+    ],
+    resource,
+  }).then((r) => r.submitted())
+
+  // both instances insert into the same keyed array simultaneously, each
+  // preserving their operational patches instead of re-diffing snapshots
+  const p1 = applyDocumentActions(instance1, {
+    actions: [
+      editDocument(
+        doc,
+        {insert: {after: 'items[_key=="a"]', items: [{_key: 'c', value: 'from instance1'}]}},
+        {preserveOperations: true},
+      ),
+    ],
+    resource: source1,
+  }).then((r) => r.submitted())
+  const p2 = applyDocumentActions(instance2, {
+    actions: [
+      editDocument(
+        doc,
+        {insert: {after: 'items[_key=="b"]', items: [{_key: 'd', value: 'from instance2'}]}},
+        {preserveOperations: true},
+      ),
+    ],
+    resource: source2,
+  }).then((r) => r.submitted())
+
+  await Promise.allSettled([p1, p2])
+
+  const finalDoc1 = state1.getCurrent()
+  const finalDoc2 = state2.getCurrent()
+
+  // neither edit overwrote the other: both keyed inserts landed and both
+  // instances converged on the same interleaved result
+  expect(finalDoc1?.['items']).toEqual(finalDoc2?.['items'])
+  expect(finalDoc1?.['items']).toEqual([
+    {_key: 'a', value: 'first'},
+    {_key: 'c', value: 'from instance1'},
+    {_key: 'b', value: 'second'},
+    {_key: 'd', value: 'from instance2'},
+  ])
+
+  state1Unsubscribe()
+  state2Unsubscribe()
+  oneOffInstance.dispose()
+})
+
 it('unpublishes and discards a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-pub-unpub', documentType: 'article', resource})
+  const documentId = DocumentId('doc-pub-unpub')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   const documentState = getDocumentState<TestDocument>(instance, doc)
   const unsubscribe = documentState.subscribe()
 
@@ -339,7 +470,7 @@ it('unpublishes and discards a document', async () => {
   })
   const publishedDoc = documentState.getCurrent()
   expect(publishedDoc).toMatchObject({
-    _id: getPublishedId(doc.documentId),
+    _id: getPublishedId(documentId),
     _rev: afterPublish.transactionId,
   })
 
@@ -347,7 +478,7 @@ it('unpublishes and discards a document', async () => {
   await applyDocumentActions(instance, {actions: [unpublishDocument(doc)], resource})
   const afterUnpublish = documentState.getCurrent()
   // In our mock implementation the _id remains the same but the published copy is removed.
-  expect(afterUnpublish?._id).toEqual(getDraftId(doc.documentId))
+  expect(afterUnpublish?._id).toEqual(getDraftId(documentId))
 
   // Discard the draft (which deletes the draft version).
   await applyDocumentActions(instance, {actions: [discardDocument(doc)], resource})
@@ -358,9 +489,10 @@ it('unpublishes and discards a document', async () => {
 })
 
 it('deletes a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-delete', documentType: 'article', resource})
+  const documentId = DocumentId('doc-delete')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
-  const documentState = getDocumentState<TestDocument>(instance, doc)
+  const documentState = getDocumentState(instance, doc)
   const unsubscribe = documentState.subscribe()
 
   await applyDocumentActions(instance, {
@@ -379,7 +511,8 @@ it('deletes a document', async () => {
 })
 
 it('cleans up document state when there are no subscribers', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-cleanup', documentType: 'article', resource})
+  const documentId = DocumentId('doc-cleanup')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   const documentState = getDocumentState<TestDocument>(instance, doc)
 
   // Subscribe to the document state.
@@ -397,14 +530,14 @@ it('cleans up document state when there are no subscribers', async () => {
   await new Promise((resolve) => setTimeout(resolve, 30))
 
   // When a new subscriber is created, if the state was cleared it should return undefined.
-  const newDocumentState = getDocumentState<TestDocument>(instance, doc)
+  const newDocumentState = getDocumentState(instance, doc)
   expect(newDocumentState.getCurrent()).toBeUndefined()
 })
 
 it('fetches documents if there are no active subscriptions for the actions applied', async () => {
-  const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article', resource})
+  const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article'})
 
-  const {getCurrent} = getDocumentState<TestDocument>(instance, doc)
+  const {getCurrent} = getDocumentState(instance, doc)
   expect(getCurrent()).toBeUndefined()
   expect(getDocumentSyncStatus(instance, doc).getCurrent()).toBeUndefined()
 
@@ -457,13 +590,9 @@ it('fetches documents if there are no active subscriptions for the actions appli
 })
 
 it('batches edit transaction into one outgoing transaction', async () => {
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
 
-  const unsubscribe = getDocumentState<TestDocument>(instance, doc).subscribe()
+  const unsubscribe = getDocumentState(instance, doc).subscribe()
 
   // this creates its own transaction
   applyDocumentActions(instance, {actions: [createDocument(doc)], resource})
@@ -490,12 +619,54 @@ it('batches edit transaction into one outgoing transaction', async () => {
   unsubscribe()
 })
 
-it('provides the consistency status via `getDocumentSyncStatus`', async () => {
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
+it('submits liveEdit document edits through observable.mutate', async () => {
+  const liveDoc = createDocumentHandle({
+    documentId: 'live-edit-test-doc',
     documentType: 'article',
+    liveEdit: true,
+  })
+  const state = getDocumentState(instance, liveDoc)
+  const unsubscribe = state.subscribe()
+
+  await firstValueFrom(state.observable.pipe(first((doc) => doc !== undefined)))
+  expect(state.getCurrent()).toMatchObject({
+    _id: 'live-edit-test-doc',
+    title: 'live initial',
+  })
+
+  const callCountBefore = mutateSubmission.mock.calls.length
+
+  const result = await applyDocumentActions(instance, {
+    actions: [editDocument(liveDoc, {set: {title: 'patched via mutate'}})],
     resource,
   })
+  await result.submitted()
+
+  expect(mutateSubmission.mock.calls.length).toBe(callCountBefore + 1)
+  const [mutationList, mutateOptions] = mutateSubmission.mock.calls[callCountBefore]!
+  expect(mutateOptions).toMatchObject({
+    transactionId: result.transactionId,
+    visibility: 'async',
+    returnDocuments: false,
+    returnFirst: false,
+    tag: 'document.mutate',
+    skipCrossDatasetReferenceValidation: true,
+  })
+  expect(mutationList.length).toBeGreaterThan(0)
+  expect(
+    mutationList.every(
+      (m) => 'patch' in m && (m as {patch: {id: string}}).patch.id === liveDoc.documentId,
+    ),
+  ).toBe(true)
+
+  expect(state.getCurrent()?.title).toBe('patched via mutate')
+  expect(client.action).not.toHaveBeenCalled()
+
+  unsubscribe()
+})
+
+it('provides the consistency status via `getDocumentSyncStatus`', async () => {
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
 
   const syncStatus = getDocumentSyncStatus(instance, doc)
   expect(syncStatus.getCurrent()).toBeUndefined()
@@ -550,13 +721,10 @@ it('reverts failed outgoing transaction locally', async () => {
     })
   })
 
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
+  const documentId = DocumentId(crypto.randomUUID())
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
-  const {getCurrent, subscribe} = getDocumentState<TestDocument>(instance, doc)
+  const {getCurrent, subscribe} = getDocumentState(instance, doc)
   const unsubscribe = subscribe()
 
   await applyDocumentActions(instance, {actions: [createDocument(doc)], resource})
@@ -621,12 +789,8 @@ it('removes a queued transaction if it fails to apply', async () => {
     })
   })
 
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
-  const state = getDocumentState<TestDocument>(instance, doc)
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  const state = getDocumentState(instance, doc)
   const unsubscribe = state.subscribe()
 
   await expect(
@@ -664,9 +828,8 @@ it('returns allowed true when no permission errors occur', async () => {
   const doc = createDocumentHandle({
     documentId: 'doc-perm-allowed',
     documentType: 'article',
-    resource,
   })
-  const state = getDocumentState<TestDocument>(instance, doc)
+  const state = getDocumentState(instance, doc)
   const unsubscribe = state.subscribe()
   await applyDocumentActions(instance, {actions: [createDocument(doc)], resource}).then((r) =>
     r.submitted(),
@@ -674,7 +837,6 @@ it('returns allowed true when no permission errors occur', async () => {
 
   // Use an action that includes a patch (so that update permission check is bypassed).
   const permissionsState = getPermissionsState(instance, {
-    resource,
     actions: [
       {
         ...doc,
@@ -691,11 +853,7 @@ it('returns allowed true when no permission errors occur', async () => {
 })
 
 it("should reject applying the action if a precondition isn't met", async () => {
-  const doc = createDocumentHandle({
-    documentId: 'does-not-exist',
-    documentType: 'article',
-    resource,
-  })
+  const doc = createDocumentHandle({documentId: 'does-not-exist', documentType: 'article'})
 
   await expect(
     applyDocumentActions(instance, {actions: [deleteDocument(doc)], resource}),
@@ -703,11 +861,7 @@ it("should reject applying the action if a precondition isn't met", async () =>
 })
 
 it("should reject applying the action if a permission isn't met", async () => {
-  const doc = createDocumentHandle({
-    documentId: 'does-not-exist',
-    documentType: 'article',
-    resource,
-  })
+  const doc = createDocumentHandle({documentId: 'does-not-exist', documentType: 'article'})
 
   const datasetAcl = [{filter: 'false', permissions: ['create']}]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
@@ -721,12 +875,8 @@ it('returns allowed false with reasons when permission errors occur', async () =
   const datasetAcl = [{filter: 'false', permissions: ['create']}]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
 
-  const doc = createDocumentHandle({
-    documentId: 'doc-perm-denied',
-    documentType: 'article',
-    resource,
-  })
-  const result = await resolvePermissions(instance, {actions: [createDocument(doc)], resource})
+  const doc = createDocumentHandle({documentId: 'doc-perm-denied', documentType: 'article'})
+  const result = await resolvePermissions(instance, {actions: [createDocument(doc)]})
 
   const message = 'You do not have permission to create a draft for document "doc-perm-denied".'
   expect(result).toMatchObject({
@@ -744,44 +894,47 @@ it('fetches dataset ACL and updates grants in the document store state', async (
   ]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
 
-  const book = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'book',
-    resource,
-  })
-  const author = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'author',
-    resource,
-  })
+  const book = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'book'})
+  const author = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'author'})
 
-  expect(await resolvePermissions(instance, {actions: [createDocument(book)], resource})).toEqual({
+  expect(await resolvePermissions(instance, {actions: [createDocument(book)]})).toEqual({
     allowed: true,
   })
-  expect(
-    await resolvePermissions(instance, {actions: [createDocument(author)], resource}),
-  ).toMatchObject({
+  expect(await resolvePermissions(instance, {actions: [createDocument(author)]})).toMatchObject({
     allowed: false,
     message: expect.stringContaining('You do not have permission to create a draft for document'),
   })
 })
 
+it('does not send credentials with the dataset ACL request', async () => {
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  await resolvePermissions(instance, {actions: [createDocument(doc)]})
+
+  const aclCall = vi
+    .mocked(client.request)
+    .mock.calls.find(([options]) => options.uri?.endsWith('/acl'))
+  expect(aclCall).toBeDefined()
+  expect(aclCall![0]).not.toHaveProperty('withCredentials')
+})
+
 it('fetches ACL for MediaLibraryResource', async () => {
-  const mediaLibraryInstance = createSanityInstance()
+  const mediaLibraryInstance = createSanityInstance({
+    projectId: 'p',
+    dataset: 'd',
+    resources: {
+      'media-library': {mediaLibraryId: 'test-media-library'},
+    },
+  })
 
   const datasetAcl = [{filter: 'true', permissions: ['read', 'update', 'create', 'history']}]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
 
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
-  const mediaLibraryResource = {mediaLibraryId: 'test-media-library'}
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  const mediaLibrarySource = {mediaLibraryId: 'test-media-library'}
 
   const result = await resolvePermissions(mediaLibraryInstance, {
     actions: [createDocument(doc)],
-    resource: mediaLibraryResource,
+    resource: mediaLibrarySource,
   })
 
   expect(result).toEqual({allowed: true})
@@ -789,21 +942,23 @@ it('fetches ACL for MediaLibraryResource', async () => {
 })
 
 it('fetches ACL for CanvasResource', async () => {
-  const canvasInstance = createSanityInstance()
+  const canvasInstance = createSanityInstance({
+    projectId: 'p',
+    dataset: 'd',
+    resources: {
+      canvas: {canvasId: 'test-canvas'},
+    },
+  })
 
   const datasetAcl = [{filter: 'true', permissions: ['read', 'update', 'create', 'history']}]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
 
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
-  const canvasResource = {canvasId: 'test-canvas'}
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  const canvasSource = {canvasId: 'test-canvas'}
 
   const result = await resolvePermissions(canvasInstance, {
     actions: [createDocument(doc)],
-    resource: canvasResource,
+    resource: canvasSource,
   })
 
   expect(result).toEqual({allowed: true})
@@ -811,16 +966,13 @@ it('fetches ACL for CanvasResource', async () => {
 })
 
 it('returns a promise that resolves when a document has been loaded in the store (useful for suspense)', async () => {
-  const doc = createDocumentHandle({
-    documentId: crypto.randomUUID(),
-    documentType: 'article',
-    resource,
-  })
+  const documentId = DocumentId(crypto.randomUUID())
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
   expect(await resolveDocument(instance, doc)).toBe(null)
 
   // use one-off instance to create the document in the mock backend
-  const oneOffInstance = createSanityInstance()
+  const oneOffInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
   const result = await applyDocumentActions(oneOffInstance, {
     actions: [createDocument(doc), editDocument(doc, {set: {title: 'initial title'}})],
     resource,
@@ -828,7 +980,7 @@ it('returns a promise that resolves when a document has been loaded in the store
   await result.submitted() // wait till submitted to server before resolving
 
   await expect(resolveDocument(instance, doc)).resolves.toMatchObject({
-    _id: getDraftId(doc.documentId),
+    _id: getDraftId(documentId),
     _type: 'article',
     title: 'initial title',
   })
@@ -839,8 +991,8 @@ it('emits an event for each action after an outgoing transaction has been accept
   const handler = vi.fn()
   const unsubscribe = subscribeDocumentEvents(instance, {resource, eventHandler: handler})
 
-  const documentId = crypto.randomUUID()
-  const doc = createDocumentHandle({documentId, documentType: 'article', resource})
+  const documentId = DocumentId(crypto.randomUUID())
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
   expect(handler).toHaveBeenCalledTimes(0)
 
   const tnx1 = await applyDocumentActions(instance, {
@@ -881,6 +1033,188 @@ it('emits an event for each action after an outgoing transaction has been accept
   unsubscribe()
 })
 
+it('creates and edits a version document with a release perspective', async () => {
+  const documentId = DocumentId('doc-release')
+  const releaseName = 'test-release'
+  const doc = createDocumentHandle({
+    documentId,
+    documentType: 'article',
+    perspective: {releaseName},
+  })
+  const versionId = `versions.${releaseName}.${documentId}`
+
+  const documentState = getDocumentState<TestDocument>(instance, doc)
+  expect(documentState.getCurrent()).toBeUndefined()
+
+  const unsubscribe = documentState.subscribe()
+
+  // Create a version document for the release
+  const {appeared} = await applyDocumentActions(instance, {
+    actions: [createDocument(doc)],
+  })
+  expect(appeared).toContain(versionId)
+
+  let currentDoc = documentState.getCurrent()
+  expect(currentDoc?._id).toEqual(versionId)
+  expect(currentDoc?._type).toEqual('article')
+
+  // Edit the version document
+  await applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'Release Version Title'}})],
+  })
+  currentDoc = documentState.getCurrent()
+  expect(currentDoc?.title).toEqual('Release Version Title')
+  expect(currentDoc?._id).toEqual(versionId)
+
+  unsubscribe()
+})
+
+it('creates a version document with initial values and then discards it', async () => {
+  const documentId = DocumentId('doc-release-discard')
+  const releaseName = 'test-release-discard'
+  const doc = createDocumentHandle({
+    documentId,
+    documentType: 'article',
+    perspective: {releaseName},
+  })
+  const versionId = `versions.${releaseName}.${documentId}`
+
+  const documentState = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = documentState.subscribe()
+
+  // Create a version document with initial values
+  await applyDocumentActions(instance, {
+    actions: [createDocument(doc, {title: 'Initial Release Title'})],
+  })
+
+  let currentDoc = documentState.getCurrent()
+  expect(currentDoc?._id).toEqual(versionId)
+  expect(currentDoc?.title).toEqual('Initial Release Title')
+
+  // Discard the version document
+  const {disappeared} = await applyDocumentActions(instance, {
+    actions: [discardDocument(doc)],
+  })
+  expect(disappeared).toContain(versionId)
+
+  currentDoc = documentState.getCurrent()
+  expect(currentDoc).toBeNull()
+
+  unsubscribe()
+})
+
+it('version edits are isolated from draft state', async () => {
+  const documentId = DocumentId('doc-version-isolation')
+  const releaseName = 'isolation-release'
+  const versionDoc = createDocumentHandle({
+    documentId,
+    documentType: 'article',
+    perspective: {releaseName},
+  })
+  const draftDoc = createDocumentHandle({documentId, documentType: 'article'})
+  const versionId = `versions.${releaseName}.${documentId}`
+
+  const versionState = getDocumentState<TestDocument>(instance, versionDoc)
+  const draftState = getDocumentState<TestDocument>(instance, draftDoc)
+
+  const unsubscribeVersion = versionState.subscribe()
+  const unsubscribeDraft = draftState.subscribe()
+
+  // Create draft and version documents
+  await applyDocumentActions(instance, {
+    actions: [createDocument(draftDoc)],
+  })
+  await applyDocumentActions(instance, {
+    actions: [editDocument(draftDoc, {set: {title: 'Draft Title'}})],
+  })
+  await applyDocumentActions(instance, {
+    actions: [createDocument(versionDoc, {title: 'Release Title'})],
+  })
+
+  // Version perspective shows the version doc
+  expect(versionState.getCurrent()?._id).toEqual(versionId)
+  expect(versionState.getCurrent()?.title).toEqual('Release Title')
+
+  // Draft state shows the draft doc
+  expect(draftState.getCurrent()?.title).toEqual('Draft Title')
+
+  // Editing the version doc should not affect the draft
+  await applyDocumentActions(instance, {
+    actions: [editDocument(versionDoc, {set: {title: 'Updated Release Title'}})],
+  })
+  expect(versionState.getCurrent()?.title).toEqual('Updated Release Title')
+  expect(draftState.getCurrent()?.title).toEqual('Draft Title')
+
+  unsubscribeVersion()
+  unsubscribeDraft()
+})
+
+it('subscribeToSubscriptionsAndListenToDocuments recovers from an OutOfSyncError instead of failing the document store', async () => {
+  const documentId = DocumentId('doc-out-of-sync-recovery')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = documentState.subscribe()
+  const draftId = getDraftId(documentId)
+
+  // Establish a synced document so the listener has a base revision.
+  const created = await applyDocumentActions(instance, {
+    actions: [createDocument(doc), editDocument(doc, {set: {title: 'initial'}})],
+  })
+  await created.submitted()
+  expect(documentState.getCurrent()?.title).toBe('initial')
+
+  // Capture the fetchDocument spy so we can detect when the listener
+  // re-subscribes. (every frest subscription re-runs fetchDocument)
+  const fetchDocumentSpy = vi.mocked(createFetchDocument).mock.results.at(-1)?.value as ReturnType<
+    typeof vi.fn
+  >
+  const fetchCallsBefore = fetchDocumentSpy.mock.calls.filter(([id]) => id === draftId).length
+
+  // Inject DEFAULT_MAX_BUFFER_SIZE mutations whose previousRev doesn't chain
+  // to the base revision (basically forcing the error)
+  const sharedListener = (
+    createSharedListener as unknown as () => {events: Subject<ListenEvent<SanityDocument>>}
+  )()
+  for (let i = 0; i < DEFAULT_MAX_BUFFER_SIZE; i++) {
+    sharedListener.events.next({
+      type: 'mutation',
+      documentId: draftId,
+      eventId: `bad-${i}`,
+      identity: 'user',
+      mutations: [],
+      timestamp: new Date().toISOString(),
+      transactionId: `bad-tx-${i}`,
+      transactionCurrentEvent: 0,
+      transactionTotalEvents: 1,
+      previousRev: `dangling-rev-${i}`,
+      resultRev: `bad-rev-${i}`,
+      transition: 'update',
+      visibility: 'query',
+    })
+  }
+
+  // The above should have triggered a retry and re-subscribed to the listener
+  await vi.waitFor(() => {
+    expect(fetchDocumentSpy.mock.calls.filter(([id]) => id === draftId).length).toBeGreaterThan(
+      fetchCallsBefore,
+    )
+  })
+
+  // The store stayed healthy through the OutOfSyncError.
+  expect(() => documentState.getCurrent()).not.toThrow()
+  expect(() => getDocumentSyncStatus(instance, doc).getCurrent()).not.toThrow()
+
+  // A follow-up edit still propagates through the recovered listener.
+  const edited = await applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'after-recovery'}})],
+    resource,
+  })
+  await edited.submitted()
+  expect(documentState.getCurrent()?.title).toBe('after-recovery')
+
+  unsubscribe()
+})
+
 vi.mock('../client/clientStore.ts', () => ({
   getClientState: vi.fn().mockReturnValue({observable: new ReplaySubject(1)}),
 }))
@@ -914,12 +1248,28 @@ vi.mock('./documentConstants.ts', async (importOriginal) => {
     ...original,
     INITIAL_OUTGOING_THROTTLE_TIME: 0,
     DOCUMENT_STATE_CLEAR_DELAY: 25,
+    OUT_OF_SYNC_RETRY_BASE_DELAY: 0,
+    OUT_OF_SYNC_RETRY_MAX_DELAY: 0,
   }
 })
 
 let client: SanityClient
 
+/** Mock for `client.observable.mutate` (liveEdit submission path); implementation reset in `beforeEach`. */
+const mutateSubmission = vi.fn(
+  async (
+    _mutations: Mutation[],
+    _options?: BaseMutationOptions,
+  ): Promise<MultipleMutationResult> => ({
+    transactionId: '',
+    documentIds: [],
+    results: [],
+  }),
+)
+
 beforeEach(() => {
+  mutateSubmission.mockReset()
+
   const client$ = (getClientState as () => StateSource<SanityClient>)()
     .observable as ReplaySubject<SanityClient>
   const sharedListener = (
@@ -930,14 +1280,130 @@ beforeEach(() => {
   )()
 
   let documents: DocumentSet = {
-    [getDraftId('existing-doc')]: {
-      _id: getDraftId('existing-doc'),
+    [getDraftId(DocumentId('existing-doc'))]: {
+      _id: getDraftId(DocumentId('existing-doc')),
       _createdAt: '2025-02-06T06:43:46.236Z',
       _updatedAt: '2025-02-06T06:43:46.236Z',
       _rev: 'initial-rev',
       _type: 'book',
       title: 'existing doc',
     },
+    'live-edit-test-doc': {
+      _id: 'live-edit-test-doc',
+      _type: 'article',
+      _createdAt: '2025-02-06T06:43:46.236Z',
+      _updatedAt: '2025-02-06T06:43:46.236Z',
+      _rev: 'rev-live-initial',
+      title: 'live initial',
+    },
+  }
+
+  const emitDatasetChangeEvents = (
+    prior: DocumentSet,
+    next: DocumentSet,
+    transactionId: string,
+    timestamp: string,
+  ) => {
+    const existingIds = new Set(
+      Object.entries(prior)
+        .filter(([, value]) => !!value)
+        .map(([key]) => key),
+    )
+    const resultingIds = new Set(
+      Object.entries(next)
+        .filter(([, value]) => !!value)
+        .map(([key]) => key),
+    )
+    const allKeys = new Set([...existingIds, ...resultingIds])
+
+    const {appeared, disappeared, updated} = Array.from(allKeys).reduce<{
+      updated: string[]
+      appeared: string[]
+      disappeared: string[]
+    }>(
+      (acc, id) => {
+        if (existingIds.has(id) && resultingIds.has(id)) {
+          acc.updated.push(id)
+        } else if (!existingIds.has(id) && resultingIds.has(id)) {
+          acc.appeared.push(id)
+        } else if (!resultingIds.has(id) && existingIds.has(id)) {
+          acc.disappeared.push(id)
+        }
+        return acc
+      },
+      {updated: [], appeared: [], disappeared: []},
+    )
+
+    const transactionTotalEvents = appeared.length + disappeared.length + updated.length
+    let transactionCurrentEvent = 0
+
+    const mutationEvents: MutationEvent[] = []
+
+    for (const id of appeared) {
+      transactionCurrentEvent++
+      const nextDoc = next[id]!
+      mutationEvents.push({
+        type: 'mutation',
+        documentId: id,
+        eventId: `${transactionId}#${id}`,
+        identity: 'example-user',
+        mutations: [{create: nextDoc}],
+        timestamp,
+        transactionId,
+        transactionCurrentEvent,
+        transactionTotalEvents,
+        transition: 'appear',
+        visibility: 'query',
+        resultRev: transactionId,
+      })
+    }
+
+    for (const id of updated) {
+      transactionCurrentEvent++
+      const prevDoc = prior[id]!
+      const nextDoc = next[id]!
+
+      mutationEvents.push({
+        type: 'mutation',
+        documentId: id,
+        eventId: `${transactionId}#${id}`,
+        identity: 'example-user',
+        mutations: diffValue(prevDoc, nextDoc).map((patch): Mutation => ({patch: {...patch, id}})),
+        timestamp,
+        transactionCurrentEvent,
+        transactionTotalEvents,
+        transactionId,
+        transition: 'update',
+        visibility: 'query',
+        previousRev: prevDoc._rev,
+        resultRev: transactionId,
+      })
+    }
+
+    for (const id of disappeared) {
+      transactionCurrentEvent++
+      const prevDoc = prior[id]!
+      mutationEvents.push({
+        type: 'mutation',
+        documentId: id,
+        eventId: `${transactionId}#${id}`,
+        identity: 'example-user',
+        mutations: [{delete: {id}}],
+        timestamp,
+        transactionId,
+        transactionCurrentEvent,
+        transactionTotalEvents,
+        transition: 'disappear',
+        visibility: 'query',
+        previousRev: prevDoc._rev,
+      })
+    }
+
+    documents = next
+
+    for (const mutationEvent of mutationEvents) {
+      sharedListener.events.next(mutationEvent)
+    }
   }
 
   vi.mocked(createFetchDocument).mockReturnValue(
@@ -949,6 +1415,33 @@ beforeEach(() => {
     ),
   )
 
+  mutateSubmission.mockImplementation(
+    async (
+      mutations: Mutation[],
+      options: BaseMutationOptions = {},
+    ): Promise<MultipleMutationResult> => {
+      const transactionId = options.transactionId ?? crypto.randomUUID()
+      const timestamp = new Date().toISOString()
+      const prior = {...documents}
+      let next = {...documents}
+      next = processMutations({documents: next, mutations, transactionId, timestamp})
+
+      if (!options.dryRun) {
+        emitDatasetChangeEvents(prior, next, transactionId, timestamp)
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      return {
+        transactionId,
+        documentIds: Object.entries(next)
+          .filter(([, v]) => !!v)
+          .map(([k]) => k),
+        results: [],
+      }
+    },
+  )
+
   const isNonNullable = <T>(t: T): t is NonNullable<T> => !!t
 
   const fetch = vi.fn(
@@ -1029,7 +1522,7 @@ beforeEach(() => {
             continue
           }
           case 'sanity.action.document.edit': {
-            const documentSource = next[i.draftId] ?? next[i.publishedId]
+            const documentSource = (i.draftId && next[i.draftId]) ?? next[i.publishedId]
             if (!documentSource) {
               throw new Error(
                 `Could not find a document to edit from \`draftId\` \`${i.draftId}\` or \`publishedId\` ${i.publishedId}`,
@@ -1039,8 +1532,8 @@ beforeEach(() => {
             next = processMutations({
               documents: next,
               mutations: [
-                {createIfNotExists: {...documentSource, _id: i.draftId}},
-                {patch: {id: i.draftId, ...i.patch}},
+                {createIfNotExists: {...documentSource, _id: i.draftId!}},
+                {patch: {id: i.draftId!, ...i.patch}},
               ],
               transactionId,
               timestamp,
@@ -1121,114 +1614,15 @@ beforeEach(() => {
             continue
           }
           default: {
-            throw new Error(`Unsupported action for mock backend: ${i.actionType}`)
+            throw new Error(
+              `Unsupported action for mock backend: ${(i as {actionType: string}).actionType}`,
+            )
           }
         }
       }
 
       if (!dryRun) {
-        const existingIds = new Set(
-          Object.entries(documents)
-            .filter(([, value]) => !!value)
-            .map(([key]) => key),
-        )
-        const resultingIds = new Set(
-          Object.entries(next)
-            .filter(([, value]) => !!value)
-            .map(([key]) => key),
-        )
-        const allKeys = new Set([...existingIds, ...resultingIds])
-
-        const {appeared, disappeared, updated} = Array.from(allKeys).reduce<{
-          updated: string[]
-          appeared: string[]
-          disappeared: string[]
-        }>(
-          (acc, id) => {
-            if (existingIds.has(id) && resultingIds.has(id)) {
-              acc.updated.push(id)
-            } else if (!existingIds.has(id) && resultingIds.has(id)) {
-              acc.appeared.push(id)
-            } else if (!resultingIds.has(id) && existingIds.has(id)) {
-              acc.disappeared.push(id)
-            }
-            return acc
-          },
-          {updated: [], appeared: [], disappeared: []},
-        )
-
-        const transactionTotalEvents = appeared.length + disappeared.length + updated.length
-        let transactionCurrentEvent = 0
-
-        const mutationEvents: MutationEvent[] = []
-
-        for (const id of appeared) {
-          transactionCurrentEvent++ // index seems to start at 1
-          const nextDoc = next[id]!
-          mutationEvents.push({
-            type: 'mutation',
-            documentId: id,
-            eventId: `${transactionId}#${id}`,
-            identity: 'example-user',
-            mutations: [{create: nextDoc}],
-            timestamp,
-            transactionId,
-            transactionCurrentEvent,
-            transactionTotalEvents,
-            transition: 'appear',
-            visibility: 'query',
-            resultRev: transactionId,
-          })
-        }
-
-        for (const id of updated) {
-          transactionCurrentEvent++
-          const prevDoc = documents[id]!
-          const nextDoc = next[id]!
-
-          mutationEvents.push({
-            type: 'mutation',
-            documentId: id,
-            eventId: `${transactionId}#${id}`,
-            identity: 'example-user',
-            mutations: diffValue(prevDoc, nextDoc).map(
-              (patch): Mutation => ({patch: {...patch, id}}),
-            ),
-            timestamp,
-            transactionCurrentEvent,
-            transactionTotalEvents,
-            transactionId,
-            transition: 'update',
-            visibility: 'query',
-            previousRev: prevDoc._rev,
-            resultRev: transactionId,
-          })
-        }
-
-        for (const id of disappeared) {
-          transactionCurrentEvent++
-          const prevDoc = documents[id]!
-          mutationEvents.push({
-            type: 'mutation',
-            documentId: id,
-            eventId: `${transactionId}#${id}`,
-            identity: 'example-user',
-            mutations: [{delete: {id}}],
-            timestamp,
-            transactionId,
-            transactionCurrentEvent,
-            transactionTotalEvents,
-            transition: 'disappear',
-            visibility: 'query',
-            previousRev: prevDoc._rev,
-          })
-        }
-
-        documents = next
-
-        for (const mutationEvent of mutationEvents) {
-          sharedListener.events.next(mutationEvent)
-        }
+        emitDatasetChangeEvents(documents, next, transactionId, timestamp)
       }
 
       // add a tick for realism
@@ -1255,6 +1649,7 @@ beforeEach(() => {
       action: (...args: Parameters<typeof action>) => from(action(...args)),
       fetch: (...args: Parameters<typeof fetch>) => from(fetch(...args)),
       request: (...args: Parameters<typeof request>) => from(request(...args)),
+      mutate: (...args: Parameters<typeof mutateSubmission>) => from(mutateSubmission(...args)),
     },
   } as SanityClient
   client$.next(client)