@reekon-tools/boldr-utils 1.8.0 → 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;

package/dist/annotation/canvas/svgRasterPlan.js

@@ -0,0 +1,225 @@
+// A whole-SVG raster may not exceed this per side. Kept modest because a full
+// raster is retained for the lifetime of the zoom level.
+export const FULL_RASTER_CAP = 4096;
+// A visible-region crop may not exceed this per side. Crops are transient and
+// sized by the screen, and every WebGL implementation this app targets
+// supports ≥8192px textures.
+export const CROP_RASTER_CAP = 8192;
+// Absolute pixel budget for one raster (≈96MB RGBA) — the caps above bound
+// each side, this bounds the area.
+export const MAX_RASTER_PIXELS = 24000000;
+// Fraction of the visible region added on each side of a crop, so small pans
+// stay inside the bitmap instead of re-rasterizing.
+export const CROP_MARGIN = 0.35;
+// Re-rasterize when the needed density outgrows the bitmap by this factor
+// (sharpen promptly on zoom-in)…
+export const REGEN_SCALE_UP = 1.3;
+// …or when the bitmap is this much denser than needed (reclaim memory lazily
+// on zoom-out; minified drawing looks fine meanwhile).
+export const REGEN_SCALE_DOWN = 0.5;
+const EMPTY_RECT = { x: 0, y: 0, width: 0, height: 0 };
+const intersectRect = (a, b) => {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    if (right <= x || bottom <= y)
+        return null;
+    return { x, y, width: right - x, height: bottom - y };
+};
+// Does `outer` contain `inner`, within eps svg-local px? An empty inner
+// (off-screen SVG) is trivially contained.
+export const rectContains = (outer, inner, eps = 0.5) => inner.width <= 0 ||
+    inner.height <= 0 ||
+    (inner.x >= outer.x - eps &&
+        inner.y >= outer.y - eps &&
+        inner.x + inner.width <= outer.x + outer.width + eps &&
+        inner.y + inner.height <= outer.y + outer.height + eps);
+// Clamp per-axis densities so `rect` rasterized at (zx, zy) fits the side cap
+// and the pixel budget, and derive the integer bitmap size.
+const capScales = (rect, zx, zy, cap) => {
+    let cx = Math.min(zx, cap / rect.width);
+    let cy = Math.min(zy, cap / rect.height);
+    const pixels = rect.width * cx * rect.height * cy;
+    if (pixels > MAX_RASTER_PIXELS) {
+        const r = Math.sqrt(MAX_RASTER_PIXELS / pixels);
+        cx *= r;
+        cy *= r;
+    }
+    const outWidth = Math.max(1, Math.ceil(rect.width * cx));
+    const outHeight = Math.max(1, Math.ceil(rect.height * cy));
+    return {
+        outWidth,
+        outHeight,
+        zx: outWidth / rect.width,
+        zy: outHeight / rect.height,
+    };
+};
+// Plan the raster the current viewport needs, or null when the inputs can't
+// produce one (degenerate sizes).
+export const planSvgRaster = (input) => {
+    const { widthPx, heightPx, dims, viewport, screenWidth, screenHeight } = input;
+    if (!(widthPx > 0) || !(heightPx > 0))
+        return null;
+    if (!(dims.width > 0) || !(dims.height > 0))
+        return null;
+    const zoom = viewport.zoom > 0 ? viewport.zoom : 1;
+    const dpr = input.dpr > 0 ? input.dpr : 1;
+    // Doc units per svg-local px (per-axis: 'stretch' fits are anisotropic).
+    const sx = dims.width / widthPx;
+    const sy = dims.height / heightPx;
+    // Device px per svg-local px the screen currently shows.
+    const zx = zoom * sx * dpr;
+    const zy = zoom * sy * dpr;
+    if (!Number.isFinite(zx) || !Number.isFinite(zy) || zx <= 0 || zy <= 0) {
+        return null;
+    }
+    const whole = { x: 0, y: 0, width: widthPx, height: heightPx };
+    const visibleDoc = {
+        x: viewport.pan.x,
+        y: viewport.pan.y,
+        width: Math.max(0, screenWidth) / zoom,
+        height: Math.max(0, screenHeight) / zoom,
+    };
+    const visible = intersectRect({
+        x: (visibleDoc.x - dims.x) / sx,
+        y: (visibleDoc.y - dims.y) / sy,
+        width: visibleDoc.width / sx,
+        height: visibleDoc.height / sy,
+    }, whole);
+    // Whole-SVG raster whenever the needed density fits the budget — pan never
+    // invalidates it. Also the fallback when the SVG is entirely off-screen
+    // (capped density; only used until something is visible again).
+    const fullFits = widthPx * zx <= FULL_RASTER_CAP &&
+        heightPx * zy <= FULL_RASTER_CAP &&
+        widthPx * zx * heightPx * zy <= MAX_RASTER_PIXELS;
+    if (fullFits || !visible) {
+        const capped = capScales(whole, zx, zy, FULL_RASTER_CAP);
+        return {
+            full: true,
+            rect: whole,
+            visible: visible ?? EMPTY_RECT,
+            ...capped,
+        };
+    }
+    const marginX = visible.width * CROP_MARGIN;
+    const marginY = visible.height * CROP_MARGIN;
+    const rect = intersectRect({
+        x: visible.x - marginX,
+        y: visible.y - marginY,
+        width: visible.width + marginX * 2,
+        height: visible.height + marginY * 2,
+    }, whole);
+    const capped = capScales(rect, zx, zy, CROP_RASTER_CAP);
+    return { full: false, rect, visible, ...capped };
+};
+// Should the applied raster be replaced by what `plan` asks for? Scale drift
+// beyond the regen thresholds always regenerates; otherwise a full raster
+// stands, and a crop stands while the visible region stays inside it.
+export const shouldRegenerateRaster = (applied, plan) => {
+    if (!plan)
+        return false;
+    if (!applied)
+        return true;
+    const rx = plan.zx / applied.zx;
+    const ry = plan.zy / applied.zy;
+    if (rx > REGEN_SCALE_UP ||
+        ry > REGEN_SCALE_UP ||
+        rx < REGEN_SCALE_DOWN ||
+        ry < REGEN_SCALE_DOWN) {
+        return true;
+    }
+    if (applied.full)
+        return false;
+    return !rectContains(applied.rect, plan.visible);
+};
+// --- SVG root-size normalization (DOM-free half) -----------------------------
+//
+// The browser rasterizes an <img> SVG from its root width/height; a root
+// without a viewBox doesn't scale at all (it clips). Given the root's
+// attributes, decide the viewBox to enforce and the user-unit size to pin the
+// root to — the coordinate space raster crops are expressed in.
+// Parse an absolute SVG length attribute. Percentages and other relative
+// units have no meaning outside a CSS layout context — treated as absent.
+export const parseSvgLength = (value) => {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!/^\d*\.?\d+(px)?$/.test(trimmed))
+        return null;
+    const parsed = parseFloat(trimmed);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+};
+export const parseViewBox = (value) => {
+    if (!value)
+        return null;
+    const parts = value
+        .trim()
+        .split(/[\s,]+/)
+        .map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+        return null;
+    }
+    const [x, y, width, height] = parts;
+    if (!(width > 0) || !(height > 0))
+        return null;
+    return { x, y, width, height };
+};
+export const svgIntrinsicSize = (viewBoxAttr, widthAttr, heightAttr, fallbackWidth, fallbackHeight) => {
+    const vb = parseViewBox(viewBoxAttr);
+    if (vb) {
+        return {
+            viewBox: viewBoxAttr.trim(),
+            minX: vb.x,
+            minY: vb.y,
+            width: vb.width,
+            height: vb.height,
+        };
+    }
+    const w = parseSvgLength(widthAttr);
+    const h = parseSvgLength(heightAttr);
+    if (w && h) {
+        return { viewBox: `0 0 ${w} ${h}`, minX: 0, minY: 0, width: w, height: h };
+    }
+    return {
+        viewBox: `0 0 ${fallbackWidth} ${fallbackHeight}`,
+        minX: 0,
+        minY: 0,
+        width: fallbackWidth,
+        height: fallbackHeight,
+    };
+};
+// Wrap a normalized SVG document in an outer <svg> whose viewBox is the crop
+// window (user units) and whose width/height are the output size in device
+// px. The wrapper's intrinsic size then EQUALS the raster destination, so
+// drawImage(img, 0, 0) never scales — critical on Chromium, which rasterizes
+// SVG drawImage sources at their intrinsic size and would otherwise magnify
+// that bitmap (the "still blurry under zoom" failure). Nesting — rather than
+// editing the inner root's viewBox — keeps percentage lengths and viewport-
+// relative units inside the document resolving against the ORIGINAL viewport.
+// preserveAspectRatio="none" absorbs the sub-pixel aspect drift from integer
+// output sizes (and any anisotropic density caps).
+export const wrapSvgForRaster = (innerXml, cropUserUnits, outWidth, outHeight) => `<svg xmlns="http://www.w3.org/2000/svg" width="${outWidth}" ` +
+    `height="${outHeight}" viewBox="${cropUserUnits.x} ${cropUserUnits.y} ` +
+    `${cropUserUnits.width} ${cropUserUnits.height}" ` +
+    `preserveAspectRatio="none">${innerXml}</svg>`;
+// Skia's SVG module and browsers disagree on the default font-size when a
+// document never specifies one: browsers use the CSS initial value 'medium'
+// (16px), Skia's is larger — unsized <text> renders visibly bigger on native
+// than the same SVG in a browser. Injecting an explicit, inheritable 16 on
+// the root pins the two to the same spec-aligned default; any font-size the
+// document does set (on the root or below) still wins through inheritance.
+// String surgery, not DOM — the native path has no DOMParser.
+export const ensureRootFontSize = (svgText, px = 16) => {
+    const match = /<svg\b[^>]*>/i.exec(svgText);
+    if (!match)
+        return svgText;
+    const tag = match[0];
+    if (/\bfont-size\s*=/i.test(tag))
+        return svgText;
+    if (/\bstyle\s*=\s*["'][^"']*font-size/i.test(tag))
+        return svgText;
+    const selfClosing = tag.endsWith('/>');
+    const insertAt = match.index + tag.length - (selfClosing ? 2 : 1);
+    return (svgText.slice(0, insertAt) + ` font-size="${px}"` + svgText.slice(insertAt));
+};

package/dist/export/buildJobCsv.js

@@ -97,8 +97,9 @@ export function buildJobCsv(input) {
             const columnHeaders = [];
             section.tableConfig.forEach((column) => {
                 columnHeaders.push(column.name);
-                if (column.type === ColumnType.Measurement ||
-                    column.type === ColumnType.Angle) {
+                if (includeField('notes') &&
+                    (column.type === ColumnType.Measurement ||
+                        column.type === ColumnType.Angle)) {
                     columnHeaders.push(`${column.name} Notes`);
                 }
             });
@@ -164,8 +165,9 @@ export function buildJobCsv(input) {
                     else {
                         row.push('');
                     }
-                    if (column.type === ColumnType.Measurement ||
-                        column.type === ColumnType.Angle) {
+                    if (includeField('notes') &&
+                        (column.type === ColumnType.Measurement ||
+                            column.type === ColumnType.Angle)) {
                         if (group.descriptions && group.descriptions[column.id]) {
                             row.push(escapeCSVField(group.descriptions[column.id]));
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",

package/dist/annotation/canvas/tools/measurementLineTool.d.ts

@@ -1,12 +0,0 @@
-import type { PlacedMeasurementRef } from '../../../types/annotation.js';
-import type { Tool } from '../Tool.js';
-export interface MeasurementLineToolOptions {
-    id?: string;
-    label?: string;
-    minDragPx?: number;
-    autoSwitchToSelect?: boolean;
-    selectToolId?: string;
-    onAutoSwitch?: (toToolId: string) => void;
-    onPlaced?: (measurement: PlacedMeasurementRef) => void;
-}
-export declare const createMeasurementLineTool: (options?: MeasurementLineToolOptions) => Tool;

package/dist/annotation/canvas/tools/measurementLineTool.js

@@ -1,95 +0,0 @@
-import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
-import { DEFAULT_LINE_POS, recomputeAnchor } from '../measurementGeometry.js';
-let counter = 0;
-const makeId = () => `annotation-${Date.now().toString(36)}-${(counter++).toString(36)}`;
-const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
-// Build the blank line-measurement annotation for a drag from `a` to `b`: a
-// 2-point line with a value tile magnetized to its center (linePos 0.5). The
-// payload mirrors useAnnotationCanvasState's placeAnnotationAtCenter so a drawn
-// line and a (legacy) center-placed one are byte-identical once committed.
-const buildLineMeasurement = (opts) => {
-    const line = { a: opts.a, b: opts.b };
-    return {
-        id: opts.id,
-        layerId: opts.layerId,
-        placement: 'line',
-        line,
-        linePos: DEFAULT_LINE_POS,
-        // Center of the line; recomputeAnchor keeps this in sync on edits.
-        anchor: recomputeAnchor(line, 'line', DEFAULT_LINE_POS, {
-            x: (opts.a.x + opts.b.x) / 2,
-            y: (opts.a.y + opts.b.y) / 2,
-        }),
-        showLabel: true,
-        showValue: true,
-        createdAt: Date.now(),
-    };
-};
-// Drag-to-draw measurement-line tool. Press-drag rubber-bands a measurement
-// annotation (a line with a blank value tile at its center); release commits
-// it. Mirrors createShapeTool's interaction so "input lines" are placed the
-// same way as shapes — draw to add, not tap-the-icon-to-add — replacing the
-// old center-place affordance. The annotation stays blank (no measurement
-// associated) until the user fills it via the tile / picker. Skia-free, like
-// every tool factory; it renders its live preview through ctx.preview, so it
-// works on web and (via the generic tool-pan dispatch) on native.
-export const createMeasurementLineTool = (options = {}) => {
-    const minDragPx = options.minDragPx ?? 4;
-    const autoSwitchToSelect = options.autoSwitchToSelect ?? true;
-    const selectToolId = options.selectToolId ?? 'select';
-    return {
-        id: options.id ?? 'measure-line',
-        label: options.label ?? 'Measurement line',
-        cursor: 'crosshair',
-        onPointerDown(event) {
-            return {
-                kind: 'measurement-line-drawing',
-                id: makeId(),
-                startWorld: event.world,
-                startScreen: event.screen,
-                moved: false,
-            };
-        },
-        onPointerMove(event, ctx, state) {
-            const s = state;
-            if (s?.kind !== 'measurement-line-drawing')
-                return s;
-            const measurement = buildLineMeasurement({
-                id: s.id,
-                layerId: firstLayerId(ctx.document),
-                a: s.startWorld,
-                b: event.world,
-            });
-            ctx.preview({ ops: [{ op: 'addMeasurement', measurement }] });
-            return { ...s, moved: true };
-        },
-        onPointerUp(event, ctx, state) {
-            const s = state;
-            if (s?.kind !== 'measurement-line-drawing')
-                return;
-            const dx = event.screen.x - s.startScreen.x;
-            const dy = event.screen.y - s.startScreen.y;
-            if (!s.moved || dx * dx + dy * dy < minDragPx * minDragPx) {
-                // Accidental tap — discard the rubber-band, commit nothing.
-                ctx.preview({ ops: [] });
-                return;
-            }
-            const measurement = buildLineMeasurement({
-                id: s.id,
-                layerId: firstLayerId(ctx.document),
-                a: s.startWorld,
-                b: event.world,
-            });
-            ctx.commit({ ops: [{ op: 'addMeasurement', measurement }] });
-            // Leave it selected (and hand back to select) so the blank line can be
-            // filled / moved straight away — the same flow as the text tool.
-            ctx.setSelection({ ids: [measurement.id] });
-            options.onPlaced?.(measurement);
-            if (autoSwitchToSelect)
-                options.onAutoSwitch?.(selectToolId);
-        },
-        onCancel(_state, ctx) {
-            ctx.preview({ ops: [] });
-        },
-    };
-};