@reekon-tools/boldr-utils 1.6.9 → 1.6.10

package/dist/canvas/AnnotationCanvasInner.d.ts

@@ -5,6 +5,7 @@ import type { MeasurementRef } from './measurementPicker.js';
 import type { Tool } from './Tool.js';
 import { type AnnotationCanvasHandle } from './useAnnotationCanvasState.js';
 import { type ViewportState } from './viewport.js';
+import type { RenderMeasurementStamp } from './measurementStampOverlay.js';
 export type { AnnotationCanvasHandle };
 export interface AnnotationCanvasInnerProps {
     canvas: AnnotationCanvasState;
@@ -19,6 +20,7 @@ export interface AnnotationCanvasInnerProps {
     decimalTolerance?: DecimalTolerance;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
+    renderMeasurementStamp?: RenderMeasurementStamp;
     stampFontSource?: unknown;
     stampValueFontSize?: number;
     stampLabelFontSize?: number;

package/dist/canvas/AnnotationCanvasInner.js

@@ -1,8 +1,9 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFont } from '@shopify/react-native-skia';
 import { useCallback, useEffect, useRef, } from 'react';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
 import { useAnnotationCanvasState, } from './useAnnotationCanvasState.js';
+import { STAMP_TILE_SIZE } from './stampLayout.js';
 const DEFAULT_PAN_TRIGGERS = ['middleMouse', 'space'];
 export const AnnotationCanvasInner = (props) => {
     const { fallbackUnit, fractionalTolerance, decimalTolerance, resolveImageUrl, stampFontSource, stampValueFontSize = 14, stampLabelFontSize = 11, gestures, width, height, style, activeToolId, tools, } = props;
@@ -161,19 +162,58 @@ export const AnnotationCanvasInner = (props) => {
         ...style,
     };
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
-    return (_jsx("div", { ref: containerRef, style: containerStyle, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerCancel: handlePointerCancel, onWheel: handleWheel, onContextMenu: handleContextMenu, children: AnnotationCanvasSkia({
-            width,
-            height,
-            effectiveCanvas: state.effectiveCanvas,
-            worldTransform: state.worldTransform,
-            measurementsById: state.measurementsById,
-            fallbackUnit,
-            fractionalTolerance,
-            decimalTolerance,
-            resolveImageUrl,
-            valueFont,
-            labelFont,
-            penDrawingStroke: state.penDrawingStroke,
-            customPreview,
-        }) }));
+    const { renderMeasurementStamp, selection } = props;
+    return (_jsxs("div", { ref: containerRef, style: containerStyle, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerCancel: handlePointerCancel, onWheel: handleWheel, onContextMenu: handleContextMenu, children: [AnnotationCanvasSkia({
+                width,
+                height,
+                effectiveCanvas: state.effectiveCanvas,
+                worldTransform: state.worldTransform,
+                measurementsById: state.measurementsById,
+                fallbackUnit,
+                fractionalTolerance,
+                decimalTolerance,
+                resolveImageUrl,
+                valueFont,
+                labelFont,
+                hideMeasurementStamps: !!renderMeasurementStamp,
+                penDrawingStroke: state.penDrawingStroke,
+                customPreview,
+            }), renderMeasurementStamp && (_jsx("div", { style: {
+                    position: 'absolute',
+                    inset: 0,
+                    pointerEvents: 'none',
+                }, children: state.effectiveCanvas.placedMeasurements.map((placed) => {
+                    const size = STAMP_TILE_SIZE * (placed.scale ?? 1);
+                    const cx = (placed.anchor.x - state.viewport.pan.x) * state.viewport.zoom;
+                    const cy = (placed.anchor.y - state.viewport.pan.y) * state.viewport.zoom;
+                    const isSelected = selection?.ids.includes(placed.id) ?? false;
+                    return (_jsxs("div", { style: {
+                            position: 'absolute',
+                            left: 0,
+                            top: 0,
+                            width: size,
+                            height: size,
+                            transform: `translate(${cx - size / 2}px, ${cy - size / 2}px)`,
+                        }, children: [renderMeasurementStamp({
+                                placed,
+                                measurement: state.measurementsById.get(placed.measurementId) ?? null,
+                                selected: isSelected,
+                                size,
+                                zoom: state.viewport.zoom,
+                            }), isSelected && (_jsx("div", { role: "button", "aria-label": "Remove measurement", onPointerDown: (e) => {
+                                    e.stopPropagation();
+                                    state.ctx.commit({
+                                        ops: [{ op: 'removeMeasurement', id: placed.id }],
+                                    });
+                                    state.ctx.setSelection(null);
+                                }, style: {
+                                    position: 'absolute',
+                                    top: -10,
+                                    right: -10,
+                                    width: 40,
+                                    height: 40,
+                                    cursor: 'pointer',
+                                    pointerEvents: 'auto',
+                                } }))] }, placed.id));
+                }) }))] }));
 };

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

@@ -1,5 +1,6 @@
 import { type MutableRefObject } from 'react';
 import { type ViewStyle } from 'react-native';
+import type { RenderMeasurementStamp } from './measurementStampOverlay.js';
 import type { DecimalTolerance, FractionalTolerance, Measurement, Units } from '../types/firestore.js';
 import type { AnnotationCanvasState, AnnotationDocumentPatch, Selection } from '../types/annotation.js';
 import type { MeasurementRef } from './measurementPicker.js';
@@ -20,6 +21,7 @@ export interface AnnotationCanvasInnerProps {
     decimalTolerance?: DecimalTolerance;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
+    renderMeasurementStamp?: RenderMeasurementStamp;
     stampFontSource?: unknown;
     stampValueFontSize?: number;
     stampLabelFontSize?: number;

package/dist/canvas/AnnotationCanvasInner.native.js

@@ -1,8 +1,9 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFont } from '@shopify/react-native-skia';
 import { useMemo, useRef } from 'react';
-import { View } from 'react-native';
+import { StyleSheet, TouchableOpacity, View } from 'react-native';
 import { Gesture, GestureDetector, GestureHandlerRootView, } from 'react-native-gesture-handler';
+import { STAMP_TILE_SIZE } from './stampLayout.js';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
 import { useAnnotationCanvasState, } from './useAnnotationCanvasState.js';
 // Native fingerprint: one finger drives the active tool, two fingers
@@ -84,19 +85,54 @@ export const AnnotationCanvasInner = (props) => {
     }, [state]);
     const activeTool = props.tools.find((t) => t.id === props.activeToolId) ?? null;
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
-    return (_jsx(GestureHandlerRootView, { style: [{ width, height }, style], children: _jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia({
-                    width,
-                    height,
-                    effectiveCanvas: state.effectiveCanvas,
-                    worldTransform: state.worldTransform,
-                    measurementsById: state.measurementsById,
-                    fallbackUnit,
-                    fractionalTolerance,
-                    decimalTolerance,
-                    resolveImageUrl,
-                    valueFont,
-                    labelFont,
-                    penDrawingStroke: state.penDrawingStroke,
-                    customPreview,
-                }) }) }) }));
+    const { renderMeasurementStamp, selection } = props;
+    return (_jsxs(GestureHandlerRootView, { style: [{ width, height }, style], children: [_jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia({
+                        width,
+                        height,
+                        effectiveCanvas: state.effectiveCanvas,
+                        worldTransform: state.worldTransform,
+                        measurementsById: state.measurementsById,
+                        fallbackUnit,
+                        fractionalTolerance,
+                        decimalTolerance,
+                        resolveImageUrl,
+                        valueFont,
+                        labelFont,
+                        hideMeasurementStamps: !!renderMeasurementStamp,
+                        penDrawingStroke: state.penDrawingStroke,
+                        customPreview,
+                    }) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => {
+                    const size = STAMP_TILE_SIZE * (placed.scale ?? 1);
+                    const cx = (placed.anchor.x - state.viewport.pan.x) * state.viewport.zoom;
+                    const cy = (placed.anchor.y - state.viewport.pan.y) * state.viewport.zoom;
+                    const isSelected = selection?.ids.includes(placed.id) ?? false;
+                    return (_jsxs(View, { pointerEvents: "box-none", style: {
+                            position: 'absolute',
+                            left: 0,
+                            top: 0,
+                            width: size,
+                            height: size,
+                            transform: [
+                                { translateX: cx - size / 2 },
+                                { translateY: cy - size / 2 },
+                            ],
+                        }, children: [_jsx(View, { pointerEvents: "none", style: StyleSheet.absoluteFill, children: renderMeasurementStamp({
+                                    placed,
+                                    measurement: state.measurementsById.get(placed.measurementId) ?? null,
+                                    selected: isSelected,
+                                    size,
+                                    zoom: state.viewport.zoom,
+                                }) }), isSelected && (_jsx(TouchableOpacity, { accessibilityRole: "button", accessibilityLabel: "Remove measurement", hitSlop: 10, onPress: () => {
+                                    state.ctx.commit({
+                                        ops: [{ op: 'removeMeasurement', id: placed.id }],
+                                    });
+                                    state.ctx.setSelection(null);
+                                }, style: {
+                                    position: 'absolute',
+                                    top: -8,
+                                    right: -8,
+                                    width: 36,
+                                    height: 36,
+                                } }))] }, placed.id));
+                }) }))] }));
 };

