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

package/src/document/reducers.ts

@@ -1,31 +1,54 @@
-import {getPublishedId} from '@sanity/client/csm'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 import {type Mutation, type PatchOperations, type SanityDocumentLike} from '@sanity/types'
-import {omit} from 'lodash-es'
 
+import {type DocumentHandle} from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type StoreContext} from '../store/defineStore'
-import {getDraftId, insecureRandomId} from '../utils/ids'
-import {type DocumentAction} from './actions'
+import {insecureRandomId} from '../utils/ids'
+import {isDeepEqual, omitProperty} from '../utils/object'
+import {setCleanupTimeout} from '../utils/setCleanupTimeout'
+import {type Action} from './actions'
 import {DOCUMENT_STATE_CLEAR_DELAY} from './documentConstants'
 import {type DocumentState, type DocumentStoreState} from './documentStore'
 import {type RemoteDocument} from './listen'
-import {ActionError, processActions} from './processActions'
+import {ActionError, processActions} from './processActions/processActions'
+import {getReleaseDocumentId, isReleaseAction} from './processActions/releaseUtil'
 import {type DocumentSet} from './processMutations'
 
 const EMPTY_REVISIONS: NonNullable<Required<DocumentState['unverifiedRevisions']>> = {}
 
+/**
+ * How many of this client's own transaction IDs to remember per document for
+ * `remote-patches` origin labeling. Sized to comfortably outlast the window
+ * between submitting a transaction and observing its listener echo.
+ */
+const MAX_RECENT_OWN_TRANSACTION_IDS = 50
+
 export type SyncTransactionState = Pick<
   DocumentStoreState,
-  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants'
+  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants' | 'identity'
 >
 
+type DocumentHandleLike = Pick<DocumentHandle, 'perspective'> & {
+  documentId?: string
+  liveEdit?: boolean
+}
+
 type ActionMap = {
   create: 'sanity.action.document.version.create'
-  createLiveEdit: 'sanity.action.document.create'
   discard: 'sanity.action.document.version.discard'
   unpublish: 'sanity.action.document.unpublish'
   delete: 'sanity.action.document.delete'
   edit: 'sanity.action.document.edit'
   publish: 'sanity.action.document.publish'
+  releaseCreate: 'sanity.action.release.create'
+  releaseEdit: 'sanity.action.release.edit'
+  releasePublish: 'sanity.action.release.publish'
+  releaseSchedule: 'sanity.action.release.schedule'
+  releaseUnschedule: 'sanity.action.release.unschedule'
+  releaseArchive: 'sanity.action.release.archive'
+  releaseUnarchive: 'sanity.action.release.unarchive'
+  releaseDelete: 'sanity.action.release.delete'
 }
 
 type OptimisticLock = {
@@ -33,14 +56,33 @@ type OptimisticLock = {
   ifPublishedRevisionId?: string
 }
 
+interface ReleaseMetadataPayload {
+  title?: string
+  description?: string
+  intendedPublishAt?: string
+  releaseType?: 'asap' | 'scheduled' | 'undecided'
+  cardinality?: 'one' | 'many'
+}
+
 export type HttpAction =
   | {actionType: ActionMap['create']; publishedId: string; attributes: SanityDocumentLike}
-  | {actionType: ActionMap['createLiveEdit']; publishedId: string; attributes: SanityDocumentLike}
   | {actionType: ActionMap['discard']; versionId: string; purge?: boolean}
   | {actionType: ActionMap['unpublish']; draftId: string; publishedId: string}
   | {actionType: ActionMap['delete']; publishedId: string; includeDrafts?: string[]}
   | {actionType: ActionMap['edit']; draftId: string; publishedId: string; patch: PatchOperations}
   | ({actionType: ActionMap['publish']; draftId: string; publishedId: string} & OptimisticLock)
+  | {
+      actionType: ActionMap['releaseCreate']
+      releaseId: string
+      metadata?: ReleaseMetadataPayload
+    }
+  | {actionType: ActionMap['releaseEdit']; releaseId: string; patch: PatchOperations}
+  | {actionType: ActionMap['releasePublish']; releaseId: string}
+  | {actionType: ActionMap['releaseSchedule']; releaseId: string; publishAt: string}
+  | {actionType: ActionMap['releaseUnschedule']; releaseId: string}
+  | {actionType: ActionMap['releaseArchive']; releaseId: string}
+  | {actionType: ActionMap['releaseUnarchive']; releaseId: string}
+  | {actionType: ActionMap['releaseDelete']; releaseId: string}
 
 /**
  * Represents a transaction that is queued to be applied but has not yet been
@@ -57,7 +99,7 @@ export interface QueuedTransaction {
    * actions don't mention draft IDs and is meant to abstract away the draft
    * model from users.
    */
-  actions: DocumentAction[]
+  actions: Action[]
   /**
    * An optional flag set to disable this transaction from being batched with
    * other transactions.
@@ -115,9 +157,9 @@ export interface AppliedTransaction extends QueuedTransaction {
   outgoingActions: HttpAction[]
 
   /**
-   * similar to `outgoingActions` but comprised of mutations instead of action.
-   * this left here for debugging purposes but could be used to send mutations
-   * to Content Lake instead of actions.
+   * similar to `outgoingActions` but comprised of mutations instead of actions.
+   * Useful for debugging, and is also used by liveEdit documents to send mutations,
+   * since they can't use the Actions API which is pretty dependent on the draft model.
    */
   outgoingMutations: Mutation[]
 }
