@reekon-tools/boldr-utils 1.10.3 → 1.12.0

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

@@ -7,7 +7,8 @@ import Animated, { runOnJS, runOnUI, useAnimatedStyle, useDerivedValue, useShare
 import { stampTileDims } from './stampLayout.js';
 import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
-import { useBackgroundSkImage } from './elements/BackgroundImageElement.js';
+import { backgroundLayersOf } from './backgroundLayers.js';
+import { BackgroundSkImageLoader } from './elements/BackgroundImageElement.js';
 import { buildRemoveMeasurementOps, } from './measurementGeometry.js';
 import { buildShapeFromDrag } from './tools/shapeTool.js';
 import { SELECTION_PAD } from './textGeometry.js';
@@ -73,10 +74,39 @@ export const AnnotationCanvasInner = (props) => {
         tileScalePlatform: 'mobile',
         animateViewport,
     });
-    // 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);
+    // Decode each background layer ONCE here and share the images 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. The stack is variable-length, so the decodes can't be a fixed
+    // hook call — a null-rendering BackgroundSkImageLoader per layer owns each
+    // one and reports it into `loadedBackgroundImages` (see the loaders in the
+    // render tree below).
+    const backgroundLayers = useMemo(() => backgroundLayersOf(state.effectiveCanvas.viewport), [state.effectiveCanvas.viewport]);
+    const [loadedBackgroundImages, setLoadedBackgroundImages] = useState({});
+    const onBackgroundSkImage = useCallback((id, image) => {
+        setLoadedBackgroundImages((prev) => prev[id] === image ? prev : { ...prev, [id]: image });
+    }, []);
+    // Removed layers must not pin their decoded bitmaps in the record forever.
+    useEffect(() => {
+        setLoadedBackgroundImages((prev) => {
+            const stale = Object.keys(prev).filter((id) => !backgroundLayers.some((l) => l.id === id));
+            if (stale.length === 0)
+                return prev;
+            const next = { ...prev };
+            for (const id of stale)
+                delete next[id];
+            return next;
+        });
+    }, [backgroundLayers]);
+    // Every current layer id is present (null until its decode lands), so the
+    // canvas elements never self-load — the loupe reuses the same decode.
+    const backgroundSkImages = useMemo(() => {
+        const out = {};
+        for (const layer of backgroundLayers) {
+            out[layer.id] = loadedBackgroundImages[layer.id] ?? null;
+        }
+        return out;
+    }, [backgroundLayers, loadedBackgroundImages]);
     // 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);
@@ -1200,6 +1230,17 @@ export const AnnotationCanvasInner = (props) => {
                 }
                 const hit = cfg.hitTest(st.ctx.document, world, zoomNow, st.ctx.tileViewportScale, st.ctx.tileScaleFactor);
                 if (!hit) {
+                    // Backgrounds can cover the whole document, so they only get the
+                    // drag once every annotation element misses, and only when ALREADY
+                    // selected (tap-to-select flows through the tool's pointer
+                    // handlers). The hit rides the exact same dragX/dragY transform and
+                    // buildTranslatePatch commit as any other element.
+                    const bg = cfg.hitTestSelectedBackground?.(st.ctx.document, world, st.ctx.selection?.ids ?? []);
+                    if (bg) {
+                        dragTargetRef.current = bg;
+                        setDraggingId(bg.id);
+                        return;
+                    }
                     st.ctx.setSelection(null);
                     dragTargetRef.current = null;
                     return;
@@ -1435,7 +1476,7 @@ export const AnnotationCanvasInner = (props) => {
         effectiveCanvas: state.effectiveCanvas,
         worldTransform,
         resolveImageUrl,
-        backgroundSkImage,
+        backgroundSkImages,
         valueFont,
         // Freehand drawing runs on the UI thread via `livePreview`, so the
         // JS-state pen preview is unused on native.
@@ -1512,7 +1553,7 @@ export const AnnotationCanvasInner = (props) => {
     // drawing to the canvas box by construction, but the stamp overlay is
     // plain RN views — without clipping, tiles panned past the edge of a
     // non-fullscreen canvas (e.g. a diagram strip) escape into surrounding UI.
-    _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, 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
+    _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [backgroundLayers.map((layer) => (_jsx(BackgroundSkImageLoader, { layer: layer, resolveUrl: resolveImageUrl, onImage: onBackgroundSkImage }, layer.id))), _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.tileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
                         ? () => {

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

@@ -23,7 +23,7 @@ export interface AnnotationCanvasSkiaProps {
     };
     viewport?: ViewportState;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
-    backgroundSkImage?: SkImage | null;
+    backgroundSkImages?: Record<string, SkImage | null>;
     valueFont: SkFont | null;
     textFontMgr?: SkTypefaceFontProvider | null;
     penDrawingStroke: AnnotationStroke | null;
@@ -92,5 +92,5 @@ export interface AnnotationCanvasSkiaProps {
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, 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, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -4,7 +4,8 @@ import { normalizeRect, placementOf } from './measurementGeometry.js';
 import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeometry.js';
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
-import { BackgroundImageElement } from './elements/BackgroundImageElement.js';
+import { backgroundLayerDocRect, backgroundLayersOf, } from './backgroundLayers.js';
+import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
 import { StrokeElement } from './elements/StrokeElement.js';
 // Default visual constants for the measurement-annotation line (the tile itself
@@ -78,8 +79,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, viewport, 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, canvasRef, }) => {
-    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, viewport: viewport, screenWidth: width, screenHeight: height })), 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, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, canvasRef, }) => {
+    const world = (_jsxs(Group, { transform: worldTransform, children: [backgroundLayersOf(effectiveCanvas.viewport).map((layer) => (_jsx(DraggableElement, { isDragging: layer.id === draggingId || layer.id === resizingId, transform: layer.id === resizingId ? resizeTransform : dragTransform, children: _jsx(BackgroundLayerElement, { layer: layer, resolveUrl: resolveImageUrl, skImage: backgroundSkImages?.[layer.id], viewport: viewport, screenWidth: width, screenHeight: height }) }, layer.id))), 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
@@ -218,6 +219,18 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                         shape.kind === 'polygon';
                     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 })] }))] }));
                 }
