In frontend/packages/shared/src/content.ts, next to extractAllContentRefs:

export function findDraftReferences(blocks: HMBlockNode[]): RefDefinition[] {
  return extractAllContentRefs(blocks).filter((ref) =>
    ref.refId.path?.some((seg) => seg.startsWith('-'))
  )
}

Rationale: extractAllContentRefs already handles every URL-bearing surface (embed, link block, button, image/video/file, query includes[].space, inline link/embed annotations) and recurses children. We only need the draft-segment filter.

Add to context shape (near line 85):

publishBlocked: {reason: 'draft-links'} | null

Initial value null (extend the error: null init around line 585).

Extend the publish.start event type so it carries blocks:

| {type: 'publish.start'; pathOverride?: string[]; blocks?: HMBlockNode[]}

Add a guard in setup({guards: {...}}):

hasDraftReferences: ({event}) => {
  if (event.type !== 'publish.start') return false
  return findDraftReferences(event.blocks ?? []).length > 0
}

Add a clearPublishBlocked action:

clearPublishBlocked: assign({publishBlocked: null})

Replace the publish.start transition (current line 764–768) with an ordered conditional array (XState v5 on accepts array of transitions; first matching guard wins):

'publish.start': [
  {
    guard: 'hasDraftReferences',
    actions: [assign({publishBlocked: () => ({reason: 'draft-links'})})],
    // No target — stay in editing.draft.idle, just assign context.
  },
  {
    target: '#DocumentLifecycle.publishing',
    guard: 'hasDraftId',
    actions: ['clearPublishBlocked', 'setPathOverrideFromEvent'],
  },
],

Also clear publishBlocked on change and reset.content actions in editing.draft.idle (and in editing.draft.changed) so the error disappears as soon as the user edits.

Add a dismiss event for explicit close:

'publish.blocked.dismiss': {
  actions: ['clearPublishBlocked'],
}

In frontend/packages/shared/src/models/document-machine.ts (or wherever selectors live — selectDraftId already exists nearby), add:

export const selectPublishBlocked = (state: DocumentMachineSnapshot) => state.context.publishBlocked

In publishNow (line 397):

const handlersRef = useEditorHandlersRef()

const publishNow = (pathOverride?: string[]) => {
  popoverState.onOpenChange(false)
  setHasTriggeredPublish()
  send({type: 'edit.start'})
  const blocks = handlersRef.current?.getCurrentBlocks() ?? []
  send({type: 'publish.start', pathOverride, blocks})
}

Note: do NOT close the popover before sending the event. Reorder so the popover stays open if the publish is blocked:

const publishNow = (pathOverride?: string[]) => {
  setHasTriggeredPublish()
  send({type: 'edit.start'})
  const blocks = handlersRef.current?.getCurrentBlocks() ?? []
  send({type: 'publish.start', pathOverride, blocks})
  // Caller side-effect: popover stays open if context.publishBlocked got set.
}

In PublishPopoverBody (line 124), read the blocked state and render an inline error block above the publish button when publishBlocked is set. On onClose, dispatch publish.blocked.dismiss so the next popover open starts clean.

const publishBlocked = useDocumentSelector(selectPublishBlocked)
// ...
{publishBlocked?.reason === 'draft-links' && (
  <div role="alert" className="...error styling...">
    Publish the referenced drafts first before publishing this document.
  </div>
)}

Disable the publish button while publishBlocked is set, so the user must either edit content (auto-clears) or close.