@reekon-tools/boldr-utils 1.6.13 → 1.6.14

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

@@ -1,5 +1,6 @@
 import { STAMP_TILE_SIZE } from '../stampLayout.js';
-import { placementOf, linePosOf, snapLinePos, lerp, recomputeAnchor, normalizeRect, rectCenter, rectCornerPoint, oppositeRectCorner, } from '../measurementGeometry.js';
+import { placementOf, linePosOf, snapLinePos, lerp, recomputeAnchor, rectCenter, rectCornerPoint, oppositeRectCorner, hitPlacedMeasurement, } from '../measurementGeometry.js';
+import { hitShapeOutline } from '../shapeGeometry.js';
 import { DEFAULT_TEXT_FONT_SIZE, resizeScaleFromDrag, textResizeGeometry, textShapeBounds, } from '../textGeometry.js';
 const HIT_PADDING = 6;
 // Hit-test in doc-space. Crude but fast — good enough for v1; tools can
@@ -14,9 +15,9 @@ const hitStroke = (stroke, p) => {
     }
     return false;
 };
-// Screen-space grab tolerance (px) for a measurement-annotation line, converted
-// to doc space via zoom (the line itself is a thin world-space stroke).
-const LINE_GRAB_PX = 12;
+// Screen-space grab tolerance (px) added around a geometric shape's outline
+// (line/arrow/rect/ellipse/polygon), converted to doc space via zoom.
+const SHAPE_GRAB_PX = 12;
 // Screen-px radius of the center snap detent when sliding a tile along its line.
 // Converted to t-space per line via (SNAP_PX / zoom) / lineLength. The native
 // slide worklet inlines the same value — keep them in sync.
@@ -24,39 +25,6 @@ const SLIDE_SNAP_PX = 12;
 // Screen-px grab radius for a line-annotation endpoint handle (converted to doc
 // space via zoom). A bit larger than the drawn handle so it's easy to grab.
 const HANDLE_GRAB_PX = 22;
