@reekon-tools/boldr-utils 1.6.24 → 1.6.26

package/dist/annotation/canvas/AnnotationCanvasInner.d.ts

@@ -35,6 +35,7 @@ export interface AnnotationCanvasInnerProps {
     height: number;
     initialViewport?: ViewportState;
     style?: CSSProperties;
+    magnifierTopOffset?: number;
     imperativeRef?: MutableRefObject<AnnotationCanvasHandle | null>;
 }
 export type PanTrigger = 'middleMouse' | 'rightMouse' | 'space';

package/dist/annotation/canvas/AnnotationCanvasInner.native.d.ts

@@ -36,6 +36,7 @@ export interface AnnotationCanvasInnerProps {
     height: number;
     initialViewport?: ViewportState;
     style?: ViewStyle;
+    magnifierTopOffset?: number;
     imperativeRef?: MutableRefObject<AnnotationCanvasHandle | null>;
 }
 export declare const AnnotationCanvasInner: (props: AnnotationCanvasInnerProps) => import("react/jsx-runtime").JSX.Element;

package/dist/annotation/canvas/AnnotationCanvasInner.native.js

@@ -1,5 +1,5 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Skia, useFont } from '@shopify/react-native-skia';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Group, Line, Rect, RoundedRect, Skia, rect, rrect, useFont, } from '@shopify/react-native-skia';
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { StyleSheet, TouchableOpacity, View, } from 'react-native';
 import { Gesture, GestureDetector, GestureHandlerRootView, } from 'react-native-gesture-handler';
@@ -7,6 +7,7 @@ import Animated, { runOnJS, runOnUI, useAnimatedStyle, useDerivedValue, useShare
 import { stampTileSize } from './stampLayout.js';
 import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
+import { useBackgroundSkImage } from './elements/BackgroundImageElement.js';
 import { buildRemoveMeasurementOps, } from './measurementGeometry.js';
 import { buildShapeFromDrag } from './tools/shapeTool.js';
 import { SELECTION_PAD } from './textGeometry.js';
@@ -29,6 +30,20 @@ const HANDLE_RING_PX = 2;
 // selectTool's MIN_SHAPE_EXTENT (the live preview must clamp identically to the
 // buildShapeCornerPatch commit). Keep the two in sync.
 const MIN_SHAPE_EXTENT = 1;
+// Magnifying-glass loupe. A separate, top-most overlay canvas re-draws the Skia
+// scene zoomed around the finger and clipped to a fixed lens window, so it sits
+// ABOVE the RN measurement/input overlay (which the main canvas sits below) and
+// never touches the main canvas (no flicker). It mounts only during a precision
+// gesture, so there's no cost at rest.
+const LOUPE_SIZE_FRACTION = 0.3; // of the smaller canvas dimension
+const LOUPE_MARGIN = 12; // points from the top-left corner
+const LOUPE_MAGNIFICATION = 2; // extra zoom inside the lens, on top of viewport
+const LOUPE_RADIUS = 16; // lens corner radius
+const LOUPE_BORDER_WIDTH = 2;
+const LOUPE_BORDER_COLOR = '#1F2937';
+const LOUPE_BG_COLOR = '#FFFFFF';
+const LOUPE_CROSSHAIR_COLOR = '#1F293799'; // ~60% dark — marks the exact point
+const LOUPE_CROSSHAIR_ARM = 9; // half-length of each crosshair arm, points
 // Native fingerprint: one finger drives the active tool, two fingers
 // pan/zoom the viewport. Tap counts as a brief pointer down+up so tools
 // like measurement-stamp (which only listen to onPointerUp) work via tap.
@@ -41,9 +56,13 @@ const MIN_SHAPE_EXTENT = 1;
 // is only re-synced once each gesture ends. The tool/tap path still hops to
 // JS (`runOnJS(true)`) since drawing/selection are React-state operations.
 export const AnnotationCanvasInner = (props) => {
-    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, width, height, style, } = props;
+    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, } = props;
     const valueFont = useFont(stampFontSource, stampValueFontSize);
     const state = useAnnotationCanvasState(props);