@@ -145,7 +187,7 @@ export function queueTransaction(
   transaction: QueuedTransaction,
 ): SyncTransactionState {
   const {transactionId, actions} = transaction
-  const prevWithSubscriptionIds = getDocumentIdsFromActions(actions).reduce(
+  const prevWithSubscriptionIds = getDocumentIdsFromHandleLikes(actions).reduce(
     (acc, id) => addSubscriptionIdToDocument(acc, id, transactionId),
     prev,
   )
@@ -163,7 +205,7 @@ export function removeQueuedTransaction(
   const transaction = prev.queued.find((t) => t.transactionId === transactionId)
   if (!transaction) return prev
 
-  const prevWithSubscriptionIds = getDocumentIdsFromActions(transaction.actions).reduce(
+  const prevWithSubscriptionIds = getDocumentIdsFromHandleLikes(transaction.actions).reduce(
     (acc, id) => removeSubscriptionIdFromDocument(acc, id, transactionId),
     prev,
   )
@@ -179,7 +221,7 @@ export function applyFirstQueuedTransaction(prev: SyncTransactionState): SyncTra
   if (!queued) return prev
   if (!prev.grants) return prev
 
-  const ids = getDocumentIdsFromActions(queued.actions)
+  const ids = getDocumentIdsFromHandleLikes(queued.actions)
   // the local value is only ever `undefined` if it has not been loaded yet
   // we can't get the next applied state unless all relevant documents are ready
   if (ids.some((id) => prev.documentStates[id]?.local === undefined)) return prev
@@ -197,6 +239,7 @@ export function applyFirstQueuedTransaction(prev: SyncTransactionState): SyncTra
     base: working,
     timestamp,
     grants: prev.grants,
+    identity: prev.identity,
   })
   const applied: AppliedTransaction = {
     ...queued,
@@ -265,6 +308,11 @@ export function batchAppliedTransactions([curr, ...rest]: AppliedTransaction[]):
   if (!next) return undefined
   if (next.disableBatching) return editAction
 
+  // Don't batch a liveEdit edit with a non-liveEdit edit — they route to different APIs
+  const nextFirst = next.actions[0]
+  const nextLiveEdit = nextFirst && 'liveEdit' in nextFirst ? nextFirst.liveEdit : false
+  if (!!action.liveEdit !== !!nextLiveEdit) return editAction
+
   return {
     disableBatching: false,
     // Use the transactionId from the later (next) transaction.
@@ -323,6 +371,15 @@ export function transitionAppliedTransactionsToOutgoing(
             // add unverified revision
             [transactionId]: {documentId, previousRev, transactionId, timestamp},
           },
+          // also track the transaction ID durably (unverified revisions can be
+          // pruned by sync events before the listener echo arrives) so
+          // `remote-patches` events label our own transactions correctly
+          recentOwnTransactionIds: [
+            ...(documentState.recentOwnTransactionIds ?? []).slice(
+              -(MAX_RECENT_OWN_TRANSACTION_IDS - 1),
+            ),
+            transactionId,
+          ],
         }
 
         return acc
@@ -337,7 +394,7 @@ export function cleanupOutgoingTransaction(prev: SyncTransactionState): SyncTran
   if (!outgoing) return prev
 
   let next = prev
-  const ids = getDocumentIdsFromActions(outgoing.actions)
+  const ids = getDocumentIdsFromHandleLikes(outgoing.actions)
   for (const transactionId of outgoing.batchedTransactionIds) {
     for (const documentId of ids) {
       next = removeSubscriptionIdFromDocument(next, documentId, transactionId)
@@ -349,8 +406,23 @@ export function cleanupOutgoingTransaction(prev: SyncTransactionState): SyncTran
 
 export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTransactionState {
   if (!prev.grants) return prev
+
+  // unregister the reverted batch's transaction-held subscriptions, symmetric
+  // with `cleanupOutgoingTransaction` on ack and `removeQueuedTransaction` on
+  // apply failure. without this, a reverted document's subscription IDs are
+  // never released and it can never be evicted
+  let base = prev
+  if (prev.outgoing) {
+    const ids = getDocumentIdsFromHandleLikes(prev.outgoing.actions)
+    for (const transactionId of prev.outgoing.batchedTransactionIds) {
+      for (const documentId of ids) {
+        base = removeSubscriptionIdFromDocument(base, documentId, transactionId)
+      }
+    }
+  }
+
   let working = Object.fromEntries(
-    Object.entries(prev.documentStates).map(([documentId, documentState]) => [
+    Object.entries(base.documentStates).map(([documentId, documentState]) => [
       documentId,
       documentState?.remote,
     ]),
@@ -359,7 +431,7 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
 
   for (const t of prev.applied) {
     try {
-      const next = processActions({...t, working, grants: prev.grants})
+      const next = processActions({...t, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       nextApplied.push({...t, ...next})
     } catch (error) {
@@ -371,11 +443,11 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
   }
 
   return {
-    ...prev,
+    ...base,
     applied: nextApplied,
     outgoing: undefined,
     documentStates: Object.fromEntries(
-      Object.entries(prev.documentStates)
+      Object.entries(base.documentStates)
         .filter((e): e is [string, DocumentState] => !!e[1])
         .map(([documentId, {unverifiedRevisions = {}, local, ...documentState}]) => {
           const next: DocumentState = {
@@ -383,7 +455,7 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
             local: documentId in working ? working[documentId] : local,
             unverifiedRevisions:
               prev.outgoing && prev.outgoing.transactionId in unverifiedRevisions
-                ? omit(unverifiedRevisions, prev.outgoing.transactionId)
+                ? omitProperty(unverifiedRevisions, prev.outgoing.transactionId)
                 : unverifiedRevisions,
           }
           return [documentId, next] as const
@@ -392,9 +464,29 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
   }
 }
 
+/**
+ * Extracts the patch operations addressed to the given document from a set of
+ * raw listener mutations, stripping the mutation-level `id` addressing so the
+ * patches are rooted at the document. A transaction can carry mutations for
+ * other documents, so anything not explicitly id-addressed to this document
+ * (including query-addressed patches) is dropped.
+ */
+function extractPatchOperations(
+  mutations: Mutation[] | undefined,
+  documentId: string,
+): PatchOperations[] {
+  if (!mutations) return []
+  return mutations.flatMap((mutation) => {
+    if (!('patch' in mutation) || !mutation.patch) return []
+    const {id, ...operations} = mutation.patch as PatchOperations & {id?: string}
+    if (id !== documentId) return []
+    return [operations]
+  })
+}
+
 export function applyRemoteDocument(
   prev: SyncTransactionState,
-  {document, documentId, previousRev, revision, timestamp, type}: RemoteDocument,
+  {document, documentId, previousRev, revision, timestamp, type, mutations}: RemoteDocument,
   events: DocumentStoreState['events'],
 ): SyncTransactionState {
   if (!prev.grants) return prev
@@ -411,7 +503,32 @@ export function applyRemoteDocument(
   const revisionToVerify = revision ? prevUnverifiedRevisions?.[revision] : undefined
   let unverifiedRevisions = prevUnverifiedRevisions ?? EMPTY_REVISIONS
   if (revision && revisionToVerify) {
-    unverifiedRevisions = omit(prevUnverifiedRevisions, revision)
+    unverifiedRevisions = omitProperty(prevUnverifiedRevisions, revision)
+  }
+
+  // surface the operational patches from this transaction before they are
+  // collapsed into the whole-document snapshot below. consumers that keep
+  // their own state (e.g. collaborative text editors) rely on these to apply
+  // remote changes without re-diffing document snapshots
+  if (type === 'mutation' && revision) {
+    const patches = extractPatchOperations(mutations, documentId)
+    if (patches.length) {
+      // `unverifiedRevisions` alone isn't a reliable origin marker: a sync
+      // event can prune an in-flight transaction's entry before its listener
+      // echo arrives. `recentOwnTransactionIds` survives that race
+      const isOwnTransaction =
+        Boolean(revisionToVerify) ||
+        (prevDocState.recentOwnTransactionIds?.includes(revision) ?? false)
+      events.next({
+        type: 'remote-patches',
+        documentId,
+        transactionId: revision,
+        previousRev,
+        timestamp,
+        patches,
+        origin: isOwnTransaction ? 'local' : 'remote',
+      })
+    }
   }
 
   // if this remote document is from a `'sync'` event (meaning that the whole
@@ -432,6 +549,34 @@ export function applyRemoteDocument(
   // matches the previous revision we expected, we can "fast-forward" and skip
   // rebasing local changes on top of this new base
   if (revisionToVerify && revisionToVerify.previousRev === previousRev) {
+    // even on a clean fast-forward, the server's result can differ from our
+    // optimistic prediction: a publish derives the published content from the
+    // server's copy of the draft, which may carry concurrent edits our
+    // prediction never saw. once nothing else is pending locally for this
+    // document (no applied transaction and no in-flight transaction, other
+    // than the one this event just confirmed, modifies it), converge `local`
+    // to the server's document. while local work that modifies this document
+    // is pending, keep the optimistic `local` so those changes stay visible;
+    // that work's own echo (or rebase) recomputes `local` later.
+    //
+    // "modifies" matters: pending work on other documents must not block
+    // convergence here (nothing would ever revisit this document's `local`),
+    // and a pending draft edit carries the published document in its working
+    // set without changing it, so a presence check would block published-doc
+    // convergence whenever a draft edit is pending. this is the same
+    // modified-test `transitionAppliedTransactionsToOutgoing` uses
+    const modifiesDocument = (transaction: AppliedTransaction) =>
+      transaction.working[documentId]?._rev !== transaction.previousRevs[documentId]
+    const nothingElsePending =
+      !prev.applied.some(modifiesDocument) &&
+      (!prev.outgoing ||
+        prev.outgoing.transactionId === revision ||
+        !modifiesDocument(prev.outgoing))
+    const local =
+      nothingElsePending && !isDeepEqual(prevDocState.local, document)
+        ? document
+        : prevDocState.local
+
     return {
       ...prev,
       documentStates: {
@@ -440,6 +585,7 @@ export function applyRemoteDocument(
           ...prevDocState,
           remote: document,
           remoteRev: revision,
+          local,
           unverifiedRevisions,
         },
       },
@@ -466,7 +612,7 @@ export function applyRemoteDocument(
   // transaction again through the listener and this same flow will run then
   for (const curr of prev.applied) {
     try {
-      const next = processActions({...curr, working, grants: prev.grants})
+      const next = processActions({...curr, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       // next includes an updated `previous` set and `working` set and updates
       // the `outgoingAction` and `outgoingMutations`. the `base` set from the
@@ -490,6 +636,12 @@ export function applyRemoteDocument(
     }
   }
 
+  // when the recompute lands on a value deep-equal to the current local
+  // (the common case for echoes of our own transactions), keep the previous
+  // reference so subscribers don't re-render for an identical value
+  const nextLocal = working[documentId]
+  const local = isDeepEqual(prevDocState.local, nextLocal) ? prevDocState.local : nextLocal
+
   return {
     ...prev,
     applied: nextApplied,
@@ -499,7 +651,7 @@ export function applyRemoteDocument(
         ...prevDocState,
         remote: document,
         remoteRev: revision,
-        local: working[documentId],
+        local,
         unverifiedRevisions,
       },
     },
@@ -538,7 +690,7 @@ export function removeSubscriptionIdFromDocument(
 
   if (!prevDocState) return prev
   if (!subscriptions.length) {
-    return {...prev, documentStates: omit(prev.documentStates, documentId)}
+    return {...prev, documentStates: omitProperty(prev.documentStates, documentId)}
   }
   return {
     ...prev,
@@ -551,22 +703,10 @@ export function removeSubscriptionIdFromDocument(
 
 export function manageSubscriberIds(
   {state}: StoreContext<SyncTransactionState>,
-  documentId: string | string[],
-  options?: {expandDraftPublished?: boolean},
+  handles: DocumentHandleLike[],
 ): () => void {
-  const expandDraftPublished = options?.expandDraftPublished ?? true
-  const documentIds = Array.from(
-    new Set(
-      expandDraftPublished
-        ? (Array.isArray(documentId) ? documentId : [documentId]).flatMap((id) => [
-            getPublishedId(id),
-            getDraftId(id),
-          ])
-        : Array.isArray(documentId)
-          ? documentId
-          : [documentId],
-    ),
-  )
+  const documentIds = getDocumentIdsFromHandleLikes(handles)
+
   const subscriptionId = insecureRandomId()
   state.set('addSubscribers', (prev) =>
     documentIds.reduce(
@@ -576,7 +716,7 @@ export function manageSubscriberIds(
   )
 
   return () => {
-    setTimeout(() => {
+    setCleanupTimeout(() => {
       state.set('removeSubscribers', (prev) =>
         documentIds.reduce(
           (acc, id) => removeSubscriptionIdFromDocument(acc, id, subscriptionId),
@@ -587,13 +727,27 @@ export function manageSubscriberIds(
   }
 }
 
-export function getDocumentIdsFromActions(actions: DocumentAction[]): string[] {
-  return Array.from(
-    new Set(
-      actions
-        .map((i) => i.documentId)
-        .filter((i) => typeof i === 'string')
-        .flatMap((documentId) => [getPublishedId(documentId), getDraftId(documentId)]),
-    ),
-  )
+// document handles are passed in via the public facing API, but we also need to
+// pull the correct document ids from action bodies, which have similar but not
+// identical shapes to the document handles. release actions also flow through
+// here, and resolve to the underlying release document id.
+function getDocumentIdsFromHandleLikes(handles: (DocumentHandleLike | Action)[]): string[] {
+  return handles.flatMap((handle) => {
+    if ('type' in handle && isReleaseAction(handle)) {
+      return [getReleaseDocumentId(handle.releaseId)]
+    }
+    const idsForDocument = []
+    if (!handle.documentId) return []
+    if (handle.liveEdit) {
+      return [handle.documentId]
+    }
+    if (isReleasePerspective(handle.perspective)) {
+      idsForDocument.push(
+        getVersionId(DocumentId(handle.documentId), handle.perspective.releaseName),
+      )
+    }
+    idsForDocument.push(getPublishedId(DocumentId(handle.documentId)))
+    idsForDocument.push(getDraftId(DocumentId(handle.documentId)))
+    return idsForDocument
+  })
 }

package/src/document/resourceRules.test.ts

@@ -0,0 +1,178 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {type EditDocumentAction} from './actions'
+import {getEffectiveDocumentModel, normalizeActionsForResource} from './resourceRules'
+
+const datasetResource = {projectId: 'p', dataset: 'd'}
+const canvasResource = {canvasId: 'canvas-1'}
+const mediaLibraryResource = {mediaLibraryId: 'ml-1'}
+
+function editAction(
+  overrides: Partial<EditDocumentAction> & Pick<EditDocumentAction, 'documentId' | 'documentType'>,
+): EditDocumentAction {
+  return {
+    type: 'document.edit',
+    patches: [{set: {foo: 'bar'}}],
+    ...overrides,
+  }
+}
+
+describe('getEffectiveDocumentModel', () => {
+  it('returns passthrough for no resource', () => {
+    expect(getEffectiveDocumentModel(undefined, 'anything')).toEqual({
+      liveEdit: undefined,
+      supportsReleases: true,
+    })
+  })
+
+  it('returns passthrough for dataset resources', () => {
+    expect(getEffectiveDocumentModel(datasetResource, 'author')).toEqual({
+      liveEdit: undefined,
+      supportsReleases: true,
+    })
+  })
+
+  it('forces liveEdit and disallows releases for canvas resources', () => {
+    expect(getEffectiveDocumentModel(canvasResource, 'page')).toEqual({
+      liveEdit: true,
+      supportsReleases: false,
+    })
+  })
+
+  it('forces liveEdit for non-asset media library types', () => {
+    expect(getEffectiveDocumentModel(mediaLibraryResource, 'sanity.imageAsset')).toEqual({
+      liveEdit: true,
+      supportsReleases: false,
+    })
+  })
+
+  it('keeps draft/published model for sanity.asset in media library', () => {
+    expect(getEffectiveDocumentModel(mediaLibraryResource, 'sanity.asset')).toEqual({
+      liveEdit: false,
+      supportsReleases: false,
+    })
+  })
+})
+
+describe('normalizeActionsForResource', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+  })
+
+  afterEach(() => {
+    warnSpy.mockRestore()
+  })
+
+  it('leaves dataset edits with a release perspective alone', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'author',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const result = normalizeActionsForResource([action], datasetResource)
+
+    expect(result[0]).toBe(action)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('strips release perspective and forces liveEdit for canvas, warning once', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], canvasResource) as [EditDocumentAction]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('Canvas')
+    expect(warnSpy.mock.calls[0][0]).toContain('page (doc1)')
+  })
+
+  it('strips release perspective and forces liveEdit for non-asset media library types', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'sanity.imageAsset',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], mediaLibraryResource) as [
+      EditDocumentAction,
+    ]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('Media Library')
+  })
+
+  it('strips release perspective but keeps draft/publish model for sanity.asset', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'sanity.asset',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], mediaLibraryResource) as [
+      EditDocumentAction,
+    ]
+
+    expect(result.liveEdit).toBeUndefined()
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('silently forces liveEdit for canvas with no release perspective', () => {
+    const action = editAction({
+      documentId: 'drafts.doc1',
+      documentType: 'page',
+      perspective: 'drafts',
+    })
+
+    const [result] = normalizeActionsForResource([action], canvasResource) as [EditDocumentAction]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('emits a single warning for multiple stripped actions in one call', () => {
+    const a = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+    const b = editAction({
+      documentId: 'versions.relA.doc2',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+
+    normalizeActionsForResource([a, b], canvasResource)
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('doc1')
+    expect(warnSpy.mock.calls[0][0]).toContain('doc2')
+  })
+
+  it('passes non-edit actions through unchanged', () => {
+    const action = {
+      type: 'document.publish' as const,
+      documentId: 'doc1',
+      documentType: 'page',
+    }
+
+    const result = normalizeActionsForResource([action], canvasResource)
+
+    expect(result[0]).toBe(action)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+})