feat(pool): optional page preview capture on reassignment (0.3.7)

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@mathnotes/mobile-ink` will be documented here.
 
+## [0.3.7] - 2026-10-02
+
+- Added `capturePreviewOnReassign` to `ContinuousEnginePool` (default `true`). Hosts that don't use page previews can set it to `false` to skip the native render and PNG encode that runs for every captured page when the pool shifts. Page data is still captured.
+
 ## [0.3.6] - 2026-10-02
 
 - iOS: selection hit-testing, the selection toolbar and `onInkSelectionChange` now share one bounds helper that rejects non-finite geometry; the event sends `null` bounds instead of NaN. The selection toolbar ignores selection bounds that are not finite. Inverted or overflowing bounds previously produced a NaN frame and terminated the app with `CALayerInvalidGeometry` (seen in production after a pooled page was cleared with a live selection, which 0.3.5 also fixes at the source).

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathnotes/mobile-ink",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Production-grade React Native ink engine with native Skia drawing and continuous canvas primitives.",
   "license": "Apache-2.0",
   "author": "BuilderPro LLC",

src/ContinuousEnginePool.tsx

@@ -54,6 +54,7 @@ export const ContinuousEnginePool = memo(forwardRef<
   onPencilDoubleTap,
   registerPerPageSlot,
   shouldCaptureBeforeReassign,
+  capturePreviewOnReassign = true,
   onSlotCaptureBeforeUnmount,
 }, ref) {
   const slotRefs = useRef<Array<PooledCanvasSlotHandle | null>>([]);
@@ -294,6 +295,7 @@ export const ContinuousEnginePool = memo(forwardRef<
           onPencilDoubleTap={onPencilDoubleTap}
           registerRef={registerPerPageSlot}
           shouldCaptureBeforeReassign={shouldCaptureBeforeReassign}
+          capturePreviewOnReassign={capturePreviewOnReassign}
           onCaptureBeforeReassign={onSlotCaptureBeforeUnmount}
         />
       ))}
@@ -318,5 +320,6 @@ export const ContinuousEnginePool = memo(forwardRef<
   prev.onPencilDoubleTap === next.onPencilDoubleTap &&
   prev.registerPerPageSlot === next.registerPerPageSlot &&
   prev.shouldCaptureBeforeReassign === next.shouldCaptureBeforeReassign &&
+  prev.capturePreviewOnReassign === next.capturePreviewOnReassign &&
   prev.onSlotCaptureBeforeUnmount === next.onSlotCaptureBeforeUnmount
 ));

src/__tests__/ContinuousEnginePool.test.tsx

@@ -190,6 +190,28 @@ describe("ContinuousEnginePool", () => {
     expect(mockReleaseEngine).toHaveBeenCalledTimes(3);
   });
 
+  it("captures page data without rendering a preview when previews are off", async () => {
+    const pages = [page(0), page(1), page(2), page(3)];
+    const onSlotCaptureBeforeUnmount = jest.fn();
+    const { poolRef } = renderPool({
+      shouldCaptureBeforeReassign: jest.fn((pageId: string) => pageId === "page-0"),
+      capturePreviewOnReassign: false,
+      onSlotCaptureBeforeUnmount,
+    });
+    await act(async () => {});
+    mockGetBase64PngData.mockClear();
+
+    await assignPages(poolRef, buildAssignments(pages.slice(0, 3), 0));
+    await assignPages(poolRef, buildAssignments(pages.slice(1, 4), 1));
+
+    expect(onSlotCaptureBeforeUnmount).toHaveBeenCalledWith(
+      "page-0",
+      '{"pages":{"0":"persisted"}}',
+      undefined,
+    );
+    expect(mockGetBase64PngData).not.toHaveBeenCalled();
+  });
+
   it("defaults pooled native canvases to the Ganesh backend", async () => {
     renderPool();
 

src/continuous-engine-pool/PooledCanvasSlot.tsx

@@ -73,6 +73,7 @@ export const PooledCanvasSlot = memo(forwardRef<PooledCanvasSlotHandle, PooledCa
     onPencilDoubleTap,
     registerRef,
     shouldCaptureBeforeReassign,
+    capturePreviewOnReassign,
     onCaptureBeforeReassign,
   }, ref) {
     const slotViewRef = useRef<View | null>(null);
@@ -91,13 +92,15 @@ export const PooledCanvasSlot = memo(forwardRef<PooledCanvasSlotHandle, PooledCa
     const forwardedReadyRef = useRef(false);
     const benchmarkRecordingActiveRef = useRef(false);
     const shouldCaptureBeforeReassignRef = useRef(shouldCaptureBeforeReassign);
+    const capturePreviewOnReassignRef = useRef(capturePreviewOnReassign);
     const captureCallbackRef = useRef(onCaptureBeforeReassign);
     const onCanvasReadyRef = useRef(onCanvasReady);
     const onSlotLoadedRef = useRef(onSlotLoaded);
     const onSelectionChangeRef = useRef(onSelectionChange);
     const getToolStateRef = useRef(getToolState);
 
     shouldCaptureBeforeReassignRef.current = shouldCaptureBeforeReassign;
+    capturePreviewOnReassignRef.current = capturePreviewOnReassign;
     captureCallbackRef.current = onCaptureBeforeReassign;
     onCanvasReadyRef.current = onCanvasReady;
     onSlotLoadedRef.current = onSlotLoaded;
@@ -289,10 +292,12 @@ export const PooledCanvasSlot = memo(forwardRef<PooledCanvasSlotHandle, PooledCa
         const data = await sourceRef.getBase64Data();
         if (data) {
           let previewUri: string | null = null;
-          try {
-            previewUri = await sourceRef.getBase64PngData(PAGE_PREVIEW_CAPTURE_SCALE);
-          } catch {
-            previewUri = null;
+          if (capturePreviewOnReassignRef.current) {
+            try {
+              previewUri = await sourceRef.getBase64PngData(PAGE_PREVIEW_CAPTURE_SCALE);
+            } catch {
+              previewUri = null;
+            }
           }
           captureCallbackRef.current(pageId, data, previewUri || undefined);
         }
@@ -683,6 +688,7 @@ export const PooledCanvasSlot = memo(forwardRef<PooledCanvasSlotHandle, PooledCa
   prev.onPencilDoubleTap === next.onPencilDoubleTap &&
   prev.registerRef === next.registerRef &&
   prev.shouldCaptureBeforeReassign === next.shouldCaptureBeforeReassign &&
+  prev.capturePreviewOnReassign === next.capturePreviewOnReassign &&
   prev.onCaptureBeforeReassign === next.onCaptureBeforeReassign
 ));
 

src/continuous-engine-pool/types.ts

@@ -89,6 +89,13 @@ export type ContinuousEnginePoolProps = {
     sourceRef?: ContinuousEnginePoolSlotRef,
   ) => void;
   shouldCaptureBeforeReassign: (pageId: string) => boolean;
+  /**
+   * Also render a PNG preview of a page captured before its slot is
+   * reassigned (passed as `previewUri` to onSlotCaptureBeforeUnmount).
+   * Defaults to true. Set false when previews are not used, to skip a
+   * native render and PNG encode on every page shift.
+   */
+  capturePreviewOnReassign?: boolean;
   onSlotCaptureBeforeUnmount: (
     pageId: string,
     data: string,
@@ -145,6 +152,7 @@ export type PooledCanvasSlotProps = {
     sourceRef?: ContinuousEnginePoolSlotRef,
   ) => void;
   shouldCaptureBeforeReassign: (pageId: string) => boolean;
+  capturePreviewOnReassign: boolean;
   onCaptureBeforeReassign: (
     pageId: string,
     data: string,