@reekon-tools/boldr-utils 1.6.12 → 1.6.14

package/dist/annotation/data/coalescedRunner.js

@@ -0,0 +1,48 @@
+// A single-flight async runner with trailing coalescing.
+//
+// Wraps an async `task` so that overlapping callers don't run it concurrently
+// and don't drop work:
+//   • While a run is in flight, every additional call returns that same
+//     in-flight promise (single-flight) instead of starting a second run.
+//   • If any call arrives during a run, exactly ONE trailing run is scheduled
+//     after the current one finishes — so work that arrived mid-run is never
+//     lost. The trailing run re-invokes `task`, which is expected to re-read the
+//     latest state each time (it takes no arguments by design).
+//   • The returned promise resolves only once the chain is fully drained, so an
+//     `await`-ing caller can rely on all queued work having completed.
+//   • A task rejection is propagated to the awaiting callers of that run but
+//     does NOT wedge the runner: `inFlight` is always cleared, and a pending
+//     trailing run still fires, so the runner self-heals after a transient
+//     failure.
+//
+// This is the concurrency primitive behind the annotation autosave/flush: it
+// guarantees a create-on-first-save can't race a concurrent flush (the old
+// boolean-guard approach silently dropped the second writer).
+export const createCoalescedRunner = (task) => {
+    let inFlight = null;
+    let pending = false;
+    const run = () => {
+        if (inFlight) {
+            // A run is already underway — remember that more work arrived and join
+            // the in-flight promise rather than starting a second concurrent run.
+            pending = true;
+            return inFlight;
+        }
+        inFlight = (async () => {
+            try {
+                await task();
+            }
+            finally {
+                inFlight = null;
+                if (pending) {
+                    // Work arrived mid-run: drain it with a single trailing run, which
+                    // re-reads the latest state. Recurses until quiescent.
+                    pending = false;
+                    await run();
+                }
+            }
+        })();
+        return inFlight;
+    };
+    return run;
+};

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

@@ -3,6 +3,7 @@ import { applyPatch, createEmptyCanvasState, } from '../../../types/annotation.j
 import { FileUploadType } from '../../../types/firestore.js';
 import { useAnnotationDoc } from './useAnnotationDoc.js';
 import { useAnnotationMutations } from './useAnnotationMutations.js';
+import { createCoalescedRunner } from '../coalescedRunner.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
@@ -15,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
@@ -51,12 +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);
-    // Guards against two creates racing if flushes overlap.
-    const creatingRef = useRef(false);
+    // 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;
@@ -107,7 +131,6 @@ export const useAnnotationCanvasDoc = (options) => {
             timerRef.current = null;
         }
         createdIdRef.current = null;
-        lastSavedJsonRef.current = null;
         setWorking(null);
         setStatus('idle');
     }, [fileId, setStatus]);
@@ -116,39 +139,48 @@ 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]);
-    const flush = useCallback(async () => {
-        if (timerRef.current) {
-            clearTimeout(timerRef.current);
-            timerRef.current = null;
-        }
+    // One pass of the persist logic: snapshots the latest working state and
+    // creates-or-updates the doc. NOT called directly — it runs through the
+    // single-flight `flush` below, which guarantees two passes never overlap (so
+    // a create-on-first-save can't race a concurrent flush) and re-invokes this
+    // to drain any work that arrived mid-pass. Because it re-reads `workingRef`
+    // each call, a trailing pass always persists the newest canvas.
+    const runFlush = useCallback(async () => {
         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);
+        // 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;
@@ -168,18 +200,18 @@ 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.
-                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),
+                    fileData: buildFileData(seed?.fileType ?? 'sketch', seed?.isLabel, canvasPayload, canvasRev),
                 });
-                creatingRef.current = false;
                 createdIdRef.current = newId;
+                createdThisPass = true;
                 if (debug) {
                     console.log('[useAnnotationCanvasDoc] created file', newId);
                 }
@@ -190,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 {
@@ -213,16 +250,47 @@ export const useAnnotationCanvasDoc = (options) => {
             }
         }
         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');
+            // Swallowed (not re-thrown): autosave/unmount call this fire-and-forget,
+            // and the canvas keeps working from local state. Callers that need to know
+            // a create succeeded (ensureFileId) detect it via the absence of an id
+            // after the flush drains, not via a rejection.
         }
     }, [scope, setStatus, saveThumbnail]);
+    // Stable indirection so the coalesced runner (created once) always calls the
+    // latest `runFlush` without being re-created when its deps change.
+    const runFlushRef = useRef(runFlush);
+    runFlushRef.current = runFlush;
+    // Single-flight runner: concurrent callers join the in-flight pass; work that
+    // arrives mid-pass triggers exactly one trailing pass. Created once.
+    const flushRunner = useMemo(() => createCoalescedRunner(() => runFlushRef.current()), []);
+    // Public flush: cancel any pending debounce, then run (or join) a persist
+    // pass. Resolves once the chain is fully drained, so `await flush()` is safe
+    // for create-before-upload and explicit Save.
+    const flush = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        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);
@@ -231,12 +299,24 @@ 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)
             return existing;
-        // No file yet — seed an empty canvas if nothing has hydrated, then flush
-        // so the existing create branch mints the doc.
+        // No file yet — seed an empty canvas if nothing has hydrated, then flush so
+        // the create branch mints the doc. `flush` is single-flight: if the
+        // debounced autosave is already creating, this call JOINS that create and
+        // waits for it to drain (rather than racing it and dropping the upload, the
+        // old bug). After the drain, the id is present unless the create truly
+        // failed — so the throw below is now a genuine error, not a race.
         if (!workingRef.current) {
             const seeded = createEmptyCanvasState(fallbackViewport);
             workingRef.current = seeded;
@@ -306,7 +386,7 @@ export const useAnnotationCanvasDoc = (options) => {
         loading,
         error,
         saveStatus,
-        save: flush,
+        save,
         ensureFileId,
         setBackgroundImage,
         clearBackgroundImage,

package/dist/exports.d.ts

@@ -18,13 +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, 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 { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, DEFAULT_LINE_POS, } from './annotation/canvas/measurementGeometry.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, 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,9 +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 { recomputeAnchor, projectToLinePos, snapLinePos, lerp, lineLength, placementOf, linePosOf, DEFAULT_LINE_POS, } from './annotation/canvas/measurementGeometry.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, 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

@@ -13,6 +13,7 @@ export interface AnnotationStroke {
     color: string;
     width: number;
     cap?: StrokeCap;
+    dash?: boolean;
     points: number[];
     pressure?: number[];
     createdAt: number;
@@ -24,6 +25,8 @@ export interface AnnotationShapeStyle {
     strokeWidth?: number;
     fontSize?: number;
     fontFamily?: string;
+    dash?: boolean;
+    cap?: StrokeCap;
 }
 export interface AnnotationShape {
     id: AnnotationElementId;
@@ -32,6 +35,7 @@ export interface AnnotationShape {
     geometry: {
         points: Vec2[];
         rotation?: number;
+        closed?: boolean;
     };
     style: AnnotationShapeStyle;
     text?: string;
@@ -51,9 +55,14 @@ export interface PlacedMeasurementRef {
         b: Vec2;
     };
     linePos?: number;
+    rect?: {
+        a: Vec2;
+        b: Vec2;
+    };
     lineColor?: string;
     lineWidth?: number;
     lineCap?: StrokeCap;
+    lineDash?: boolean;
     leader?: {
         from: Vec2;
         to: Vec2;

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;

package/package.json

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