@sanity/sdk 2.8.0 → 2.9.0

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,
@@ -65,6 +67,10 @@ let instance: SanityInstance
 let instance1: SanityInstance
 let instance2: SanityInstance
 
+const source = {projectId: 'p', dataset: 'd'}
+const source1 = {projectId: 'p', dataset: 'd1'}
+const source2 = {projectId: 'p', dataset: 'd2'}
+
 beforeEach(() => {
   instance = createSanityInstance({projectId: 'p', dataset: 'd'})
   // test uses two instances that share the same in-memory dataset, but separate
@@ -81,8 +87,9 @@ afterEach(() => {
 })
 
 it('creates, edits, and publishes a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-single', documentType: 'article'})
-  const documentState = getDocumentState(instance, doc)
+  const documentId = DocumentId('doc-single')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
 
   // Initially the document is undefined
   expect(documentState.getCurrent()).toBeUndefined()
@@ -90,15 +97,19 @@ it('creates, edits, and publishes a document', async () => {
   const unsubscribe = documentState.subscribe()
 
   // Create a new document
-  const {appeared} = await applyDocumentActions(instance, {actions: [createDocument(doc)]})
-  expect(appeared).toContain(getDraftId(doc.documentId))
+  const {appeared} = await applyDocumentActions(instance, {
+    actions: [createDocument(doc)],
+    source,
+  })
+  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, {
     actions: [editDocument(doc, {set: {title: 'My First Article'}})],
+    source,
   })
   currentDoc = documentState.getCurrent()
   expect(currentDoc?.title).toEqual('My First Article')
@@ -106,17 +117,19 @@ it('creates, edits, and publishes a document', async () => {
   // Publish the document; the resulting transactionId is used as the new _rev
   const {transactionId, submitted} = await applyDocumentActions(instance, {
     actions: [publishDocument(doc)],
+    source,
   })
   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'})
-  const documentState = getDocumentState(instance, doc)
+  const documentId = DocumentId('doc-with-initial')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
 
   expect(documentState.getCurrent()).toBeUndefined()
 
@@ -131,11 +144,12 @@ it('creates a document with initial values', async () => {
         count: 42,
       }),
     ],
+    source,
   })
-  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)
@@ -144,8 +158,9 @@ it('creates a document with initial values', async () => {
 })
 
 it('edits existing documents', async () => {
-  const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article'})
-  const state = getDocumentState(instance, doc)
+  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
   expect(state.getCurrent()).toBeUndefined()
@@ -156,15 +171,16 @@ 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',
   })
 
   await applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'updated title'}})],
+    source,
   })
   expect(state.getCurrent()).toMatchObject({
-    _id: getDraftId(doc.documentId),
+    _id: getDraftId(documentId),
     title: 'updated title',
   })
 