+                // A selected background layer: outline its doc rect and offer ONE
+                // bottom-right handle — backgrounds scale uniformly about their
+                // top-left corner (the transform origin), so a single opposite-corner
+                // grab is the whole gizmo. Chrome tracks the live drag/resize
+                // transform the same way the layer itself does above.
+                const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
+                if (layer) {
+                    const r = backgroundLayerDocRect(layer);
+                    const isResizing = layer.id === resizingId;
+                    const liveTransform = isResizing ? resizeTransform : dragTransform;
+                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }), handleRadius != null && (_jsx(Handle, { c: { x: r.x + r.width, y: r.y + r.height }, 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] }));
     return (_jsx(Canvas, { ref: canvasRef, style: { width, height }, children: wrapContent ? wrapContent(world) : world }));

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

@@ -52,7 +52,7 @@ export interface ShapeDrawConfig {
     startCap?: StrokeCap;
     dash?: boolean;
 }
-export type DragElementKind = 'stroke' | 'shape' | 'measurement';
+export type DragElementKind = 'stroke' | 'shape' | 'measurement' | 'background';
 export interface DragSelectionConfig {
     hitTest(doc: AnnotationCanvasState, world: Vec2, zoom: number, viewportTileScale?: number, tileScaleFactor?: number): {
         id: AnnotationElementId;
@@ -78,6 +78,13 @@ export interface DragSelectionConfig {
     } | null;
     buildShapeCornerPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, corner: RectCorner, delta: Vec2): AnnotationDocumentPatch | null;
     isSelectedTileGrab?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number, viewportTileScale?: number, tileScaleFactor?: number): boolean;
+    hitTestBackground?(doc: AnnotationCanvasState, world: Vec2): {
+        id: AnnotationElementId;
+    } | null;
+    hitTestSelectedBackground?(doc: AnnotationCanvasState, world: Vec2, selectedIds: AnnotationElementId[]): {
+        id: AnnotationElementId;
+        kind: 'background';
+    } | null;
     hitTestResizeHandle?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): ResizeGeometry | null;
     buildResizePatch?(doc: AnnotationCanvasState, id: AnnotationElementId, delta: Vec2): AnnotationDocumentPatch | null;
 }

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