package/dist/canvas/AnnotationCanvasSkia.d.ts

@@ -20,7 +20,8 @@ export interface AnnotationCanvasSkiaProps {
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     valueFont: SkFont | null;
     labelFont: SkFont | null;
+    hideMeasurementStamps?: boolean;
     penDrawingStroke: AnnotationStroke | null;
     customPreview?: ReactNode;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, measurementsById, fallbackUnit, fractionalTolerance, decimalTolerance, resolveImageUrl, valueFont, labelFont, penDrawingStroke, customPreview, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, measurementsById, fallbackUnit, fractionalTolerance, decimalTolerance, resolveImageUrl, valueFont, labelFont, hideMeasurementStamps, penDrawingStroke, customPreview, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;

package/dist/canvas/AnnotationCanvasSkia.js

@@ -16,4 +16,5 @@ import { StrokeElement } from './elements/StrokeElement.js';
 // 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, measurementsById, fallbackUnit, fractionalTolerance, decimalTolerance, resolveImageUrl, valueFont, labelFont, penDrawingStroke, customPreview, }) => (_jsx(Canvas, { style: { width, height }, children: _jsxs(Group, { transform: worldTransform, children: [effectiveCanvas.viewport.backgroundImage && (_jsx(BackgroundImageElement, { image: effectiveCanvas.viewport.backgroundImage, docWidth: effectiveCanvas.viewport.width, docHeight: effectiveCanvas.viewport.height, fit: effectiveCanvas.viewport.backgroundFit ?? 'contain', resolveUrl: resolveImageUrl })), effectiveCanvas.strokes.map((stroke) => (_jsx(StrokeElement, { stroke: stroke }, stroke.id))), effectiveCanvas.shapes.map((shape) => (_jsx(ShapeElement, { shape: shape, font: valueFont }, shape.id))), effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampElement, { placed: placed, measurement: measurementsById.get(placed.measurementId) ?? null, fallbackUnit: fallbackUnit ?? Units.Millimeters, fractionalTolerance: fractionalTolerance, decimalTolerance: decimalTolerance, valueFont: valueFont, labelFont: labelFont }, placed.id))), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), customPreview] }) }));
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, measurementsById, fallbackUnit, fractionalTolerance, decimalTolerance, resolveImageUrl, valueFont, labelFont, hideMeasurementStamps, penDrawingStroke, customPreview, }) => (_jsx(Canvas, { style: { width, height }, children: _jsxs(Group, { transform: worldTransform, children: [effectiveCanvas.viewport.backgroundImage && (_jsx(BackgroundImageElement, { image: effectiveCanvas.viewport.backgroundImage, docWidth: effectiveCanvas.viewport.width, docHeight: effectiveCanvas.viewport.height, fit: effectiveCanvas.viewport.backgroundFit ?? 'contain', resolveUrl: resolveImageUrl })), effectiveCanvas.strokes.map((stroke) => (_jsx(StrokeElement, { stroke: stroke }, stroke.id))), effectiveCanvas.shapes.map((shape) => (_jsx(ShapeElement, { shape: shape, font: valueFont }, shape.id))), !hideMeasurementStamps &&
+                effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampElement, { placed: placed, measurement: measurementsById.get(placed.measurementId) ?? null, fallbackUnit: fallbackUnit ?? Units.Millimeters, fractionalTolerance: fractionalTolerance, decimalTolerance: decimalTolerance, valueFont: valueFont, labelFont: labelFont }, placed.id))), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), customPreview] }) }));