@@ -172,23 +188,31 @@ it('edits existing documents', async () => {
 })
 
 it('sets optimistic changes synchronously', async () => {
-  const doc = createDocumentHandle({documentId: 'optimistic', documentType: 'article'})
+  const doc1 = {
+    documentId: DocumentId('optimistic'),
+    documentType: 'article',
+  }
+  const doc2 = {
+    documentId: DocumentId('optimistic'),
+    documentType: 'article',
+  }
 
-  const state1 = getDocumentState(instance1, doc)
-  const state2 = getDocumentState(instance2, doc)
+  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(instance1, doc)
+  await resolveDocument(instance1, doc1)
 
   // then the actions are synchronous
   expect(state1.getCurrent()).toBeNull()
-  applyDocumentActions(instance1, {actions: [createDocument(doc)]})
-  expect(state1.getCurrent()).toMatchObject({_id: getDraftId(doc.documentId)})
+  applyDocumentActions(instance1, {actions: [createDocument(doc1)], source: source1})
+  expect(state1.getCurrent()).toMatchObject({_id: getDraftId(doc1.documentId)})
   const actionResult1Promise = applyDocumentActions(instance1, {
-    actions: [editDocument(doc, {set: {title: 'initial title'}})],
+    actions: [editDocument(doc1, {set: {title: 'initial title'}})],
+    source: source1,
   })
   expect(state1.getCurrent()?.title).toBe('initial title')
 
@@ -208,7 +232,8 @@ it('sets optimistic changes synchronously', async () => {
 
   // synchronous for state 2
   const actionResult2Promise = applyDocumentActions(instance2, {
-    actions: [editDocument(doc, {set: {title: 'updated title'}})],
+    actions: [editDocument(doc2, {set: {title: 'updated title'}})],
+    source: source2,
   })
   expect(state2.getCurrent()?.title).toBe('updated title')
   // async for state 1
@@ -231,16 +256,19 @@ it('propagates changes between two instances', async () => {
   const state2Unsubscribe = state2.subscribe()
 
   // Create the document from instance1.
-  await applyDocumentActions(instance1, {actions: [createDocument(doc)]}).then((r) => r.submitted())
+  await applyDocumentActions(instance1, {actions: [createDocument(doc)], source: source1}).then(
+    (r) => r.submitted(),
+  )
 
   const doc1 = state1.getCurrent()
   const doc2 = state2.getCurrent()
-  expect(doc1?._id).toEqual(getDraftId(doc.documentId))
-  expect(doc2?._id).toEqual(getDraftId(doc.documentId))
+  expect(doc1?._id).toEqual(getDraftId(DocumentId(doc.documentId)))
+  expect(doc2?._id).toEqual(getDraftId(DocumentId(doc.documentId)))
 
   // Now, edit the document from instance2.
   await applyDocumentActions(instance2, {
     actions: [editDocument(doc, {set: {title: 'Hello world!'}})],
+    source: source2,
   }).then((r) => r.submitted())
 
   const updated1 = state1.getCurrent()
@@ -268,16 +296,19 @@ it('handles concurrent edits and resolves conflicts', async () => {
       createDocument(doc),
       editDocument(doc, {set: {title: 'The quick brown fox jumps over the lazy dog'}}),
     ],
+    source,
   }).then((res) => res.submitted())
 
   // 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'}})],
+    source: source1,
   }).then((r) => r.submitted())
   const p2 = applyDocumentActions(instance2, {
     actions: [
       editDocument(doc, {set: {title: 'The quick brown elephant jumps over the lazy dog'}}),
     ],
+    source: source2,
   }).then((r) => r.submitted())
 
   // Wait for both actions to complete (or reject).
@@ -294,27 +325,31 @@ it('handles concurrent edits and resolves conflicts', async () => {
 })
 
 it('unpublishes and discards a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-pub-unpub', documentType: 'article'})
-  const documentState = getDocumentState(instance, doc)
+  const documentId = DocumentId('doc-pub-unpub')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
   const unsubscribe = documentState.subscribe()
 
   // Create and publish the document.
-  await applyDocumentActions(instance, {actions: [createDocument(doc)]})
-  const afterPublish = await applyDocumentActions(instance, {actions: [publishDocument(doc)]})
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], source})
+  const afterPublish = await applyDocumentActions(instance, {
+    actions: [publishDocument(doc)],
+    source,
+  })
   const publishedDoc = documentState.getCurrent()
   expect(publishedDoc).toMatchObject({
-    _id: getPublishedId(doc.documentId),
+    _id: getPublishedId(documentId),
     _rev: afterPublish.transactionId,
   })
 
   // Unpublish the document (which should delete the published version and create a draft).
-  await applyDocumentActions(instance, {actions: [unpublishDocument(doc)]})
+  await applyDocumentActions(instance, {actions: [unpublishDocument(doc)], source})
   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)]})
+  await applyDocumentActions(instance, {actions: [discardDocument(doc)], source})
   const afterDiscard = documentState.getCurrent()
   expect(afterDiscard).toBeNull()
 
@@ -322,17 +357,21 @@ it('unpublishes and discards a document', async () => {
 })
 
 it('deletes a document', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-delete', documentType: 'article'})
+  const documentId = DocumentId('doc-delete')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
   const documentState = getDocumentState(instance, doc)
   const unsubscribe = documentState.subscribe()
 
-  await applyDocumentActions(instance, {actions: [createDocument(doc), publishDocument(doc)]})
+  await applyDocumentActions(instance, {
+    actions: [createDocument(doc), publishDocument(doc)],
+    source,
+  })
   const docValue = documentState.getCurrent()
   expect(docValue).toBeDefined()
 
   // Delete the document.
-  await applyDocumentActions(instance, {actions: [deleteDocument(doc)]})
+  await applyDocumentActions(instance, {actions: [deleteDocument(doc)], source})
   const afterDelete = documentState.getCurrent()
   expect(afterDelete).toBeNull()
 
@@ -340,14 +379,15 @@ it('deletes a document', async () => {
 })
 
 it('cleans up document state when there are no subscribers', async () => {
-  const doc = createDocumentHandle({documentId: 'doc-cleanup', documentType: 'article'})
-  const documentState = getDocumentState(instance, doc)
+  const documentId = DocumentId('doc-cleanup')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
 
   // Subscribe to the document state.
   const unsubscribe = documentState.subscribe()
 
   // Create a document.
-  await applyDocumentActions(instance, {actions: [createDocument(doc)]})
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], source})
   expect(documentState.getCurrent()).toBeDefined()
 
   // Unsubscribe from the document.