@@ -0,0 +1,20 @@
+import type { AnnotationBackgroundLayer, AnnotationViewport, BackgroundLayerTransform } from '../../types/annotation.js';
+export declare const LEGACY_BACKGROUND_LAYER_ID = "background-legacy";
+export declare const BACKGROUND_PLACEMENT_GAP_RATIO = 0.02;
+export declare const backgroundLayersOf: (viewport: AnnotationViewport) => AnnotationBackgroundLayer[];
+export declare const backgroundLayerDocRect: (layer: AnnotationBackgroundLayer) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare const backgroundLayersUnionRect: (layers: AnnotationBackgroundLayer[]) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export declare const placeNewBackgroundLayer: (existing: AnnotationBackgroundLayer[], dims: {
+    width: number;
+    height: number;
+}, viewport: AnnotationViewport) => BackgroundLayerTransform;

package/dist/annotation/canvas/backgroundLayers.js

@@ -0,0 +1,98 @@
+import { imageDocRect } from './viewport.js';
+// Id of the layer synthesized from the legacy single
+// `viewport.backgroundImage` slot. Deterministic (never random): two clients
+// that materialize the array independently must converge on the SAME layer,
+// since id equality is what lets their update/remove ops target it.
+export const LEGACY_BACKGROUND_LAYER_ID = 'background-legacy';
+// Horizontal gap between the existing background union and a newly placed
+// image, as a fraction of the union's width (see placeNewBackgroundLayer).
+export const BACKGROUND_PLACEMENT_GAP_RATIO = 0.02;
+// Normalized view of a viewport's background stack. When only the legacy
+// single field exists, it is presented as one layer whose transform
+// reproduces the legacy fit placement exactly (via imageDocRect) under the
+// deterministic legacy id. The axes scale independently so a legacy
+// 'stretch' fit converts losslessly.
+export const backgroundLayersOf = (viewport) => {
+    if (viewport.backgroundImages)
+        return viewport.backgroundImages;
+    const legacy = viewport.backgroundImage;
+    if (!legacy)
+        return [];
+    const dims = imageDocRect(legacy.widthPx, legacy.heightPx, viewport.width, viewport.height, viewport.backgroundFit ?? 'contain');
+    // Zero/unknown intrinsic dimensions: imageDocRect's guard makes such an
+    // image fill the whole doc rect, and the synthesized layer must occupy the
+    // same rect — both for rendering and for the fit/tile math that reads
+    // backgroundLayerDocRect. Adopting the doc rect as the intrinsic size (at
+    // scale 1) reproduces that placement with a finite, JSON-safe transform;
+    // a 0-intrinsic layer at any scale would collapse to a 0x0 rect instead.
+    const degenerate = !(legacy.widthPx > 0) || !(legacy.heightPx > 0);
+    return [
+        {
+            id: LEGACY_BACKGROUND_LAYER_ID,
+            storagePath: legacy.storagePath,
+            downloadUrl: legacy.downloadUrl,
+            widthPx: degenerate ? dims.width : legacy.widthPx,
+            heightPx: degenerate ? dims.height : legacy.heightPx,
+            // Only include `format` when defined — the layer must survive a
+            // JSON round-trip without growing/losing keys (Firestore writes strip
+            // undefined values), so absence stays absence.
+            ...(legacy.format ? { format: legacy.format } : {}),
+            transform: {
+                x: dims.x,
+                y: dims.y,
+                scaleX: degenerate ? 1 : dims.width / legacy.widthPx,
+                scaleY: degenerate ? 1 : dims.height / legacy.heightPx,
+            },
+        },
+    ];
+};
+// The doc-space rectangle a layer occupies: the intrinsic pixel grid under
+// the layer's translate+scale.
+export const backgroundLayerDocRect = (layer) => ({
+    x: layer.transform.x,
+    y: layer.transform.y,
+    width: layer.widthPx * layer.transform.scaleX,
+    height: layer.heightPx * layer.transform.scaleY,
+});
+// Bounding box of every layer's doc rect. Null when there are no layers —
+// callers fall back to the document rect.
+export const backgroundLayersUnionRect = (layers) => {
+    if (layers.length === 0)
+        return null;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const layer of layers) {
+        const rect = backgroundLayerDocRect(layer);
+        minX = Math.min(minX, rect.x);
+        minY = Math.min(minY, rect.y);
+        maxX = Math.max(maxX, rect.x + rect.width);
+        maxY = Math.max(maxY, rect.y + rect.height);
+    }
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+};
+// Placement for a newly added image. The first image contain-fits into the
+// doc rect — the same place the legacy single image lands, so a one-image doc
+// is indistinguishable from a legacy one. Later images sit beside the
+// existing content: scaled uniformly so their doc height matches the union
+// rect's height, offset right of the union by a width-relative gap.
+export const placeNewBackgroundLayer = (existing, dims, viewport) => {
+    const union = backgroundLayersUnionRect(existing);
+    if (!union) {
+        const rect = imageDocRect(dims.width, dims.height, viewport.width, viewport.height, 'contain');
+        return {
+            x: rect.x,
+            y: rect.y,
+            scaleX: dims.width > 0 ? rect.width / dims.width : 1,
+            scaleY: dims.height > 0 ? rect.height / dims.height : 1,
+        };
+    }
+    const scale = dims.height > 0 ? union.height / dims.height : 1;
+    return {
+        x: union.x + union.width + BACKGROUND_PLACEMENT_GAP_RATIO * union.width,
+        y: union.y,
+        scaleX: scale,
+        scaleY: scale,
+    };
+};

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