+    // Decode the background image ONCE here and share it with both the main
+    // canvas and the magnifier loupe. If each canvas loaded its own, the loupe
+    // would flash its blank base every gesture while it re-resolved + re-decoded.
+    const backgroundSkImage = useBackgroundSkImage(state.effectiveCanvas.viewport.backgroundImage, resolveImageUrl);
     // Latest state behind a ref so the gesture object can be built once and
     // never rebuilt mid-gesture — its JS callbacks read `stateRef.current`.
     const stateRef = useRef(state);
@@ -68,6 +87,40 @@ export const AnnotationCanvasInner = (props) => {
             { translateY: -panY.value },
         ];
     });
+    // Magnifying-glass loupe. The live touch (screen points) rides shared values
+    // the gesture worklets update; `magnifying` (React state) gates whether the
+    // loupe shader wraps the canvas at all — so the extra fullscreen pass exists
+    // only while a precision gesture is in flight (drawing, shape rubber-band,
+    // endpoint/corner drags), never during idle renders or viewport pan/zoom.
+    const magTouchX = useSharedValue(0);
+    const magTouchY = useSharedValue(0);
+    const [magnifying, setMagnifying] = useState(false);
+    // Lens geometry (screen points): a fixed square in the top-left, pushed below
+    // any overlaid toolbar by magnifierTopOffset. Its CENTER maps to the live
+    // touch point, so the magnified slice is the canvas around the finger.
+    const loupeSize = Math.round(Math.min(width, height) * LOUPE_SIZE_FRACTION);
+    const loupeX = LOUPE_MARGIN;
+    const loupeY = magnifierTopOffset + LOUPE_MARGIN;
+    const loupeCx = loupeX + loupeSize / 2;
+    const loupeCy = loupeY + loupeSize / 2;
+    // World→lens transform: take the live screen point under the finger to the
+    // lens center, scaled by LOUPE_MAGNIFICATION on top of the viewport zoom.
+    // screen' = lensCenter + m * (worldTransform(world) - touch). Composed as a
+    // transform list (last entry applied to the point first), prepended onto the
+    // viewport's own [scale, -pan] ops.
+    const loupeTransform = useDerivedValue(() => {
+        'worklet';
+        return [
+            { translateX: loupeCx },
+            { translateY: loupeCy },
+            { scale: LOUPE_MAGNIFICATION },
+            { translateX: -magTouchX.value },
+            { translateY: -magTouchY.value },
+            { scale: zoom.value },
+            { translateX: -panX.value },
+            { translateY: -panY.value },
+        ];
+    }, [loupeCx, loupeCy]);
     // In-flight freehand stroke, owned by the UI thread. The drawing gesture
     // appends world-space points to `livePoints`; `livePath` rebuilds the Skia
     // path off it. React state is untouched until the stroke commits on
