@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/src/modules/documents/backend/documents/[id]/documentPagination.ts

@@ -0,0 +1,352 @@
+import { Extension } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey, type EditorState, type Transaction } from '@tiptap/pm/state'
+import { Decoration, DecorationSet, type EditorView } from '@tiptap/pm/view'
+
+export const A4_PAGE_WIDTH_MM = 210
+export const A4_PAGE_HEIGHT_MM = 297
+export const DOCUMENT_PAGE_HORIZONTAL_MARGIN_MM = 20
+export const DOCUMENT_PAGE_VERTICAL_MARGIN_MM = 22
+export const DOCUMENT_PAGE_GUTTER_PX = 24
+
+const CSS_PIXELS_PER_MM = 96 / 25.4
+const PAGE_CONTENT_HEIGHT_PX = (
+  A4_PAGE_HEIGHT_MM - (DOCUMENT_PAGE_VERTICAL_MARGIN_MM * 2)
+) * CSS_PIXELS_PER_MM
+const PAGE_VERTICAL_MARGIN_PX = DOCUMENT_PAGE_VERTICAL_MARGIN_MM * CSS_PIXELS_PER_MM
+const PAGE_BREAK_EPSILON_PX = 0.5
+export const DOCUMENT_PAGINATION_UPDATE_DELAY_MS = 120
+
+export type PaginationBlockMeasurement = {
+  position: number
+  top: number
+  bottom: number
+}
+
+export type DocumentPageBreak = {
+  position: number
+  remainingContentHeight: number
+  totalHeight: number
+}
+
+type PaginationPluginState = {
+  breaks: DocumentPageBreak[]
+  decorations: DecorationSet
+}
+
+type PaginationMeta = {
+  breaks: DocumentPageBreak[]
+}
+
+export const DOCUMENT_PAGINATION_PLUGIN_KEY = new PluginKey<PaginationPluginState>('documentsPagination')
+
+function nextPageBreak(
+  position: number,
+  remainingContentHeight: number,
+  pageMarginHeight: number,
+  pageGutterHeight: number,
+): DocumentPageBreak {
+  const safeRemaining = Math.max(0, remainingContentHeight)
+  return {
+    position,
+    remainingContentHeight: safeRemaining,
+    totalHeight: safeRemaining + (pageMarginHeight * 2) + pageGutterHeight,
+  }
+}
+
+export function calculateDocumentPageBreaks(
+  blocks: PaginationBlockMeasurement[],
+  options: {
+    pageContentHeight?: number
+    firstPageUsedHeight?: number
+    pageMarginHeight?: number
+    pageGutterHeight?: number
+  } = {},
+): DocumentPageBreak[] {
+  const pageContentHeight = Math.max(1, options.pageContentHeight ?? PAGE_CONTENT_HEIGHT_PX)
+  const firstPageUsedHeight = Math.max(0, options.firstPageUsedHeight ?? 0)
+  const pageMarginHeight = Math.max(0, options.pageMarginHeight ?? PAGE_VERTICAL_MARGIN_PX)
+  const pageGutterHeight = Math.max(0, options.pageGutterHeight ?? DOCUMENT_PAGE_GUTTER_PX)
+  const breaks: DocumentPageBreak[] = []
+  let pageStart = -Math.min(firstPageUsedHeight, pageContentHeight)
+  let pageBottom = pageStart + pageContentHeight
+
+  for (const block of blocks) {
+    const top = Math.max(0, block.top)
+    const bottom = Math.max(top, block.bottom)
+    const height = bottom - top
+    if (bottom <= pageBottom + PAGE_BREAK_EPSILON_PX) continue
+
+    const hasEarlierContentOnPage = top > pageStart + PAGE_BREAK_EPSILON_PX
+    if (height > pageContentHeight) {
+      if (hasEarlierContentOnPage) {
+        breaks.push(nextPageBreak(
+          block.position,
+          pageBottom - top,
+          pageMarginHeight,
+          pageGutterHeight,
+        ))
+        pageStart = top
+        pageBottom = pageStart + pageContentHeight
+      }
+      while (bottom > pageBottom + PAGE_BREAK_EPSILON_PX) {
+        pageStart = pageBottom
+        pageBottom = pageStart + pageContentHeight
+      }
+      continue
+    }
+
+    breaks.push(nextPageBreak(
+      block.position,
+      pageBottom - top,
+      pageMarginHeight,
+      pageGutterHeight,
+    ))
+    pageStart = top
+    pageBottom = pageStart + pageContentHeight
+  }
+
+  return breaks
+}
+
+function createPageBreakDom(pageBreak: DocumentPageBreak, pageNumber: number): HTMLElement {
+  const root = document.createElement('div')
+  root.className = 'om-doc-page-break'
+  root.contentEditable = 'false'
+  root.setAttribute('aria-hidden', 'true')
+  root.setAttribute('data-document-page-break', '')
+
+  const pageEnd = document.createElement('div')
+  pageEnd.className = 'om-doc-page-end'
+  pageEnd.style.height = `${pageBreak.remainingContentHeight + PAGE_VERTICAL_MARGIN_PX}px`
+  const pageNumberLabel = document.createElement('span')
+  pageNumberLabel.className = 'om-doc-page-number'
+  pageNumberLabel.textContent = String(pageNumber)
+  pageEnd.append(pageNumberLabel)
+  const gutter = document.createElement('div')
+  gutter.className = 'om-doc-page-gutter'
+  gutter.style.height = `${DOCUMENT_PAGE_GUTTER_PX}px`
+  const pageStart = document.createElement('div')
+  pageStart.className = 'om-doc-page-start'
+  pageStart.setAttribute('data-document-page-start', '')
+  pageStart.style.height = `${PAGE_VERTICAL_MARGIN_PX}px`
+  root.append(pageEnd, gutter, pageStart)
+  return root
+}
+
+function createDecorations(doc: ProseMirrorNode, breaks: DocumentPageBreak[]): DecorationSet {
+  return DecorationSet.create(doc, breaks.map((pageBreak, index) => Decoration.widget(
+    pageBreak.position,
+    () => createPageBreakDom(pageBreak, index + 1),
+    {
+      key: [
+        'document-page-break',
+        pageBreak.position,
+        index + 1,
+        pageBreak.remainingContentHeight,
+      ].join(':'),
+      side: -1,
+      ignoreSelection: true,
+    },
+  )))
+}
+
+function readPaginationMeta(transaction: Transaction): PaginationMeta | null {
+  const meta = transaction.getMeta(DOCUMENT_PAGINATION_PLUGIN_KEY) as PaginationMeta | undefined
+  return meta && Array.isArray(meta.breaks) ? meta : null
+}
+
+function paginationStateApply(
+  transaction: Transaction,
+  current: PaginationPluginState,
+  _oldState: EditorState,
+  newState: EditorState,
+): PaginationPluginState {
+  const meta = readPaginationMeta(transaction)
+  if (meta) {
+    return {
+      breaks: meta.breaks,
+      decorations: createDecorations(newState.doc, meta.breaks),
+    }
+  }
+  if (!transaction.docChanged) return current
+  const mappedBreaks = current.breaks.map((pageBreak) => ({
+    ...pageBreak,
+    position: transaction.mapping.map(pageBreak.position, -1),
+  }))
+  return {
+    breaks: mappedBreaks,
+    decorations: current.decorations.map(transaction.mapping, transaction.doc),
+  }
+}
+
+function breaksEqual(left: DocumentPageBreak[], right: DocumentPageBreak[]): boolean {
+  return left.length === right.length && left.every((value, index) => {
+    const candidate = right[index]
+    return candidate !== undefined
+      && value.position === candidate.position
+      && Math.abs(value.remainingContentHeight - candidate.remainingContentHeight) < PAGE_BREAK_EPSILON_PX
+      && Math.abs(value.totalHeight - candidate.totalHeight) < PAGE_BREAK_EPSILON_PX
+  })
+}
+
+function measureTopLevelBlocks(view: EditorView, currentBreaks: DocumentPageBreak[]): PaginationBlockMeasurement[] {
+  const rootRect = view.dom.getBoundingClientRect()
+  const paper = view.dom.closest<HTMLElement>('.om-doc-paper')
+  const paperWidthCssPx = A4_PAGE_WIDTH_MM * CSS_PIXELS_PER_MM
+  const scale = paper ? Math.max(0.01, paper.getBoundingClientRect().width / paperWidthCssPx) : 1
+  const blocks: PaginationBlockMeasurement[] = []
+  let breakIndex = 0
+  let insertedHeight = 0
+
+  view.state.doc.forEach((_node, position) => {
+    const nodeDom = view.nodeDOM(position)
+    if (!(nodeDom instanceof HTMLElement)) return
+    const rect = nodeDom.getBoundingClientRect()
+    while (breakIndex < currentBreaks.length) {
+      const pageBreak = currentBreaks[breakIndex]
+      if (!pageBreak || pageBreak.position > position) break
+      insertedHeight += pageBreak.totalHeight
+      breakIndex += 1
+    }
+    blocks.push({
+      position,
+      top: ((rect.top - rootRect.top) / scale) - insertedHeight,
+      bottom: ((rect.bottom - rootRect.top) / scale) - insertedHeight,
+    })
+  })
+  return blocks
+}
+
+function firstPageUsedHeight(view: EditorView): number {
+  const paper = view.dom.closest<HTMLElement>('.om-doc-paper')
+  if (!paper) return 0
+  const paperRect = paper.getBoundingClientRect()
+  const paperWidthCssPx = A4_PAGE_WIDTH_MM * CSS_PIXELS_PER_MM
+  const scale = Math.max(0.01, paperRect.width / paperWidthCssPx)
+  const paddingTop = Number.parseFloat(getComputedStyle(paper).paddingTop) || PAGE_VERTICAL_MARGIN_PX
+  return Math.max(0, ((view.dom.getBoundingClientRect().top - paperRect.top) / scale) - paddingTop)
+}
+
+export function createDocumentPaginationPlugin(): Plugin<PaginationPluginState> {
+  return new Plugin<PaginationPluginState>({
+    key: DOCUMENT_PAGINATION_PLUGIN_KEY,
+    state: {
+      init: () => ({ breaks: [], decorations: DecorationSet.empty }),
+      apply: paginationStateApply,
+    },
+    props: {
+      decorations: (state) => DOCUMENT_PAGINATION_PLUGIN_KEY.getState(state)?.decorations ?? null,
+    },
+    view: (view) => {
+      let frame: number | null = null
+      let updateTimer: number | null = null
+      let destroyed = false
+      const recompute = () => {
+        frame = null
+        if (destroyed) return
+        const current = DOCUMENT_PAGINATION_PLUGIN_KEY.getState(view.state)?.breaks ?? []
+        const next = calculateDocumentPageBreaks(measureTopLevelBlocks(view, current), {
+          firstPageUsedHeight: firstPageUsedHeight(view),
+        })
+        if (breaksEqual(current, next)) return
+        view.dispatch(
+          view.state.tr
+            .setMeta(DOCUMENT_PAGINATION_PLUGIN_KEY, { breaks: next } satisfies PaginationMeta)
+            .setMeta('addToHistory', false),
+        )
+      }
+      const schedule = () => {
+        if (destroyed || frame !== null) return
+        if (updateTimer !== null) {
+          window.clearTimeout(updateTimer)
+          updateTimer = null
+        }
+        frame = requestAnimationFrame(recompute)
+      }
+      const scheduleDocumentUpdate = () => {
+        if (destroyed) return
+        if (updateTimer !== null) window.clearTimeout(updateTimer)
+        updateTimer = window.setTimeout(() => {
+          updateTimer = null
+          schedule()
+        }, DOCUMENT_PAGINATION_UPDATE_DELAY_MS)
+      }
+      const resizeObserver = typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(schedule)
+      resizeObserver?.observe(view.dom)
+      const paper = view.dom.closest<HTMLElement>('.om-doc-paper')
+      if (paper) resizeObserver?.observe(paper)
+      view.dom.addEventListener('load', schedule, true)
+      window.addEventListener('resize', schedule)
+      schedule()
+
+      return {
+        update: (_nextView, previousState) => {
+          if (previousState.doc === view.state.doc) return
+          scheduleDocumentUpdate()
+        },
+        destroy: () => {
+          destroyed = true
+          if (frame !== null) cancelAnimationFrame(frame)
+          if (updateTimer !== null) window.clearTimeout(updateTimer)
+          resizeObserver?.disconnect()
+          view.dom.removeEventListener('load', schedule, true)
+          window.removeEventListener('resize', schedule)
+        },
+      }
+    },
+  })
+}
+
+export const DocumentPagination = Extension.create({
+  name: 'documentPagination',
+  addProseMirrorPlugins() {
+    return [createDocumentPaginationPlugin()]
+  },
+})
+
+export const DOCUMENT_PAGINATION_STYLES = `
+.om-doc-paper {
+  box-sizing: border-box;
+  width: ${A4_PAGE_WIDTH_MM}mm;
+  min-width: ${A4_PAGE_WIDTH_MM}mm;
+  max-width: ${A4_PAGE_WIDTH_MM}mm;
+  min-height: ${A4_PAGE_HEIGHT_MM}mm;
+  padding: ${DOCUMENT_PAGE_VERTICAL_MARGIN_MM}mm ${DOCUMENT_PAGE_HORIZONTAL_MARGIN_MM}mm;
+}
+.om-doc-canvas {
+  overflow-x: auto;
+  scrollbar-gutter: stable;
+  overscroll-behavior-inline: contain;
+}
+.om-doc-paper .om-doc-page-break {
+  display: block;
+  width: ${A4_PAGE_WIDTH_MM}mm;
+  margin-left: -${DOCUMENT_PAGE_HORIZONTAL_MARGIN_MM}mm;
+  pointer-events: none;
+  user-select: none;
+}
+.om-doc-paper .om-doc-page-end,
+.om-doc-paper .om-doc-page-start {
+  background: var(--card);
+}
+.om-doc-paper .om-doc-page-end {
+  position: relative;
+}
+.om-doc-paper .om-doc-page-number {
+  position: absolute;
+  right: ${DOCUMENT_PAGE_HORIZONTAL_MARGIN_MM}mm;
+  bottom: 6mm;
+  color: var(--muted-foreground);
+  font-size: 0.75rem;
+  line-height: 1rem;
+}
+.om-doc-paper .om-doc-page-gutter {
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+  background: var(--muted);
+  box-shadow: inset 0 1px 2px color-mix(in oklab, var(--foreground) 8%, transparent);
+}
+`

