Frontend handle this

src-ui/src/app/components/document-detail/document-detail.component.html

@@ -95,6 +95,21 @@
   <div class="col-md-6 col-xl-5 mb-4">
 
     <form [formGroup]='documentForm' (ngSubmit)="save()">
+      @if (remoteUpdateDetected) {
+        <div class="alert alert-warning d-flex flex-column flex-md-row align-items-md-center gap-2" role="alert">
+          <div class="flex-fill">
+            <div class="fw-semibold" i18n>Document was updated.</div>
+            @if (remoteUpdateModified) {
+              <div class="small" i18n>Remote update detected at {{ remoteUpdateModified | date:'medium' }}.</div>
+            }
+            <div class="small" i18n>Saving your local edits now may overwrite remote changes.</div>
+          </div>
+          <div class="btn-group btn-group-sm">
+            <button type="button" class="btn btn-warning" (click)="reloadRemoteVersion()" i18n>Reload</button>
+            <button type="button" class="btn btn-outline-secondary" (click)="dismissRemoteUpdateWarning()" i18n>Dismiss</button>
+          </div>
+        </div>
+      }
 
       <div class="btn-toolbar mb-1 border-bottom">
         <div class="btn-group pb-3">

src-ui/src/app/components/document-detail/document-detail.component.spec.ts

@@ -1205,17 +1205,19 @@ describe('DocumentDetailComponent', () => {
     expect(errorSpy).toHaveBeenCalled()
   })
 