@@ -1,16 +1,19 @@
 import { type SkImage } from '@shopify/react-native-skia';
-import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
+import type { AnnotationBackgroundImage, AnnotationBackgroundLayer } from '../../../types/annotation.js';
 import type { ViewportState } from '../viewport.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;
+export interface BackgroundSkImageLoaderProps {
+    layer: AnnotationBackgroundLayer;
+    resolveUrl?: (path: string) => Promise<string>;
+    onImage: (id: string, image: SkImage | null) => void;
+}
+export declare const BackgroundSkImageLoader: ({ layer, resolveUrl, onImage, }: BackgroundSkImageLoaderProps) => null;
+export interface BackgroundLayerElementProps {
+    layer: AnnotationBackgroundLayer;
     resolveUrl?: (path: string) => Promise<string>;
     skImage?: SkImage | null;
     viewport?: ViewportState;
     screenWidth?: number;
     screenHeight?: number;
 }
-export declare const BackgroundImageElement: import("react").MemoExoticComponent<({ image, docWidth, docHeight, fit, resolveUrl, skImage: skImageProp, viewport, screenWidth, screenHeight, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;
+export declare const BackgroundLayerElement: import("react").MemoExoticComponent<({ layer, resolveUrl, skImage: skImageProp, viewport, screenWidth, screenHeight, }: BackgroundLayerElementProps) => import("react/jsx-runtime").JSX.Element | null>;

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

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Image, useImage } from '@shopify/react-native-skia';
-import { memo } from 'react';
-import { imageDocRect } from '../viewport.js';
+import { Group, Image, useImage, } from '@shopify/react-native-skia';
+import { memo, useEffect, useRef } from 'react';
+import { backgroundLayerDocRect } from '../backgroundLayers.js';
 import { useBackgroundUrl } from './backgroundUrl.js';
 import { BackgroundSvgElement } from './BackgroundSvg.js';
 // Resolve a background image's URL and decode it to an SkImage. Exported so a
@@ -15,21 +15,55 @@ export const useBackgroundSkImage = (image, resolveUrl) => {
     const url = useBackgroundUrl(image, resolveUrl);
     return useImage(url || null);
 };
-export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, skImage: skImageProp, viewport, screenWidth, screenHeight, }) => {
-    const isSvg = image.format === 'svg';
+// Null-rendering decode host: one mounted instance per background layer, so a
+// variable-length layer stack gets per-image hooks without any component
+// mapping over hooks. The consumer (the native Inner) mounts one per layer,
+// accumulates the reported images into a Record keyed by layer id, and feeds
+// that to every canvas sharing the decode (main + magnifier loupe).
+export const BackgroundSkImageLoader = ({ layer, resolveUrl, onImage, }) => {
+    // SVG layers never draw through an SkImage (BackgroundSvgElement owns its
+    // own vector pipeline), so skip the decode and report null.
+    const image = useBackgroundSkImage(layer.format === 'svg' ? null : layer, resolveUrl);
+    // The callback rides a ref so an inline consumer closure doesn't re-report
+    // (and re-render the collector) every render.
+    const onImageRef = useRef(onImage);
+    onImageRef.current = onImage;
+    useEffect(() => {
+        onImageRef.current(layer.id, image);
+    }, [layer.id, image]);
+    return null;
+};
+// One background layer: the image's intrinsic pixel grid drawn under the
+// layer's translate+scale, so its doc rect is backgroundLayerDocRect(layer).
+// A component (not inlined into the scene helper) because each layer owns
+// per-image hooks — URL resolution and raster decode — and AnnotationCanvasSkia
+// is a hook-free plain function.
+export const BackgroundLayerElement = memo(({ layer, resolveUrl, skImage: skImageProp, viewport, screenWidth, screenHeight, }) => {
+    const isSvg = layer.format === 'svg';
     // Self-load only when no pre-decoded image is provided; the hook still runs
     // unconditionally (with a null source, so it no-ops) to satisfy hook rules.
     const provided = skImageProp !== undefined;
-    const loaded = useBackgroundSkImage(provided || isSvg ? null : image, resolveUrl);
+    const loaded = useBackgroundSkImage(provided || isSvg ? null : layer, resolveUrl);
     const skImage = provided ? skImageProp : loaded;
+    const t = layer.transform;
+    let content = null;
     if (isSvg) {
         // Environment-forked renderer (one shared module — see BackgroundSvg):
         // native draws true vectors through Skia's SVG module; web rasterizes
-        // through the browser at viewport resolution.
-        return (_jsx(BackgroundSvgElement, { image: image, docWidth: docWidth, docHeight: docHeight, fit: fit, resolveUrl: resolveUrl, viewport: viewport, screenWidth: screenWidth, screenHeight: screenHeight }));
+        // through the browser at viewport resolution. Both draw at intrinsic
+        // size — the Group below owns the placement — but the web rasterizer
+        // still needs the doc rect to crop against the visible region.
+        content = (_jsx(BackgroundSvgElement, { image: layer, dims: backgroundLayerDocRect(layer), resolveUrl: resolveUrl, viewport: viewport, screenWidth: screenWidth, screenHeight: screenHeight }));
+    }
+    else if (skImage) {
+        content = (_jsx(Image, { image: skImage, x: 0, y: 0, width: layer.widthPx, height: layer.heightPx, fit: "fill" }));
     }
-    if (!skImage)
+    if (!content)
         return null;
-    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" }));
+    return (_jsx(Group, { transform: [
+            { translateX: t.x },
+            { translateY: t.y },
+            { scaleX: t.scaleX },
+            { scaleY: t.scaleY },
+        ], children: content }));
 });

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

@@ -1,10 +1,9 @@
-import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
+import type { AnnotationBackgroundImage } from '../../../types/annotation.js';
 import { type ViewportState } from '../viewport.js';
+import { type RectPx } from '../svgRasterPlan.js';
 export interface BackgroundSvgProps {
     image: AnnotationBackgroundImage;
-    docWidth: number;
-    docHeight: number;
-    fit?: BackgroundFit;
+    dims: RectPx;
     resolveUrl?: (path: string) => Promise<string>;
     viewport?: ViewportState;
     screenWidth?: number;

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

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Group, Image as SkiaImage, ImageSVG, Skia, } from '@shopify/react-native-skia';
+import { Image as SkiaImage, ImageSVG, Skia, } from '@shopify/react-native-skia';
 import { memo, useCallback, useEffect, useRef, useState } from 'react';
-import { DEFAULT_VIEWPORT, imageDocRect, } from '../viewport.js';
+import { DEFAULT_VIEWPORT } from '../viewport.js';
 import { ensureRootFontSize, planSvgRaster, shouldRegenerateRaster, svgIntrinsicSize, wrapSvgForRaster, } from '../svgRasterPlan.js';
 import { useBackgroundUrl } from './backgroundUrl.js';
 // SVG background renderer. ONE shared module for both platforms — this file
@@ -91,22 +91,17 @@ const useBackgroundSkSvg = (url) => {
     }, [url]);
     return svg;
 };