@@ -597,6 +650,8 @@ export const AnnotationCanvasInner = (props) => {
             const id = pointerIdRef.current++;
             const screen = { x: e.x, y: e.y };
             inFlightRef.current = { id, lastScreen: screen };
+            magTouchX.value = e.x;
+            magTouchY.value = e.y;
             stateRef.current.dispatchPointerDown(buildEvent(id, screen));
         })
             .onUpdate((e) => {
@@ -605,6 +660,12 @@ export const AnnotationCanvasInner = (props) => {
                 return;
             const screen = { x: e.x, y: e.y };
             f.lastScreen = screen;
+            // Drag-to-draw tools (measurement line / rectangle) run through this
+            // JS-thread pointer path; show the loupe once the touch actually moves
+            // so a plain tap-to-place tool never flashes it.
+            magTouchX.value = e.x;
+            magTouchY.value = e.y;
+            setMagnifying(true);
             stateRef.current.dispatchPointerMove(buildEvent(f.id, screen));
         })
             .onEnd((e) => {
@@ -615,6 +676,7 @@ export const AnnotationCanvasInner = (props) => {
             inFlightRef.current = null;
         })
             .onFinalize(() => {
+            setMagnifying(false);
             if (inFlightRef.current) {
                 stateRef.current.dispatchPointerCancel();
                 inFlightRef.current = null;
@@ -794,9 +856,14 @@ export const AnnotationCanvasInner = (props) => {
                     e.x / zoom.value + panX.value,
                     e.y / zoom.value + panY.value,
                 ];
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
+                runOnJS(setMagnifying)(true);
             })
                 .onChange((e) => {
                 'worklet';
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
                 const wx = e.x / zoom.value + panX.value;
                 const wy = e.y / zoom.value + panY.value;
                 const pts = livePoints.value;
@@ -832,6 +899,7 @@ export const AnnotationCanvasInner = (props) => {
                 // Cancel path (no onEnd): drop the in-flight preview. After a normal
                 // end the buffer is already empty, so this is a no-op.
                 livePoints.value = [];
+                runOnJS(setMagnifying)(false);
             });
         };
         // Shape rubber-band (line/arrow/rect/triangle/circle tools) — one finger,
@@ -867,12 +935,17 @@ export const AnnotationCanvasInner = (props) => {
                 const wx = e.x / zoom.value + panX.value;
                 const wy = e.y / zoom.value + panY.value;
                 liveShape.value = { active: true, ax: wx, ay: wy, bx: wx, by: wy };
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
+                runOnJS(setMagnifying)(true);
             })
                 .onChange((e) => {
                 'worklet';
                 const s = liveShape.value;
                 if (!s.active)
                     return;
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
                 liveShape.value = {
                     active: true,
                     ax: s.ax,
@@ -919,6 +992,7 @@ export const AnnotationCanvasInner = (props) => {
                 // Cancel path (no onEnd): drop the in-flight rubber-band. After a
                 // normal end the slot is already inactive, so this is a no-op.
                 liveShape.value = { active: false, ax: 0, ay: 0, bx: 0, by: 0 };
+                runOnJS(setMagnifying)(false);
             });
         };
         // Element drag (select tool) — one finger, UI thread. Hit-tests on the JS
@@ -953,6 +1027,7 @@ export const AnnotationCanvasInner = (props) => {
                             };
                             epTargetRef.current = { id: selId, handle };
                             setEpDragId(selId);
+                            setMagnifying(true);
                             return;
                         }
                     }
@@ -974,6 +1049,7 @@ export const AnnotationCanvasInner = (props) => {
                             };
                             shapeEpTargetRef.current = { id: selId, handle: shapeHandle };
                             setShapeEpDragId(selId);
+                            setMagnifying(true);
                             return;
                         }
                     }
@@ -990,6 +1066,7 @@ export const AnnotationCanvasInner = (props) => {
                         };
                         resizeTargetRef.current = { id: selId };
                         setResizingId(selId);
+                        setMagnifying(true);
                         return;
                     }
                     // Rectangle-annotation corner handle — also selected-element-only.
@@ -1003,6 +1080,7 @@ export const AnnotationCanvasInner = (props) => {
                         };
                         rectTargetRef.current = { id: selId, corner: rectCornerHit.corner };
                         setRectDragId(selId);
+                        setMagnifying(true);
                         return;
                     }
                     // Shape (rect/ellipse/polygon) bounding-box corner handle — the shape
@@ -1030,6 +1108,7 @@ export const AnnotationCanvasInner = (props) => {
                             corner: shapeCornerHit.corner,
                         };
                         setShapeResizeId(selId);
+                        setMagnifying(true);
                         return;
                     }
                 }