-  it('should warn when open document does not match doc retrieved from backend on init', () => {
-    let openModal: NgbModalRef
-    modalService.activeInstances.subscribe((modals) => (openModal = modals[0]))
+  it('should show remote update warning when open local draft is older than backend on init', () => {
     const modalSpy = jest.spyOn(modalService, 'open')
-    const openDoc = Object.assign({}, doc)
+    const openDoc = Object.assign({}, doc, {
+      __changedFields: ['title'],
+    })
     // simulate a document being modified elsewhere and db updated
-    doc.modified = new Date()
+    const remoteDoc = Object.assign({}, doc, {
+      modified: new Date(new Date(doc.modified).getTime() + 1000),
+    })
     jest
       .spyOn(activatedRoute, 'paramMap', 'get')
       .mockReturnValue(of(convertToParamMap({ id: 3, section: 'details' })))
-    jest.spyOn(documentService, 'get').mockReturnValueOnce(of(doc))
+    jest.spyOn(documentService, 'get').mockReturnValueOnce(of(remoteDoc))
     jest.spyOn(openDocumentsService, 'getOpenDocument').mockReturnValue(openDoc)
     jest.spyOn(customFieldsService, 'listAll').mockReturnValue(
       of({
@@ -1225,11 +1227,11 @@ describe('DocumentDetailComponent', () => {
       })
     )
     fixture.detectChanges() // calls ngOnInit
-    expect(modalSpy).toHaveBeenCalledWith(ConfirmDialogComponent)
-    const closeSpy = jest.spyOn(openModal, 'close')
-    const confirmDialog = openModal.componentInstance as ConfirmDialogComponent
-    confirmDialog.confirmClicked.next(confirmDialog)
-    expect(closeSpy).toHaveBeenCalled()
+    expect(component.remoteUpdateDetected).toBeTruthy()
+    expect(component.remoteUpdateModified).toEqual(
+      remoteDoc.modified.toISOString()
+    )
+    expect(modalSpy).not.toHaveBeenCalledWith(ConfirmDialogComponent)
   })
 
   it('should change preview element by render type', () => {

src-ui/src/app/components/document-detail/document-detail.component.ts

@@ -1,4 +1,4 @@
-import { AsyncPipe, NgTemplateOutlet } from '@angular/common'
+import { AsyncPipe, DatePipe, NgTemplateOutlet } from '@angular/common'
 import { HttpClient, HttpResponse } from '@angular/common/http'
 import { Component, inject, OnDestroy, OnInit, ViewChild } from '@angular/core'
 import {
@@ -80,6 +80,7 @@ import { TagService } from 'src/app/services/rest/tag.service'
 import { UserService } from 'src/app/services/rest/user.service'
 import { SettingsService } from 'src/app/services/settings.service'
 import { ToastService } from 'src/app/services/toast.service'
+import { WebsocketStatusService } from 'src/app/services/websocket-status.service'
 import { getFilenameFromContentDisposition } from 'src/app/utils/http'
 import { ISODateAdapter } from 'src/app/utils/ngb-iso-date-adapter'
 import * as UTIF from 'utif'
@@ -163,6 +164,7 @@ enum ContentRenderType {
     MonetaryComponent,
     UrlComponent,
     SuggestionsDropdownComponent,
+    DatePipe,
     CustomDatePipe,
     FileSizePipe,
     IfPermissionsDirective,
@@ -205,6 +207,7 @@ export class DocumentDetailComponent
   private componentRouterService = inject(ComponentRouterService)
   private deviceDetectorService = inject(DeviceDetectorService)
   private savedViewService = inject(SavedViewService)
+  private websocketStatusService = inject(WebsocketStatusService)
 
   @ViewChild('inputTitle')
   titleInput: TextComponent
@@ -270,6 +273,8 @@ export class DocumentDetailComponent
   customFields: CustomField[]
 
   public downloading: boolean = false
+  remoteUpdateDetected: boolean = false
+  remoteUpdateModified: string | null = null
 
   public readonly CustomFieldDataType = CustomFieldDataType
 
@@ -432,7 +437,14 @@ export class DocumentDetailComponent
       )
   }
 
-  private loadDocument(documentId: number): void {
+  private hasLocalEdits(doc: Document): boolean {
+    return (
+      this.openDocumentService.isDirty(doc) || !!doc.__changedFields?.length
+    )
+  }
+
+  private loadDocument(documentId: number, forceRemote: boolean = false): void {
+    this.dismissRemoteUpdateWarning()
     this.previewUrl = this.documentsService.getPreviewUrl(documentId)
     this.updatePdfSource()
     this.http
@@ -477,21 +489,28 @@ export class DocumentDetailComponent
             openDocument.duplicate_documents = doc.duplicate_documents
             this.openDocumentService.save()
           }
-          const useDoc = openDocument || doc
-          if (openDocument) {
-            if (
-              new Date(doc.modified) > new Date(openDocument.modified) &&
-              !this.modalService.hasOpenModals()
-            ) {
-              const modal = this.modalService.open(ConfirmDialogComponent)
-              modal.componentInstance.title = $localize`Document changes detected`
-              modal.componentInstance.messageBold = $localize`The version of this document in your browser session appears older than the existing version.`
-              modal.componentInstance.message = $localize`Saving the document here may overwrite other changes that were made. To restore the existing version, discard your changes or close the document.`
-              modal.componentInstance.cancelBtnClass = 'visually-hidden'
-              modal.componentInstance.btnCaption = $localize`Ok`
-              modal.componentInstance.confirmClicked.subscribe(() =>
-                modal.close()
-              )
+          let useDoc = openDocument || doc
+          if (openDocument && forceRemote) {
+            Object.assign(openDocument, doc)
+            openDocument.__changedFields = []
+            this.openDocumentService.setDirty(openDocument, false)
+            this.openDocumentService.save()
+            useDoc = openDocument
+          } else if (openDocument) {
+            if (new Date(doc.modified) > new Date(openDocument.modified)) {
+              if (this.hasLocalEdits(openDocument)) {
+                this.remoteUpdateDetected = true
+                this.remoteUpdateModified = doc.modified
+                  ? new Date(doc.modified).toISOString()
+                  : null
+              } else {
+                // No local edits to preserve, so keep the tab in sync automatically.
+                Object.assign(openDocument, doc)
+                openDocument.__changedFields = []
+                this.openDocumentService.setDirty(openDocument, false)
+                this.openDocumentService.save()
+                useDoc = openDocument
+              }
             }
           } else {
             this.openDocumentService
@@ -522,6 +541,38 @@ export class DocumentDetailComponent
       })
   }
 
+  private handleIncomingDocumentUpdated(data: {
+    document_id: number
+    modified?: string
+  }): void {
+    if (!this.documentId || data.document_id !== this.documentId) return
+    if (!this.document || this.networkActive) return
+
+    if (this.openDocumentService.isDirty(this.document)) {
+      this.remoteUpdateDetected = true
+      this.remoteUpdateModified = data.modified ?? null
+    } else {
+      this.docChangeNotifier.next(this.documentId)
+      this.loadDocument(this.documentId, true)
+      this.toastService.showInfo(
+        $localize`Document reloaded with latest changes.`
+      )
+    }
+  }
+
+  dismissRemoteUpdateWarning() {
+    this.remoteUpdateDetected = false
+    this.remoteUpdateModified = null
+  }
+
+  reloadRemoteVersion() {
+    if (!this.documentId) return
+
+    this.docChangeNotifier.next(this.documentId)
+    this.loadDocument(this.documentId, true)
+    this.toastService.showInfo($localize`Document reloaded.`)
+  }
+
   ngOnInit(): void {
     this.setZoom(
       this.settings.get(SETTINGS_KEYS.PDF_VIEWER_ZOOM_SETTING) as PdfZoomScale
@@ -580,6 +631,11 @@ export class DocumentDetailComponent
 
     this.getCustomFields()
 
+    this.websocketStatusService
+      .onDocumentUpdated()
+      .pipe(takeUntil(this.unsubscribeNotifier))
+      .subscribe((data) => this.handleIncomingDocumentUpdated(data))
+
     this.route.paramMap
       .pipe(
         filter(
@@ -914,6 +970,7 @@ export class DocumentDetailComponent
       )
       .subscribe({
         next: (doc) => {
+          this.dismissRemoteUpdateWarning()
           Object.assign(this.document, doc)
           doc['permissions_form'] = {
             owner: doc.owner,
@@ -960,6 +1017,7 @@ export class DocumentDetailComponent
       .pipe(first())
       .subscribe({
         next: (docValues) => {
+          this.dismissRemoteUpdateWarning()
           // in case data changed while saving eg removing inbox_tags
           this.documentForm.patchValue(docValues)
           const newValues = Object.assign({}, this.documentForm.value)
@@ -1039,6 +1097,7 @@ export class DocumentDetailComponent
       .pipe(first())
       .subscribe({
         next: ({ updateResult, nextDocId, closeResult }) => {
+          this.dismissRemoteUpdateWarning()
           this.error = null
           this.networkActive = false
           if (closeResult && updateResult && nextDocId) {
@@ -1135,7 +1194,7 @@ export class DocumentDetailComponent
         .subscribe({
           next: () => {
             this.toastService.showInfo(
-              $localize`Reprocess operation for "${this.document.title}" will begin in the background. Close and re-open or reload this document after the operation has completed to see new content.`
+              $localize`Reprocess operation for "${this.document.title}" will begin in the background.`
             )
             if (modal) {
               modal.close()

src-ui/src/app/data/websocket-document-updated-message.ts

@@ -0,0 +1,7 @@
+export interface WebsocketDocumentUpdatedMessage {
+  document_id: number
+  modified?: string
+  owner_id?: number
+  users_can_view?: number[]
+  groups_can_view?: number[]
+}

src-ui/src/app/services/websocket-status.service.spec.ts

@@ -416,4 +416,25 @@ describe('ConsumerStatusService', () => {
     websocketStatusService.disconnect()
     expect(deleted).toBeTruthy()
   })
+
+  it('should trigger updated subject on document updated', () => {
+    let updated = false
+    websocketStatusService.onDocumentUpdated().subscribe((data) => {
+      updated = true
+      expect(data.document_id).toEqual(12)
+    })
+
+    websocketStatusService.connect()
+    server.send({
+      type: WebsocketStatusType.DOCUMENT_UPDATED,
+      data: {
+        document_id: 12,
+        modified: '2026-02-17T00:00:00Z',
+        owner_id: 1,
+      },
+    })
+
+    websocketStatusService.disconnect()
+    expect(updated).toBeTruthy()
+  })
 })

src-ui/src/app/services/websocket-status.service.ts

@@ -2,6 +2,7 @@ import { Injectable, inject } from '@angular/core'
 import { Subject } from 'rxjs'
 import { environment } from 'src/environments/environment'
 import { User } from '../data/user'
+import { WebsocketDocumentUpdatedMessage } from '../data/websocket-document-updated-message'
 import { WebsocketDocumentsDeletedMessage } from '../data/websocket-documents-deleted-message'
 import { WebsocketProgressMessage } from '../data/websocket-progress-message'
 import { SettingsService } from './settings.service'
@@ -9,6 +10,7 @@ import { SettingsService } from './settings.service'
 export enum WebsocketStatusType {
   STATUS_UPDATE = 'status_update',
   DOCUMENTS_DELETED = 'documents_deleted',
+  DOCUMENT_UPDATED = 'document_updated',
 }
 
 // see ProgressStatusOptions in src/documents/plugins/helpers.py
@@ -103,6 +105,8 @@ export class WebsocketStatusService {
   private documentConsumptionFinishedSubject = new Subject<FileStatus>()
   private documentConsumptionFailedSubject = new Subject<FileStatus>()
   private documentDeletedSubject = new Subject<boolean>()
+  private documentUpdatedSubject =
+    new Subject<WebsocketDocumentUpdatedMessage>()
   private connectionStatusSubject = new Subject<boolean>()
 
   private get(taskId: string, filename?: string) {
@@ -169,7 +173,10 @@ export class WebsocketStatusService {
         data: messageData,
       }: {
         type: WebsocketStatusType
-        data: WebsocketProgressMessage | WebsocketDocumentsDeletedMessage
+        data:
+          | WebsocketProgressMessage
+          | WebsocketDocumentsDeletedMessage
+          | WebsocketDocumentUpdatedMessage
       } = JSON.parse(ev.data)
 
       switch (type) {
@@ -177,6 +184,12 @@ export class WebsocketStatusService {
           this.documentDeletedSubject.next(true)
           break
 
+        case WebsocketStatusType.DOCUMENT_UPDATED:
+          this.handleDocumentUpdated(
+            messageData as WebsocketDocumentUpdatedMessage
+          )
+          break
+
         case WebsocketStatusType.STATUS_UPDATE:
           this.handleProgressUpdate(messageData as WebsocketProgressMessage)
           break
@@ -184,7 +197,11 @@ export class WebsocketStatusService {
     }
   }
 
-  private canViewMessage(messageData: WebsocketProgressMessage): boolean {
+  private canViewMessage(messageData: {
+    owner_id?: number
+    users_can_view?: number[]
+    groups_can_view?: number[]
+  }): boolean {
     // see paperless.consumers.StatusConsumer._can_view
     const user: User = this.settingsService.currentUser
     return (
@@ -244,6 +261,15 @@ export class WebsocketStatusService {
     }
   }
 
+  handleDocumentUpdated(messageData: WebsocketDocumentUpdatedMessage) {
+    // fallback if backend didn't restrict message
+    if (!this.canViewMessage(messageData)) {
+      return
+    }
+
+    this.documentUpdatedSubject.next(messageData)
+  }
+
   fail(status: FileStatus, message: string) {
     status.message = message
     status.phase = FileStatusPhase.FAILED
@@ -297,6 +323,10 @@ export class WebsocketStatusService {
     return this.documentDeletedSubject
   }
 
+  onDocumentUpdated() {
+    return this.documentUpdatedSubject
+  }
+
   onConnectionStatus() {
     return this.connectionStatusSubject.asObservable()
   }

src/documents/apps.py

@@ -15,6 +15,7 @@ class DocumentsConfig(AppConfig):
         from documents.signals.handlers import add_to_index
         from documents.signals.handlers import run_workflows_added
         from documents.signals.handlers import run_workflows_updated
+        from documents.signals.handlers import send_websocket_document_updated
         from documents.signals.handlers import set_correspondent
         from documents.signals.handlers import set_document_type
         from documents.signals.handlers import set_storage_path
@@ -29,6 +30,7 @@ class DocumentsConfig(AppConfig):
         document_consumption_finished.connect(run_workflows_added)
         document_consumption_finished.connect(add_or_update_document_in_llm_index)
         document_updated.connect(run_workflows_updated)
+        document_updated.connect(send_websocket_document_updated)
 
         import documents.schema  # noqa: F401
 

src/documents/plugins/helpers.py

@@ -100,3 +100,25 @@ class DocumentsStatusManager(BaseStatusManager):
         }
 
         self.send(payload)
+
+    def send_document_updated(
+        self,
+        *,
+        document_id: int,
+        modified: str | None = None,
+        owner_id: int | None = None,
+        users_can_view: list[int] | None = None,
+        groups_can_view: list[int] | None = None,
+    ) -> None:
+        payload = {
+            "type": "document_updated",
+            "data": {
+                "document_id": document_id,
+                "modified": modified,
+                "owner_id": owner_id,
+                "users_can_view": users_can_view or [],
+                "groups_can_view": groups_can_view or [],
+            },
+        }
+
+        self.send(payload)

src/documents/signals/handlers.py

@@ -45,6 +45,7 @@ from documents.models import WorkflowAction
 from documents.models import WorkflowRun
 from documents.models import WorkflowTrigger
 from documents.permissions import get_objects_for_user_owner_aware
+from documents.plugins.helpers import DocumentsStatusManager
 from documents.templating.utils import convert_format_str_to_template_format
 from documents.workflows.actions import build_workflow_action_context
 from documents.workflows.actions import execute_email_action
@@ -753,6 +754,28 @@ def run_workflows_updated(
     )
 
 
+def send_websocket_document_updated(
+    sender,
+    document: Document,
+    **kwargs,
+) -> None:
+    # At this point, workflows may already have applied additional changes.
+    document.refresh_from_db()
+
+    from documents.data_models import DocumentMetadataOverrides
+
+    doc_overrides = DocumentMetadataOverrides.from_document(document)
+
+    with DocumentsStatusManager() as status_mgr:
+        status_mgr.send_document_updated(
+            document_id=document.id,
+            modified=document.modified.isoformat() if document.modified else None,
+            owner_id=doc_overrides.owner_id,
+            users_can_view=doc_overrides.view_users,
+            groups_can_view=doc_overrides.view_groups,
+        )
+
+
 def run_workflows(
     trigger_type: WorkflowTrigger.WorkflowTriggerType,
     document: Document | ConsumableDocument,

src/paperless/consumers.py

@@ -52,3 +52,10 @@ class StatusConsumer(WebsocketConsumer):
             self.close()
         else:
             self.send(json.dumps(event))
+
+    def document_updated(self, event) -> None:
+        if not self._authenticated():
+            self.close()
+        else:
+            if self._can_view(event["data"]):
+                self.send(json.dumps(event))

src/paperless/tests/test_websockets.py

@@ -158,6 +158,39 @@ class TestWebSockets(TestCase):
 
         await communicator.disconnect()
 
+    @mock.patch("paperless.consumers.StatusConsumer._can_view")
+    @mock.patch("paperless.consumers.StatusConsumer._authenticated")
+    async def test_receive_document_updated(self, _authenticated, _can_view) -> None:
+        _authenticated.return_value = True
+        _can_view.return_value = True
+
+        communicator = WebsocketCommunicator(application, "/ws/status/")
+        connected, _ = await communicator.connect()
+        self.assertTrue(connected)
+
+        message = {
+            "type": "document_updated",
+            "data": {
+                "document_id": 10,
+                "modified": "2026-02-17T00:00:00Z",
+                "owner_id": 1,
+                "users_can_view": [1],
+                "groups_can_view": [],
+            },
+        }
+
+        channel_layer = get_channel_layer()
+        await channel_layer.group_send(
+            "status_updates",
+            message,
+        )
+
+        response = await communicator.receive_json_from()
+
+        self.assertEqual(response, message)
+
+        await communicator.disconnect()
+
     @mock.patch("channels.layers.InMemoryChannelLayer.group_send")
     def test_manager_send_progress(self, mock_group_send) -> None:
         with ProgressManager(task_id="test") as manager: