@reekon-tools/boldr-utils 1.8.1 → 1.8.2

package/dist/annotation/canvas/AnnotationCanvasInner.js

@@ -293,6 +293,7 @@ export const AnnotationCanvasInner = (props) => {
                 height,
                 effectiveCanvas: state.effectiveCanvas,
                 worldTransform: state.worldTransform,
+                viewport: state.viewport,
                 resolveImageUrl,
                 canvasRef,
                 valueFont,

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

@@ -1,6 +1,7 @@
 import { type CanvasRef, type SkFont, type SkImage, type SkPath, type SkTypefaceFontProvider, type Transforms3d } from '@shopify/react-native-skia';
 import type { ReactNode, RefObject } from 'react';
 import type { AnnotationCanvasState, AnnotationStroke, StrokeCap } from '../../types/annotation.js';
+import type { ViewportState } from './viewport.js';
 type AnimatedPoint = {
     x: number;
     y: number;
@@ -20,6 +21,7 @@ export interface AnnotationCanvasSkiaProps {
     worldTransform: Transforms3d | {
         value: Transforms3d;
     };
+    viewport?: ViewportState;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     backgroundSkImage?: SkImage | null;
     valueFont: SkFont | null;
@@ -90,5 +92,5 @@ export interface AnnotationCanvasSkiaProps {
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-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, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+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 {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -78,8 +78,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, 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 })), 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, 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) => {
                 // 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

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

@@ -1,5 +1,6 @@
 import { type SkImage } from '@shopify/react-native-skia';
 import type { AnnotationBackgroundImage, BackgroundFit } 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;
@@ -8,5 +9,8 @@ export interface BackgroundImageElementProps {
     fit?: BackgroundFit;
     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, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;
+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>;

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

@@ -1,121 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Group, Image, ImageSVG, Skia, useImage, } from '@shopify/react-native-skia';
-import { memo, useEffect, useRef, useState } from 'react';
+import { Image, useImage } from '@shopify/react-native-skia';
+import { memo } from 'react';
 import { imageDocRect } from '../viewport.js';
-// Resolve a background image's (possibly expired) storage URL. Shared by the
-// raster and SVG loaders below.
-const useBackgroundUrl = (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
-    // network URL resolve on every render.
-    const resolveUrlRef = useRef(resolveUrl);
-    resolveUrlRef.current = resolveUrl;
-    useEffect(() => {
-        if (!image)
-            return;
-        let cancelled = false;
-        const resolve = resolveUrlRef.current;
-        if (resolve) {
-            // A rejecting resolver (e.g. offline URL resolution) must never become
-            // an unhandled rejection here — keep the current url; the consumer's
-            // own retries/invalidations drive the re-resolve.
-            resolve(image.storagePath)
-                .then((next) => {
-                if (!cancelled)
-                    setUrl(next);
-            })
-                .catch(() => { });
-        }
-        else {
-            setUrl(image.downloadUrl);
-        }
-        return () => {
-            cancelled = true;
-        };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [image?.downloadUrl, image?.storagePath]);
-    return url;
-};
-// Null-safe SVG loader. NOT RN Skia's useSVG: that hook throws synchronously
-// on a null/undefined source (despite its DataSourceParam type), so it can't
-// be called unconditionally from a component that usually renders raster
-// backgrounds. An empty url resolves to null (nothing to draw yet).
-// Loaded through Skia's own scheme-agnostic data loader rather than fetch():
-// RN's Android networking rejects non-http(s) schemes, and offline-first
-// consumers resolve the background to a local file:// URI (fromURI handles
-// file://, http(s) and data: on native and web alike). fetch() remains as a
-// fallback for any environment where fromURI can't service the URL.
-const useBackgroundSvg = (url) => {
-    const [svg, setSvg] = useState(null);
-    useEffect(() => {
-        if (!url) {
-            setSvg(null);
-            return;
-        }
-        let cancelled = false;
-        (async () => {
-            try {
-                let next = null;
-                try {
-                    const data = await Skia.Data.fromURI(url);
-                    next = Skia.SVG.MakeFromData(data);
-                    data.dispose();
-                }
-                catch {
-                    const res = await fetch(url);
-                    next = Skia.SVG.MakeFromString(await res.text());
-                }
-                if (!cancelled)
-                    setSvg(next);
-            }
-            catch (e) {
-                console.warn('[BackgroundImageElement] failed to load SVG background', e);
-            }
-        })();
-        return () => {
-            cancelled = true;
-        };
-    }, [url]);
-    return svg;
-};
+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
 // 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`. Raster only — SVG
-// backgrounds self-load in the element below (parsing an SVG is cheap).
+// backgrounds self-load in BackgroundSvgElement (parsing an SVG is cheap).
 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, }) => {
+export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, skImage: skImageProp, viewport, screenWidth, screenHeight, }) => {
     const isSvg = image.format === 'svg';
-    // Self-load only when no pre-decoded image is provided; the hooks still run
-    // unconditionally (with a null source, so they no-op) to satisfy hook rules.
+    // 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 svgUrl = useBackgroundUrl(isSvg ? image : null, resolveUrl);
-    const svg = useBackgroundSvg(isSvg ? svgUrl : '');
     const skImage = provided ? skImageProp : loaded;
-    const dims = imageDocRect(image.widthPx, image.heightPx, docWidth, docHeight, fit);
     if (isSvg) {
-        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 re-rasterizes per frame, 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 }) }));
+        // 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 }));
     }
     if (!skImage)
         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" }));
 });

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

@@ -0,0 +1,13 @@
+import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
+import { type ViewportState } from '../viewport.js';
+export interface BackgroundSvgProps {
+    image: AnnotationBackgroundImage;
+    docWidth: number;
+    docHeight: number;
+    fit?: BackgroundFit;
+    resolveUrl?: (path: string) => Promise<string>;
+    viewport?: ViewportState;
+    screenWidth?: number;
+    screenHeight?: number;
+}
+export declare const BackgroundSvgElement: import("react").MemoExoticComponent<(props: BackgroundSvgProps) => import("react/jsx-runtime").JSX.Element>;

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

@@ -0,0 +1,337 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Group, 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 { ensureRootFontSize, planSvgRaster, shouldRegenerateRaster, svgIntrinsicSize, wrapSvgForRaster, } from '../svgRasterPlan.js';
+import { useBackgroundUrl } from './backgroundUrl.js';
+// SVG background renderer. ONE shared module for both platforms — this file
+// is reached through shared modules (AnnotationCanvasSkia →
+// BackgroundImageElement), and imports from shared modules can't fork by
+// filename: this package's platform split works only via explicit
+// `.native.js` imports from files that are themselves native-only (see
+// index.native.ts) — Metro does NOT platform-expand the compiled `./X.js`
+// specifiers. So the fork happens at runtime instead, on the question that
+// actually matters: can the browser rasterize the SVG for us?
+//
+// - Browser path (web): RN Skia's web build has no SVG module — its
+//   <ImageSVG> snapshots a hidden <img> at the SVG's intrinsic pixel size
+//   every frame, so canvas zoom magnifies pixels. Instead let the browser — a
+//   fully compliant SVG renderer, text, CSS, filters and all — rasterize the
+//   SVG at the resolution the current viewport needs (see svgRasterPlan.ts),
+//   import that bitmap once as an SkImage, and draw it like any raster
+//   background. Zoom/pan changes re-rasterize (debounced) only when they
+//   outgrow the applied bitmap.
+//
+// - Skia path (native): Skia's SVG module draws true vectors through the
+//   canvas transform — crisp at any zoom. It only renders <text> when the DOM
+//   is built with a font manager (without one they are silently dropped — the
+//   C++ factory skips setFontManager entirely), so pass the system one.
+const HAS_DOM = typeof document !== 'undefined' &&
+    typeof DOMParser !== 'undefined' &&
+    typeof XMLSerializer !== 'undefined';
+// --- Skia path (native) ------------------------------------------------------
+// Resolve the platform's system font manager once; an SVG referencing a
+// family the device lacks still falls back to the default typeface instead of
+// disappearing.
+let systemFontMgr;
+const getSystemFontMgr = () => {
+    if (systemFontMgr === undefined) {
+        try {
+            systemFontMgr = Skia.FontMgr.System();
+        }
+        catch (e) {
+            console.warn('[BackgroundSvg] system font manager unavailable', e);
+            systemFontMgr = null;
+        }
+    }
+    return systemFontMgr;
+};
+// Null-safe SVG loader. NOT RN Skia's useSVG: that hook throws synchronously
+// on a null/undefined source (despite its DataSourceParam type), so it can't
+// be called unconditionally while the url resolves. An empty url resolves to
+// null (nothing to draw yet).
+// Loaded as TEXT first so the source can be normalized (ensureRootFontSize —
+// Skia's default font-size for unsized text is larger than the browsers'
+// 16px). SkData exposes no byte access, so when fetch() can't service the
+// scheme (RN's Android networking rejects file://, which offline-first
+// consumers resolve cached backgrounds to), fall back to Skia's own loader
+// with the raw bytes — such documents skip the font-size normalization but
+// still render, explicit sizes intact.
+const useBackgroundSkSvg = (url) => {
+    const [svg, setSvg] = useState(null);
+    useEffect(() => {
+        if (!url) {
+            setSvg(null);
+            return;
+        }
+        let cancelled = false;
+        (async () => {
+            try {
+                const fontMgr = getSystemFontMgr();
+                let next = null;
+                try {
+                    const res = await fetch(url);
+                    next = Skia.SVG.MakeFromString(ensureRootFontSize(await res.text()), fontMgr);
+                }
+                catch {
+                    const data = await Skia.Data.fromURI(url);
+                    next = Skia.SVG.MakeFromData(data, fontMgr);
+                    data.dispose();
+                }
+                if (!cancelled)
+                    setSvg(next);
+            }
+            catch (e) {
+                console.warn('[BackgroundSvg] failed to load SVG background', e);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [url]);
+    return svg;
+};
+const SkSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', 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 }) }));
+};
+// --- Browser path (web) ------------------------------------------------------
+const REGEN_DEBOUNCE_MS = 150;
+// Parse the SVG and normalize its root so it can be crop-wrapped: enforce a
+// viewBox (a root without one CLIPS when its size changes instead of
+// scaling) and pin width/height to the user-unit size so the nested
+// viewport maps 1:1 inside the wrapper.
+const prepareSvg = (text, localWidthPx, localHeightPx) => {
+    if (!(localWidthPx > 0) || !(localHeightPx > 0))
+        return null;
+    const doc = new DOMParser().parseFromString(text, 'image/svg+xml');
+    if (doc.getElementsByTagName('parsererror').length > 0)
+        return null;
+    const root = doc.documentElement;
+    const size = svgIntrinsicSize(root.getAttribute('viewBox'), root.getAttribute('width'), root.getAttribute('height'), localWidthPx, localHeightPx);
+    root.setAttribute('viewBox', size.viewBox);
+    root.setAttribute('width', String(size.width));
+    root.setAttribute('height', String(size.height));
+    return {
+        innerXml: new XMLSerializer().serializeToString(root),
+        ux: size.width / localWidthPx,
+        uy: size.height / localHeightPx,
+        minX: size.minX,
+        minY: size.minY,
+        failed: false,
+    };
+};
+// Decode an SVG string to a drawable <img>. The element retains its SVG
+// document once loaded, so the blob URL is revoked immediately.
+const loadSvgImage = (xml) => new Promise((resolve, reject) => {
+    const objectUrl = URL.createObjectURL(new Blob([xml], { type: 'image/svg+xml' }));
+    const img = document.createElement('img');
+    img.onload = () => {
+        URL.revokeObjectURL(objectUrl);
+        resolve(img);
+    };
+    img.onerror = () => {
+        URL.revokeObjectURL(objectUrl);
+        reject(new Error('SVG image failed to decode'));
+    };
+    img.src = objectUrl;
+});
+const BrowserSvgBackground = ({ image, docWidth, docHeight, fit = 'contain', resolveUrl, viewport, screenWidth, screenHeight, }) => {
+    const url = useBackgroundUrl(image, resolveUrl);
+    const [svgText, setSvgText] = useState(null);
+    useEffect(() => {
+        if (!url) {
+            setSvgText(null);
+            return;
+        }
+        let cancelled = false;
+        (async () => {
+            try {
+                const res = await fetch(url);
+                const text = await res.text();
+                if (!cancelled)
+                    setSvgText(text);
+            }
+            catch (e) {
+                console.warn('[BackgroundSvg] failed to load SVG background', e);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [url]);
+    const [applied, setApplied] = useState(null);
+    const appliedRef = useRef(null);
+    const preparedRef = useRef(null);
+    const inputsRef = useRef(null);
+    const busyRef = useRef(false);
+    const pendingRef = useRef(false);
+    // Bumped whenever in-flight raster results must be discarded (source
+    // 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 = {
+        widthPx: image.widthPx,
+        heightPx: image.heightPx,
+        dims,
+        viewport: viewport ?? DEFAULT_VIEWPORT,
+        screenWidth: screenWidth ?? docWidth,
+        screenHeight: screenHeight ?? docHeight,
+        dpr: typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1,
+    };
+    const run = useCallback(async () => {
+        const prepared = preparedRef.current;
+        const inputs = inputsRef.current;
+        if (!prepared || prepared.failed || !inputs)
+            return;
+        const plan = planSvgRaster(inputs);
+        if (!plan || !shouldRegenerateRaster(appliedRef.current, plan))
+            return;
+        if (busyRef.current) {
+            // A raster is in flight; re-evaluate once it lands.
+            pendingRef.current = true;
+            return;
+        }
+        busyRef.current = true;
+        const gen = genRef.current;
+        try {
+            // Wrap the document so the crop window IS the wrapper's viewBox and the
+            // output size IS its intrinsic size, then draw 1:1 — see
+            // wrapSvgForRaster for why scaling inside drawImage is not an option.
+            const wrapped = wrapSvgForRaster(prepared.innerXml, {
+                x: prepared.minX + plan.rect.x * prepared.ux,
+                y: prepared.minY + plan.rect.y * prepared.uy,
+                width: plan.rect.width * prepared.ux,
+                height: plan.rect.height * prepared.uy,
+            }, plan.outWidth, plan.outHeight);
+            const img = await loadSvgImage(wrapped);
+            const canvas = document.createElement('canvas');
+            canvas.width = plan.outWidth;
+            canvas.height = plan.outHeight;
+            const ctx = canvas.getContext('2d');
+            if (!ctx)
+                throw new Error('2d canvas context unavailable');
+            ctx.drawImage(img, 0, 0);
+            const skImage = Skia.Image.MakeImageFromNativeBuffer(canvas);
+            // A failed import wraps a null CanvasKit image; poking it throws into
+            // the catch below rather than crashing at draw time.
+            skImage.width();
+            if (gen === genRef.current) {
+                const next = {
+                    image: skImage,
+                    rect: plan.rect,
+                    full: plan.full,
+                    zx: plan.zx,
+                    zy: plan.zy,
+                };
+                appliedRef.current = next;
+                setApplied(next);
+            }
+            else {
+                skImage.dispose();
+            }
+        }
+        catch (e) {
+            prepared.failed = true;
+            console.warn('[BackgroundSvg] failed to rasterize SVG background', e);
+        }
+        finally {
+            busyRef.current = false;
+            if (pendingRef.current) {
+                pendingRef.current = false;
+                void run();
+            }
+        }
+    }, []);
+    const schedule = useCallback((delayMs) => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            void run();
+        }, delayMs);
+    }, [run]);
+    // (Re)prepare the <img> when the SVG source changes. URL re-resolution
+    // that yields identical text short-circuits at setSvgText.
+    useEffect(() => {
+        preparedRef.current = null;
+        appliedRef.current = null;
+        setApplied(null);
+        if (!svgText)
+            return;
+        const prepared = prepareSvg(svgText, image.widthPx, image.heightPx);
+        if (!prepared) {
+            console.warn('[BackgroundSvg] unparseable SVG background');
+            return;
+        }
+        preparedRef.current = prepared;
+        schedule(0);
+        return () => {
+            genRef.current++;
+            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).
+    const vp = viewport ?? DEFAULT_VIEWPORT;
+    useEffect(() => {
+        if (!preparedRef.current)
+            return;
+        schedule(appliedRef.current ? REGEN_DEBOUNCE_MS : 0);
+    }, [
+        vp.zoom,
+        vp.pan.x,
+        vp.pan.y,
+        screenWidth,
+        screenHeight,
+        docWidth,
+        docHeight,
+        fit,
+        image.widthPx,
+        image.heightPx,
+        schedule,
+    ]);
+    // Dispose replaced bitmaps after the commit that stopped drawing them,
+    // and everything on unmount.
+    const prevAppliedRef = useRef(null);
+    useEffect(() => {
+        const prev = prevAppliedRef.current;
+        if (prev && prev !== applied)
+            prev.image.dispose();
+        prevAppliedRef.current = applied;
+    }, [applied]);
+    useEffect(() => () => {
+        genRef.current++;
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        prevAppliedRef.current?.image.dispose();
+        prevAppliedRef.current = null;
+    }, []);
+    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" }) }));
+};
+// HAS_DOM is fixed for the life of the process, so each mount renders one
+// branch consistently (no hook-order hazard).
+export const BackgroundSvgElement = memo((props) => HAS_DOM ? (_jsx(BrowserSvgBackground, { ...props })) : (_jsx(SkSvgBackground, { ...props })));

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

@@ -0,0 +1,2 @@
+import type { AnnotationBackgroundImage } from '../../../types/annotation.js';
+export declare const useBackgroundUrl: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>) => string;

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

@@ -0,0 +1,38 @@
+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).
+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
+    // identity, not the function's. Consumers commonly pass an inline closure
+    // (a new reference each render); depending on it directly would re-run a
+    // network URL resolve on every render.
+    const resolveUrlRef = useRef(resolveUrl);
+    resolveUrlRef.current = resolveUrl;
+    useEffect(() => {
+        if (!image)
+            return;
+        let cancelled = false;
+        const resolve = resolveUrlRef.current;
+        if (resolve) {
+            // A rejecting resolver (e.g. offline URL resolution) must never become
+            // an unhandled rejection here — keep the current url; the consumer's
+            // own retries/invalidations drive the re-resolve.
+            resolve(image.storagePath)
+                .then((next) => {
+                if (!cancelled)
+                    setUrl(next);
+            })
+                .catch(() => { });
+        }
+        else {
+            setUrl(image.downloadUrl);
+        }
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [image?.downloadUrl, image?.storagePath]);
+    return url;
+};

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

@@ -0,0 +1,56 @@
+import type { ViewportState } from './viewport.js';
+export interface RectPx {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SvgRasterPlan {
+    full: boolean;
+    rect: RectPx;
+    visible: RectPx;
+    outWidth: number;
+    outHeight: number;
+    zx: number;
+    zy: number;
+}
+export interface AppliedRasterKey {
+    full: boolean;
+    rect: RectPx;
+    zx: number;
+    zy: number;
+}
+export interface SvgRasterInput {
+    widthPx: number;
+    heightPx: number;
+    dims: RectPx;
+    viewport: ViewportState;
+    screenWidth: number;
+    screenHeight: number;
+    dpr: number;
+}
+export declare const FULL_RASTER_CAP = 4096;
+export declare const CROP_RASTER_CAP = 8192;
+export declare const MAX_RASTER_PIXELS = 24000000;
+export declare const CROP_MARGIN = 0.35;
+export declare const REGEN_SCALE_UP = 1.3;
+export declare const REGEN_SCALE_DOWN = 0.5;
+export declare const rectContains: (outer: RectPx, inner: RectPx, eps?: number) => boolean;
+export declare const planSvgRaster: (input: SvgRasterInput) => SvgRasterPlan | null;
+export declare const shouldRegenerateRaster: (applied: AppliedRasterKey | null, plan: SvgRasterPlan | null) => boolean;
+export declare const parseSvgLength: (value: string | null) => number | null;
+export declare const parseViewBox: (value: string | null) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export declare const svgIntrinsicSize: (viewBoxAttr: string | null, widthAttr: string | null, heightAttr: string | null, fallbackWidth: number, fallbackHeight: number) => {
+    viewBox: string;
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+};
+export declare const wrapSvgForRaster: (innerXml: string, cropUserUnits: RectPx, outWidth: number, outHeight: number) => string;
+export declare const ensureRootFontSize: (svgText: string, px?: number) => string;