-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 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);
-    if (dx <= half && dy <= half)
-        return true;
-    // Measurement annotation: also grab anywhere along the line body.
-    if (m.line) {
-        const r = LINE_GRAB_PX / zoom;
-        if (segmentDistanceSq(p.x, p.y, m.line.a.x, m.line.a.y, m.line.b.x, m.line.b.y) <=
-            r * r) {
-            return true;
-        }
-    }
-    // Rectangle annotation: grab anywhere along the border (the interior stays
-    // transparent to hits so elements behind the rect remain selectable).
-    if (m.rect && placementOf(m) === 'rectangle') {
-        const n = normalizeRect(m.rect);
-        const r2 = (LINE_GRAB_PX / zoom) ** 2;
-        if (segmentDistanceSq(p.x, p.y, n.minX, n.minY, n.maxX, n.minY) <= r2 ||
-            segmentDistanceSq(p.x, p.y, n.maxX, n.minY, n.maxX, n.maxY) <= r2 ||
-            segmentDistanceSq(p.x, p.y, n.maxX, n.maxY, n.minX, n.maxY) <= r2 ||
-            segmentDistanceSq(p.x, p.y, n.minX, n.maxY, n.minX, n.minY) <= r2) {
-            return true;
-        }
-    }
-    return false;
-};
 const segmentDistanceSq = (px, py, ax, ay, bx, by) => {
     const abx = bx - ax;
     const aby = by - ay;
@@ -73,48 +41,32 @@ 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, zoom))
+        if (hitPlacedMeasurement(m, world, zoom)) {
             return { id: m.id, kind: 'measurement' };
+        }
     }
     for (let i = doc.shapes.length - 1; i >= 0; i--) {
-        // Default shape hit test: bounding box of the shape's points + padding.
-        // Text shapes store only their top-left anchor, so their box comes from
-        // the estimated text bounds instead.
         const s = doc.shapes[i];
-        let minX;
-        let maxX;
-        let minY;
-        let maxY;
         if (s.kind === 'text') {
+            // Text shapes store only their top-left anchor, so their hit box comes
+            // from the estimated text bounds.
             const b = textShapeBounds(s);
             if (!b)
                 continue;
-            ({ minX, maxX, minY, maxY } = b);
-        }
-        else {
-            const pts = s.geometry.points;
-            if (pts.length === 0)
-                continue;
-            minX = pts[0].x;
-            maxX = pts[0].x;
-            minY = pts[0].y;
-            maxY = pts[0].y;
-            for (let j = 1; j < pts.length; j++) {
-                const p = pts[j];
-                if (p.x < minX)
-                    minX = p.x;
-                if (p.x > maxX)
-                    maxX = p.x;
-                if (p.y < minY)
-                    minY = p.y;
-                if (p.y > maxY)
-                    maxY = p.y;
+            if (world.x >= b.minX - HIT_PADDING &&
+                world.x <= b.maxX + HIT_PADDING &&
+                world.y >= b.minY - HIT_PADDING &&
+                world.y <= b.maxY + HIT_PADDING) {
+                return { id: s.id, kind: 'shape' };
             }
+            continue;
         }
-        if (world.x >= minX - HIT_PADDING &&
-            world.x <= maxX + HIT_PADDING &&
-            world.y >= minY - HIT_PADDING &&
-            world.y <= maxY + HIT_PADDING) {
+        // Geometric shapes hit on their painted outline, not their bounding box —
+        // a long diagonal line's box would swallow taps nowhere near the ink, and
+        // a shape's interior stays transparent to hits so elements inside remain
+        // selectable. Grab radius = half the stroke + a screen-constant pad.
+        const tol = (s.style.strokeWidth ?? 2) / 2 + SHAPE_GRAB_PX / zoom;
+        if (hitShapeOutline(s, world, tol)) {
             return { id: s.id, kind: 'shape' };
         }
     }
@@ -203,7 +155,9 @@ const slidePatch = (doc, id, delta, zoom) => {
     const snapT = SLIDE_SNAP_PX / zoom / Math.sqrt(lenSq);
     t = snapLinePos(t, snapT);
     const anchor = lerp(m.line.a, m.line.b, t);
-    return { ops: [{ op: 'updateMeasurement', id, patch: { linePos: t, anchor } }] };
+    return {
+        ops: [{ op: 'updateMeasurement', id, patch: { linePos: t, anchor } }],
+    };
 };
 // Which endpoint handle of a (selected) line annotation is under `world`.
 // Prefers the nearer endpoint when both are within range.
@@ -271,7 +225,11 @@ const rectCornerPatch = (doc, id, corner, delta) => {
     };
     return {
         ops: [
-            { op: 'updateMeasurement', id, patch: { rect, anchor: rectCenter(rect) } },
+            {
+                op: 'updateMeasurement',
+                id,
+                patch: { rect, anchor: rectCenter(rect) },
+            },
         ],
     };
 };
@@ -417,7 +375,10 @@ export const createSelectTool = () => ({
         const s = state;
         if (s?.kind !== 'dragging')
             return s;
-        const delta = { x: event.world.x - s.start.x, y: event.world.y - s.start.y };
+        const delta = {
+            x: event.world.x - s.start.x,
+            y: event.world.y - s.start.y,
+        };
         const patch = dragPatch(s, ctx.document, delta, ctx.viewport.state.zoom);
         if (patch)
             ctx.preview(patch);
@@ -438,7 +399,7 @@ export const createSelectTool = () => ({
     },
     hitTest(element, p) {
         if (element.kind === 'measurement')
-            return hitMeasurement(element, p);
+            return hitPlacedMeasurement(element, p);
         if (element.kind === 'stroke')
             return hitStroke(element, p);
         return false;

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

@@ -0,0 +1,25 @@
+import type { AnnotationShape, StrokeCap, Vec2 } from '../../../types/annotation.js';
+import { type ShapeToolKind } from '../shapeGeometry.js';
+import type { Tool } from '../Tool.js';
+export interface ShapeToolOptions {
+    kind?: ShapeToolKind;
+    id?: string;
+    label?: string;
+    color?: string;
+    width?: number;
+    cap?: StrokeCap;
+    dash?: boolean;
+    minDragPx?: number;
+}
+export declare const buildShapeFromDrag: (opts: {
+    kind: ShapeToolKind;
+    a: Vec2;
+    b: Vec2;
+    color: string;
+    width: number;
+    cap?: StrokeCap;
+    dash?: boolean;
+    layerId: string;
+    id?: string;
+}) => AnnotationShape;
+export declare const createShapeTool: (options?: ShapeToolOptions) => Tool;

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

@@ -0,0 +1,111 @@
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
+import { annotationKindFor, shapePointsFromDrag, } from '../shapeGeometry.js';
+let counter = 0;
+const makeId = (prefix) => `${prefix}-${Date.now().toString(36)}-${(counter++).toString(36)}`;
+const DEFAULT_LABELS = {
+    line: 'Line',
+    rect: 'Rectangle',
+    triangle: 'Triangle',
+    ellipse: 'Circle',
+};
+// Assemble the committed AnnotationShape for a drag from `a` to `b`. Shared
+// by the web pointer handlers below AND the native UI-thread gesture (which
+// rubber-bands on shared values and calls this once on release) — one source
+// of truth for kind mapping, styling, and the no-undefined-keys rule
+// (Firestore rejects undefined values, so optional style keys are spread in
+// only when set).
+export const buildShapeFromDrag = (opts) => ({
+    id: opts.id ?? makeId('shape'),
+    layerId: opts.layerId,
+    kind: annotationKindFor(opts.kind),
+    geometry: { points: shapePointsFromDrag(opts.kind, opts.a, opts.b) },
+    style: {
+        stroke: opts.color,
+        strokeWidth: opts.width,
+        ...(opts.dash && { dash: true }),
+        // Caps only mean something on an open line; 'round' is the implicit
+        // default so it stays un-persisted.
+        ...(opts.kind === 'line' &&
+            opts.cap &&
+            opts.cap !== 'round' && { cap: opts.cap }),
+    },
+    createdAt: Date.now(),
+});
+const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
+// Drag-to-draw shape tool (line/arrow/rect/triangle/circle). Press-drag
+// rubber-bands the shape from the press point; release commits it as an
+// AnnotationShape. On native the drag runs on the UI thread via the
+// `shapeDraw` config; the pointer handlers below are the web/parity
+// implementation. Skia-free, like every tool factory.
+export const createShapeTool = (options = {}) => {
+    const kind = options.kind ?? 'line';
+    const color = options.color ?? '#111827';
+    const width = options.width ?? 2;
+    const cap = options.cap;
+    const dash = options.dash ?? false;
+    const minDragPx = options.minDragPx ?? 4;
+    return {
+        id: options.id ?? kind,
+        label: options.label ?? DEFAULT_LABELS[kind],
+        cursor: 'crosshair',
+        // Drives UI-thread rubber-banding on native (see ShapeDrawConfig).
+        shapeDraw: { kind, color, width, ...(cap && { cap }), dash },
+        onPointerDown(event, ctx) {
+            return {
+                kind: 'shape-drawing',
+                shape: buildShapeFromDrag({
+                    kind,
+                    a: event.world,
+                    b: event.world,
+                    color,
+                    width,
+                    cap,
+                    dash,
+                    layerId: firstLayerId(ctx.document),
+                }),
+                startWorld: event.world,
+                startScreen: event.screen,
+                moved: false,
+            };
+        },
+        onPointerMove(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'shape-drawing')
+                return s;
+            const next = {
+                ...s,
+                moved: true,
+                shape: {
+                    ...s.shape,
+                    geometry: {
+                        points: shapePointsFromDrag(kind, s.startWorld, event.world),
+                    },
+                },
+            };
+            ctx.preview({ ops: [{ op: 'addShape', shape: next.shape }] });
+            return next;
+        },
+        onPointerUp(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'shape-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 shape = {
+                ...s.shape,
+                geometry: {
+                    points: shapePointsFromDrag(kind, s.startWorld, event.world),
+                },
+            };
+            ctx.commit({ ops: [{ op: 'addShape', shape }] });
+        },
+        onCancel(_state, ctx) {
+            ctx.preview({ ops: [] });
+        },
+    };
+};

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -42,7 +42,9 @@ export const useAnnotationCanvasState = (props) => {
             return pickMeasurement ? pickMeasurement() : Promise.resolve(null);
         },
         requestTextInput(options) {
-            return requestTextInput ? requestTextInput(options) : Promise.resolve(null);
+            return requestTextInput
+                ? requestTextInput(options)
+                : Promise.resolve(null);
         },
         applyPan(deltaScreen) {
             setViewport((v) => panBy(v, deltaScreen));
@@ -63,6 +65,24 @@ export const useAnnotationCanvasState = (props) => {
     // would otherwise capture a stale ctx/viewport).
     const ctxRef = useRef(ctx);
     ctxRef.current = ctx;
+    // Tool hand-over. When the active tool's identity changes — a real tool
+    // switch OR the consumer rebuilding the tools array (e.g. a style change
+    // recreates every factory) — give the outgoing instance a chance to wind
+    // down multi-gesture work (the polygon tool commits its in-progress
+    // vertices), then drop any leftover gesture state/preview so the incoming
+    // tool starts clean. Keyed on object identity, not id: a rebuilt instance
+    // has fresh closure state, so the old instance must still wind down.
+    const prevToolRef = useRef(null);
+    useEffect(() => {
+        const prev = prevToolRef.current;
+        prevToolRef.current = activeTool;
+        if (!prev || prev === activeTool)
+            return;
+        prev.onDeactivate?.(ctxRef.current);
+        activePointerIdRef.current = null;
+        setToolState(undefined);
+        setPreviewPatch(null);
+    }, [activeTool]);
     const dispatchPointerDown = useCallback((event) => {
         if (!activeTool)
             return;
@@ -94,11 +114,15 @@ export const useAnnotationCanvasState = (props) => {
         setToolState(undefined);
     }, [activeTool, ctx, toolState]);
     const dispatchPointerCancel = useCallback(() => {
-        if (activeTool)
-            activeTool.onCancel?.(toolState, ctx);
+        // Clear FIRST, then let the tool react: state updates batch, so a tool
+        // whose onCancel re-emits a preview (the polygon tool keeps its placed
+        // vertices visible across an interrupting two-finger pan) wins over the
+        // clear instead of being clobbered by it.
         activePointerIdRef.current = null;
         setToolState(undefined);
         setPreviewPatch(null);
+        if (activeTool)
+            activeTool.onCancel?.(toolState, ctx);
     }, [activeTool, ctx, toolState]);
     const pan = useCallback((deltaScreen) => {
         setViewport((v) => panBy(v, deltaScreen));

package/dist/annotation/data/hooks/useAnnotationCanvasDoc.js

@@ -16,11 +16,16 @@ const EMPTY_SCOPE = {
 };
 // 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) => ({
+const buildFileData = (fileType, isLabel, canvas, canvasRev) => ({
     fileType,
     ...(isLabel !== undefined ? { isLabel } : {}),
     canvas,
+    canvasRev,
 });
+// Random id for this editing session, used to stamp writes (see canvasRev in
+// AnnotationFileData). Uniqueness only needs to hold across the handful of
+// clients that ever touch one annotation doc.
+const makeClientId = () => `${Date.now().toString(36)}-${Math.floor(Math.random() * 0x100000000).toString(36)}`;
 // 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
@@ -52,10 +57,30 @@ export const useAnnotationCanvasDoc = (options) => {
     const uploadImageRef = useRef(uploadImage);
     // Guards against overlapping thumbnail captures (each save fires one).
     const thumbnailSavingRef = useRef(false);
+    // Set by the public `save()` so the next successful flush refreshes the
+    // thumbnail; debounced autosaves leave it false (capture is too costly to
+    // run mid-session — see captureThumbnail). Consumed (cleared) by each flush
+    // pass that attempts a write, so a failed explicit save drops the request
+    // instead of leaking the capture into some later autosave.
+    const thumbnailRequestedRef = useRef(false);
+    // In-flight capture+upload from the latest flush, so `save()` can await it —
+    // callers that navigate away right after saving must not unmount the view
+    // mid-capture.
+    const thumbnailPromiseRef = useRef(undefined);
     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);
+    // This session's identity + write counter, stamped into `fileData.canvasRev`
+    // on every flush. An incoming snapshot carrying our clientId is the echo of
+    // our own write — state we already hold — and must not be re-applied (doing
+    // so replaces every object identity in the working canvas, busting all
+    // memoization downstream).
+    const clientIdRef = useRef(null);
+    if (clientIdRef.current === null)
+        clientIdRef.current = makeClientId();
+    const writeSeqRef = useRef(0);
+    // Monotonic local-edit counter: bumped on every commit. A flush snapshots it
+    // before writing and compares after, so "did edits land mid-flight?" is an
+    // integer comparison instead of re-serializing the whole document.
+    const editSeqRef = useRef(0);
     workingRef.current = working;
     dataRef.current = data;
     statusRef.current = saveStatus;
@@ -106,7 +131,6 @@ export const useAnnotationCanvasDoc = (options) => {
             timerRef.current = null;
         }
         createdIdRef.current = null;
-        lastSavedJsonRef.current = null;
         setWorking(null);
         setStatus('idle');
     }, [fileId, setStatus]);
@@ -115,24 +139,22 @@ export const useAnnotationCanvasDoc = (options) => {
         // 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)
+        // Ignore the echo of this session's own writes: the doc carries the
+        // canvasRev we stamped, so its content is (at most as new as) what we
+        // already hold. Only a doc written by ANOTHER client is a genuine remote
+        // change worth re-hydrating — which replaces all element identities, so
+        // it must never happen on the routine save → echo round-trip.
+        if (data?.fileData.canvasRev?.clientId === clientIdRef.current)
             return;
-        lastSavedJsonRef.current = incomingJson;
         setWorking(hydrateCanvasState(data, fallbackViewport));
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [data]);
@@ -148,6 +170,17 @@ export const useAnnotationCanvasDoc = (options) => {
         if (!canvas || !scope)
             return;
         const json = JSON.stringify(canvas);
+        // Edits up to this point are covered by this write; anything committed
+        // while the write is in flight bumps editSeqRef past this snapshot.
+        const editSeqAtFlush = editSeqRef.current;
+        // Claim the thumbnail request for THIS pass: honored on success, dropped
+        // on failure (the next explicit save re-requests it).
+        const wantThumbnail = thumbnailRequestedRef.current;
+        thumbnailRequestedRef.current = false;
+        const canvasRev = {
+            clientId: clientIdRef.current,
+            seq: ++writeSeqRef.current,
+        };
         const id = fileIdRef.current ?? createdIdRef.current;
         const mode = id ? 'update' : 'create';
         const debug = debugRef.current;
@@ -167,6 +200,7 @@ export const useAnnotationCanvasDoc = (options) => {
         // rejects undefined field values unless ignoreUndefinedProperties is set.
         const canvasPayload = JSON.parse(json);
         setStatus('saving');
+        let createdThisPass = false;
         try {
             if (!id) {
                 // First save with no file — create the doc seeded with the canvas.
@@ -174,9 +208,10 @@ export const useAnnotationCanvasDoc = (options) => {
                 const newId = await createRef.current({
                     type: FileUploadType.Canvas,
                     ...(seed?.name !== undefined ? { name: seed.name } : {}),
-                    fileData: buildFileData(seed?.fileType ?? 'sketch', seed?.isLabel, canvasPayload),
+                    fileData: buildFileData(seed?.fileType ?? 'sketch', seed?.isLabel, canvasPayload, canvasRev),
                 });
                 createdIdRef.current = newId;
+                createdThisPass = true;
                 if (debug) {
                     console.log('[useAnnotationCanvasDoc] created file', newId);
                 }
@@ -187,22 +222,27 @@ export const useAnnotationCanvasDoc = (options) => {
                 await updateRef.current(id, {
                     fileData: buildFileData(doc?.fileData.fileType ??
                         createSeedRef.current?.fileType ??
-                        'sketch', doc?.fileData.isLabel ?? createSeedRef.current?.isLabel, canvasPayload),
+                        'sketch', doc?.fileData.isLabel ?? createSeedRef.current?.isLabel, canvasPayload, canvasRev),
                 });
                 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).
+            // Refresh the thumbnail when an explicit save() asked for it, or when
+            // this pass CREATED the file — every file gets at least one thumbnail
+            // so the grid never shows a blank tile for a canvas the user drew and
+            // then backed out of without an explicit save. Routine debounced
+            // autosaves skip it: capture means a full view snapshot + encode on the
+            // JS thread, which would jank the very drawing session that triggered
+            // the save. Fire-and-forget for the flush itself; save() awaits the
+            // stashed promise so explicit savers can navigate safely after.
             const savedId = fileIdRef.current ?? createdIdRef.current;
-            if (savedId)
-                void saveThumbnail(savedId);
+            if (savedId && (wantThumbnail || createdThisPass)) {
+                thumbnailPromiseRef.current = 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) {
+            if (editSeqRef.current !== editSeqAtFlush) {
                 setStatus('dirty');
             }
             else {
@@ -239,7 +279,18 @@ export const useAnnotationCanvasDoc = (options) => {
         return flushRunner();
     }, [flushRunner]);
     const onCommit = useCallback((patch) => {
-        setWorking((prev) => (prev ? applyPatch(prev, patch) : prev));
+        editSeqRef.current += 1;
+        setWorking((prev) => {
+            if (!prev)
+                return prev;
+            const next = applyPatch(prev, patch);
+            // Keep the flush snapshot in lockstep with editSeqRef: a flush that
+            // starts before React re-renders must not pair this commit's seq bump
+            // with the pre-commit canvas (it would mark the edit 'saved' without
+            // ever writing it).
+            workingRef.current = next;
+            return next;
+        });
         setStatus('dirty');
         if (timerRef.current)
             clearTimeout(timerRef.current);
@@ -248,6 +299,14 @@ export const useAnnotationCanvasDoc = (options) => {
             void flush();
         }, debounceMs);
     }, [debounceMs, flush, setStatus]);
+    // Explicit save (Save button, "done" actions): also refreshes the file's
+    // thumbnail, which autosaves deliberately skip. Resolves only after the
+    // capture+upload too, so a caller may unmount the view right after.
+    const save = useCallback(async () => {
+        thumbnailRequestedRef.current = true;
+        await flush();
+        await thumbnailPromiseRef.current;
+    }, [flush]);
     const ensureFileId = useCallback(async () => {
         const existing = fileIdRef.current ?? createdIdRef.current;
         if (existing)
@@ -327,7 +386,7 @@ export const useAnnotationCanvasDoc = (options) => {
         loading,
         error,
         saveStatus,
-        save: flush,
+        save,
         ensureFileId,
         setBackgroundImage,
         clearBackgroundImage,

package/dist/exports.d.ts

@@ -18,15 +18,18 @@ export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
 export type { AnnotationCanvasHandle } from './annotation/canvas/useAnnotationCanvasState.js';
 export type { GestureConfig, PanTrigger, AnnotationCanvasInnerProps, } from './annotation/canvas/AnnotationCanvasInner.js';
-export type { CanvasPointerEvent, RequestTextInput, Tool, ToolContext, ToolState, } from './annotation/canvas/Tool.js';
+export type { CanvasPointerEvent, RequestTextInput, ShapeDrawConfig, Tool, ToolContext, ToolState, } from './annotation/canvas/Tool.js';
 export type { MeasurementRef, PickMeasurement, } from './annotation/canvas/measurementPicker.js';
 export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './annotation/canvas/measurementStampOverlay.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './annotation/canvas/viewport.js';
-export { createPenTool, type PenToolOptions } from './annotation/canvas/tools/penTool.js';
+export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, type MeasurementStampToolOptions, } from './annotation/canvas/tools/measurementStampTool.js';
-export { createPanTool, type PanToolOptions } from './annotation/canvas/tools/panTool.js';
+export { createPanTool, type PanToolOptions, } from './annotation/canvas/tools/panTool.js';
 export { createTextTool, type TextToolOptions, } from './annotation/canvas/tools/textTool.js';
+export { createShapeTool, buildShapeFromDrag, type ShapeToolOptions, } from './annotation/canvas/tools/shapeTool.js';
+export { createPolygonTool, type PolygonToolOptions, } from './annotation/canvas/tools/polygonTool.js';
+export { annotationKindFor, hitShapeOutline, shapePointsFromDrag, type ShapeToolKind, } from './annotation/canvas/shapeGeometry.js';
 export { DEFAULT_TEXT_FONT_SIZE, MIN_TEXT_FONT_SIZE, MAX_TEXT_FONT_SIZE, textShapeBounds, textResizeGeometry, type ResizeGeometry, type TextBounds, } from './annotation/canvas/textGeometry.js';
-export { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, normalizeRect, rectCenter, rectCornerPoint, oppositeRectCorner, DEFAULT_LINE_POS, type NormalizedRect, type RectCorner, } from './annotation/canvas/measurementGeometry.js';
+export { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, normalizeRect, rectCenter, rectCornerPoint, oppositeRectCorner, hitPlacedMeasurement, DEFAULT_LINE_POS, type NormalizedRect, type RectCorner, } from './annotation/canvas/measurementGeometry.js';
 export { toSkiaStrokeCap, arrowheadTriangle, arrowheadLength, } from './annotation/canvas/strokeGeometry.js';

package/dist/exports.js

@@ -22,11 +22,14 @@ export { useAnnotationCanvasDoc, } from './annotation/data/hooks/useAnnotationCa
 export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, } from './annotation/canvas/viewport.js';
-export { createPenTool } from './annotation/canvas/tools/penTool.js';
+export { createPenTool, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './annotation/canvas/tools/measurementStampTool.js';
-export { createPanTool } from './annotation/canvas/tools/panTool.js';
+export { createPanTool, } from './annotation/canvas/tools/panTool.js';
 export { createTextTool, } from './annotation/canvas/tools/textTool.js';
+export { createShapeTool, buildShapeFromDrag, } from './annotation/canvas/tools/shapeTool.js';
+export { createPolygonTool, } from './annotation/canvas/tools/polygonTool.js';
+export { annotationKindFor, hitShapeOutline, shapePointsFromDrag, } from './annotation/canvas/shapeGeometry.js';
 export { DEFAULT_TEXT_FONT_SIZE, MIN_TEXT_FONT_SIZE, MAX_TEXT_FONT_SIZE, textShapeBounds, textResizeGeometry, } from './annotation/canvas/textGeometry.js';
-export { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, normalizeRect, rectCenter, rectCornerPoint, oppositeRectCorner, DEFAULT_LINE_POS, } from './annotation/canvas/measurementGeometry.js';
+export { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, normalizeRect, rectCenter, rectCornerPoint, oppositeRectCorner, hitPlacedMeasurement, DEFAULT_LINE_POS, } from './annotation/canvas/measurementGeometry.js';
 export { toSkiaStrokeCap, arrowheadTriangle, arrowheadLength, } from './annotation/canvas/strokeGeometry.js';

package/dist/formulas/calculateFormula.js

@@ -105,9 +105,7 @@ export const calculateFormula = (formula, formulas, columns, tableConfig, measur
     // Validate that all required inputs are filled out
     const missingInputs = [];
     for (const [variable, mapping] of Object.entries(currentMappings)) {
-        const mappingObj = typeof mapping === 'string'
-            ? { id: mapping, type: 'column' }
-            : mapping;
+        const mappingObj = typeof mapping === 'string' ? { id: mapping, type: 'column' } : mapping;
         // Only check column references (formula references are handled separately)
         if (mappingObj.type === 'column' || !mappingObj.type) {
             const columnId = mappingObj.id;

package/dist/types/annotation.d.ts

@@ -26,6 +26,7 @@ export interface AnnotationShapeStyle {
     fontSize?: number;
     fontFamily?: string;
     dash?: boolean;
+    cap?: StrokeCap;
 }
 export interface AnnotationShape {
     id: AnnotationElementId;
@@ -34,6 +35,7 @@ export interface AnnotationShape {
     geometry: {
         points: Vec2[];
         rotation?: number;
+        closed?: boolean;
     };
     style: AnnotationShapeStyle;
     text?: string;

package/dist/types/firestore.d.ts

@@ -113,6 +113,10 @@ export interface AnnotationFileData {
     fileType: 'sketch' | 'document';
     isLabel?: boolean;
     canvas?: AnnotationCanvasState;
+    canvasRev?: {
+        clientId: string;
+        seq: number;
+    };
 }
 export interface CalculatorFileData {
     templateId: string;