@@ -1064,6 +1143,8 @@ export const AnnotationCanvasInner = (props) => {
             };
             const endSelectDrag = (dx, dy) => {
                 const st = stateRef.current;
+                // Any precision sub-drag that turned the loupe on is ending now.
+                setMagnifying(false);
                 // Resize commit: scale the shape by the final drag (clamped in
                 // buildResizePatch exactly like the live preview).
                 const rT = resizeTargetRef.current;
@@ -1158,6 +1239,7 @@ export const AnnotationCanvasInner = (props) => {
                 setDraggingId(null);
             };
             const cancelSelectDrag = () => {
+                setMagnifying(false);
                 // No commit — dropping the gating ids snaps everything back.
                 dragTargetRef.current = null;
                 slideTargetRef.current = null;
@@ -1182,6 +1264,10 @@ export const AnnotationCanvasInner = (props) => {
                 dragEnded.value = false;
                 dragX.value = 0;
                 dragY.value = 0;
+                // The loupe (turned on by beginSelectDrag only for precision sub-
+                // drags) follows the live finger, not the hit-test origin.
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
                 // Hit-test at the touch-down point — onStart fires only after the
                 // pan threshold, so back out the accumulated translation.
                 runOnJS(beginSelectDrag)({
@@ -1191,6 +1277,8 @@ export const AnnotationCanvasInner = (props) => {
             })
                 .onChange((e) => {
                 'worklet';
+                magTouchX.value = e.x;
+                magTouchY.value = e.y;
                 // World-space delta from the drag origin. Applied to the element
                 // only once draggingId is set; otherwise it affects nothing.
                 dragX.value = e.translationX / zoom.value;
@@ -1251,80 +1339,89 @@ export const AnnotationCanvasInner = (props) => {
     const activeTool = props.tools.find((t) => t.id === props.activeToolId) ?? null;
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
     const { renderMeasurementStamp, onMeasurementStampPress, onMeasurementStampLongPress, resolveStampMeasurement, onMeasurementStampRemove, selection, } = props;
-    return (_jsxs(GestureHandlerRootView, { style: [{ width, height }, style], children: [_jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia({
-                        width,
-                        height,
-                        effectiveCanvas: state.effectiveCanvas,
-                        worldTransform,
-                        resolveImageUrl,
-                        valueFont,
-                        // Freehand drawing runs on the UI thread via `livePreview`, so the
-                        // JS-state pen preview is unused on native.
-                        penDrawingStroke: null,
-                        livePreview: freehand
-                            ? {
-                                path: livePath,
-                                handoffPaths: [
-                                    handoffPath0,
-                                    handoffPath1,
-                                    handoffPath2,
-                                    handoffPath3,
-                                ],
-                                color: freehand.color,
-                                width: freehand.width,
-                                cap: freehand.cap ?? 'round',
-                                dash: freehand.dash ?? false,
-                                opacity: freehand.variant === 'highlighter' ? 0.3 : 1,
-                            }
-                            : null,
-                        // UI-thread shape rubber-band (live + pending handoffs) — only
-                        // while a shape tool is active (handoffs always release within a
-                        // frame or two of the commit, before the tool can change).
-                        shapePreview: shapeDraw
-                            ? {
-                                path: shapeBodyPath,
-                                headPath: shapeHeadPath,
-                                color: shapeDraw.color,
-                                width: shapeDraw.width,
-                                cap: shapeDraw.cap ?? 'round',
-                                dash: shapeDraw.dash ?? false,
-                            }
-                            : null,
-                        draggingId,
-                        dragTransform,
-                        resizingId,
-                        resizeTransform,
-                        selectedId: selection?.ids[0] ?? null,
-                        endpointDragId: epDragId,
-                        shapeEndpointDragId: shapeEpDragId,
-                        liveLineP1,
-                        liveLineP2,
-                        rectDragId,
-                        liveRect: {
-                            x: liveRectX,
-                            y: liveRectY,
-                            width: liveRectW,
-                            height: liveRectH,
-                        },
-                        shapeResizeId,
-                        shapeResizePath,
-                        shapeResizeBox: {
-                            x: shapeResizeBoxX,
-                            y: shapeResizeBoxY,
-                            width: shapeResizeBoxW,
-                            height: shapeResizeBoxH,
-                        },
-                        // Endpoint/corner handles are drag affordances — only the select
-                        // tool can act on them, so suppress them when the active tool has
-                        // no drag support (e.g. view mode's pan tool, where a selected
-                        // measurement still shows its tile chrome but must not advertise
-                        // draggability).
-                        handleRadius: activeTool?.dragSelection ? handleRadius : undefined,
-                        handleRingWidth: activeTool?.dragSelection
-                            ? handleRingWidth
-                            : undefined,
-                        customPreview,
-                    }) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
+    // The Skia scene props, shared by the main canvas and the loupe overlay. The
+    // loupe re-runs the SAME scene with a magnifying world transform + a lens
+    // clip (see loupeWrap) in a separate top-most canvas, so it shows live vector
+    // content (the dragged line, handles, strokes) magnified above everything.
+    const skiaProps = {
+        width,
+        height,
+        effectiveCanvas: state.effectiveCanvas,
+        worldTransform,
+        resolveImageUrl,
+        backgroundSkImage,
+        valueFont,
+        // Freehand drawing runs on the UI thread via `livePreview`, so the
+        // JS-state pen preview is unused on native.
+        penDrawingStroke: null,
+        livePreview: freehand
+            ? {
+                path: livePath,
+                handoffPaths: [
+                    handoffPath0,
+                    handoffPath1,
+                    handoffPath2,
+                    handoffPath3,
+                ],
+                color: freehand.color,
+                width: freehand.width,
+                cap: freehand.cap ?? 'round',
+                dash: freehand.dash ?? false,
+                opacity: freehand.variant === 'highlighter' ? 0.3 : 1,
+            }
+            : null,
+        // UI-thread shape rubber-band (live + pending handoffs) — only while a
+        // shape tool is active (handoffs always release within a frame or two of
+        // the commit, before the tool can change).
+        shapePreview: shapeDraw
+            ? {
+                path: shapeBodyPath,
+                headPath: shapeHeadPath,
+                color: shapeDraw.color,
+                width: shapeDraw.width,
+                cap: shapeDraw.cap ?? 'round',
+                dash: shapeDraw.dash ?? false,
+            }
+            : null,
+        draggingId,
+        dragTransform,
+        resizingId,
+        resizeTransform,
+        selectedId: selection?.ids[0] ?? null,
+        endpointDragId: epDragId,
+        shapeEndpointDragId: shapeEpDragId,
+        liveLineP1,
+        liveLineP2,
+        rectDragId,
+        liveRect: {
+            x: liveRectX,
+            y: liveRectY,
+            width: liveRectW,
+            height: liveRectH,
+        },
+        shapeResizeId,
+        shapeResizePath,
+        shapeResizeBox: {
+            x: shapeResizeBoxX,
+            y: shapeResizeBoxY,
+            width: shapeResizeBoxW,
+            height: shapeResizeBoxH,
+        },
+        // Endpoint/corner handles are drag affordances — only the select tool can
+        // act on them, so suppress them when the active tool has no drag support
+        // (e.g. view mode's pan tool, where a selected measurement still shows its
+        // tile chrome but must not advertise draggability).
+        handleRadius: activeTool?.dragSelection ? handleRadius : undefined,
+        handleRingWidth: activeTool?.dragSelection ? handleRingWidth : undefined,
+        customPreview,
+    };
+    // Lens window for the loupe: an opaque white base + the magnified scene
+    // clipped to a rounded square, a border, and a crosshair marking the exact
+    // point under the finger. Drawn in the overlay canvas's screen space (the
+    // magnification lives in loupeTransform, applied to `content`).
+    const loupeClip = rrect(rect(loupeX, loupeY, loupeSize, loupeSize), LOUPE_RADIUS, LOUPE_RADIUS);
+    const loupeWrap = (content) => (_jsxs(_Fragment, { children: [_jsxs(Group, { clip: loupeClip, children: [_jsx(Rect, { x: loupeX, y: loupeY, width: loupeSize, height: loupeSize, color: LOUPE_BG_COLOR }), content] }), _jsx(RoundedRect, { x: loupeX, y: loupeY, width: loupeSize, height: loupeSize, r: LOUPE_RADIUS, color: LOUPE_BORDER_COLOR, style: "stroke", strokeWidth: LOUPE_BORDER_WIDTH }), _jsx(Line, { p1: { x: loupeCx - LOUPE_CROSSHAIR_ARM, y: loupeCy }, p2: { x: loupeCx + LOUPE_CROSSHAIR_ARM, y: loupeCy }, color: LOUPE_CROSSHAIR_COLOR, strokeWidth: 1.5 }), _jsx(Line, { p1: { x: loupeCx, y: loupeCy - LOUPE_CROSSHAIR_ARM }, p2: { x: loupeCx, y: loupeCy + LOUPE_CROSSHAIR_ARM }, color: LOUPE_CROSSHAIR_COLOR, strokeWidth: 1.5 })] }));
+    return (_jsxs(GestureHandlerRootView, { style: [{ width, height }, style], children: [_jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia(skiaProps) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
                         ? (state.measurementsById.get(placed.measurementId) ?? null)
                         : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, rectCtx: rectCtx, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.effectiveCanvas.tileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: () => {
                         const defaultRemove = () => {
@@ -1338,7 +1435,11 @@ export const AnnotationCanvasInner = (props) => {
                             return;
                         }
                         defaultRemove();
-                    } }, placed.id))) }))] }));
+                    } }, placed.id))) })), magnifying && (_jsx(View, { pointerEvents: "none", style: StyleSheet.absoluteFill, children: AnnotationCanvasSkia({
+                    ...skiaProps,
+                    worldTransform: loupeTransform,
+                    wrapContent: loupeWrap,
+                }) }))] }));
 };
 const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging, sliding, endpointDragging, rectResizing, zoomSnapshot, zoom, panX, panY, dragX, dragY, slideCtx, epCtx, rectCtx, renderMeasurementStamp, tileScaleFactor, tileViewportScale, onStampPress, onStampLongPress, onRemove, }) => {
     const size = stampTileSize(placed, tileScaleFactor, tileViewportScale);

package/dist/annotation/canvas/AnnotationCanvasSkia.d.ts

@@ -1,4 +1,4 @@
-import { type SkFont, type SkPath, type SkTypefaceFontProvider, type Transforms3d } from '@shopify/react-native-skia';
+import { type SkFont, type SkImage, type SkPath, type SkTypefaceFontProvider, type Transforms3d } from '@shopify/react-native-skia';
 import type { ReactNode } from 'react';
 import type { AnnotationCanvasState, AnnotationStroke, StrokeCap } from '../../types/annotation.js';
 type AnimatedPoint = {
@@ -21,6 +21,7 @@ export interface AnnotationCanvasSkiaProps {
         value: Transforms3d;
     };
     resolveImageUrl?: (storagePath: string) => Promise<string>;
+    backgroundSkImage?: SkImage | null;
     valueFont: SkFont | null;
     textFontMgr?: SkTypefaceFontProvider | null;
     penDrawingStroke: AnnotationStroke | null;
@@ -86,6 +87,7 @@ export interface AnnotationCanvasSkiaProps {
         value: number;
     };
     customPreview?: ReactNode;
+    wrapContent?: (content: ReactNode) => ReactNode;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, backgroundSkImage, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -74,7 +74,8 @@ const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElem
 // since the function-call pattern works identically on native we use it
 // in both Inners for consistency. Don't add hooks here; this is a plain
 // JSX-returning helper, not a component.
-export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, }) => (_jsx(Canvas, { style: { width, height }, children: _jsxs(Group, { transform: worldTransform, children: [effectiveCanvas.viewport.backgroundImage && (_jsx(BackgroundImageElement, { image: effectiveCanvas.viewport.backgroundImage, docWidth: effectiveCanvas.viewport.width, docHeight: effectiveCanvas.viewport.height, fit: effectiveCanvas.viewport.backgroundFit ?? 'contain', resolveUrl: resolveImageUrl })), effectiveCanvas.strokes.map((stroke) => (_jsx(DraggableElement, { isDragging: stroke.id === draggingId, transform: dragTransform, children: _jsx(StrokeElement, { stroke: stroke }) }, stroke.id))), effectiveCanvas.shapes.map((shape) => {
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, backgroundSkImage, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, }) => {
+    const world = (_jsxs(Group, { transform: worldTransform, children: [effectiveCanvas.viewport.backgroundImage && (_jsx(BackgroundImageElement, { image: effectiveCanvas.viewport.backgroundImage, docWidth: effectiveCanvas.viewport.width, docHeight: effectiveCanvas.viewport.height, fit: effectiveCanvas.viewport.backgroundFit ?? 'contain', resolveUrl: resolveImageUrl, skImage: backgroundSkImage })), effectiveCanvas.strokes.map((stroke) => (_jsx(DraggableElement, { isDragging: stroke.id === draggingId, transform: dragTransform, children: _jsx(StrokeElement, { stroke: stroke }) }, stroke.id))), effectiveCanvas.shapes.map((shape) => {
                 // Line/arrow shapes support endpoint editing. When selected they show
                 // grab handles at both ends; during an endpoint drag the line renders
                 // from the live endpoints (one following the finger) — the shape twin
@@ -214,4 +215,6 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                     return (_jsxs(_Fragment, { children: [_jsx(SelectionBox, { bounds: b, isDragging: isLive, transform: liveTransform }), resizeGeom && handleRadius != null && (_jsx(DraggableElement, { isDragging: isLive, transform: liveTransform, children: _jsx(Handle, { c: resizeGeom.handle, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }) })), cornerResizable && handleRadius != null && (_jsxs(DraggableElement, { isDragging: isDragging, transform: dragTransform, children: [_jsx(Handle, { c: { x: b.minX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.minX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR })] }))] }));
                 }
                 return null;
-            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), customPreview] }) }));
+            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), customPreview] }));
+    return (_jsx(Canvas, { style: { width, height }, children: wrapContent ? wrapContent(world) : world }));
+};