-const SkSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', resolveUrl, }) => {
+const SkSvgBackground = ({ image, resolveUrl }) => {
     const url = useBackgroundUrl(image, resolveUrl);
     const svg = useBackgroundSkSvg(url);
-    const dims = imageDocRect(image.widthPx, image.heightPx, docWidth, docHeight, fit);
     if (!svg)
         return null;
-    // Draw the SVG at its stamped intrinsic size inside a scale transform
-    // (rather than relying on ImageSVG's own fitting, which only applies to
-    // sources with a viewBox). The vector source renders through the canvas
-    // transform, so it stays crisp at any canvas zoom.
-    return (_jsx(Group, { transform: [
-            { translateX: dims.x },
-            { translateY: dims.y },
-            { scaleX: dims.width / image.widthPx },
-            { scaleY: dims.height / image.heightPx },
-        ], children: _jsx(ImageSVG, { svg: svg, x: 0, y: 0, width: image.widthPx, height: image.heightPx }) }));
+    // Draw the SVG at its stamped intrinsic size (rather than relying on
+    // ImageSVG's own fitting, which only applies to sources with a viewBox) —
+    // the caller's Group maps intrinsic px to the layer's doc rect. The vector
+    // source renders through the canvas transform, so it stays crisp at any
+    // canvas zoom.
+    return (_jsx(ImageSVG, { svg: svg, x: 0, y: 0, width: image.widthPx, height: image.heightPx }));
 };
 // --- Browser path (web) ------------------------------------------------------
 const REGEN_DEBOUNCE_MS = 150;