package/src/modules/documents/backend/documents/[id]/editorPresenceStyles.ts

@@ -0,0 +1,77 @@
+export const EDITOR_PRESENCE_STYLES = `
+.om-doc-collab .collaboration-carets__caret {
+  position: relative;
+  margin-left: -1px;
+  margin-right: -1px;
+  border-left-width: 2px;
+  border-left-style: solid;
+  border-right-width: 0;
+  box-sizing: border-box;
+  cursor: help;
+  pointer-events: auto;
+}
+.om-doc-collab .collaboration-carets__caret::before {
+  position: absolute;
+  top: -0.4em;
+  bottom: -0.4em;
+  left: -7px;
+  width: 14px;
+  content: '';
+}
+.om-doc-collab .collaboration-carets__label {
+  position: absolute;
+  top: -1.55em;
+  left: -2px;
+  max-width: 180px;
+  overflow: hidden;
+  border-radius: var(--radius-sm, 0.25rem);
+  padding: 1px 6px;
+  color: var(--primary-foreground);
+  font-size: var(--font-size-overline);
+  font-weight: 600;
+  line-height: var(--font-size-overline--line-height);
+  opacity: 0;
+  pointer-events: none;
+  text-overflow: ellipsis;
+  user-select: none;
+  white-space: nowrap;
+  animation: om-doc-caret-flag 2.6s ease forwards;
+}
+.om-doc-collab .collaboration-carets__caret:hover .collaboration-carets__label,
+.om-doc-collab .collaboration-carets__caret:focus .collaboration-carets__label,
+.om-doc-collab .collaboration-carets__caret:focus-visible .collaboration-carets__label {
+  animation: none;
+  opacity: 1;
+}
+.om-doc-collab .collaboration-carets__caret:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+.om-doc-preview .collaboration-carets__caret,
+.om-doc-preview .ProseMirror-yjs-selection {
+  display: none;
+}
+.ProseMirror .om-entity-ref {
+  display: inline-flex;
+  align-items: center;
+  max-width: 100%;
+  border: 1px solid color-mix(in oklab, var(--primary) 24%, transparent);
+  border-radius: var(--radius-sm, 0.25rem);
+  background: color-mix(in oklab, var(--primary) 12%, transparent);
+  color: var(--primary);
+  cursor: default;
+  font-weight: 500;
+  line-height: 1.6;
+  padding: 0 0.375em;
+  vertical-align: baseline;
+  white-space: nowrap;
+}
+@keyframes om-doc-caret-flag {
+  0% { opacity: 0; transform: translateY(3px); }
+  8%, 52% { opacity: 1; transform: translateY(0); }
+  100% { opacity: 0; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .om-doc-collab .collaboration-carets__label { animation: none; opacity: 1; }
+}
+`

