@reekon-tools/boldr-utils 1.6.8 → 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/AnnotationDataProvider.d.ts

@@ -39,7 +39,7 @@ export interface UploadedImageRef {
     bytes?: number;
 }
 export type AnnotationFile = Extract<FileUpload, {
-    type: FileUploadType.Annotation;
+    type: FileUploadType.Canvas;
 }>;
 export interface AnnotationFileSummary {
     id: string;

package/dist/data/InMemoryAnnotationProvider.js

@@ -1,4 +1,4 @@
-import { FileUploadType, } from '../types/firestore.js';
+import { FileUploadType } from '../types/firestore.js';
 import { isFieldOp, } from './AnnotationDataProvider.js';
 const scopeKey = (s) => `${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
 const jobKey = (s) => `${s.orgId}/${s.projectId}/${s.jobId}`;
@@ -69,7 +69,7 @@ export class InMemoryAnnotationProvider {
             thumbnailUrl: seed.thumbnailUrl ?? null,
             createdAt: seed.createdAt ?? new Date(),
             createdBy: seed.createdBy,
-            type: FileUploadType.Annotation,
+            type: FileUploadType.Canvas,
             fileData: seed.fileData ?? { fileType: 'sketch' },
         };
         this.getBucket(scope).set(id, file);

package/dist/data/canvasPersistence.d.ts

@@ -0,0 +1,3 @@
+import { type AnnotationCanvasState, type AnnotationViewport } from '../types/annotation.js';
+import type { AnnotationFile } from './AnnotationDataProvider.js';
+export declare const hydrateCanvasState: (file: AnnotationFile | null, fallbackViewport?: Partial<AnnotationViewport>) => AnnotationCanvasState;

package/dist/data/canvasPersistence.js

@@ -0,0 +1,26 @@
+import { createEmptyCanvasState, } from '../types/annotation.js';
+// Bring a persisted canvas forward to the current schema. Keyed on
+// `schemaVersion` so each client migrates identically and the provider can
+// stay a dumb transport. Identity for v1 today; add a `case 1: return
+// upgradeV1toV2(raw)` arm when the schema bumps.
+const migrateCanvasState = (raw) => {
+    switch (raw.schemaVersion) {
+        case 1:
+            return raw;
+        default:
+            // Forward-compat: a doc written by a newer client. Trust it as-is
+            // rather than risk a lossy downgrade-write.
+            return raw;
+    }
+};
+// Turn a loaded annotation file into a working canvas state ready to feed the
+// canvas. Missing/legacy docs (no `fileData.canvas`) start from an empty
+// canvas sized by `fallbackViewport`. This is the single entry point for going
+// from `useAnnotationDoc` data to an `AnnotationCanvasState` — consumers should
+// not call `createEmptyCanvasState` directly.
+export const hydrateCanvasState = (file, fallbackViewport) => {
+    const persisted = file?.fileData.canvas;
+    if (!persisted)
+        return createEmptyCanvasState(fallbackViewport);
+    return migrateCanvasState(persisted);
+};

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

@@ -0,0 +1,33 @@
+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;
+    fileId: string | null;
+    fallbackViewport?: Partial<AnnotationViewport>;
+    debounceMs?: number;
+    createSeed?: {
+        name?: string;
+        fileType?: 'sketch' | 'document';
+        isLabel?: boolean;
+    };
+    onFileCreated?: (fileId: string) => void;
+    onSaveError?: (error: unknown) => void;
+    captureThumbnail?: () => Promise<ImageBlob | null>;
+    debugLogging?: boolean;
+}
+export interface UseAnnotationCanvasDocResult {
+    canvas: AnnotationCanvasState;
+    onCommit: (patch: AnnotationDocumentPatch) => void;
+    loading: boolean;
+    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

@@ -0,0 +1,314 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { applyPatch, createEmptyCanvasState, } from '../../types/annotation.js';
+import { FileUploadType } from '../../types/firestore.js';
+import { useAnnotationDoc } from './useAnnotationDoc.js';
+import { useAnnotationMutations } from './useAnnotationMutations.js';
+import { hydrateCanvasState } from '../canvasPersistence.js';
+// Stable placeholder so useAnnotationMutations (which requires a non-null
+// scope) can be called unconditionally. Never used to write — flushes are
+// guarded on a real scope.
+const EMPTY_SCOPE = {
+    orgId: '',
+    projectId: '',
+    jobId: '',
+    groupId: '',
+};
+// Build the persisted fileData, omitting `isLabel` when undefined so the write
+// contains no undefined values (Firestore rejects them on RN).
+const buildFileData = (fileType, isLabel, canvas) => ({
+    fileType,
+    ...(isLabel !== undefined ? { isLabel } : {}),
+    canvas,
+});
+// Orchestrates load + auto-save for the annotation canvas. Hydrates the working
+// state from the persisted doc, applies commits optimistically, and persists
+// (debounced) through the data provider — creating the file on first save when
+// 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, captureThumbnail, debugLogging = false, } = options;
+    const { data, loading, error } = useAnnotationDoc(scope, fileId);
+    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
+    // re-creating timers on every keystroke.
+    const workingRef = useRef(null);
+    const dataRef = useRef(data);
+    const statusRef = useRef('idle');
+    const timerRef = useRef(null);
+    const createRef = useRef(create);
+    const updateRef = useRef(update);
+    const fileIdRef = useRef(fileId);
+    // Id of a file this hook created on first save (when opened with no fileId).
+    // Used for subsequent updates and to recognize the caller echoing it back
+    // into `fileId`.
+    const createdIdRef = useRef(null);
+    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.
+    const lastSavedJsonRef = useRef(null);
+    // Guards against two creates racing if flushes overlap.
+    const creatingRef = useRef(false);
+    workingRef.current = working;
+    dataRef.current = data;
+    statusRef.current = saveStatus;
+    createRef.current = create;
+    updateRef.current = update;
+    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) —
+    // our working state is already correct and must not be wiped.
+    useEffect(() => {
+        if (fileIdRef.current === fileId)
+            return;
+        fileIdRef.current = fileId;
+        if (fileId !== null && fileId === createdIdRef.current)
+            return;
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        createdIdRef.current = null;
+        lastSavedJsonRef.current = null;
+        setWorking(null);
+        setStatus('idle');
+    }, [fileId, setStatus]);
+    // Hydrate / reconcile from the persisted doc.
+    useEffect(() => {
+        // First load — always hydrate.
+        if (workingRef.current === null) {
+            setWorking(hydrateCanvasState(data, fallbackViewport));
+            lastSavedJsonRef.current = data?.fileData.canvas
+                ? JSON.stringify(data.fileData.canvas)
+                : null;
+            return;
+        }
+        // A write of ours is queued or in flight — ignore the snapshot; it is
+        // either the echo of our write or about to be superseded by it.
+        if (statusRef.current === 'saving' || timerRef.current !== null)
+            return;
+        // Clean locally: accept a genuine remote change, but ignore the echo of
+        // our own last write (same content).
+        const incoming = data?.fileData.canvas;
+        if (!incoming)
+            return;
+        const incomingJson = JSON.stringify(incoming);
+        if (incomingJson === lastSavedJsonRef.current)
+            return;
+        lastSavedJsonRef.current = incomingJson;
+        setWorking(hydrateCanvasState(data, fallbackViewport));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [data]);
+    const flush = useCallback(async () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        const canvas = workingRef.current;
+        // Nothing to persist, or no real target scope yet.
+        if (!canvas || !scope)
+            return;
+        if (creatingRef.current)
+            return;
+        const json = JSON.stringify(canvas);
+        const id = fileIdRef.current ?? createdIdRef.current;
+        const mode = id ? 'update' : 'create';
+        const debug = debugRef.current;
+        if (debug) {
+            console.log('[useAnnotationCanvasDoc] save attempt', {
+                mode,
+                fileId: id,
+                scope,
+                bytes: json.length,
+                strokes: canvas.strokes.length,
+                shapes: canvas.shapes.length,
+                measurements: canvas.placedMeasurements.length,
+            });
+        }
+        // Round-trip through JSON to drop `undefined` keys (e.g. an empty canvas's
+        // viewport.backgroundImage/backgroundFit). Firestore — RN in particular —
+        // rejects undefined field values unless ignoreUndefinedProperties is set.
+        const canvasPayload = JSON.parse(json);
+        setStatus('saving');
+        try {
+            if (!id) {
+                // First save with no file — create the doc seeded with the canvas.
+                creatingRef.current = true;
+                const seed = createSeedRef.current;
+                const newId = await createRef.current({
+                    type: FileUploadType.Canvas,
+                    ...(seed?.name !== undefined ? { name: seed.name } : {}),
+                    fileData: buildFileData(seed?.fileType ?? 'sketch', seed?.isLabel, canvasPayload),
+                });
+                creatingRef.current = false;
+                createdIdRef.current = newId;
+                if (debug) {
+                    console.log('[useAnnotationCanvasDoc] created file', newId);
+                }
+                onFileCreatedRef.current?.(newId);
+            }
+            else {
+                const doc = dataRef.current;
+                await updateRef.current(id, {
+                    fileData: buildFileData(doc?.fileData.fileType ??
+                        createSeedRef.current?.fileType ??
+                        'sketch', doc?.fileData.isLabel ?? createSeedRef.current?.isLabel, canvasPayload),
+                });
+                if (debug) {
+                    console.log('[useAnnotationCanvasDoc] updated file', id);
+                }
+            }
+            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;
+            if (latest && JSON.stringify(latest) !== json) {
+                setStatus('dirty');
+            }
+            else {
+                setStatus('saved');
+            }
+        }
+        catch (e) {
+            creatingRef.current = false;
+            // Always log save failures with context — these are otherwise invisible
+            // (the canvas keeps working from local state).
+            console.error(`[useAnnotationCanvasDoc] ${mode} failed`, { fileId: id, scope, bytes: json.length }, e);
+            onSaveErrorRef.current?.(e);
+            setStatus('error');
+        }
+    }, [scope, setStatus, saveThumbnail]);
+    const onCommit = useCallback((patch) => {
+        setWorking((prev) => (prev ? applyPatch(prev, patch) : prev));
+        setStatus('dirty');
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            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) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+            void flush();
+        }
+    }, [flush]);
+    const canvas = useMemo(() => working ?? createEmptyCanvasState(fallbackViewport), [working, fallbackViewport]);
+    return {
+        canvas,
+        onCommit,
+        loading,
+        error,
+        saveStatus,
+        save: flush,
+        ensureFileId,
+        setBackgroundImage,
+        clearBackgroundImage,
+    };
+};

