@extend-ai/react-docx 0.7.0-alpha.6 → 0.7.0-alpha.7

package/README.md

@@ -158,7 +158,7 @@ export function EditorExample() {
 
 ## Thumbnail Hook
 
-The library can expose page thumbnails from mounted viewer surfaces so you can build your own page strip, mini-map, or navigation UI.
+The library can expose page thumbnails so you can build your own page strip, mini-map, or navigation UI. Thumbnail painting can render from the live page surface when it is mounted, or from an offscreen one-page surface when viewer virtualization has unmounted that page.
 
 ```tsx
 import * as React from "react";
@@ -194,10 +194,7 @@ export function ThumbnailExample() {
         ))}
       </div>
 
-      <DocxEditorViewer
-        editor={editor}
-        pageVirtualization={{ enabled: false }}
-      />
+      <DocxEditorViewer editor={editor} />
     </div>
   );
 }
@@ -205,10 +202,9 @@ export function ThumbnailExample() {
 
 Notes:
 
-- Thumbnails are produced from mounted page DOM.
+- Thumbnail canvases can stay attached in a virtualized sidebar; only canvases you mount request paint work.
 - Thumbnail sizing is bounded by `maxWidthPx` and `maxHeightPx`, so downstream UIs can bias toward portrait thumbnail rails.
-- If page virtualization is enabled, offscreen pages can report `status: "unavailable"`.
-- For a full thumbnail rail, disable virtualization or manage the visible page range yourself.
+- If the main viewer has virtualized a page away, thumbnail rendering mounts an isolated offscreen page surface long enough to rasterize that page.
 
 ## Useful Hooks
 

package/dist/index.cjs

@@ -23682,13 +23682,14 @@ function ensureDocxViewerPageSurfaceRegistry(editor) {
     registry = {
       pageElements: /* @__PURE__ */ new Map(),
       pageContentKeys: /* @__PURE__ */ new Map(),
+      pageSizes: /* @__PURE__ */ new Map(),
       listeners: /* @__PURE__ */ new Set()
     };
     docxViewerPageSurfaceRegistryByEditor.set(owner, registry);
   }
   return registry;
 }
-function syncDocxViewerPageSurfaceContentKeys(editor, contentKeysByPage) {
+function syncDocxViewerPageSurfaceContentKeys(editor, contentKeysByPage, pageSizesByPage = []) {
   const registry = ensureDocxViewerPageSurfaceRegistry(editor);
   let changed = false;
   contentKeysByPage.forEach((contentKey, pageIndex) => {
@@ -23697,12 +23698,27 @@ function syncDocxViewerPageSurfaceContentKeys(editor, contentKeysByPage) {
       changed = true;
     }
   });
+  pageSizesByPage.forEach((pageSize, pageIndex) => {
+    const widthPx = Math.max(1, Math.round(pageSize.widthPx));
+    const heightPx = Math.max(1, Math.round(pageSize.heightPx));
+    const previous = registry.pageSizes.get(pageIndex);
+    if (previous?.widthPx !== widthPx || previous?.heightPx !== heightPx) {
+      registry.pageSizes.set(pageIndex, { widthPx, heightPx });
+      changed = true;
+    }
+  });
   registry.pageContentKeys.forEach((_, pageIndex) => {
     if (pageIndex >= contentKeysByPage.length) {
       registry.pageContentKeys.delete(pageIndex);
       changed = true;
     }
   });
+  registry.pageSizes.forEach((_, pageIndex) => {
+    if (pageIndex >= pageSizesByPage.length) {
+      registry.pageSizes.delete(pageIndex);
+      changed = true;
+    }
+  });
   if (changed) {
     notifyDocxViewerPageSurfaceSubscribers(registry);
   }
@@ -23719,7 +23735,7 @@ function notifyDocxViewerPageSurfaceSubscribers(registry) {
     listener();
   });
 }
-function registerDocxViewerPageSurface(editor, pageIndex, element) {
+function registerDocxViewerPageSurface(editor, pageIndex, element, previousElement) {
   const registry = ensureDocxViewerPageSurfaceRegistry(editor);
   const normalizedPageIndex = Math.max(0, Math.round(pageIndex));
   const currentElement = registry.pageElements.get(normalizedPageIndex);
@@ -23734,9 +23750,22 @@ function registerDocxViewerPageSurface(editor, pageIndex, element) {
   if (!currentElement) {
     return;
   }
+  if (previousElement && currentElement !== previousElement) {
+    return;
+  }
   registry.pageElements.delete(normalizedPageIndex);
   notifyDocxViewerPageSurfaceSubscribers(registry);
 }
+function resolveDocxViewerRegisteredPageSurfaceSize(registry, pageIndex, fallbackWidthPx, fallbackHeightPx) {
+  const registeredSize = registry.pageSizes.get(pageIndex);
+  if (registeredSize) {
+    return registeredSize;
+  }
+  return {
+    widthPx: Math.max(1, Math.round(fallbackWidthPx)),
+    heightPx: Math.max(1, Math.round(fallbackHeightPx))
+  };
+}
 function resolveDocxViewerPageSurfaceSize(element, fallbackWidthPx, fallbackHeightPx) {
   if (element) {
     const rect = element.getBoundingClientRect();
@@ -23770,6 +23799,104 @@ function resolveDocxViewerPageSurfaceSize(element, fallbackWidthPx, fallbackHeig
     heightPx: Math.max(1, Math.round(fallbackHeightPx))
   };
 }
+function DocxDetachedThumbnailPageSurface({
+  editor,
+  pageIndex
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    DocxEditorViewer,
+    {
+      editor,
+      mode: "read-only",
+      visiblePageRange: { startPageIndex: pageIndex, endPageIndex: pageIndex },
+      pageVirtualization: { enabled: false },
+      showTrackedChanges: editor.showTrackedChanges,
+      showComments: editor.showComments,
+      style: {
+        background: "transparent",
+        padding: 0,
+        margin: 0
+      }
+    }
+  );
+}
+var DocxDetachedThumbnailSurfaceRenderer = class {
+  host;
+  root;
+  activePageIndex;
+  async renderPageSurface(params) {
+    if (typeof document === "undefined" || typeof window === "undefined") {
+      return void 0;
+    }
+    const { editor, registry, pageIndex } = params;
+    await this.ensureRoot();
+    if (!this.root) {
+      return void 0;
+    }
+    if (this.activePageIndex !== pageIndex) {
+      this.activePageIndex = pageIndex;
+      this.root.render(
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          DocxDetachedThumbnailPageSurface,
+          {
+            editor,
+            pageIndex
+          }
+        )
+      );
+    }
+    return this.waitForPageSurface(registry, pageIndex);
+  }
+  clear() {
+    if (this.root) {
+      this.root.unmount();
+      this.root = void 0;
+    }
+    if (this.host?.parentNode) {
+      this.host.parentNode.removeChild(this.host);
+    }
+    this.host = void 0;
+    this.activePageIndex = void 0;
+  }
+  async ensureRoot() {
+    if (this.root) {
+      return;
+    }
+    if (typeof document === "undefined") {
+      return;
+    }
+    const host = document.createElement("div");
+    host.setAttribute("data-docx-thumbnail-detached-renderer", "true");
+    Object.assign(host.style, {
+      position: "fixed",
+      left: "-100000px",
+      top: "0",
+      width: "1px",
+      height: "1px",
+      overflow: "visible",
+      opacity: "0",
+      pointerEvents: "none",
+      zIndex: "-1"
+    });
+    document.body.appendChild(host);
+    this.host = host;
+    const { createRoot } = await import("react-dom/client");
+    this.root = createRoot(host);
+  }
+  async waitForPageSurface(registry, pageIndex) {
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const pageElement2 = registry.pageElements.get(pageIndex);
+      if (pageElement2?.isConnected) {
+        return pageElement2;
+      }
+      await new Promise((resolve) => {
+        window.requestAnimationFrame(() => resolve());
+      });
+    }
+    const pageElement = registry.pageElements.get(pageIndex);
+    return pageElement?.isConnected ? pageElement : void 0;
+  }
+};
 var DOCX_THUMBNAIL_SURFACE_CACHE_MAX_ENTRIES = 32;
 var DOCX_THUMBNAIL_MIN_RASTER_INTERVAL_MS = 200;
 function resolveDocxPageThumbnailResolution(options) {
@@ -23847,6 +23974,7 @@ function useDocxPageThumbnails(editor, options = {}) {
   );
   const thumbnailSurfaceCacheRef = React.useRef(void 0);
   const thumbnailRasterQueueRef = React.useRef(void 0);
+  const detachedThumbnailSurfaceRendererRef = React.useRef(void 0);
   const lastPaintedThumbnailKeyByCanvasRef = React.useRef(
     /* @__PURE__ */ new WeakMap()
   );
@@ -23869,8 +23997,17 @@ function useDocxPageThumbnails(editor, options = {}) {
   React.useEffect(() => {
     thumbnailSurfaceCacheRef.current?.clear();
     thumbnailRasterQueueRef.current?.clear();
+    detachedThumbnailSurfaceRendererRef.current?.clear();
+    detachedThumbnailSurfaceRendererRef.current = void 0;
     lastPaintedThumbnailKeyByCanvasRef.current = /* @__PURE__ */ new WeakMap();
   }, [editor.documentLoadNonce, pageSurfaceRegistryOwner]);
+  React.useEffect(
+    () => () => {
+      detachedThumbnailSurfaceRendererRef.current?.clear();
+      detachedThumbnailSurfaceRendererRef.current = void 0;
+    },
+    []
+  );
   const thumbnailResolutionOptionsKey = React.useMemo(() => {
     const bounds = options.resolution;
     const boundsKey = typeof bounds === "number" ? `n${bounds}` : bounds ? `b${bounds.maxWidth ?? ""}x${bounds.maxHeight ?? ""}` : "";
@@ -23898,11 +24035,6 @@ function useDocxPageThumbnails(editor, options = {}) {
         return;
       }
       const requiresAttachedTarget = canvas === void 0;
-      const pageElement = pageSurfaceRegistry.pageElements.get(pageIndex);
-      if (!pageElement || !pageElement.isConnected) {
-        updatePageThumbnailState(pageIndex, "unavailable");
-        return;
-      }
       const force = renderOptions?.force === true;
       const lastPaintedKey = lastPaintedThumbnailKeyByCanvasRef.current.get(targetCanvas);
       if (!force && lastPaintedKey !== void 0 && lastPaintedKey === thumbnailSkipKeyForPage(pageIndex)) {
@@ -23914,41 +24046,67 @@ function useDocxPageThumbnails(editor, options = {}) {
         if (requiresAttachedTarget && attachedCanvasByPageRef.current.get(pageIndex) !== targetCanvas) {
           return;
         }
-        const livePageElement = pageSurfaceRegistry.pageElements.get(pageIndex);
-        if (!livePageElement || !livePageElement.isConnected) {
-          updatePageThumbnailState(pageIndex, "unavailable");
-          return;
-        }
         const runSkipKey = thumbnailSkipKeyForPage(pageIndex);
-        const sourceSize = resolveDocxViewerPageSurfaceSize(
-          livePageElement,
+        const fallbackSourceSize = resolveDocxViewerRegisteredPageSurfaceSize(
+          pageSurfaceRegistry,
+          pageIndex,
           fallbackLayout.pageWidthPx,
           fallbackLayout.pageHeightPx
         );
         const resolution = resolveDocxPageThumbnailResolution({
-          sourceWidthPx: sourceSize.widthPx,
-          sourceHeightPx: sourceSize.heightPx,
+          sourceWidthPx: fallbackSourceSize.widthPx,
+          sourceHeightPx: fallbackSourceSize.heightPx,
           resolution: options.resolution,
           maxWidthPx: options.maxWidthPx,
           maxHeightPx: options.maxHeightPx,
           pixelRatio: options.pixelRatio
         });
-        const surfaceKey = runSkipKey === void 0 ? void 0 : `${runSkipKey}|${sourceSize.widthPx}x${sourceSize.heightPx}|${resolution.pixelWidthPx}x${resolution.pixelHeightPx}`;
+        const surfaceKey = runSkipKey === void 0 ? void 0 : `${runSkipKey}|${fallbackSourceSize.widthPx}x${fallbackSourceSize.heightPx}|${resolution.pixelWidthPx}x${resolution.pixelHeightPx}`;
         const surfaceCache = ensureThumbnailSurfaceCache();
         try {
           let surface = !force && surfaceKey !== void 0 ? surfaceCache.get(surfaceKey) : void 0;
           if (!surface) {
-            surface = await rasterizeDocxThumbnailSurface({
-              pageElement: livePageElement,
-              sourceWidthPx: sourceSize.widthPx,
-              sourceHeightPx: sourceSize.heightPx,
-              widthPx: resolution.widthPx,
-              heightPx: resolution.heightPx,
-              pixelWidthPx: resolution.pixelWidthPx,
-              pixelHeightPx: resolution.pixelHeightPx
-            });
-            if (surfaceKey !== void 0) {
-              surfaceCache.set(surfaceKey, surface);
+            let livePageElement = pageSurfaceRegistry.pageElements.get(pageIndex);
+            let renderedDetachedSurface = false;
+            try {
+              if (!livePageElement || !livePageElement.isConnected) {
+                if (!detachedThumbnailSurfaceRendererRef.current) {
+                  detachedThumbnailSurfaceRendererRef.current = new DocxDetachedThumbnailSurfaceRenderer();
+                }
+                livePageElement = await detachedThumbnailSurfaceRendererRef.current.renderPageSurface(
+                  {
+                    editor,
+                    registry: pageSurfaceRegistry,
+                    pageIndex
+                  }
+                );
+                renderedDetachedSurface = true;
+              }
+              if (!livePageElement || !livePageElement.isConnected) {
+                updatePageThumbnailState(pageIndex, "unavailable");
+                return;
+              }
+              const sourceSize = resolveDocxViewerPageSurfaceSize(
+                livePageElement,
+                fallbackSourceSize.widthPx,
+                fallbackSourceSize.heightPx
+              );
+              surface = await rasterizeDocxThumbnailSurface({
+                pageElement: livePageElement,
+                sourceWidthPx: sourceSize.widthPx,
+                sourceHeightPx: sourceSize.heightPx,
+                widthPx: resolution.widthPx,
+                heightPx: resolution.heightPx,
+                pixelWidthPx: resolution.pixelWidthPx,
+                pixelHeightPx: resolution.pixelHeightPx
+              });
+              if (surfaceKey !== void 0) {
+                surfaceCache.set(surfaceKey, surface);
+              }
+            } finally {
+              if (renderedDetachedSurface) {
+                detachedThumbnailSurfaceRendererRef.current?.clear();
+              }
             }
           }
           blitDocxThumbnailSurface(surface, targetCanvas, resolution);
@@ -23980,7 +24138,8 @@ function useDocxPageThumbnails(editor, options = {}) {
       options.pixelRatio,
       pageSurfaceRegistry,
       thumbnailSkipKeyForPage,
-      updatePageThumbnailState
+      updatePageThumbnailState,
+      editor
     ]
   );
   const requestAttachedThumbnailRenders = React.useCallback(
@@ -24024,10 +24183,15 @@ function useDocxPageThumbnails(editor, options = {}) {
     const totalPages = Math.max(1, editor.totalPages);
     return Array.from({ length: totalPages }, (_, pageIndex) => {
       const pageElement = mountedPageElements.get(pageIndex);
-      const sourceSize = resolveDocxViewerPageSurfaceSize(
+      const sourceSize = pageElement && pageElement.isConnected ? resolveDocxViewerPageSurfaceSize(
         pageElement,
         fallbackLayout.pageWidthPx,
         fallbackLayout.pageHeightPx
+      ) : resolveDocxViewerRegisteredPageSurfaceSize(
+        pageSurfaceRegistry,
+        pageIndex,
+        fallbackLayout.pageWidthPx,
+        fallbackLayout.pageHeightPx
       );
       const resolution = resolveDocxPageThumbnailResolution({
         sourceWidthPx: sourceSize.widthPx,
@@ -24097,6 +24261,7 @@ function useDocxPageThumbnails(editor, options = {}) {
     options.maxHeightPx,
     options.maxWidthPx,
     options.pixelRatio,
+    pageSurfaceRegistry,
     pageThumbnailStates
   ]);
   const paintThumbnail = React.useCallback(
@@ -25393,13 +25558,23 @@ function DocxEditorViewer({
       if (cached) {
         return cached;
       }
+      let registeredElement = null;
       const nextRef = (element) => {
         if (element) {
+          registeredElement = element;
           pageElementsRef.current.set(normalizedPageIndex, element);
         } else {
           pageElementsRef.current.delete(normalizedPageIndex);
         }
-        registerDocxViewerPageSurface(editor, normalizedPageIndex, element);
+        registerDocxViewerPageSurface(
+          editor,
+          normalizedPageIndex,
+          element,
+          registeredElement
+        );
+        if (!element) {
+          registeredElement = null;
+        }
       };
       pageSurfaceRefCallbacksRef.current.set(normalizedPageIndex, nextRef);
       return nextRef;
@@ -26462,12 +26637,27 @@ function DocxEditorViewer({
     pageSectionInfoByIndex,
     trackedChangesEnabled
   ]);
+  const pageThumbnailSurfaceSizesByPage = React.useMemo(
+    () => pageNodeSegmentsByPage.map((_, pageIndex) => {
+      const pageLayout = pageSectionInfoByIndex[pageIndex]?.layout ?? documentLayout;
+      return {
+        widthPx: pageLayout.pageWidthPx,
+        heightPx: pageLayout.pageHeightPx
+      };
+    }),
+    [documentLayout, pageNodeSegmentsByPage, pageSectionInfoByIndex]
+  );
   React.useEffect(() => {
     syncDocxViewerPageSurfaceContentKeys(
       editor,
-      pageThumbnailContentKeysByPage
+      pageThumbnailContentKeysByPage,
+      pageThumbnailSurfaceSizesByPage
     );
-  }, [pageSurfaceRegistryOwner, pageThumbnailContentKeysByPage]);
+  }, [
+    pageSurfaceRegistryOwner,
+    pageThumbnailContentKeysByPage,
+    pageThumbnailSurfaceSizesByPage
+  ]);
   const resolveStyleRefFieldValueForPage = React.useMemo(() => {
     const valueCache = /* @__PURE__ */ new Map();
     const nodes = editor.model.nodes;