@open-mercato/documents 0.10.1-develop.7925.1.ec40f75262 → 0.10.1-develop.7929.1.0822b5d5fd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/documents",
-  "version": "0.10.1-develop.7925.1.ec40f75262",
+  "version": "0.10.1-develop.7929.1.0822b5d5fd",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     "@hocuspocus/server": "^4.4.0",
     "@hocuspocus/transformer": "^4.3.0",
     "@mikro-orm/core": "^7.1.14",
-    "@open-mercato/events": "0.10.1-develop.7925.1.ec40f75262",
-    "@open-mercato/ui": "0.10.1-develop.7925.1.ec40f75262",
+    "@open-mercato/events": "0.10.1-develop.7929.1.0822b5d5fd",
+    "@open-mercato/ui": "0.10.1-develop.7929.1.0822b5d5fd",
     "@tiptap/core": "3.32.0",
     "@tiptap/extension-bubble-menu": "3.32.0",
     "@tiptap/extension-collaboration": "3.32.0",
@@ -112,13 +112,13 @@
   },
   "peerDependencies": {
     "@mikro-orm/postgresql": "^7.0.14",
-    "@open-mercato/shared": "0.10.1-develop.7925.1.ec40f75262",
+    "@open-mercato/shared": "0.10.1-develop.7929.1.0822b5d5fd",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/core": "0.10.1-develop.7925.1.ec40f75262",
-    "@open-mercato/shared": "0.10.1-develop.7925.1.ec40f75262",
+    "@open-mercato/core": "0.10.1-develop.7929.1.0822b5d5fd",
+    "@open-mercato/shared": "0.10.1-develop.7929.1.0822b5d5fd",
     "@types/jest": "^30.0.0",
     "@types/pg": "^8.23.1",
     "@types/react": "^19.2.18",

package/server/documents-collab-server.ts

@@ -26,9 +26,12 @@ import type {
   onChangePayload,
   onRequestPayload,
   onStoreDocumentPayload,
+  onStatelessPayload,
   Server as HocuspocusServer,
 } from '@hocuspocus/server'
 import * as Y from 'yjs'
+import { collabContentSaveRequestSchema } from '@open-mercato/documents/modules/documents/data/validators'
+import { containsDocumentSnapshot } from '@open-mercato/documents/modules/documents/lib/collabPersistence'
 import { hasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
@@ -2505,6 +2508,32 @@ export function createCollabHooks(deps: CollabHooksDeps) {
     assertConnectionAuthorization,
     establishConnectionAuthorization,
     releaseConnectionAuthorization,
+    async saveContent(data: {
+      documentName: string
+      document: Y.Doc
+      context: CollabContext
+      store: (confirmPersistence: (snapshot: Y.Snapshot) => void) => Promise<unknown>
+    }): Promise<boolean> {
+      try {
+        assertScopedContext(data.context)
+        const scope = roomScopes.get(data.document)
+        const isCurrent = () => data.context.documentId === data.documentName
+          && scope?.tenantId === data.context.tenantId
+          && scope.organizationId === data.context.organizationId
+          && !data.context.readOnly
+          && !isInvalidated(data.documentName, data.document)
+          && !isFinalDrainPending(data.documentName)
+        if (!isCurrent() || !(await deps.authorizeContext(data.context)) || !isCurrent()) return false
+        const requested = Y.snapshot(data.document)
+        const confirmation: { snapshot: Y.Snapshot | null } = { snapshot: null }
+        await data.store((snapshot) => { confirmation.snapshot = snapshot })
+        if (!isCurrent() || !(await deps.authorizeContext(data.context)) || !isCurrent()) return false
+        const durable = confirmation.snapshot
+        return Boolean(durable && containsDocumentSnapshot(durable, requested))
+      } catch {
+        return false
+      }
+    },
     reauthorizeActiveConnection,
     recordRedisAggregate(document: Y.Doc, byteLength: number): void {
       const previous = roomResourceBudgets.get(document)
@@ -2747,6 +2776,7 @@ export function createCollabHooks(deps: CollabHooksDeps) {
       documentName: string
       context: CollabContext
       document: Y.Doc
+      confirmPersistence?: (snapshot: Y.Snapshot) => void
     }): Promise<void> {
       try {
         assertScopedContext(data.context)
@@ -2833,6 +2863,7 @@ export function createCollabHooks(deps: CollabHooksDeps) {
             logger.warn('materialization failed; preserving previous html/text', { room: data.documentName })
           }
           const yjsState = Buffer.from(Y.encodeStateAsUpdate(data.document))
+          const storingSnapshot = Y.snapshot(data.document)
           const resourceBudgetRevision = roomResourceBudgets.get(data.document)?.revision ?? 0
           assertDocumentContentResourceLimits({
             yjsState,
@@ -2950,6 +2981,7 @@ export function createCollabHooks(deps: CollabHooksDeps) {
             })
           }
           deps.onPersisted?.(data.document, yjsState, collaborationGeneration)
+          if (materialized) data.confirmPersistence?.(storingSnapshot)
           if (finalDrainAuthorized) deps.finalDrainRegistry?.complete(data.document)
           return
         }
@@ -3141,6 +3173,8 @@ export async function main(): Promise<void> {
   const finalDrainRegistry = createCollabFinalDrainRegistry()
   let server: HocuspocusServer<CollabContext> | null = null
   let redisStoreExtension: DocumentsCollabRedisExtension | null = null
+  const savingConnections = new WeakSet<object>()
+  const storeConfirmations = new WeakMap<onStoreDocumentPayload<CollabContext>, (snapshot: Y.Snapshot) => void>()
   const closeRoomConnectionsForContentReset = (documentName: string): void => {
     if (server) closeCollabRoomConnectionsForContentReset(server.hocuspocus, documentName)
   }
@@ -3325,8 +3359,53 @@ export async function main(): Promise<void> {
         documentName: data.documentName,
         context: data.lastContext,
         document: data.document,
+        confirmPersistence: storeConfirmations.get(data),
       })
     },
+    async onStateless(data: onStatelessPayload) {
+      let value: unknown
+      try { value = JSON.parse(data.payload) } catch { return }
+      const request = collabContentSaveRequestSchema.safeParse(value)
+      if (!request.success) return
+      const respond = (saved: boolean) => data.connection.sendStateless(JSON.stringify({
+        type: 'documents.content.saved',
+        requestId: request.data.requestId,
+        saved,
+      }))
+      if (savingConnections.has(data.connection) || !server) {
+        respond(false)
+        return
+      }
+      savingConnections.add(data.connection)
+      try {
+        const runtime = server.hocuspocus
+        const context: CollabContext = data.connection.context
+        const saved = await hooks.saveContent({
+          documentName: data.documentName,
+          document: data.document,
+          context,
+          store: async (confirmPersistence) => {
+            const payload: onStoreDocumentPayload<CollabContext> = {
+              instance: runtime,
+              document: data.document,
+              documentName: data.documentName,
+              clientsCount: data.document.getConnectionsCount(),
+              lastContext: context,
+              lastTransactionOrigin: { source: 'local', context },
+            }
+            storeConfirmations.set(payload, confirmPersistence)
+            try {
+              await runtime.storeDocumentHooks(data.document, payload, true)
+            } finally {
+              storeConfirmations.delete(payload)
+            }
+          },
+        })
+        respond(saved)
+      } finally {
+        savingConnections.delete(data.connection)
+      }
+    },
     async onRequest(data: onRequestPayload) {
       return handleCollabServerRequest(data)
     },

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

@@ -19,6 +19,7 @@ import { useDocumentEditor } from './useDocumentEditor'
 import { useFallbackContentPersistence } from './useFallbackContentPersistence'
 import { useDocumentTitle } from './useDocumentTitle'
 import { useEditorInsertions } from './useEditorInsertions'
+import { saveCollaborativeContent } from './saveCollaborativeContent'
 
 type Props = DocumentEditorIslandProps & {
   transport: 'collab' | 'fallback'
@@ -62,6 +63,21 @@ export function DocumentEditorSurface(input: Props) {
     readOnly: effectiveReadOnly,
     onTitleChange: input.onTitleChange,
   })
+  React.useEffect(() => {
+    const controller = new AbortController()
+    input.onSaveReady?.(async () => {
+      if (controller.signal.aborted || input.readOnly || !editorModel.editorRef.current) return false
+      return input.transport === 'fallback'
+        ? fallbackPersistence.saveNow()
+        : input.collabResources
+          ? saveCollaborativeContent(input.collabResources, controller.signal)
+          : false
+    })
+    return () => {
+      controller.abort()
+      input.onSaveReady?.(null)
+    }
+  }, [editorModel.editorRef, fallbackPersistence.saveNow, input.collabResources, input.onSaveReady, input.readOnly, input.transport])
   const insertions = useEditorInsertions({
     documentId: input.documentId,
     editorRef: editorModel.editorRef,

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

@@ -79,6 +79,17 @@ export function DocumentPageClient({ documentId }: { documentId: string }) {
   const scrollVersionsIntoView = React.useRef(false)
   const [editorEpoch, setEditorEpoch] = React.useState(0)
   const [editor, setEditor] = React.useState<Editor | null>(null)
+  const contentSaveRef = React.useRef<{ documentId: string; save: () => Promise<boolean> } | null>(null)
+  const displayedDocumentId = state.status === 'ready' ? state.document.id : null
+  const registerContentSave = React.useCallback((save: (() => Promise<boolean>) | null) => {
+    contentSaveRef.current = save && displayedDocumentId ? { documentId: displayedDocumentId, save } : null
+  }, [displayedDocumentId])
+  const saveBeforeSnapshot = React.useCallback(async () => {
+    const registered = contentSaveRef.current
+    if (!registered || registered.documentId !== documentId) return false
+    const saved = await registered.save()
+    return saved && contentSaveRef.current === registered
+  }, [documentId])
   const [commentFocusRequest, setCommentFocusRequest] = React.useState<CommentFocusRequest | null>(null)
   const requestSequence = React.useRef(0)
   const mutationContextId = `documents-detail:${documentId}`
@@ -135,6 +146,7 @@ export function DocumentPageClient({ documentId }: { documentId: string }) {
     const nextContent = contentCall.status === 404
       ? { contentHtml: '', updatedAt: null }
       : normalizeDocumentContent(contentCall.result)
+    contentSaveRef.current = null
     setState((current) => current.status === 'ready' ? {
       ...current,
       content: nextContent,
@@ -411,6 +423,7 @@ export function DocumentPageClient({ documentId }: { documentId: string }) {
                 documentUpdatedAt={document.updatedAt}
                 readOnly={!capabilities.canEdit}
                 onEditorReady={setEditor}
+                onSaveReady={registerContentSave}
                 onContentConflict={handleContentConflict}
                 onComment={capabilities.canComment ? (anchor) => setCommentFocusRequest((current) => ({ anchor, requestId: (current?.requestId ?? 0) + 1 })) : undefined}
                 onTitleChange={(title, updatedAt) => setState((current) => current.status === 'ready' ? {
@@ -441,6 +454,7 @@ export function DocumentPageClient({ documentId }: { documentId: string }) {
                   canRestore={capabilities.canEdit}
                   contentUpdatedAt={content.updatedAt}
                   onRestored={reloadEditor}
+                  onBeforeSnapshot={saveBeforeSnapshot}
                 />
               </div>
             ) : null}

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

@@ -65,6 +65,7 @@ type VersionHistoryPanelProps = {
    */
   contentUpdatedAt?: string | null
   onRestored?: () => void | Promise<void>
+  onBeforeSnapshot?: () => Promise<boolean>
 }
 
 export { resolveVersionRestoreCapability } from './componentCapabilities'
@@ -75,6 +76,7 @@ export function VersionHistoryPanel({
   tier,
   canRestore,
   onRestored,
+  onBeforeSnapshot,
 }: VersionHistoryPanelProps) {
   const t = useT()
   const mayRestore = resolveVersionRestoreCapability(canRestore, tier)
@@ -85,6 +87,7 @@ export function VersionHistoryPanel({
   const [restoringVersionId, setRestoringVersionId] = React.useState<string | null>(null)
   const [previewVersionId, setPreviewVersionId] = React.useState<string | null>(null)
   const restoreInFlight = React.useRef(false)
+  const snapshotInFlight = React.useRef(false)
   const reloadSequence = React.useRef(0)
   const activeReload = React.useRef<AbortController | null>(null)
   const activeDocumentId = React.useRef<string | null>(null)
@@ -141,16 +144,25 @@ export function VersionHistoryPanel({
   }, [reload])
 
   const handleSnapshot = React.useCallback(async () => {
-    if (!mayRestore) return
+    if (!mayRestore || snapshotInFlight.current) return
+    snapshotInFlight.current = true
     setIsCreating(true)
     const nextLabel = label.trim() || null
     try {
       await runMutation({
-        operation: () => apiCallOrThrow(
-          `/api/documents/${encodeURIComponent(documentId)}/versions`,
-          { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ label: nextLabel }) },
-          { errorMessage: t('documents.versions.error.save') },
-        ),
+        operation: async () => {
+          if (onBeforeSnapshot && !(await onBeforeSnapshot())) {
+            throw new Error(t('documents.versions.error.save'))
+          }
+          if (currentDocumentIdRef.current !== documentId) {
+            throw new Error(t('documents.versions.error.save'))
+          }
+          return apiCallOrThrow(
+            `/api/documents/${encodeURIComponent(documentId)}/versions`,
+            { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ label: nextLabel }) },
+            { errorMessage: t('documents.versions.error.save') },
+          )
+        },
         context: { formId: mutationContextId, resourceKind: 'documents.document_version', resourceId: documentId, retryLastMutation },
         mutationPayload: { label: nextLabel },
       })
@@ -162,8 +174,11 @@ export function VersionHistoryPanel({
     } catch (error) {
       if (currentDocumentIdRef.current !== documentId) return
       flash(error instanceof Error ? error.message : t('documents.versions.error.save'), 'error')
-    } finally { setIsCreating(false) }
-  }, [documentId, label, mayRestore, mutationContextId, reload, retryLastMutation, runMutation, t])
+    } finally {
+      snapshotInFlight.current = false
+      setIsCreating(false)
+    }
+  }, [documentId, label, mayRestore, mutationContextId, onBeforeSnapshot, reload, retryLastMutation, runMutation, t])
 
   const handleRestore = React.useCallback(async (version: VersionPreview) => {
     if (!mayRestore || restoreInFlight.current) return

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

@@ -20,6 +20,7 @@ export type DocumentEditorIslandProps = {
   documentUpdatedAt?: string | null
   readOnly: boolean
   onEditorReady?: (editor: Editor | null) => void
+  onSaveReady?: (save: (() => Promise<boolean>) | null) => void
   onComment?: (anchor: CommentAnchor) => void
   onContentConflict?: () => void
   onTitleChange?: (title: string, updatedAt: string | null) => void

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

@@ -0,0 +1,43 @@
+import type { CollabResources } from './editorTypes'
+import { collabContentSaveResponseSchema } from '../../../data/validators'
+import { COLLAB_CONTENT_SAVE_TIMEOUT_MS } from '../../../lib/collabPersistence'
+
+export function saveCollaborativeContent(
+  resources: CollabResources,
+  signal: AbortSignal,
+): Promise<boolean> {
+  const { provider } = resources
+  if (signal.aborted || !provider.synced || provider.configuration.websocketProvider.status !== 'connected') {
+    return Promise.resolve(false)
+  }
+  const requestId = crypto.randomUUID()
+  return new Promise<boolean>((resolve) => {
+    const finish = (saved: boolean) => {
+      clearTimeout(timer)
+      provider.off('stateless', onStateless)
+      provider.off('close', onFailure)
+      provider.off('disconnect', onFailure)
+      provider.off('destroy', onFailure)
+      signal.removeEventListener('abort', onFailure)
+      resolve(saved)
+    }
+    const onFailure = () => finish(false)
+    const onStateless = ({ payload }: { payload: string }) => {
+      let value: unknown
+      try { value = JSON.parse(payload) } catch { return }
+      const response = collabContentSaveResponseSchema.safeParse(value)
+      if (response.success && response.data.requestId === requestId) finish(response.data.saved)
+    }
+    const timer = setTimeout(onFailure, COLLAB_CONTENT_SAVE_TIMEOUT_MS)
+    provider.on('stateless', onStateless)
+    provider.on('close', onFailure)
+    provider.on('disconnect', onFailure)
+    provider.on('destroy', onFailure)
+    signal.addEventListener('abort', onFailure, { once: true })
+    try {
+      provider.sendStateless(JSON.stringify({ type: 'documents.content.save', requestId }))
+    } catch {
+      finish(false)
+    }
+  })
+}

package/src/modules/documents/data/validators.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+
 import {
   DOCUMENTS_MAX_CONTENT_HTML_BYTES,
   DOCUMENTS_MAX_CONTENT_TEXT_BYTES,
@@ -7,6 +8,17 @@ import {
 import { containsCanonicalUuid } from '../lib/displayLabels'
 import { DOCUMENT_VERSION_LABEL_MAX_LENGTH } from '../lib/versionLabels'
 
+export const collabContentSaveRequestSchema = z.object({
+  type: z.literal('documents.content.save'),
+  requestId: z.string().uuid(),
+})
+
+export const collabContentSaveResponseSchema = z.object({
+  type: z.literal('documents.content.saved'),
+  requestId: z.string().uuid(),
+  saved: z.boolean(),
+})
+
 const uuid = () => z.string().uuid('documents.validation.common.invalidUuid')
 
 function blankStringToNull(value: unknown): unknown {

package/src/modules/documents/lib/collabPersistence.ts

@@ -0,0 +1,10 @@
+import * as Y from 'yjs'
+
+export const COLLAB_CONTENT_SAVE_TIMEOUT_MS = 15000
+
+export function containsDocumentSnapshot(durable: Y.Snapshot, requested: Y.Snapshot): boolean {
+  for (const [clientId, clock] of requested.sv) {
+    if ((durable.sv.get(clientId) ?? 0) < clock) return false
+  }
+  return Y.equalDeleteSets(Y.mergeDeleteSets([durable.ds, requested.ds]), durable.ds)
+}