package/src/modules/documents/backend/documents/[id]/editorTypes.ts

@@ -0,0 +1,84 @@
+import type { Editor } from '@tiptap/core'
+import type { HocuspocusProvider } from '@hocuspocus/provider'
+import type * as Y from 'yjs'
+import { cn } from '@open-mercato/shared/lib/utils'
+import type { CommentAnchor } from './CommentAnchorNavigation'
+
+export type CollabTokenUser = { id: string; name: string; color: string }
+export type CollabResources = { ydoc: Y.Doc; provider: HocuspocusProvider; user: CollabTokenUser }
+export type PresenceUser = { key: string; name: string; color: string }
+export type ConnectionStatus = 'connecting' | 'connected' | 'reconnecting' | 'offline'
+export type EditorSelectionRange = { from: number; to: number }
+export type EditorWordCount = { words: number; characters: number }
+export type EditorMode = 'edit' | 'preview'
+
+export type DocumentEditorIslandProps = {
+  documentId: string
+  title: string
+  initialContentHtml: string
+  contentUpdatedAt?: string | null
+  documentUpdatedAt?: string | null
+  readOnly: boolean
+  onEditorReady?: (editor: Editor | null) => void
+  onComment?: (anchor: CommentAnchor) => void
+  onContentConflict?: () => void
+  onTitleChange?: (title: string, updatedAt: string | null) => void
+}
+
+export type CollabState =
+  | { mode: 'connecting' }
+  | { mode: 'fallback'; readOnly: boolean }
+  | { mode: 'collab'; resources: CollabResources; connectionStatus: ConnectionStatus; presenceUsers: PresenceUser[]; serverReadOnly: boolean }
+
+export function resolveEditorMode(readOnly: boolean, serverReadOnly: boolean, requested: EditorMode): EditorMode {
+  return readOnly || serverReadOnly ? 'preview' : requested
+}
+
+export function canCreateSelectionComment(input: {
+  permissionReadOnly: boolean
+  mode: EditorMode
+  transport: 'collab' | 'fallback'
+  hasCommentHandler: boolean
+}): boolean {
+  if (!input.hasCommentHandler || input.transport !== 'collab') return false
+  const effectiveReadOnly = input.permissionReadOnly || input.mode === 'preview'
+  return !effectiveReadOnly || input.permissionReadOnly
+}
+
+export function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null
+}
+
+export function readString(record: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = record[key]
+    if (typeof value === 'string' && value.trim()) return value
+  }
+  return null
+}
+
+export function readNumber(record: Record<string, unknown>, ...keys: string[]): number | null {
+  for (const key of keys) {
+    const value = record[key]
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+  }
+  return null
+}
+
+export const DOCUMENT_EDITOR_CONTENT_CLASS = cn(
+  'max-w-none text-foreground',
+  '[&_.ProseMirror]:min-h-96 [&_.ProseMirror]:focus-visible:outline-none',
+  '[&_.ProseMirror>*:first-child]:mt-0 [&_.ProseMirror>*:last-child]:mb-0',
+  '[&_h1]:mb-4 [&_h1]:mt-8 [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:leading-tight',
+  '[&_h2]:mb-3 [&_h2]:mt-7 [&_h2]:text-2xl [&_h2]:font-semibold [&_h2]:leading-tight',
+  '[&_h3]:mb-2 [&_h3]:mt-6 [&_h3]:text-xl [&_h3]:font-semibold',
+  '[&_p]:my-4 [&_p]:leading-7 [&_ul]:my-4 [&_ul]:list-disc [&_ul]:pl-6',
+  '[&_ol]:my-4 [&_ol]:list-decimal [&_ol]:pl-6 [&_li]:my-1',
+  '[&_blockquote]:my-6 [&_blockquote]:border-l-4 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:italic',
+  '[&_pre]:my-6 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-muted [&_pre]:p-4 [&_pre]:font-mono [&_pre]:text-sm',
+  '[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4',
+  '[&_img]:my-6 [&_img]:h-auto [&_img]:max-w-full [&_img]:rounded-md',
+  '[&_table]:my-6 [&_table]:w-full [&_table]:border-collapse',
+  '[&_td]:border [&_td]:border-border [&_td]:px-3 [&_td]:py-2',
+  '[&_th]:border [&_th]:border-border [&_th]:bg-muted [&_th]:px-3 [&_th]:py-2 [&_th]:text-left',
+)