@@ -374,6 +414,7 @@ it('fetches documents if there are no active subscriptions for the actions appli
   // transaction for this action has been accepted by the server
   const setNewTitle = applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'new title'}})],
+    source,
   })
   expect(getCurrent()?.title).toBeUndefined()
   expect(getDocumentSyncStatus(instance, doc).getCurrent()).toBe(false)
@@ -382,9 +423,15 @@ it('fetches documents if there are no active subscriptions for the actions appli
   expect(getCurrent()?.title).toBe('new title')
 
   // there is an active subscriber now so the edits are synchronous
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'updated title'}})]})
+  applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'updated title'}})],
+    source,
+  })
   expect(getCurrent()?.title).toBe('updated title')
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'updated title!'}})]})
+  applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'updated title!'}})],
+    source,
+  })
   expect(getCurrent()?.title).toBe('updated title!')
 
   expect(getDocumentSyncStatus(instance, doc).getCurrent()).toBe(false)
@@ -392,6 +439,7 @@ it('fetches documents if there are no active subscriptions for the actions appli
   // await submitted in order to test that there is no subscriptions
   const result = await applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'updated title'}})],
+    source,
   })
   await result.submitted()
 
@@ -400,6 +448,7 @@ it('fetches documents if there are no active subscriptions for the actions appli
 
   const setNewNewTitle = applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'new new title'}})],
+    source,
   })
   // now we'll have to await again
   expect(getCurrent()?.title).toBe(undefined)
@@ -414,14 +463,15 @@ it('batches edit transaction into one outgoing transaction', async () => {
   const unsubscribe = getDocumentState(instance, doc).subscribe()
 
   // this creates its own transaction
-  applyDocumentActions(instance, {actions: [createDocument(doc)]})
+  applyDocumentActions(instance, {actions: [createDocument(doc)], source})
 
   // these get batched into one
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!'}})]})
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!!'}})]})
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!!!'}})]})
+  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!'}})], source})
+  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!!'}})], source})
+  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'name!!!'}})], source})
   const res = await applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'name!!!!'}})],
+    source,
   })
   await res.submitted()
 
@@ -434,6 +484,52 @@ it('batches edit transaction into one outgoing transaction', async () => {
   unsubscribe()
 })
 
+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'}})],
+    source,
+  })
+  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'})
 
@@ -443,7 +539,7 @@ it('provides the consistency status via `getDocumentSyncStatus`', async () => {
   const unsubscribe = syncStatus.subscribe()
   expect(syncStatus.getCurrent()).toBe(true)
 
-  const applied = applyDocumentActions(instance, {actions: [createDocument(doc)]})
+  const applied = applyDocumentActions(instance, {actions: [createDocument(doc)], source})
   expect(syncStatus.getCurrent()).toBe(false)
 
   const createResult = await applied
@@ -452,11 +548,17 @@ it('provides the consistency status via `getDocumentSyncStatus`', async () => {
   await createResult.submitted()
   expect(syncStatus.getCurrent()).toBe(true)
 
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'initial name'}})]})
+  applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'initial name'}})],
+    source,
+  })
   expect(syncStatus.getCurrent()).toBe(false)
 
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'updated name'}})]})
-  const publishResult = applyDocumentActions(instance, {actions: [publishDocument(doc)]})
+  applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'updated name'}})],
+    source,
+  })
+  const publishResult = applyDocumentActions(instance, {actions: [publishDocument(doc)], source})
   expect(syncStatus.getCurrent()).toBe(false)
   await publishResult.then((res) => res.submitted())
   expect(syncStatus.getCurrent()).toBe(true)
@@ -473,35 +575,45 @@ it('reverts failed outgoing transaction locally', async () => {
   })
 
   const revertedEventPromise = new Promise<TransactionRevertedEvent>((resolve) => {
-    const unsubscribe = subscribeDocumentEvents(instance, (e) => {
-      if (e.type === 'reverted') {
-        resolve(e)
-        unsubscribe()
-      }
+    const unsubscribe = subscribeDocumentEvents(instance, {
+      source,
+      eventHandler: (e) => {
+        if (e.type === 'reverted') {
+          resolve(e)
+          unsubscribe()
+        }
+      },
     })
   })
 
-  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  const documentId = DocumentId(crypto.randomUUID())
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
   const {getCurrent, subscribe} = getDocumentState(instance, doc)
   const unsubscribe = subscribe()
 
-  await applyDocumentActions(instance, {actions: [createDocument(doc)]})
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'the'}})]})
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'the quick'}})]})
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], source})
+  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'the'}})], source})
+  applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'the quick'}})],
+    source,
+  })
 
   // this edit action is simulated to fail from the backend and will be reverted
   const revertedActionResult = applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'the quick brown'}})],
     transactionId: 'force-revert',
     disableBatching: true,