package/dist/exports.d.ts

@@ -13,13 +13,16 @@ export { AnnotationDataProviderContext, useAnnotationData, type AnnotationDataPr
 export { useAnnotationDoc, type UseAnnotationDocResult, } from './data/hooks/useAnnotationDoc.js';
 export { useAnnotationList, type UseAnnotationListResult, } from './data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, type AnnotationMutations, } from './data/hooks/useAnnotationMutations.js';
+export { useAnnotationCanvasDoc, type SaveStatus, type UseAnnotationCanvasDocOptions, type UseAnnotationCanvasDocResult, } from './data/hooks/useAnnotationCanvasDoc.js';
+export { hydrateCanvasState } from './data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './data/InMemoryAnnotationProvider.js';
-export type { AnnotationCanvasHandle, } from './canvas/useAnnotationCanvasState.js';
+export type { AnnotationCanvasHandle } from './canvas/useAnnotationCanvasState.js';
 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 { createPenTool, type PenToolOptions } from './canvas/tools/penTool.js';
 export { createSelectTool } from './canvas/tools/selectTool.js';
 export { createMeasurementStampTool, type MeasurementStampToolOptions, } from './canvas/tools/measurementStampTool.js';
-export { createPanTool, type PanToolOptions, } from './canvas/tools/panTool.js';
+export { createPanTool, type PanToolOptions } from './canvas/tools/panTool.js';

package/dist/exports.js

@@ -18,9 +18,11 @@ export { AnnotationDataProviderContext, useAnnotationData, } from './data/Annota
 export { useAnnotationDoc, } from './data/hooks/useAnnotationDoc.js';
 export { useAnnotationList, } from './data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, } from './data/hooks/useAnnotationMutations.js';
+export { useAnnotationCanvasDoc, } from './data/hooks/useAnnotationCanvasDoc.js';
+export { hydrateCanvasState } from './data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './data/InMemoryAnnotationProvider.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, } from './canvas/viewport.js';
-export { createPenTool, } from './canvas/tools/penTool.js';
+export { createPenTool } from './canvas/tools/penTool.js';
 export { createSelectTool } from './canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './canvas/tools/measurementStampTool.js';
