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

package/src/document/documentStore.ts

@@ -1,7 +1,7 @@
-import {type Action} from '@sanity/client'
-import {getPublishedId} from '@sanity/client/csm'
+import {type Action, type Mutation} from '@sanity/client'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 import {jsonMatch} from '@sanity/json-match'
-import {type SanityDocument} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 import {type ExprNode} from 'groq-js'
 import {
   catchError,
@@ -17,15 +17,18 @@ import {
   Observable,
   of,
   pairwise,
+  retry,
   startWith,
   Subject,
   switchMap,
   tap,
   throttle,
+  throwError,
   timer,
   withLatestFrom,
 } from 'rxjs'
 
+import {getCurrentUserState} from '../auth/authStore'
 import {type ClientOptions, getClientState} from '../client/clientStore'
 import {
   type DocumentHandle,
@@ -34,6 +37,7 @@ import {
   isDatasetResource,
   isMediaLibraryResource,
 } from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {
   bindActionByResource,
   type BoundResourceKey,
@@ -42,11 +46,20 @@ import {
 import {type SanityInstance} from '../store/createSanityInstance'
 import {createStateSourceAction, type StateSource} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
-import {getDraftId} from '../utils/ids'
 import {type DocumentAction} from './actions'
-import {API_VERSION, INITIAL_OUTGOING_THROTTLE_TIME} from './documentConstants'
-import {type DocumentEvent, getDocumentEvents} from './events'
+import {
+  API_VERSION,
+  INITIAL_OUTGOING_THROTTLE_TIME,
+  OUT_OF_SYNC_RETRY_BASE_DELAY,
+  OUT_OF_SYNC_RETRY_MAX_DELAY,
+} from './documentConstants'
+import {
+  type DocumentEvent,
+  type DocumentTransactionSubmissionResult,
+  getDocumentEvents,
+} from './events'
 import {listen, OutOfSyncError} from './listen'
+import {type JsonMatch} from './patchOperations'
 import {
   calculatePermissions,
   createGrantsLookup,
@@ -54,13 +67,13 @@ import {
   type DocumentPermissionsResult,
   type Grant,
 } from './permissions'
-import {ActionError} from './processActions'
+import {ActionError} from './processActions/processActions'
+import {isReleaseAction} from './processActions/releaseUtil'
 import {
   type AppliedTransaction,
   applyFirstQueuedTransaction,
   applyRemoteDocument,
   cleanupOutgoingTransaction,
-  getDocumentIdsFromActions,
   manageSubscriberIds,
   type OutgoingTransaction,
   type QueuedTransaction,
@@ -77,6 +90,10 @@ export interface DocumentStoreState {
   applied: AppliedTransaction[]
   outgoing?: OutgoingTransaction
   grants?: Record<Grant, ExprNode>
+  /**
+   * The current user's identity (their user ID).
+   */
+  identity?: string
   error?: unknown
   sharedListener: SharedListener
   fetchDocument: (documentId: string) => Observable<SanityDocument | null>
@@ -116,6 +133,14 @@ export interface DocumentState {
    * local transactions on top of this new remote.
    */
   unverifiedRevisions?: {[TTransactionId in string]?: UnverifiedDocumentRevision}
+  /**
+   * transaction IDs recently submitted by this client for this document,
+   * newest last. used to label `remote-patches` events with the correct
+   * `origin` even after the corresponding `unverifiedRevisions` entry has
+   * been pruned (e.g. by a sync event that raced the listener echo). capped
+   * to the most recent entries.
+   */
+  recentOwnTransactionIds?: string[]
 }
 
 export const documentStore = defineStore<DocumentStoreState, BoundResourceKey>({
@@ -136,6 +161,7 @@ export const documentStore = defineStore<DocumentStoreState, BoundResourceKey>({
       subscribeToSubscriptionsAndListenToDocuments(context),
       subscribeToAppliedAndSubmitNextTransaction(context),
       subscribeToClientAndFetchDatasetAcl(context),
+      subscribeToCurrentUserAndSetIdentity(context),
     ]
 
     return () => {
@@ -158,6 +184,29 @@ export interface DocumentOptions<
   path?: TPath
 }
 
+/** @beta */
+export function getDocumentState<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+): StateSource<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | undefined | null>
+
+/** @beta */
+export function getDocumentState<
+  TPath extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+): StateSource<
+  JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
+>
+
 /** @beta */
 export function getDocumentState<TData>(
   instance: SanityInstance,
@@ -175,29 +224,28 @@ const _getDocumentState = bindActionByResource(
   documentStore,
   createStateSourceAction({
     selector: ({state: {error, documentStates}}, options: DocumentOptions<string | undefined>) => {
-      const {documentId, path, liveEdit} = options
+      const {documentId: docId, path, liveEdit, perspective} = options
+      const documentId = DocumentId(docId)
       if (error) throw error
+      let document: SanityDocument | null | undefined
 
       if (liveEdit) {
-        // For liveEdit documents, only look at the single document
-        const document = documentStates[documentId]?.local
-        if (document === undefined) return undefined
-        if (!path) return document
-        const result = jsonMatch(document, path).next()
-        if (result.done) return undefined
-        const {value} = result.value
-        return value
+        document = documentStates[documentId]?.local
+      } else {
+        let version: SanityDocument | null | undefined
+        if (isReleasePerspective(perspective)) {
+          const versionId = getVersionId(documentId, perspective.releaseName)
+          version = documentStates[versionId]?.local
+          // early exit if we don't have the version document and we're in a release perspective
+          if (version === undefined) return undefined
+        }
+        const draft = documentStates[getDraftId(documentId)]?.local
+        const published = documentStates[getPublishedId(documentId)]?.local
+        // early exit if we don't have all the documents for draft/published logic
+        if (draft === undefined || published === undefined) return undefined
+        document = version ?? draft ?? published
       }
 
-      // Standard draft/published logic
-      const draftId = getDraftId(documentId)
-      const publishedId = getPublishedId(documentId)
-      const draft = documentStates[draftId]?.local
-      const published = documentStates[publishedId]?.local
-
-      // wait for draft and published to be loaded before returning a value
-      if (draft === undefined || published === undefined) return undefined
-      const document = draft ?? published
       if (!path) return document
       const result = jsonMatch(document, path).next()
       if (result.done) return undefined
@@ -205,20 +253,24 @@ const _getDocumentState = bindActionByResource(
       return value
     },
     onSubscribe: (context, options: DocumentOptions<string | undefined>) =>
-      manageSubscriberIds(context, options.documentId, {expandDraftPublished: !options.liveEdit}),
+      manageSubscriberIds(context, [options]),
   }),
 )
 
 /** @beta */
-export function resolveDocument<TData extends SanityDocument>(
+export function resolveDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
   instance: SanityInstance,
-  docHandle: DocumentHandle,
-): Promise<TData | null>
+  docHandle: DocumentHandle<TDocumentType, TDataset, TProjectId>,
+): Promise<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null>
 /** @beta */
-export function resolveDocument(
+export function resolveDocument<TData extends SanityDocument>(
   instance: SanityInstance,
-  docHandle: DocumentHandle,
-): Promise<SanityDocument | null>
+  docHandle: DocumentHandle<string, string, string>,
+): Promise<TData | null>
 /** @beta */
 export function resolveDocument(
   ...args: Parameters<typeof _resolveDocument>
@@ -245,32 +297,32 @@ export const getDocumentSyncStatus = bindActionByResource(
       {state: {error, documentStates: documents, outgoing, applied, queued}},
       doc: DocumentHandle,
     ) => {
-      const documentId = typeof doc === 'string' ? doc : doc.documentId
+      const documentId = DocumentId(typeof doc === 'string' ? doc : doc.documentId)
       if (error) throw error
 
       if (doc.liveEdit) {
         // For liveEdit documents, only check the single document
-        const document = documents[documentId]
-        if (document === undefined) return undefined
-        return !queued.length && !applied.length && !outgoing
+        if (documents[documentId] === undefined) return undefined
+      } else {
+        const version = isReleasePerspective(doc.perspective)
+          ? documents[getVersionId(documentId, doc.perspective.releaseName)]
+          : undefined
+        if (isReleasePerspective(doc.perspective) && version === undefined) return undefined
+        // Standard draft/published logic
+        const draft = documents[getDraftId(documentId)]
+        const published = documents[getPublishedId(documentId)]
+        if (draft === undefined || published === undefined) return undefined
       }
-
-      // Standard draft/published logic
-      const draftId = getDraftId(documentId)
-      const publishedId = getPublishedId(documentId)
-
-      const draft = documents[draftId]
-      const published = documents[publishedId]
-
-      if (draft === undefined || published === undefined) return undefined
       return !queued.length && !applied.length && !outgoing
     },
-    onSubscribe: (context, doc: DocumentHandle) => manageSubscriberIds(context, doc.documentId),
+    onSubscribe: (context, doc: DocumentHandle) => {
+      return manageSubscriberIds(context, [doc])
+    },
   }),
 )
 
 type PermissionsStateOptions = {
-  resource: DocumentResource
+  resource?: DocumentResource
   actions: DocumentAction[]
 }
 
@@ -279,8 +331,9 @@ export const getPermissionsState = bindActionByResource(
   documentStore,
   createStateSourceAction({
     selector: calculatePermissions,
-    onSubscribe: (context, {actions}: PermissionsStateOptions) =>
-      manageSubscriberIds(context, getDocumentIdsFromActions(actions)),
+    onSubscribe: (context, {actions}: PermissionsStateOptions) => {
+      manageSubscriberIds(context, actions)
+    },
   }) as StoreAction<
     DocumentStoreState,
     [PermissionsStateOptions],
@@ -301,7 +354,7 @@ export const resolvePermissions = bindActionByResource(
 /** @beta */
 export const subscribeDocumentEvents = bindActionByResource(
   documentStore,
-  ({state}, options: {resource: DocumentResource; eventHandler: (e: DocumentEvent) => void}) => {
+  ({state}, options: {resource?: DocumentResource; eventHandler: (e: DocumentEvent) => void}) => {
     const {events} = state.get()
     const subscription = events.subscribe(options.eventHandler)
     return () => subscription.unsubscribe()
@@ -365,24 +418,48 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
       withLatestFrom(
         getClientState(instance, {
           apiVersion: API_VERSION,
-          ...(resource ? {resource} : {}),
+          resource,
         }).observable,
       ),
       concatMap(([outgoing, client]) => {
         if (!outgoing) return EMPTY
+
+        const revertOnError = catchError((error: unknown) => {
+          state.set('revertOutgoingTransaction', revertOutgoingTransaction)
+          const message = error instanceof Error ? error.message : 'Request failed'
+          events.next({type: 'reverted', message, outgoing, error})
+          return EMPTY
+        })
+
+        const toResult = map((result: unknown) => ({
+          result: result as DocumentTransactionSubmissionResult,
+          outgoing,
+        }))
+
+        // liveEdit transactions route to the mutations API; everything else routes
+        // to the actions API. processActions rejects transactions that mix the two,
+        // and reducers won't batch across that boundary, so a batch is always
+        // entirely liveEdit or entirely not.
+        if (outgoing.actions.some((action) => !isReleaseAction(action) && action.liveEdit)) {
+          return client.observable
+            .mutate(outgoing.outgoingMutations as Mutation[], {
+              transactionId: outgoing.transactionId,
+              visibility: 'async',
+              returnDocuments: false,
+              returnFirst: false,
+              tag: 'document.mutate',
+              skipCrossDatasetReferenceValidation: true,
+            })
+            .pipe(revertOnError, toResult)
+        }
+
         return client.observable
           .action(outgoing.outgoingActions as Action[], {
             transactionId: outgoing.transactionId,
             skipCrossDatasetReferenceValidation: true,
+            tag: 'document.action',
           })
-          .pipe(
-            catchError((error) => {
-              state.set('revertOutgoingTransaction', revertOutgoingTransaction)
-              events.next({type: 'reverted', message: error.message, outgoing, error})
-              return EMPTY
-            }),
-            map((result) => ({result, outgoing})),
-          )
+          .pipe(revertOnError, toResult)
       }),
       tap(({outgoing, result}) => {
         state.set('cleanupOutgoingTransaction', cleanupOutgoingTransaction)
@@ -424,8 +501,8 @@ const subscribeToSubscriptionsAndListenToDocuments = (
           ...added.map((id) => ({id, add: true})),
           ...removed.map((id) => ({id, add: false})),
         ].sort((a, b) => {
-          const aIsDraft = a.id === getDraftId(a.id)
-          const bIsDraft = b.id === getDraftId(b.id)
+          const aIsDraft = a.id === getDraftId(DocumentId(a.id))
+          const bIsDraft = b.id === getDraftId(DocumentId(b.id))
 
           if (aIsDraft && bIsDraft) return a.id.localeCompare(b.id, 'en-US')
           if (aIsDraft) return -1
@@ -441,10 +518,15 @@ const subscribeToSubscriptionsAndListenToDocuments = (
           switchMap((e) => {
             if (!e.add) return EMPTY
             return listen(context, e.id).pipe(
-              catchError((error) => {
-                // retry on `OutOfSyncError`
-                if (error instanceof OutOfSyncError) listen(context, e.id)
-                throw error
+              retry({
+                delay: (error, retryCount) => {
+                  if (!(error instanceof OutOfSyncError)) return throwError(() => error)
+                  const backoff = Math.min(
+                    OUT_OF_SYNC_RETRY_BASE_DELAY * 2 ** (retryCount - 1),
+                    OUT_OF_SYNC_RETRY_MAX_DELAY,
+                  )
+                  return timer(backoff)
+                },
               }),
               tap((remote) =>
                 state.set('applyRemoteDocument', (prev) =>
@@ -464,10 +546,7 @@ const subscribeToClientAndFetchDatasetAcl = ({
   state,
   key: {resource},
 }: StoreContext<DocumentStoreState, BoundResourceKey>) => {
-  const clientOptions: ClientOptions = {apiVersion: API_VERSION}
-  if (resource) {
-    clientOptions.resource = resource
-  }
+  const clientOptions: ClientOptions = {apiVersion: API_VERSION, resource}
 
   let uri: string
   if (resource && isDatasetResource(resource)) {
@@ -486,7 +565,6 @@ const subscribeToClientAndFetchDatasetAcl = ({
         client.observable.request<DatasetAcl>({
           uri,
           tag: 'acl.get',
-          withCredentials: true,
         }),
       ),
       tap((datasetAcl) => state.set('setGrants', {grants: createGrantsLookup(datasetAcl)})),
@@ -495,3 +573,16 @@ const subscribeToClientAndFetchDatasetAcl = ({
       error: (error) => state.set('setError', {error}),
     })
 }
+
+const subscribeToCurrentUserAndSetIdentity = ({
+  instance,
+  state,
+}: StoreContext<DocumentStoreState, BoundResourceKey>) =>
+  getCurrentUserState(instance).observable.subscribe({
+    next: (currentUser) => state.set('setIdentity', {identity: currentUser?.id}),
+    // A transient identity-fetch failure (network blip, expired token, or a
+    // normal logout/re-login transition) should not brick all document
+    // operations. Reset the identity to `undefined` and keep going — GROQ's
+    // `identity()` then evaluates to null, matching the unauthenticated state.
+    error: () => state.set('setIdentity', {identity: undefined}),
+  })

package/src/document/events.test.ts

@@ -1,6 +1,6 @@
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentAction} from '../document/actions'
+import {type Action, type DocumentAction} from '../document/actions'
 import {type DocumentEvent, getDocumentEvents} from '../document/events'
 import {type OutgoingTransaction} from '../document/reducers'
 
@@ -41,11 +41,66 @@ describe('getDocumentEvents', () => {
     expect(events).toHaveLength(outgoing.actions.length)
     events.forEach((event) => {
       const action = outgoing.actions.find(
-        (a) => 'documentId' in event && event.documentId === a.documentId,
+        (a) => 'documentId' in a && 'documentId' in event && event.documentId === a.documentId,
       )
       expect(action).toBeDefined()
       expect(event.type).toEqual(expectedMap[action!.type])
       expect((event as Extract<DocumentEvent, {outgoing: unknown}>).outgoing).toBe(outgoing)
     })
   })
+
+  it('emits created/edited/deleted events for release.create/edit/delete with release doc IDs', () => {
+    const outgoing: OutgoingTransaction = {
+      transactionId: 'txn-release',
+      actions: [
+        {type: 'release.create', releaseId: 'r1'} as Action,
+        {type: 'release.edit', releaseId: 'r2', patch: {set: {}}} as Action,
+        {type: 'release.delete', releaseId: 'r3'} as Action,
+      ],
+      disableBatching: false,
+      batchedTransactionIds: [],
+      outgoingActions: [],
+      outgoingMutations: [],
+      base: {},
+      working: {},
+      previous: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:00:00.000Z',
+    }
+
+    const events = getDocumentEvents(outgoing)
+    expect(events).toEqual([
+      {type: 'created', documentId: '_.releases.r1', outgoing},
+      {type: 'edited', documentId: '_.releases.r2', outgoing},
+      {type: 'deleted', documentId: '_.releases.r3', outgoing},
+    ])
+  })
+
+  it('skips release actions that have no local mutation (publish/schedule/archive/etc.)', () => {
+    const outgoing: OutgoingTransaction = {
+      transactionId: 'txn-release-noop',
+      actions: [
+        {type: 'release.publish', releaseId: 'r1'} as Action,
+        {
+          type: 'release.schedule',
+          releaseId: 'r2',
+          publishAt: '2026-01-01T00:00:00.000Z',
+        } as Action,
+        {type: 'release.unschedule', releaseId: 'r3'} as Action,
+        {type: 'release.archive', releaseId: 'r4'} as Action,
+        {type: 'release.unarchive', releaseId: 'r5'} as Action,
+      ],
+      disableBatching: false,
+      batchedTransactionIds: [],
+      outgoingActions: [],
+      outgoingMutations: [],
+      base: {},
+      working: {},
+      previous: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:00:00.000Z',
+    }
+
+    expect(getDocumentEvents(outgoing)).toEqual([])
+  })
 })

package/src/document/events.ts

@@ -1,8 +1,15 @@
-import {type SanityClient} from '@sanity/client'
+import {type MultipleMutationResult, type SanityClient} from '@sanity/client'
+import {type PatchOperations} from '@sanity/types'
 
-import {type DocumentAction} from './actions'
+import {type DocumentAction, type ReleaseAction} from './actions'
+import {getReleaseDocumentId, isReleaseAction} from './processActions/releaseUtil'
 import {type OutgoingTransaction} from './reducers'
 
+/** @beta Response body from submitting an outgoing transaction (actions or mutations API). */
+export type DocumentTransactionSubmissionResult =
+  | Awaited<ReturnType<SanityClient['action']>>
+  | MultipleMutationResult
+
 /** @beta */
 export type DocumentEvent =
   | ActionErrorEvent
@@ -15,6 +22,7 @@ export type DocumentEvent =
   | DocumentPublishedEvent
   | DocumentUnpublishedEvent
   | DocumentDiscardedEvent
+  | DocumentRemotePatchesEvent
 
 /**
  * @beta
@@ -35,7 +43,7 @@ export interface ActionErrorEvent {
 export interface TransactionAcceptedEvent {
   type: 'accepted'
   outgoing: OutgoingTransaction
-  result: Awaited<ReturnType<SanityClient['action']>>
+  result: DocumentTransactionSubmissionResult
 }
 /**
  * @beta
@@ -113,31 +121,79 @@ export interface DocumentDiscardedEvent {
   outgoing: OutgoingTransaction
 }
 
-export function getDocumentEvents(outgoing: OutgoingTransaction): DocumentEvent[] {
-  const documentIdsByAction = Object.entries(
-    outgoing.actions.reduce(
-      (acc, {type, documentId}) => {
-        const ids = acc[type] || new Set()
-        if (documentId) ids.add(documentId)
-        acc[type] = ids
-        return acc
-      },
-      {} as Record<DocumentAction['type'], Set<string>>,
-    ),
-  ) as [DocumentAction['type'], Set<string>][]
+/**
+ * @beta
+ * Event emitted when patches for a document are observed through the listener.
+ *
+ * Unlike the whole-document snapshots the store keeps, these are the raw patch
+ * operations from the transaction that produced the change, preserving the
+ * operational intent of the edit (e.g. keyed array inserts/unsets). Consumers
+ * that maintain their own local state, like collaborative text editors, can
+ * apply these directly instead of diffing document snapshots.
+ *
+ * `origin` is `'local'` when the transaction was submitted by this document
+ * store instance (an own edit observed back through the listener) and
+ * `'remote'` when it came from another client.
+ */
+export interface DocumentRemotePatchesEvent {
+  type: 'remote-patches'
+  /** The ID of the document version the patches apply to (e.g. a draft ID). */
+  documentId: string
+  /** The transaction ID that carried these patches. */
+  transactionId: string
+  /** The revision the document was at before this transaction. */
+  previousRev?: string
+  /** The timestamp of the transaction. */
+  timestamp: string
+  /** The patch operations, rooted at the document. */
+  patches: PatchOperations[]
+  /** Whether the transaction originated from this client or another one. */
+  origin: 'local' | 'remote'
+}
+
+// Release actions that write a mutation to the local release doc map onto
+// the regular per-document events with `documentId = '_.releases.<releaseId>'`.
+// The other release actions (publish/schedule/unschedule/archive/unarchive)
+// don't mutate local state, so they aren't in the map and get skipped — they
+// surface through the transaction-level `accepted`/`reverted` events instead.
+const actionMap = {
+  'document.create': 'created',
+  'document.delete': 'deleted',
+  'document.discard': 'discarded',
+  'document.edit': 'edited',
+  'document.publish': 'published',
+  'document.unpublish': 'unpublished',
+  'release.create': 'created',
+  'release.edit': 'edited',
+  'release.delete': 'deleted',
+} satisfies Partial<Record<DocumentAction['type'] | ReleaseAction['type'], DocumentEvent['type']>>
 
-  const actionMap = {
-    'document.create': 'created',
-    'document.delete': 'deleted',
-    'document.discard': 'discarded',
-    'document.edit': 'edited',
-    'document.publish': 'published',
-    'document.unpublish': 'unpublished',
-  } satisfies Record<DocumentAction['type'], DocumentEvent['type']>
+type MappedActionType = keyof typeof actionMap
+
+export function getDocumentEvents(outgoing: OutgoingTransaction): DocumentEvent[] {
+  const documentIdsByAction = outgoing.actions.reduce(
+    (acc, action) => {
+      if (!(action.type in actionMap)) return acc
+      const documentId = isReleaseAction(action)
+        ? getReleaseDocumentId(action.releaseId)
+        : action.documentId
+      if (!documentId) return acc
+      const type = action.type as MappedActionType
+      const ids = acc[type] ?? new Set<string>()
+      ids.add(documentId)
+      acc[type] = ids
+      return acc
+    },
+    {} as Partial<Record<MappedActionType, Set<string>>>,
+  )
 
-  return documentIdsByAction.flatMap(([actionType, documentIds]) =>
-    Array.from(documentIds).map(
-      (documentId): DocumentEvent => ({type: actionMap[actionType], documentId, outgoing}),
+  return Object.entries(documentIdsByAction).flatMap(([actionType, documentIds]) =>
+    Array.from(documentIds ?? []).map(
+      (documentId): DocumentEvent => ({
+        type: actionMap[actionType as MappedActionType],
+        documentId,
+        outgoing,
+      }),
     ),
   )
 }

package/src/document/listen.test.ts

@@ -205,4 +205,60 @@ describe('sortListenerEvents operator', () => {
     const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
     expect(events).toEqual([other])
   })
+
+  it('should discard replayed events already reflected in the base', async () => {
+    // The snapshot is at rev2; a resumed listener replays the event that
+    // produced rev2. It should be discarded instead of clogging the buffer.
+    const sync = createSyncEvent('rev2')
+    const replayed = createMutationEvent({
+      id: 'replayed',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const source$ = of(sync, replayed)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync])
+  })
+
+  it('should discard the replayed part of a chain and apply the rest', async () => {
+    // The snapshot is at rev2; the listener replays rev1->rev2 followed by a
+    // genuinely new rev2->rev3. Only the new event should be emitted.
+    const sync = createSyncEvent('rev2')
+    const replayed = createMutationEvent({
+      id: 'replayed',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const fresh = createMutationEvent({
+      id: 'fresh',
+      previousRev: 'rev2',
+      resultRev: 'rev3',
+    })
+    const source$ = of(sync, replayed, fresh)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync, fresh])
+  })
+
+  it('should discard a multi-event replayed chain that leads up to the base', async () => {
+    const sync = createSyncEvent('rev3')
+    // two replayed events that together lead up to the base revision
+    const replayedA = createMutationEvent({
+      id: 'replayedA',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const replayedB = createMutationEvent({
+      id: 'replayedB',
+      previousRev: 'rev2',
+      resultRev: 'rev3',
+    })
+    const fresh = createMutationEvent({
+      id: 'fresh',
+      previousRev: 'rev3',
+      resultRev: 'rev4',
+    })
+    const source$ = of(sync, replayedA, replayedB, fresh)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync, fresh])
+  })
 })