test(collaboration): fix soft-offline feature tests

Add a Phase 1 to each soft-offline test that types content and waits
for Hocuspocus to persist it (content_binary present) before switching
to the unreachable URL. An empty document never triggers a Y.Doc write,
so IndexedDB stayed empty and Phase 2 fell into blocking-offline mode
instead of soft-offline mode.

For the readonly soft-offline test, Phase 1 now logs in as admin to
type the seed content (readonly users cannot write), then switches to
the readonly user for the offline visit.

Also add blocking: param support to ConnectionErrorNoticeComponent and
documents controller to display a distinct "server unreachable" message
when no local IndexedDB cache exists.

Author: akabiru

frontend/src/elements/block-note-element.ts

@@ -113,7 +113,7 @@ class BlockNoteElement extends HTMLElement {
 
     this.renderCallback = (provider:HocuspocusProvider) => {
       this.reactRoot?.render(
-        React.createElement(React.StrictMode, null, this.BlockNoteReactContainer(provider))
+        React.createElement(React.StrictMode, null, this.BlockNoteReactContainer(provider, LiveCollaborationManager.hasLocalCache))
       );
     };
 
@@ -138,7 +138,7 @@ class BlockNoteElement extends HTMLElement {
     }
   }
 
-  private BlockNoteReactContainer = (hocuspocusProvider:HocuspocusProvider) => {
+  private BlockNoteReactContainer = (hocuspocusProvider:HocuspocusProvider, hasLocalCache:boolean) => {
     return React.createElement(
       ShadowDomWrapper,
       { target: this.editorMount },
@@ -151,6 +151,7 @@ class BlockNoteElement extends HTMLElement {
           attachmentsUploadUrl: this.getAttribute('attachments-upload-url') ?? '',
           attachmentsCollectionKey: this.getAttribute('attachments-collection-key') ?? '',
           hocuspocusProvider: hocuspocusProvider,
+          hasLocalCache: hasLocalCache,
           errorContainer: this.errorContainer,
         }
       )

frontend/src/react/OpBlockNoteContainer.tsx

@@ -44,6 +44,7 @@ export interface OpBlockNoteContainerProps {
   attachmentsUploadUrl:string;
   attachmentsCollectionKey:string;
   hocuspocusProvider:HocuspocusProvider;
+  hasLocalCache?:boolean;
   errorContainer?:HTMLElement;
 }
 
@@ -54,10 +55,11 @@ export default function OpBlockNoteContainer({
   attachmentsUploadUrl,
   attachmentsCollectionKey,
   hocuspocusProvider,
+  hasLocalCache = false,
   errorContainer,
 }:OpBlockNoteContainerProps) {
   const doc:Y.Doc = hocuspocusProvider.document;
-  const { isLoading, offlineMode } = useCollaboration(hocuspocusProvider);
+  const { isLoading, offlineMode, blockingOffline } = useCollaboration(hocuspocusProvider, hasLocalCache);
   const hadErrorRef = useRef(false);
 
   // Fetch error/recovery template based on connection state
@@ -66,7 +68,7 @@ export default function OpBlockNoteContainer({
 
     if (offlineMode) {
       hadErrorRef.current = true;
-      void fetchConnectionTemplate('error', errorContainer);
+      void fetchConnectionTemplate('error', errorContainer, { blocking: blockingOffline });
     } else if (hadErrorRef.current) {
       // Only fetch recovery if we previously had an error (avoid fetching on initial render)
       void fetchConnectionTemplate('recovery', errorContainer);
@@ -77,6 +79,14 @@ export default function OpBlockNoteContainer({
     return <DocumentLoadingSkeleton />;
   }
 
+  // When offline with no local cache, show only the error banner (rendered via
+  // errorContainer) and hide the editor entirely. A fresh empty Y.Doc must not be
+  // editable — it would be synced as authoritative server state on reconnect,
+  // overwriting real document content.
+  if (blockingOffline) {
+    return null;
+  }
+
   return (
     <OpBlockNoteEditor
       activeUser={activeUser}

frontend/src/react/helpers/connection-template-fetcher.ts

@@ -66,14 +66,16 @@ function parseTurboStreamContent(html:string):string|null {
 export async function fetchConnectionTemplate(
   type:'error'|'recovery',
   targetElement:HTMLElement,
+  options:{ blocking?:boolean } = {},
 ):Promise<void> {
   const documentId = getDocumentIdFromUrl();
   if (!documentId) {
     console.error('Could not extract document ID from URL');
     return;
   }
 
-  const url = `/documents/${documentId}/render_connection_${type}`;
+  const url = new URL(`/documents/${documentId}/render_connection_${type}`, window.location.origin);
+  if (options.blocking) url.searchParams.set('blocking', 'true');
 
   try {
     const response = await fetch(url, {

frontend/src/react/hooks/useCollaboration.ts

@@ -125,19 +125,24 @@ function useProviderAuthError(onAuthError:() => void) {
  * exposes it as React state for the BlockNote editor.
  *
  * Returns:
- * - `isLoading`   — true while waiting for the first sync after mount.
- * - `offlineMode` — true when the connection is lost or timed out;
- *                   the editor remains editable and changes are queued
- *                   locally (IndexedDB) until the server is reachable again.
+ * - `isLoading`       — true while waiting for the first sync after mount.
+ * - `offlineMode`     — true when the connection is lost or timed out; the editor
+ *                       remains editable and changes are queued locally (IndexedDB)
+ *                       until the server is reachable again (only when hasLocalCache).
+ * - `blockingOffline` — true when offline AND IndexedDB had no cached content at
+ *                       provider initialisation; the caller should hide the editor
+ *                       entirely to prevent a fresh empty Y.Doc from being synced as
+ *                       authoritative server state on reconnect.
  *
  * Transitions:
- *   mount → synced           : isLoading false, offlineMode false
- *   mount → timeout (5s)     : isLoading false, offlineMode true
- *   connected → disconnect   : offlineMode true
- *   offline → re-synced      : offlineMode false
- *   any → auth error         : isLoading false, offlineMode true
+ *   mount → synced                          : isLoading false, offlineMode false
+ *   mount → timeout (5s), hasLocalCache     : isLoading false, offlineMode true
+ *   mount → timeout (5s), !hasLocalCache    : isLoading false, blockingOffline true
+ *   connected → disconnect                  : offlineMode true
+ *   offline → re-synced                     : offlineMode false
+ *   any → auth error                        : isLoading false, offlineMode true
  */
-function useCollaboration(provider:HocuspocusProvider) {
+function useCollaboration(provider:HocuspocusProvider, hasLocalCache = false) {
   const [isLoading, setIsLoading] = useState(true);
   const [offlineMode, setOfflineMode] = useState(false);
 
@@ -168,7 +173,11 @@ function useCollaboration(provider:HocuspocusProvider) {
   useCollaborationProvider(provider, handleSynced, handleDisconnect);
   useProviderAuthError(handleAuthError);
 
-  return { isLoading, offlineMode } as const;
+  // When offline with no local cache, block the editor entirely to prevent an
+  // empty Y.Doc from being synced as the authoritative document on reconnect.
+  const blockingOffline = offlineMode && !hasLocalCache;
+
+  return { isLoading, offlineMode, blockingOffline } as const;
 }
 
 export { useCollaboration };

frontend/src/stimulus/controllers/dynamic/documents/init-yjs-provider.controller.ts

@@ -125,6 +125,11 @@ export default class extends Controller {
       this.destroyIndexedDBPersistence();
     }
 
+    // Detect whether IndexedDB contained cached content for this document.
+    // A non-trivial state vector (> 1 byte) means the Y.Doc has real operations from a previous session.
+    const hasLocalCache = Y.encodeStateVector(ydoc).byteLength > 1;
+    LiveCollaborationManager.setHasLocalCache(hasLocalCache);
+
     // If disconnect() was called during the IndexedDB await (e.g., Turbo navigation),
     // abort to avoid overwriting the active provider on the new page.
     if (!this.element.isConnected) {

frontend/src/stimulus/helpers/live-collaboration-helpers.ts

@@ -38,6 +38,20 @@ class LiveCollaborationManagerClass {
   yjsDocInstance:Doc|null = null;
 
   private listeners:Listener[] = [];
+  private hasLocalCacheValue = false;
+
+  /**
+   * Records whether IndexedDB had locally-cached document content at the time the
+   * provider was set up. Used by the editor to decide between soft offline mode
+   * (has cache → editing allowed) and hard blocking mode (no cache → editor hidden).
+   */
+  setHasLocalCache(value:boolean):void {
+    this.hasLocalCacheValue = value;
+  }
+
+  get hasLocalCache():boolean {
+    return this.hasLocalCacheValue;
+  }
 
   /**
    * Initializes the YJS Provider
@@ -84,6 +98,7 @@ class LiveCollaborationManagerClass {
     this.destroyYjsDoc();
 
     this.listeners = [];
+    this.hasLocalCacheValue = false;
   }
 
   private destroyYjsProvider():void {

modules/documents/app/components/documents/show_edit_view/connection_error_notice_component.html.erb

@@ -37,7 +37,9 @@
         data: { turbo: false },
         size: :medium
       ) { I18n.t("documents.show_edit_view.connection_error_notice.action") }
-      description_key = if readonly
+      description_key = if blocking
+                          "documents.show_edit_view.connection_error_notice.description_server_unavailable"
+                        elsif readonly
                           "documents.show_edit_view.connection_error_notice.description_readonly"
                         else
                           "documents.show_edit_view.connection_error_notice.description"

modules/documents/app/components/documents/show_edit_view/connection_error_notice_component.rb

@@ -35,8 +35,15 @@ class ConnectionErrorNoticeComponent < ApplicationComponent
 
       alias_method :document, :model
 
+      def initialize(document, blocking: false)
+        super(document)
+        @blocking = blocking
+      end
+
       private
 
+      attr_reader :blocking
+
       def readonly
         @readonly ||= User.current.allowed_in_project?(:view_documents, document.project) &&
           !User.current.allowed_in_project?(:manage_documents, document.project)

modules/documents/app/controllers/documents_controller.rb

@@ -79,7 +79,10 @@ def render_last_saved_at
   end
 
   def render_connection_error
-    update_via_turbo_stream(component: Documents::ShowEditView::ConnectionErrorNoticeComponent.new(@document))
+    blocking = ActiveRecord::Type::Boolean.new.cast(params[:blocking].presence || false)
+    update_via_turbo_stream(
+      component: Documents::ShowEditView::ConnectionErrorNoticeComponent.new(@document, blocking:)
+    )
 
     respond_with_turbo_streams
   end

modules/documents/config/locales/en.yml

@@ -94,6 +94,9 @@ en:
         description_readonly: |-
           You are currently offline.
           Real-time updates will resume once the connection is restored.
+        description_server_unavailable: |-
+          Unable to open document because the real-time text collaboration server is unreachable.
+          Please contact the administrator if the problem persists.
         action: Try again
       connection_recovery_notice:
         description: "The connection to the real-time text collaboration server has been restored."