package/src/modules/documents/backend/documents/[id]/page.meta.ts

@@ -0,0 +1,12 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['documents.view'],
+  pageTitle: 'Document',
+  pageTitleKey: 'documents.nav.document',
+  pageGroup: 'Documents',
+  pageGroupKey: 'documents.nav.group',
+  breadcrumb: [
+    { label: 'Documents', labelKey: 'documents.nav.documents', href: '/backend/documents' },
+    { label: 'Document', labelKey: 'documents.nav.document' },
+  ],
+}

package/src/modules/documents/backend/documents/[id]/page.tsx

@@ -0,0 +1,6 @@
+import { DocumentPageClient } from './DocumentPageClient'
+
+export default async function DocumentEditorPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  return <DocumentPageClient documentId={id} />
+}

package/src/modules/documents/backend/documents/[id]/relatedRecordModel.ts

@@ -0,0 +1,49 @@
+import {
+  firstSafeDocumentsDisplayLabel,
+  sanitizeDocumentsDisplayLabel,
+} from '../../../lib/displayLabels'
+import {
+  getEntityTokenFieldNames,
+  type DocumentEntityType,
+} from '../../../lib/entityRegistry'
+import { readBoolean, readRecord, readString } from '../documentUi'
+
+export type RelatedRecord = {
+  id: string
+  entityType: DocumentEntityType
+  label: string
+  href: string | null
+  canOpen: boolean
+  source: 'chip' | 'template' | 'related-panel'
+  updatedAt: string
+  values: Record<string, string | null>
+}
+
+export function normalizeRelatedRecord(value: unknown, fallbackLabel: string): RelatedRecord | null {
+  const record = readRecord(value)
+  if (!record) return null
+  const id = readString(record, 'id')
+  const entityType = readString(record, 'entityType', 'entity_type') as DocumentEntityType | null
+  const label = firstSafeDocumentsDisplayLabel(readString(record, 'label'), fallbackLabel)
+  const updatedAt = readString(record, 'updatedAt', 'updated_at')
+  const source = readString(record, 'source') as RelatedRecord['source'] | null
+  if (!id || !entityType || !label || !updatedAt || !source) return null
+  const canOpen = readBoolean(record, 'canOpen', 'can_open') ?? false
+  const rawValues = canOpen ? readRecord(record.values) : null
+  const values = rawValues
+    ? Object.fromEntries(Array.from(getEntityTokenFieldNames(entityType), (field) => [
+        field,
+        sanitizeDocumentsDisplayLabel(rawValues[field]),
+      ]))
+    : {}
+  return {
+    id,
+    entityType,
+    label,
+    updatedAt,
+    source,
+    href: readString(record, 'href'),
+    canOpen,
+    values,
+  }
+}

package/src/modules/documents/backend/documents/[id]/restoreVersion.ts

@@ -0,0 +1,49 @@
+import {
+  apiCallOrThrow,
+  withScopedApiRequestHeaders,
+} from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { normalizeDocumentContent } from '../documentUi'
+
+type RestoreVersionWithCurrentContentTokenInput = {
+  documentId: string
+  versionId: string
+  errorMessage: string
+}
+
+/**
+ * Restore a version against the content row's CURRENT optimistic-lock token.
+ *
+ * The token observed when the page loaded is unusable here: every keystroke
+ * the caller made since (materialized by the collaboration sidecar, or saved
+ * by the single-user autosave) advanced `updated_at`, so restoring after any
+ * edit answered a spurious 409, and a document opened before its content row
+ * existed had no token at all. Reading the token immediately before the
+ * restore keeps the lock meaningful for the concurrent-write race it exists
+ * for, while the server-side pre-restore snapshot preserves whatever
+ * collaborators wrote in between.
+ */
+export async function restoreVersionWithCurrentContentToken({
+  documentId,
+  versionId,
+  errorMessage,
+}: RestoreVersionWithCurrentContentTokenInput) {
+  const contentCall = await apiCallOrThrow<unknown>(
+    `/api/documents/${encodeURIComponent(documentId)}/content`,
+    undefined,
+    { errorMessage },
+  )
+  const contentUpdatedAt = normalizeDocumentContent(contentCall.result).updatedAt
+  if (!contentUpdatedAt || !Number.isFinite(Date.parse(contentUpdatedAt))) {
+    throw new Error(errorMessage)
+  }
+
+  return withScopedApiRequestHeaders(
+    buildOptimisticLockHeader(contentUpdatedAt),
+    () => apiCallOrThrow(
+      `/api/documents/${encodeURIComponent(documentId)}/versions/${encodeURIComponent(versionId)}/restore`,
+      { method: 'POST' },
+      { errorMessage },
+    ),
+  )
+}