-export { createPanTool, } from './canvas/tools/panTool.js';
+export { createPanTool } from './canvas/tools/panTool.js';

package/dist/types/firestore.d.ts

@@ -100,6 +100,7 @@ export interface SelectedTemplate extends FirestoreDoc {
 }
 export declare enum FileUploadType {
     Annotation = "annotation",
+    Canvas = "canvas",
     Template = "template",
     Background = "background",
     LayoutGroup = "layoutGroup",
@@ -148,6 +149,7 @@ interface FileUploadBase {
     id: string;
     name: string;
     thumbnailUrl: string | null;
+    folderPath?: string;
     createdBy?: {
         userId: string;
         firstName?: string;
@@ -158,6 +160,9 @@ interface FileUploadBase {
 export type FileUpload = FileUploadBase & ({
     type: FileUploadType.Annotation;
     fileData: AnnotationFileData;
+} | {
+    type: FileUploadType.Canvas;
+    fileData: AnnotationFileData;
 } | {
     type: FileUploadType.Calculator;
     fileData: CalculatorFileData;

package/dist/types/firestore.js

@@ -18,6 +18,9 @@ export var TemplateType;
 export var FileUploadType;
 (function (FileUploadType) {
     FileUploadType["Annotation"] = "annotation";
+    // v2 Skia photo-annotation canvas. Distinct from the legacy PSPDFKit
+    // `Annotation` docs so file-open routing sends it to the canvas editor.
+    FileUploadType["Canvas"] = "canvas";
     FileUploadType["Template"] = "template";
     FileUploadType["Background"] = "background";
     FileUploadType["LayoutGroup"] = "layoutGroup";

package/package.json

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