@@ -149,7 +144,7 @@ const loadSvgImage = (xml) => new Promise((resolve, reject) => {
     };
     img.src = objectUrl;
 });
-const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', resolveUrl, viewport, screenWidth, screenHeight, }) => {
+const BrowserSvgBackground = ({ image, dims, resolveUrl, viewport, screenWidth, screenHeight, }) => {
     const url = useBackgroundUrl(image, resolveUrl);
     const [svgText, setSvgText] = useState(null);
     useEffect(() => {
@@ -183,7 +178,6 @@ const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', res
     // changed, unmount).
     const genRef = useRef(0);
     const timerRef = useRef(null);
-    const dims = imageDocRect(image.widthPx, image.heightPx, docWidth, docHeight, fit);
     // Latest plan inputs live in a ref so the async raster loop always plans
     // against current values without effect churn on every pan frame.
     inputsRef.current = {
@@ -191,8 +185,8 @@ const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', res
         heightPx: image.heightPx,
         dims,
         viewport: viewport ?? DEFAULT_VIEWPORT,
-        screenWidth: screenWidth ?? docWidth,
-        screenHeight: screenHeight ?? docHeight,
+        screenWidth: screenWidth ?? dims.width,
+        screenHeight: screenHeight ?? dims.height,
         dpr: typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1,
     };
     const run = useCallback(async () => {
@@ -287,8 +281,9 @@ const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', res
             preparedRef.current = null;
         };
     }, [svgText, image.widthPx, image.heightPx, schedule]);
-    // Follow the viewport: debounce-regenerate when zoom/pan/layout outgrow
-    // the applied bitmap (run() no-ops when they haven't).
+    // Follow the viewport: debounce-regenerate when zoom/pan/layout — or the
+    // layer's own doc rect (a background drag/scale changes how much screen it
+    // covers) — outgrow the applied bitmap (run() no-ops when they haven't).
     const vp = viewport ?? DEFAULT_VIEWPORT;
     useEffect(() => {
         if (!preparedRef.current)
@@ -300,9 +295,10 @@ const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', res
         vp.pan.y,
         screenWidth,
         screenHeight,
-        docWidth,
-        docHeight,
-        fit,
+        dims.x,
+        dims.y,
+        dims.width,
+        dims.height,
         image.widthPx,
         image.heightPx,
         schedule,
@@ -325,12 +321,10 @@ const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', res
     }, []);
     if (!applied || !(image.widthPx > 0) || !(image.heightPx > 0))
         return null;
-    return (_jsx(Group, { transform: [
-            { translateX: dims.x },
-            { translateY: dims.y },
-            { scaleX: dims.width / image.widthPx },
-            { scaleY: dims.height / image.heightPx },
-        ], children: _jsx(SkiaImage, { image: applied.image, x: applied.rect.x, y: applied.rect.y, width: applied.rect.width, height: applied.rect.height, fit: "fill" }) }));
+    // `applied.rect` is in svg-local px — the same space the caller's Group
+    // maps to the layer's doc rect — so the crop lands exactly where the
+    // vector content it rasterized would.
+    return (_jsx(SkiaImage, { image: applied.image, x: applied.rect.x, y: applied.rect.y, width: applied.rect.width, height: applied.rect.height, fit: "fill" }));
 };
 // HAS_DOM is fixed for the life of the process, so each mount renders one
 // branch consistently (no hook-order hazard).

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

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 // Resolve a background image's (possibly expired) storage URL. Shared by the
-// raster loader (BackgroundImageElement) and both SVG render paths
-// (BackgroundSvg).
+// raster loader (BackgroundLayerElement / BackgroundSkImageLoader) and both
+// SVG render paths (BackgroundSvg).
 export const useBackgroundUrl = (image, resolveUrl) => {
     const [url, setUrl] = useState(image?.downloadUrl ?? '');
     // Hold resolveUrl in a ref so re-resolution is keyed only on the image