From aec1fd4bcfcdd691a18082db23dc57df97dc4d62 Mon Sep 17 00:00:00 2001
From: Clarence Palmer <c@cepvi.dev>
Date: Fri, 22 May 2026 00:37:54 -0700
Subject: [PATCH 1/2] fix(editor): keep container measurable while loading for
 comments visibility

---
 packages/react/AGENTS.md                   |  2 +-
 packages/react/src/SuperDocEditor.test.tsx | 12 ++++++++++++
 packages/react/src/SuperDocEditor.tsx      |  4 +++-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/packages/react/AGENTS.md b/packages/react/AGENTS.md
index e345bec0ea..c70dd31ac0 100644
--- a/packages/react/AGENTS.md
+++ b/packages/react/AGENTS.md
@@ -62,7 +62,7 @@ Pass `contained` to scroll inside a fixed-height parent. The wrapper must have a
 
 ## SSR Behavior
 
-- Container divs are always rendered (hidden with `display: none` until initialized)
+- Container divs are always rendered and remain measurable while loading
 - No `isClient` state or extra rerender — containers exist from first render
 - SuperDoc initializes in `useEffect` (client-side only) and mounts into the existing containers
 - `renderLoading()` shown alongside hidden containers until initialization completes
diff --git a/packages/react/src/SuperDocEditor.test.tsx b/packages/react/src/SuperDocEditor.test.tsx
index d40ff03b64..3ec34d2b6b 100644
--- a/packages/react/src/SuperDocEditor.test.tsx
+++ b/packages/react/src/SuperDocEditor.test.tsx
@@ -84,6 +84,18 @@ describe('SuperDocEditor', () => {
 
       expect(container.querySelector('[data-testid="loading"]')).toBeTruthy();
     });
+
+    it('keeps the editor container measurable while loading', () => {
+      const { container } = render(
+        <SuperDocEditor renderLoading={() => <div data-testid='loading'>Loading...</div>} />,
+      );
+
+      const editorContainer = container.querySelector('.superdoc-editor-container') as HTMLElement;
+
+      expect(editorContainer.style.display).not.toBe('none');
+      expect(editorContainer.style.visibility).toBe('hidden');
+      expect(editorContainer.style.pointerEvents).toBe('none');
+    });
   });
 
   describe('callbacks', () => {
diff --git a/packages/react/src/SuperDocEditor.tsx b/packages/react/src/SuperDocEditor.tsx
index b022552456..250ad5ea9b 100644
--- a/packages/react/src/SuperDocEditor.tsx
+++ b/packages/react/src/SuperDocEditor.tsx
@@ -245,7 +245,9 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
   }, [documentProp, user, users, modules, role, hideToolbar, contained, containerId, toolbarId]);
 
   const wrapperClassName = ['superdoc-wrapper', className].filter(Boolean).join(' ');
-  const hideWhenLoading: CSSProperties | undefined = isLoading ? { display: 'none' } : undefined;
+  const hideWhenLoading: CSSProperties | undefined = isLoading
+    ? { visibility: 'hidden', pointerEvents: 'none' }
+    : undefined;
 
   const wrapperStyle: CSSProperties = {
     ...style,

From bf3ce722256984aa97a0c65f69f08efbe7706bbb Mon Sep 17 00:00:00 2001
From: Clarence Palmer <c@cepvi.dev>
Date: Fri, 22 May 2026 00:53:07 -0700
Subject: [PATCH 2/2] fix: account for layout space

---
 packages/react/src/SuperDocEditor.test.tsx | 18 ++++++++++++++++++
 packages/react/src/SuperDocEditor.tsx      | 14 +++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/SuperDocEditor.test.tsx b/packages/react/src/SuperDocEditor.test.tsx
index 3ec34d2b6b..e77c85a1f9 100644
--- a/packages/react/src/SuperDocEditor.test.tsx
+++ b/packages/react/src/SuperDocEditor.test.tsx
@@ -96,6 +96,24 @@ describe('SuperDocEditor', () => {
       expect(editorContainer.style.visibility).toBe('hidden');
       expect(editorContainer.style.pointerEvents).toBe('none');
     });
+
+    it('overlays loading content while contained and loading', () => {
+      const { container } = render(
+        <SuperDocEditor contained renderLoading={() => <div data-testid='loading'>Loading...</div>} />,
+      );
+
+      const wrapper = container.querySelector('.superdoc-wrapper') as HTMLElement;
+      const editorContainer = container.querySelector('.superdoc-editor-container') as HTMLElement;
+      const loadingContainer = container.querySelector('.superdoc-loading-container') as HTMLElement;
+
+      expect(wrapper.style.position).toBe('relative');
+      expect(editorContainer.style.display).not.toBe('none');
+      expect(editorContainer.style.visibility).toBe('hidden');
+      expect(editorContainer.style.flex).toBe('1 1 0%');
+      expect(loadingContainer.style.position).toBe('absolute');
+      expect(loadingContainer.style.inset).toBe('0');
+      expect(loadingContainer.style.zIndex).toBe('1');
+    });
   });
 
   describe('callbacks', () => {
diff --git a/packages/react/src/SuperDocEditor.tsx b/packages/react/src/SuperDocEditor.tsx
index 250ad5ea9b..e21f286681 100644
--- a/packages/react/src/SuperDocEditor.tsx
+++ b/packages/react/src/SuperDocEditor.tsx
@@ -252,6 +252,14 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
   const wrapperStyle: CSSProperties = {
     ...style,
     ...(contained && { display: 'flex', flexDirection: 'column' as const }),
+    ...(isLoading &&
+      renderLoading && { position: style?.position && style.position !== 'static' ? style.position : 'relative' }),
+  };
+
+  const loadingStyle: CSSProperties = {
+    position: 'absolute',
+    inset: 0,
+    zIndex: 1,
   };
 
   return (
@@ -264,7 +272,11 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
         className='superdoc-editor-container'
         style={{ ...hideWhenLoading, ...(contained && { flex: 1, minHeight: 0 }) }}
       />
-      {isLoading && !hasError && renderLoading && <div className='superdoc-loading-container'>{renderLoading()}</div>}
+      {isLoading && !hasError && renderLoading && (
+        <div className='superdoc-loading-container' style={loadingStyle}>
+          {renderLoading()}
+        </div>
+      )}
       {hasError && <div className='superdoc-error-container'>Failed to load editor. Check console for details.</div>}
     </div>
   );