+    source,
   })
 
   applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'the quick brown fox'}})],
+    source,
   })
   await applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'the quick brown fox jumps'}})],
+    source,
   }).then((e) => e.submitted())
 
   await expect(revertedEventPromise).resolves.toMatchObject({
@@ -521,6 +633,7 @@ it('reverts failed outgoing transaction locally', async () => {
   // check that we can still edit after recovering from the error
   applyDocumentActions(instance, {
     actions: [editDocument(doc, {set: {title: 'TEST the quick fox jumps'}})],
+    source,
   })
   expect(getCurrent()?.title).toBe('TEST the quick fox jumps')
 
@@ -530,11 +643,14 @@ it('reverts failed outgoing transaction locally', async () => {
 
 it('removes a queued transaction if it fails to apply', async () => {
   const actionErrorEventPromise = new Promise<ActionErrorEvent>((resolve) => {
-    const unsubscribe = subscribeDocumentEvents(instance, (e) => {
-      if (e.type === 'error') {
-        resolve(e)
-        unsubscribe()
-      }
+    const unsubscribe = subscribeDocumentEvents(instance, {
+      source,
+      eventHandler: (e) => {
+        if (e.type === 'error') {
+          resolve(e)
+          unsubscribe()
+        }
+      },
     })
   })
 
@@ -543,7 +659,10 @@ it('removes a queued transaction if it fails to apply', async () => {
   const unsubscribe = state.subscribe()
 
   await expect(
-    applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: "can't set"}})]}),
+    applyDocumentActions(instance, {
+      actions: [editDocument(doc, {set: {title: "can't set"}})],
+      source,
+    }),
   ).rejects.toThrowError(/Cannot edit document/)
 
   await expect(actionErrorEventPromise).resolves.toMatchObject({
@@ -553,8 +672,8 @@ it('removes a queued transaction if it fails to apply', async () => {
   })
 
   // editing should still work after though (no crashing)
-  await applyDocumentActions(instance, {actions: [createDocument(doc)]})
-  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'can set!'}})]})
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], source})
+  applyDocumentActions(instance, {actions: [editDocument(doc, {set: {title: 'can set!'}})], source})
 
   expect(state.getCurrent()?.title).toBe('can set!')
 
@@ -574,7 +693,9 @@ it('returns allowed true when no permission errors occur', async () => {
   })
   const state = getDocumentState(instance, doc)
   const unsubscribe = state.subscribe()