package/dist/annotation/canvas/elements/BackgroundImageElement.d.ts

@@ -1,9 +1,12 @@
+import { type SkImage } from '@shopify/react-native-skia';
 import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
+export declare const useBackgroundSkImage: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>) => SkImage | null;
 export interface BackgroundImageElementProps {
     image: AnnotationBackgroundImage;
     docWidth: number;
     docHeight: number;
     fit?: BackgroundFit;
     resolveUrl?: (path: string) => Promise<string>;
+    skImage?: SkImage | null;
 }
-export declare const BackgroundImageElement: import("react").MemoExoticComponent<({ image, docWidth, docHeight, fit, resolveUrl, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;
+export declare const BackgroundImageElement: import("react").MemoExoticComponent<({ image, docWidth, docHeight, fit, resolveUrl, skImage: skImageProp, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;

package/dist/annotation/canvas/elements/BackgroundImageElement.js

@@ -1,22 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Image, useImage } from '@shopify/react-native-skia';
 import { memo, useEffect, useRef, useState } from 'react';
-const computeFit = (imgW, imgH, docW, docH, fit) => {
-    // Guard against unknown/zero image dimensions: dividing by them yields
-    // Infinity → NaN geometry, and a <Image> with NaN bounds renders nothing
-    // (a silent "background never appears"). Fall back to filling the doc.
-    if (!(imgW > 0) || !(imgH > 0) || fit === 'stretch') {
-        return { x: 0, y: 0, width: docW, height: docH };
-    }
-    const scale = fit === 'cover'
-        ? Math.max(docW / imgW, docH / imgH)
-        : Math.min(docW / imgW, docH / imgH);
-    const w = imgW * scale;
-    const h = imgH * scale;
-    return { x: (docW - w) / 2, y: (docH - h) / 2, width: w, height: h };
-};
-export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, }) => {
-    const [url, setUrl] = useState(image.downloadUrl);
+import { imageDocRect } from '../viewport.js';
+// Resolve a background image's (possibly expired) storage URL and decode it to
+// an SkImage. Exported so a consumer can hoist the decode ABOVE the canvas and
+// share one SkImage across multiple canvases (e.g. the main canvas + a
+// magnifier overlay) — otherwise each canvas mounts its own loader and flashes
+// a blank while it re-resolves + re-decodes. Returns null until loaded, or when
+// `image` is null/undefined. Hooks run unconditionally regardless of `image`.
+export const useBackgroundSkImage = (image, resolveUrl) => {
+    const [url, setUrl] = useState(image?.downloadUrl ?? '');
     // Hold resolveUrl in a ref so re-resolution is keyed only on the image
     // identity, not the function's. Consumers commonly pass an inline closure
     // (a new reference each render); depending on it directly would re-run a
@@ -24,6 +17,8 @@ export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit =
     const resolveUrlRef = useRef(resolveUrl);
     resolveUrlRef.current = resolveUrl;
     useEffect(() => {
+        if (!image)
+            return;
         let cancelled = false;
         const resolve = resolveUrlRef.current;
         if (resolve) {
@@ -38,10 +33,17 @@ export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit =
         return () => {
             cancelled = true;
         };
-    }, [image.downloadUrl, image.storagePath]);
-    const skImage = useImage(url);
+    }, [image?.downloadUrl, image?.storagePath]);
+    return useImage(url || null);
+};
+export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, skImage: skImageProp, }) => {
+    // Self-load only when no pre-decoded image is provided; the hook still runs
+    // unconditionally (with a null image, so it no-ops) to satisfy hook rules.
+    const provided = skImageProp !== undefined;
+    const loaded = useBackgroundSkImage(provided ? null : image, resolveUrl);
+    const skImage = provided ? skImageProp : loaded;
     if (!skImage)
         return null;
-    const dims = computeFit(image.widthPx, image.heightPx, docWidth, docHeight, fit);
+    const dims = imageDocRect(image.widthPx, image.heightPx, docWidth, docHeight, fit);
     return (_jsx(Image, { image: skImage, x: dims.x, y: dims.y, width: dims.width, height: dims.height, fit: "fill" }));
 });