package/dist/canvas/measurementStampOverlay.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import type { PlacedMeasurementRef } from '../types/annotation.js';
+import type { Measurement } from '../types/firestore.js';
+export interface MeasurementStampRenderArgs {
+    placed: PlacedMeasurementRef;
+    measurement: Measurement | null;
+    selected: boolean;
+    size: number;
+    zoom: number;
+}
+export type RenderMeasurementStamp = (args: MeasurementStampRenderArgs) => ReactNode;

package/dist/canvas/measurementStampOverlay.js

@@ -0,0 +1 @@
+export {};

package/dist/canvas/stampLayout.d.ts

@@ -2,3 +2,4 @@ export declare const STAMP_WIDTH = 120;
 export declare const STAMP_HEIGHT = 44;
 export declare const STAMP_PADDING_X = 10;
 export declare const STAMP_PADDING_Y = 6;
+export declare const STAMP_TILE_SIZE = 120;

package/dist/canvas/stampLayout.js

@@ -6,3 +6,9 @@ export const STAMP_WIDTH = 120;
 export const STAMP_HEIGHT = 44;
 export const STAMP_PADDING_X = 10;
 export const STAMP_PADDING_Y = 6;
+// Constant SCREEN-space edge length of a placed measurement rendered as a
+// square tile (the overlay path — see measurementStampOverlay.ts). The tile
+// is a fixed-size pin: its on-screen size is this times `placed.scale` and
+// does NOT change with zoom (only its position tracks the canvas). Also drives
+// the select-tool hit box, which converts it back to doc space via the zoom.
+export const STAMP_TILE_SIZE = 120;