-  await applyDocumentActions(instance, {actions: [createDocument(doc)]}).then((r) => r.submitted())
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], source}).then((r) =>
+    r.submitted(),
+  )
 
   // Use an action that includes a patch (so that update permission check is bypassed).
   const permissionsState = getPermissionsState(instance, {
@@ -596,9 +717,9 @@ 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'})
 
-  await expect(applyDocumentActions(instance, {actions: [deleteDocument(doc)]})).rejects.toThrow(
-    'The document you are trying to delete does not exist.',
-  )
+  await expect(
+    applyDocumentActions(instance, {actions: [deleteDocument(doc)], source}),
+  ).rejects.toThrow('The document you are trying to delete does not exist.')
 })
 
 it("should reject applying the action if a permission isn't met", async () => {
@@ -607,9 +728,9 @@ it("should reject applying the action if a permission isn't met", async () => {
   const datasetAcl = [{filter: 'false', permissions: ['create']}]
   vi.mocked(client.request).mockResolvedValue(datasetAcl)
 
-  await expect(applyDocumentActions(instance, {actions: [createDocument(doc)]})).rejects.toThrow(
-    'You do not have permission to create a draft for document "does-not-exist".',
-  )
+  await expect(
+    applyDocumentActions(instance, {actions: [createDocument(doc)], source}),
+  ).rejects.toThrow('You do not have permission to create a draft for document "does-not-exist".')
 })
 
 it('returns allowed false with reasons when permission errors occur', async () => {
@@ -647,8 +768,57 @@ it('fetches dataset ACL and updates grants in the document store state', async (
   })
 })
 
-it('returns a promise that resolves when a document has been loaded in the store (useful for suspense)', async () => {
+it('fetches ACL for MediaLibrarySource', async () => {
+  const mediaLibraryInstance = createSanityInstance({
+    projectId: 'p',
+    dataset: 'd',
+    sources: {
+      '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'})
+  const mediaLibrarySource = {mediaLibraryId: 'test-media-library'}
+
+  const result = await resolvePermissions(mediaLibraryInstance, {
+    actions: [createDocument(doc)],
+    source: mediaLibrarySource,
+  })
+
+  expect(result).toEqual({allowed: true})
+  mediaLibraryInstance.dispose()
+})
+
+it('fetches ACL for CanvasSource', async () => {
+  const canvasInstance = createSanityInstance({
+    projectId: 'p',
+    dataset: 'd',
+    sources: {
+      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'})
+  const canvasSource = {canvasId: 'test-canvas'}
+
+  const result = await resolvePermissions(canvasInstance, {
+    actions: [createDocument(doc)],
+    source: canvasSource,
+  })
+
+  expect(result).toEqual({allowed: true})
+  canvasInstance.dispose()
+})
+
+it('returns a promise that resolves when a document has been loaded in the store (useful for suspense)', async () => {
+  const documentId = DocumentId(crypto.randomUUID())
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
 
   expect(await resolveDocument(instance, doc)).toBe(null)
 
@@ -656,11 +826,12 @@ it('returns a promise that resolves when a document has been loaded in the store
   const oneOffInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
   const result = await applyDocumentActions(oneOffInstance, {
     actions: [createDocument(doc), editDocument(doc, {set: {title: 'initial title'}})],
+    source,
   })
   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',
   })
@@ -669,9 +840,9 @@ it('returns a promise that resolves when a document has been loaded in the store
 
 it('emits an event for each action after an outgoing transaction has been accepted', async () => {
   const handler = vi.fn()
-  const unsubscribe = subscribeDocumentEvents(instance, handler)
+  const unsubscribe = subscribeDocumentEvents(instance, {source, eventHandler: handler})
 
-  const documentId = crypto.randomUUID()
+  const documentId = DocumentId(crypto.randomUUID())
   const doc = createDocumentHandle({documentId, documentType: 'article'})
   expect(handler).toHaveBeenCalledTimes(0)
 
@@ -681,6 +852,7 @@ it('emits an event for each action after an outgoing transaction has been accept
       editDocument(doc, {set: {title: 'new name'}}),
       publishDocument(doc),
     ],
+    source,
   }).then((e) => e.submitted())
   expect(handler).toHaveBeenCalledTimes(4)
 
@@ -691,6 +863,7 @@ it('emits an event for each action after an outgoing transaction has been accept
       editDocument(doc, {set: {title: 'updated name'}}),
       discardDocument(doc),
     ],
+    source,
   }).then((e) => e.submitted())
   expect(handler).toHaveBeenCalledTimes(9)
 
@@ -706,11 +879,127 @@ it('emits an event for each action after an outgoing transaction has been accept
     [{type: 'accepted', outgoing: {transactionId: tnx2.transactionId}}],
   ])
 
-  await applyDocumentActions(instance, {actions: [deleteDocument(doc)]})
+  await applyDocumentActions(instance, {actions: [deleteDocument(doc)], source})
 
   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()
+})
+
 vi.mock('../client/clientStore.ts', () => ({
   getClientState: vi.fn().mockReturnValue({observable: new ReplaySubject(1)}),
 }))
@@ -749,7 +1038,21 @@ vi.mock('./documentConstants.ts', async (importOriginal) => {
 
 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 = (
@@ -760,14 +1063,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(
@@ -779,6 +1198,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(
@@ -859,8 +1305,8 @@ beforeEach(() => {
             continue
           }
           case 'sanity.action.document.edit': {
-            const source = next[i.draftId] ?? next[i.publishedId]
-            if (!source) {
+            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}`,
               )
@@ -869,8 +1315,8 @@ beforeEach(() => {
             next = processMutations({
               documents: next,
               mutations: [
-                {createIfNotExists: {...source, _id: i.draftId}},
-                {patch: {id: i.draftId, ...i.patch}},
+                {createIfNotExists: {...documentSource, _id: i.draftId!}},
+                {patch: {id: i.draftId!, ...i.patch}},
               ],
               transactionId,
               timestamp,
@@ -951,114 +1397,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
@@ -1085,6 +1432,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)