package/dist/canvas/tools/selectTool.js

@@ -1,4 +1,4 @@
-import { STAMP_HEIGHT, STAMP_WIDTH } from '../stampLayout.js';
+import { STAMP_TILE_SIZE } from '../stampLayout.js';
 const HIT_PADDING = 6;
 // Hit-test in doc-space. Crude but fast — good enough for v1; tools can
 // override via `hitTest` for more precision later.
@@ -12,16 +12,16 @@ const hitStroke = (stroke, p) => {
     }
     return false;
 };
-const hitMeasurement = (m, p) => {
-    // Stamp rectangle is fixed-size, centered on the anchor and scaled by
-    // `placed.scale`. Match the hit box exactly to that rectangle (plus a
-    // small padding so the click target feels generous).
+const hitMeasurement = (m, p, zoom = 1) => {
+    // The stamp renders as a constant *screen*-size square centered on the
+    // anchor, so its doc-space footprint shrinks as you zoom in. Convert the
+    // screen-space half-extent (+ padding) back to doc space via the zoom so
+    // the hit box always matches what's drawn.
     const scale = m.scale ?? 1;
-    const halfW = (STAMP_WIDTH * scale) / 2 + HIT_PADDING;
-    const halfH = (STAMP_HEIGHT * scale) / 2 + HIT_PADDING;
+    const half = ((STAMP_TILE_SIZE * scale) / 2 + HIT_PADDING) / zoom;
     const dx = Math.abs(p.x - m.anchor.x);
     const dy = Math.abs(p.y - m.anchor.y);
-    return dx <= halfW && dy <= halfH;
+    return dx <= half && dy <= half;
 };
 const segmentDistanceSq = (px, py, ax, ay, bx, by) => {
     const abx = bx - ax;
@@ -35,11 +35,11 @@ const segmentDistanceSq = (px, py, ax, ay, bx, by) => {
     const dy = py - cy;
     return dx * dx + dy * dy;
 };
-const findHit = (doc, world) => {
+const findHit = (doc, world, zoom) => {
     // Hit-test in z-order (top first): measurements > shapes > strokes.
     for (let i = doc.placedMeasurements.length - 1; i >= 0; i--) {
         const m = doc.placedMeasurements[i];
-        if (hitMeasurement(m, world))
+        if (hitMeasurement(m, world, zoom))
             return { id: m.id, kind: 'measurement' };
     }
     for (let i = doc.shapes.length - 1; i >= 0; i--) {
@@ -135,7 +135,7 @@ export const createSelectTool = () => ({
     label: 'Select',
     cursor: 'default',
     onPointerDown(event, ctx) {
-        const hit = findHit(ctx.document, event.world);
+        const hit = findHit(ctx.document, event.world, ctx.viewport.state.zoom);
         if (!hit) {
             ctx.setSelection(null);
             return { kind: 'idle' };

package/dist/canvas/useAnnotationCanvasState.d.ts

@@ -10,6 +10,7 @@ export interface AnnotationCanvasHandle {
     canRedo(): boolean;
     zoomToFit(): void;
     resetView(): void;
+    placeMeasurementAtCenter(ref: MeasurementRef): void;
 }
 export interface UseAnnotationCanvasStateProps {
     canvas: AnnotationCanvasState;

package/dist/canvas/useAnnotationCanvasState.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { applyPatch, invertPatch, } from '../types/annotation.js';
+import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../types/annotation.js';
 import { createViewportApi, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
 // Platform-agnostic state machine for the annotation canvas. Web and native
 // inners share this hook; each wraps it with platform-specific event
@@ -54,6 +54,10 @@ export const useAnnotationCanvasState = (props) => {
         onSelectionChange,
         pickMeasurement,
     ]);
+    // Live ctx for imperative handle methods (which are created in an effect and
+    // would otherwise capture a stale ctx/viewport).
+    const ctxRef = useRef(ctx);
+    ctxRef.current = ctx;
     const dispatchPointerDown = useCallback((event) => {
         if (!activeTool)
             return;
@@ -136,6 +140,30 @@ export const useAnnotationCanvasState = (props) => {
             resetView() {
                 setViewport(DEFAULT_VIEWPORT);
             },
+            placeMeasurementAtCenter(ref) {
+                const c = ctxRef.current;
+                const anchor = c.viewport.screenToWorld({
+                    x: width / 2,
+                    y: height / 2,
+                });
+                const placed = {
+                    id: `measurement-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`,
+                    layerId: c.document.layers[0]?.id ?? DEFAULT_LAYER_ID,
+                    measurementPath: ref.measurementPath,
+                    measurementId: ref.measurementId,
+                    groupId: ref.groupId,
+                    anchor,
+                    labelOverride: ref.label,
+                    unitOverride: ref.unit,
+                    showLabel: true,
+                    showValue: true,
+                    createdAt: Date.now(),
+                };
+                c.commit({ ops: [{ op: 'addMeasurement', measurement: placed }] });
+                // Select it so the consumer can immediately move it (the consumer is
+                // responsible for switching to its move/select tool).
+                c.setSelection({ ids: [placed.id] });
+            },
         };
         return () => {
             if (imperativeRef)

package/dist/data/hooks/useAnnotationCanvasDoc.d.ts

@@ -1,5 +1,5 @@
-import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport } from '../../types/annotation.js';
-import type { JobGroupScope } from '../AnnotationDataProvider.js';
+import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport, type BackgroundFit } from '../../types/annotation.js';
+import type { ImageBlob, JobGroupScope } from '../AnnotationDataProvider.js';
 export type SaveStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error';
 export interface UseAnnotationCanvasDocOptions {
     scope: JobGroupScope | null;
@@ -13,6 +13,7 @@ export interface UseAnnotationCanvasDocOptions {
     };
     onFileCreated?: (fileId: string) => void;
     onSaveError?: (error: unknown) => void;
+    captureThumbnail?: () => Promise<ImageBlob | null>;
     debugLogging?: boolean;
 }
 export interface UseAnnotationCanvasDocResult {
@@ -22,5 +23,11 @@ export interface UseAnnotationCanvasDocResult {
     error: Error | null;
     saveStatus: SaveStatus;
     save: () => Promise<void>;
+    ensureFileId: () => Promise<string>;
+    setBackgroundImage: (blob: ImageBlob, dims: {
+        width: number;
+        height: number;
+    }, fit?: BackgroundFit) => Promise<void>;
+    clearBackgroundImage: () => Promise<void>;
 }
 export declare const useAnnotationCanvasDoc: (options: UseAnnotationCanvasDocOptions) => UseAnnotationCanvasDocResult;

package/dist/data/hooks/useAnnotationCanvasDoc.js

@@ -26,9 +26,9 @@ const buildFileData = (fileType, isLabel, canvas) => ({
 // no `fileId` was supplied. Composes the existing low-level hooks so it stays
 // decoupled from any specific Firebase SDK.
 export const useAnnotationCanvasDoc = (options) => {
-    const { scope, fileId, fallbackViewport, debounceMs = 800, createSeed, onFileCreated, onSaveError, debugLogging = false, } = options;
+    const { scope, fileId, fallbackViewport, debounceMs = 800, createSeed, onFileCreated, onSaveError, captureThumbnail, debugLogging = false, } = options;
     const { data, loading, error } = useAnnotationDoc(scope, fileId);
-    const { create, update } = useAnnotationMutations(scope ?? EMPTY_SCOPE);
+    const { create, update, uploadImage, deleteImage } = useAnnotationMutations(scope ?? EMPTY_SCOPE);
     const [working, setWorking] = useState(null);
     const [saveStatus, setSaveStatus] = useState('idle');
     // Refs let the debounced/unmount flush read the latest values without
@@ -47,6 +47,10 @@ export const useAnnotationCanvasDoc = (options) => {
     const createSeedRef = useRef(createSeed);
     const onFileCreatedRef = useRef(onFileCreated);
     const onSaveErrorRef = useRef(onSaveError);
+    const captureThumbnailRef = useRef(captureThumbnail);
+    const uploadImageRef = useRef(uploadImage);
+    // Guards against overlapping thumbnail captures (each save fires one).
+    const thumbnailSavingRef = useRef(false);
     const debugRef = useRef(debugLogging);
     // JSON of the canvas we last wrote, to recognize (and ignore) the snapshot
     // echo of our own write when reconciling incoming remote changes.
@@ -61,11 +65,33 @@ export const useAnnotationCanvasDoc = (options) => {
     createSeedRef.current = createSeed;
     onFileCreatedRef.current = onFileCreated;
     onSaveErrorRef.current = onSaveError;
+    captureThumbnailRef.current = captureThumbnail;
+    uploadImageRef.current = uploadImage;
     debugRef.current = debugLogging;
     const setStatus = useCallback((next) => {
         statusRef.current = next;
         setSaveStatus(next);
     }, []);
+    // Fire-and-forget thumbnail capture + upload, run after each successful save.
+    // Stable identity (reads refs) so it doesn't churn `flush`'s deps. Skips when
+    // no capturer is supplied or a capture is already in flight.
+    const saveThumbnail = useCallback(async (fileId) => {
+        const capture = captureThumbnailRef.current;
+        if (!capture || thumbnailSavingRef.current)
+            return;
+        thumbnailSavingRef.current = true;
+        try {
+            const blob = await capture();
+            if (blob)
+                await uploadImageRef.current(fileId, 'thumbnail', blob);
+        }
+        catch (e) {
+            console.warn('[useAnnotationCanvasDoc] thumbnail save failed', e);
+        }
+        finally {
+            thumbnailSavingRef.current = false;
+        }
+    }, []);
     // Reset working state when the target document changes so the next snapshot
     // hydrates the new file rather than leaking the previous one. Skip the reset
     // when the new fileId is one we just created (the caller echoing it back) —
@@ -171,6 +197,11 @@ export const useAnnotationCanvasDoc = (options) => {
                 }
             }
             lastSavedJsonRef.current = json;
+            // Refresh the file's thumbnail to match what was just saved (fire and
+            // forget — never blocks or fails the save).
+            const savedId = fileIdRef.current ?? createdIdRef.current;
+            if (savedId)
+                void saveThumbnail(savedId);
             // If new edits landed mid-flight, stay dirty and let the next debounce
             // (or unmount) flush them.
             const latest = workingRef.current;
@@ -189,7 +220,7 @@ export const useAnnotationCanvasDoc = (options) => {
             onSaveErrorRef.current?.(e);
             setStatus('error');
         }
-    }, [scope, setStatus]);
+    }, [scope, setStatus, saveThumbnail]);
     const onCommit = useCallback((patch) => {
         setWorking((prev) => (prev ? applyPatch(prev, patch) : prev));
         setStatus('dirty');
@@ -200,6 +231,66 @@ export const useAnnotationCanvasDoc = (options) => {
             void flush();
         }, debounceMs);
     }, [debounceMs, flush, setStatus]);
+    const ensureFileId = useCallback(async () => {
+        const existing = fileIdRef.current ?? createdIdRef.current;
+        if (existing)
+            return existing;
+        // No file yet — seed an empty canvas if nothing has hydrated, then flush
+        // so the existing create branch mints the doc.
+        if (!workingRef.current) {
+            const seeded = createEmptyCanvasState(fallbackViewport);
+            workingRef.current = seeded;
+            setWorking(seeded);
+        }
+        await flush();
+        const id = fileIdRef.current ?? createdIdRef.current;
+        if (!id) {
+            throw new Error('Unable to create annotation file before background upload');
+        }
+        return id;
+    }, [flush, fallbackViewport]);
+    const setBackgroundImage = useCallback(async (blob, dims, fit = 'contain') => {
+        const id = await ensureFileId();
+        const ref = await uploadImage(id, 'background', blob);
+        onCommit({
+            ops: [
+                {
+                    op: 'setViewport',
+                    patch: {
+                        backgroundImage: {
+                            storagePath: ref.storagePath,
+                            downloadUrl: ref.downloadUrl,
+                            widthPx: dims.width,
+                            heightPx: dims.height,
+                        },
+                        backgroundFit: fit,
+                    },
+                },
+            ],
+        });
+    }, [ensureFileId, uploadImage, onCommit]);
+    const clearBackgroundImage = useCallback(async () => {
+        const bg = workingRef.current?.viewport.backgroundImage;
+        const id = fileIdRef.current ?? createdIdRef.current;
+        if (bg && id) {
+            try {
+                await deleteImage(id, bg.storagePath);
+            }
+            catch (e) {
+                // Non-fatal: still clear the viewport reference even if the storage
+                // object is already gone.
+                console.warn('[useAnnotationCanvasDoc] failed to delete background image', e);
+            }
+        }
+        onCommit({
+            ops: [
+                {
+                    op: 'setViewport',
+                    patch: { backgroundImage: undefined, backgroundFit: undefined },
+                },
+            ],
+        });
+    }, [deleteImage, onCommit]);
     // Flush any pending edits on unmount.
     useEffect(() => () => {
         if (timerRef.current) {
@@ -216,5 +307,8 @@ export const useAnnotationCanvasDoc = (options) => {
         error,
         saveStatus,
         save: flush,
+        ensureFileId,
+        setBackgroundImage,
+        clearBackgroundImage,
     };
 };

package/dist/exports.d.ts

@@ -20,6 +20,7 @@ export type { AnnotationCanvasHandle } from './canvas/useAnnotationCanvasState.j
 export type { GestureConfig, PanTrigger, AnnotationCanvasInnerProps, } from './canvas/AnnotationCanvasInner.js';
 export type { CanvasPointerEvent, Tool, ToolContext, ToolState, } from './canvas/Tool.js';
 export type { MeasurementRef, PickMeasurement, } from './canvas/measurementPicker.js';
+export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './canvas/measurementStampOverlay.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './canvas/viewport.js';
 export { createPenTool, type PenToolOptions } from './canvas/tools/penTool.js';
 export { createSelectTool } from './canvas/tools/selectTool.js';

package/package.json

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