@reekon-tools/boldr-utils 1.19.6 → 1.20.0

package/dist/annotation/canvas/snapGeometry.js

@@ -0,0 +1,168 @@
+// Magnetic snapping for line endpoints (Asana 1217966180270874). While an
+// endpoint of a measurement line (`placement: 'line'`) or a line/arrow shape is
+// being placed or dragged, it snaps to nearby geometry: other lines' endpoints
+// and midpoints, polygon/rect vertices, and measurement-rectangle corners.
+// Skia-free, safe in tools, hit-tests and unit tests.
+//
+// `snapNearest`/`snapDelta` carry 'worklet' directives: the native Inner calls
+// them per frame on the UI thread (the live endpoint derived values and the
+// shape rubber-band gesture) — the same mechanism planeGeometry's grid
+// generators rely on. Keep them free of closures over non-worklet module
+// functions (numeric constants are fine) so the workletizer can lift them.
+//
+// Targets travel to the UI thread as a FLAT number array (`[x, y, kind, …]`,
+// stride SNAP_STRIDE) written once per drag — see `encodeSnapTargets`.
+import { placementOf, normalizeRect } from './measurementGeometry.js';
+// Screen-px capture radius: the grabbed endpoint jumps to a target once it is
+// within this many pixels of it. Converted to doc space via `/ zoom` at drag
+// begin (frozen for the drag, like the slide detent's SLIDE_SNAP_PX).
+export const SNAP_RADIUS_PX = 16;
+// Screen-px radius / ring width of the snap indicator drawn around the target
+// while a snap is active. Larger than the endpoint handle (HANDLE_RADIUS_PX 7)
+// so the ring frames the handle instead of hiding under it.
+export const SNAP_RING_PX = 11;
+export const SNAP_RING_WIDTH_PX = 2;
+// Target kinds, ordered by priority: on an exact distance tie the LOWER kind
+// wins, so a true endpoint/vertex beats a midpoint sitting on the same pixel.
+export const SNAP_KIND_POINT = 0;
+export const SNAP_KIND_MIDPOINT = 1;
+// Flat encoding stride: [x, y, kind].
+export const SNAP_STRIDE = 3;
+// Every snap target in the document, in doc space. `excludeId` drops the
+// element being edited ENTIRELY (its endpoints and midpoint) — snapping a
+// line's endpoint onto its own other end would collapse it, and onto its own
+// midpoint would halve it. Targets:
+//  - measurement `placement:'line'`: a, b (point) + midpoint. Plane-edge
+//    tiles included — their endpoints are real geometry even though the
+//    select tool refuses to drag them.
+//  - measurement `placement:'rectangle'`: the four normalized corners.
+//  - shape line/arrow: both endpoints + midpoint.
+//  - shape rect: the four normalized corners (stored as two opposite corners).
+//  - shape polygon (triangles included): every vertex.
+//  - ellipse, text, strokes, backgrounds: nothing.
+// Degenerate (zero-length) lines contribute their coincident endpoints but no
+// midpoint.
+export const collectSnapTargets = (doc, excludeId) => {
+    const out = [];
+    const point = (p, sourceId) => out.push({ x: p.x, y: p.y, kind: SNAP_KIND_POINT, sourceId });
+    const segment = (a, b, sourceId) => {
+        point(a, sourceId);
+        point(b, sourceId);
+        if (a.x !== b.x || a.y !== b.y) {
+            out.push({
+                x: (a.x + b.x) / 2,
+                y: (a.y + b.y) / 2,
+                kind: SNAP_KIND_MIDPOINT,
+                sourceId,
+            });
+        }
+    };
+    const corners = (r, sourceId) => {
+        const n = normalizeRect(r);
+        point({ x: n.minX, y: n.minY }, sourceId);
+        point({ x: n.maxX, y: n.minY }, sourceId);
+        point({ x: n.maxX, y: n.maxY }, sourceId);
+        point({ x: n.minX, y: n.maxY }, sourceId);
+    };
+    for (const m of doc.placedMeasurements) {
+        if (excludeId != null && m.id === excludeId)
+            continue;
+        const placement = placementOf(m);
+        if (placement === 'line' && m.line)
+            segment(m.line.a, m.line.b, m.id);
+        else if (placement === 'rectangle' && m.rect)
+            corners(m.rect, m.id);
+    }
+    for (const s of doc.shapes) {
+        if (excludeId != null && s.id === excludeId)
+            continue;
+        const pts = s.geometry.points;
+        switch (s.kind) {
+            case 'line':
+            case 'arrow': {
+                const [a, b] = pts;
+                if (a && b)
+                    segment(a, b, s.id);
+                break;
+            }
+            case 'rect': {
+                const [a, b] = pts;
+                if (a && b)
+                    corners({ a, b }, s.id);
+                break;
+            }
+            case 'polygon':
+                for (const p of pts)
+                    point(p, s.id);
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+};
+// Flat `[x, y, kind, …]` buffer for UI-thread transfer (a plain number[],
+// like the freehand `livePoints` — TypedArrays aren't proven shareable here).
+export const encodeSnapTargets = (targets) => {
+    const flat = new Array(targets.length * SNAP_STRIDE);
+    for (let i = 0; i < targets.length; i++) {
+        const t = targets[i];
+        flat[i * SNAP_STRIDE] = t.x;
+        flat[i * SNAP_STRIDE + 1] = t.y;
+        flat[i * SNAP_STRIDE + 2] = t.kind;
+    }
+    return flat;
+};
+export const collectSnapTargetsFlat = (doc, excludeId) => encodeSnapTargets(collectSnapTargets(doc, excludeId));
+// Nearest target to (x, y) within `radiusDoc` (inclusive), or null. Ties on
+// distance go to the lower kind (point beats midpoint); remaining ties to the
+// earlier target. `radiusDoc <= 0` disables snapping. Worklet-callable.
+export const snapNearest = (x, y, flat, radiusDoc) => {
+    'worklet';
+    if (radiusDoc <= 0)
+        return null;
+    const r2 = radiusDoc * radiusDoc;
+    let bestD2 = Infinity;
+    let bestKind = Infinity;
+    let bestIdx = -1;
+    for (let i = 0; i + 2 < flat.length; i += 3) {
+        const dx = flat[i] - x;
+        const dy = flat[i + 1] - y;
+        const d2 = dx * dx + dy * dy;
+        if (d2 > r2)
+            continue;
+        const kind = flat[i + 2];
+        if (d2 < bestD2 || (d2 === bestD2 && kind < bestKind)) {
+            bestD2 = d2;
+            bestKind = kind;
+            bestIdx = i;
+        }
+    }
+    if (bestIdx < 0)
+        return null;
+    return {
+        x: flat[bestIdx],
+        y: flat[bestIdx + 1],
+        kind: flat[bestIdx + 2] === 1 ? 1 : 0,
+        index: bestIdx / 3,
+    };
+};
+// Snap a DRAG: `base` is the grabbed endpoint's committed position and `delta`
+// the raw world-space drag offset. Returns the effective delta that lands the
+// endpoint exactly on the nearest target (or the raw delta when nothing is in
+// range), so the existing delta-based patch builders stay untouched. Worklet-
+// callable — the native select gesture runs it in onEnd so the commit matches
+// the live preview bit-for-bit.
+export const snapDelta = (base, delta, flat, radiusDoc) => {
+    'worklet';
+    const hit = snapNearest(base.x + delta.x, base.y + delta.y, flat, radiusDoc);
+    if (!hit)
+        return { delta, hit: null };
+    return { delta: { x: hit.x - base.x, y: hit.y - base.y }, hit };
+};
+// Snap an ABSOLUTE point (drag-to-create tools place raw world points).
+export const snapPoint = (p, flat, radiusDoc) => {
+    'worklet';
+    const hit = snapNearest(p.x, p.y, flat, radiusDoc);
+    return hit ? { point: { x: hit.x, y: hit.y }, hit } : { point: p, hit: null };
+};

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

@@ -1,5 +1,6 @@
 import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
 import { DEFAULT_LINE_POS, recomputeAnchor, rectCenter, } from '../measurementGeometry.js';
+import { collectSnapTargetsFlat, snapPoint } from '../snapGeometry.js';
 // The `line*` style fields for a placed measurement, built from the tool's
 // style options. Undefined fields are dropped (never emitted) so the render
 // defaults apply and Firestore never sees an `undefined` value.
@@ -22,6 +23,25 @@ const lineStyleFields = (placement, style) => {
     }
     return out;
 };
+// Snap state for a fresh line press. The new annotation isn't in the doc yet,
+// so nothing needs excluding. Empty when snapping is off.
+const snapStateForPress = (ctx, placement) => placement === 'line' && ctx.snap?.enabled
+    ? {
+        snap: {
+            targets: collectSnapTargetsFlat(ctx.document),
+            radiusDoc: ctx.snap.radiusPx / ctx.viewport.state.zoom,
+        },
+    }
+    : {};
+// The world point a drag end should use: snapped when a target is in range.
+// Reports the target (or null) to the indicator.
+const snapEnd = (s, ctx, world) => {
+    if (!s.snap)
+        return world;
+    const r = snapPoint(world, s.snap.targets, s.snap.radiusDoc);
+    ctx.snap?.setIndicator(r.hit ? { x: r.hit.x, y: r.hit.y } : null);
+    return r.point;
+};
 let counter = 0;
 const makeId = () => `annotation-${Date.now().toString(36)}-${(counter++).toString(36)}`;
 const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
@@ -130,13 +150,21 @@ export const createMeasurementTool = (options = {}) => {
         id: options.id ?? defaultId,
         label: options.label ?? defaultLabel,
         cursor: 'crosshair',
-        onPointerDown(event) {
+        onPointerDown(event, ctx) {
+            const snap = snapStateForPress(ctx, placement);
+            // The START of a new line snaps too (a leader that begins exactly on a
+            // corner is the point of the feature); the ring flashes there until the
+            // first move re-evaluates it against the moving end.
+            const startWorld = snap.snap
+                ? snapPoint(event.world, snap.snap.targets, snap.snap.radiusDoc).point
+                : event.world;
             return {
                 kind: 'measurement-drawing',
                 id: makeId(),
-                startWorld: event.world,
+                startWorld,
                 startScreen: event.screen,
                 moved: false,
+                ...snap,
             };
         },
         onPointerMove(event, ctx, state) {
@@ -149,7 +177,7 @@ export const createMeasurementTool = (options = {}) => {
                 placement,
                 linePos,
                 a: s.startWorld,
-                b: event.world,
+                b: snapEnd(s, ctx, event.world),
                 style,
                 valueSource: valueSourceFor(ctx),
             });
@@ -160,6 +188,7 @@ export const createMeasurementTool = (options = {}) => {
             const s = state;
             if (s?.kind !== 'measurement-drawing')
                 return;
+            ctx.snap?.setIndicator(null);
             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) {
@@ -167,18 +196,23 @@ export const createMeasurementTool = (options = {}) => {
                 ctx.preview({ ops: [] });
                 return;
             }
+            // Same snap as the last move, so the commit equals the preview.
+            const b = s.snap
+                ? snapPoint(event.world, s.snap.targets, s.snap.radiusDoc).point
+                : event.world;
             place(ctx, buildMeasurement({
                 id: s.id,
                 layerId: firstLayerId(ctx.document),
                 placement,
                 linePos,
                 a: s.startWorld,
-                b: event.world,
+                b,
                 style,
                 valueSource: valueSourceFor(ctx),
             }));
         },
         onCancel(_state, ctx) {
+            ctx.snap?.setIndicator(null);
             ctx.preview({ ops: [] });
         },
     };

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

@@ -2,6 +2,7 @@ import { MAX_BACKGROUND_DOC_EXTENT, MIN_BACKGROUND_DOC_EXTENT, backgroundCropBar
 import { stampTileDims } from '../stampLayout.js';
 import { placementOf, linePosOf, snapLinePos, lerp, recomputeAnchor, rectCenter, rectCornerPoint, oppositeRectCorner, hitPlacedMeasurement, } from '../measurementGeometry.js';
 import { hitShapeOutline, visualShapeBounds } from '../shapeGeometry.js';
+import { collectSnapTargetsFlat, snapDelta } from '../snapGeometry.js';
 import { DEFAULT_TEXT_FONT_SIZE, resizeScaleFromDrag, textResizeGeometry, textShapeBounds, } from '../textGeometry.js';
 import { editTextShape } from './textEditing.js';
 const HIT_PADDING = 6;
@@ -238,6 +239,32 @@ const slidePatch = (doc, id, delta, zoom) => {
         ops: [{ op: 'updateMeasurement', id, patch: { linePos: t, anchor } }],
     };
 };
+// Committed position of the grabbed endpoint — the base the drag delta (and
+// the snap) is measured from. Measurement lines keep endpoints on `line.a/b`,
+// shape lines on `geometry.points[0/1]`.
+const endpointBase = (doc, id, elementKind, handle) => {
+    if (elementKind === 'shape') {
+        const sh = doc.shapes.find((x) => x.id === id);
+        const p = sh?.geometry.points[handle === 'a' ? 0 : 1];
+        return p ?? null;
+    }
+    const m = doc.placedMeasurements.find((x) => x.id === id);
+    if (!m?.line)
+        return null;
+    return handle === 'a' ? m.line.a : m.line.b;
+};
+// Snap bookkeeping for an endpoint grab: harvest every OTHER element's targets
+// once (ctx.document is the committed doc, so in-flight previews never leak
+// in) and freeze the capture radius in doc space at the grab zoom. Empty when
+// snapping is off, so the drag stays a plain delta.
+const snapStateForGrab = (ctx, excludeId, zoom) => ctx.snap?.enabled
+    ? {
+        snap: {
+            targets: collectSnapTargetsFlat(ctx.document, excludeId),
+            radiusDoc: ctx.snap.radiusPx / zoom,
+        },
+    }
+    : {};
 // Which endpoint handle of a (selected) line annotation is under `world`.
 // Prefers the nearer endpoint when both are within range.
 const findHandleHit = (doc, id, world, zoom) => {
@@ -777,6 +804,7 @@ export const createSelectTool = (options = {}) => ({
                     handle,
                     start: world,
                     delta: { x: 0, y: 0 },
+                    ...snapStateForGrab(ctx, selId, zoom),
                 };
             }
             const shapeHandle = findShapeHandleHit(ctx.document, selId, world, zoom);
@@ -790,6 +818,7 @@ export const createSelectTool = (options = {}) => ({
                     handle: shapeHandle,
                     start: world,
                     delta: { x: 0, y: 0 },
+                    ...snapStateForGrab(ctx, selId, zoom),
                 };
             }
             const resizeGeom = findResizeHandleHit(ctx.document, selId, world, zoom);
@@ -935,7 +964,7 @@ export const createSelectTool = (options = {}) => ({
         }
         if (s?.kind !== 'dragging')
             return s;
-        const delta = {
+        let delta = {
             x: event.world.x - s.start.x,
             y: event.world.y - s.start.y,
         };
@@ -945,12 +974,24 @@ export const createSelectTool = (options = {}) => ({
             pendingTextEditId = null;
             pendingBackgroundDeselectId = null;
         }
+        // Magnetic endpoint snap: bend the delta so the grabbed end lands on the
+        // nearest target in range, and show the ring there. The snapped delta is
+        // what gets stored, so onPointerUp's commit reuses it unchanged.
+        if (s.mode === 'endpoint' && s.snap && s.handle) {
+            const base = endpointBase(ctx.document, s.id, s.elementKind, s.handle);
+            if (base) {
+                const r = snapDelta(base, delta, s.snap.targets, s.snap.radiusDoc);
+                delta = r.delta;
+                ctx.snap?.setIndicator(r.hit ? { x: r.hit.x, y: r.hit.y } : null);
+            }
+        }
         const patch = dragPatch(s, ctx.document, delta, ctx.viewport.state.zoom);
         if (patch)
             ctx.preview(patch);
         return { ...s, delta };
     },
     onPointerUp(_event, ctx, state) {
+        ctx.snap?.setIndicator(null);
         const editId = pendingTextEditId;
         pendingTextEditId = null;
         const deselectId = pendingBackgroundDeselectId;
@@ -984,6 +1025,7 @@ export const createSelectTool = (options = {}) => ({
     onCancel(_state, ctx) {
         pendingTextEditId = null;
         pendingBackgroundDeselectId = null;
+        ctx.snap?.setIndicator(null);
         ctx.preview({ ops: [] });
     },
     hitTest(element, p) {

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

@@ -1,5 +1,15 @@
 import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
 import { annotationKindFor, shapePointsFromDrag, } from '../shapeGeometry.js';
+import { collectSnapTargetsFlat, snapPoint } from '../snapGeometry.js';
+const snapStateForPress = (ctx, kind) => kind === 'line' && ctx.snap?.enabled
+    ? {
+        snap: {
+            targets: collectSnapTargetsFlat(ctx.document),
+            radiusDoc: ctx.snap.radiusPx / ctx.viewport.state.zoom,
+        },
+    }
+    : {};
+const snapWorld = (s, world) => s.snap ? snapPoint(world, s.snap.targets, s.snap.radiusDoc) : null;
 let counter = 0;
 const makeId = (prefix) => `${prefix}-${Date.now().toString(36)}-${(counter++).toString(36)}`;
 const DEFAULT_LABELS = {
@@ -61,12 +71,14 @@ export const createShapeTool = (options = {}) => {
             dash,
         },
         onPointerDown(event, ctx) {
+            const snap = snapStateForPress(ctx, kind);
+            const startWorld = snapWorld(snap, event.world)?.point ?? event.world;
             return {
                 kind: 'shape-drawing',
                 shape: buildShapeFromDrag({
                     kind,
-                    a: event.world,
-                    b: event.world,
+                    a: startWorld,
+                    b: startWorld,
                     color,
                     width,
                     cap,
@@ -74,22 +86,28 @@ export const createShapeTool = (options = {}) => {
                     dash,
                     layerId: firstLayerId(ctx.document),
                 }),
-                startWorld: event.world,
+                startWorld,
                 startScreen: event.screen,
                 moved: false,
+                ...snap,
             };
         },
         onPointerMove(event, ctx, state) {
             const s = state;
             if (s?.kind !== 'shape-drawing')
                 return s;
+            const snapped = snapWorld(s, event.world);
+            if (s.snap) {
+                ctx.snap?.setIndicator(snapped?.hit ? { x: snapped.hit.x, y: snapped.hit.y } : null);
+            }
+            const end = snapped?.point ?? event.world;
             const next = {
                 ...s,
                 moved: true,
                 shape: {
                     ...s.shape,
                     geometry: {
-                        points: shapePointsFromDrag(kind, s.startWorld, event.world),
+                        points: shapePointsFromDrag(kind, s.startWorld, end),
                     },
                 },
             };
@@ -100,6 +118,7 @@ export const createShapeTool = (options = {}) => {
             const s = state;
             if (s?.kind !== 'shape-drawing')
                 return;
+            ctx.snap?.setIndicator(null);
             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) {
@@ -107,15 +126,18 @@ export const createShapeTool = (options = {}) => {
                 ctx.preview({ ops: [] });
                 return;
             }
+            // Same snap as the last move, so the commit equals the preview.
+            const end = snapWorld(s, event.world)?.point ?? event.world;
             const shape = {
                 ...s.shape,
                 geometry: {
-                    points: shapePointsFromDrag(kind, s.startWorld, event.world),
+                    points: shapePointsFromDrag(kind, s.startWorld, end),
                 },
             };
             ctx.commit({ ops: [{ op: 'addShape', shape }] });
         },
         onCancel(_state, ctx) {
+            ctx.snap?.setIndicator(null);
             ctx.preview({ ops: [] });
         },
     };

package/dist/annotation/canvas/useAnnotationCanvasState.d.ts

@@ -64,6 +64,7 @@ export interface UseAnnotationCanvasStateProps {
     measurements?: Measurement[];
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;
+    snapToGeometry?: boolean;
     width: number;
     height: number;
     initialViewport?: ViewportState;
@@ -94,6 +95,7 @@ export interface AnnotationCanvasStateApi {
     fileTileScaleFactor: number;
     penDrawingStroke: AnnotationStroke | null;
     customPreviewState: ToolState;
+    snapIndicator: Vec2 | null;
     dispatchPointerDown(event: CanvasPointerEvent): void;
     dispatchPointerMove(event: CanvasPointerEvent): void;
     dispatchPointerUp(event: CanvasPointerEvent): void;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, resolveTileScaleFactor, stampTileDims, STAMP_TILE_SIZE, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
+import { SNAP_RADIUS_PX } from './snapGeometry.js';
 import { createViewportApi, fitRectToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './viewport.js';
 import { computeZoomFloor, pdfFirstPageDocRect } from './pdfDocument.js';
 import { backgroundLayerDocRect, backgroundLayersOf, backgroundLayersUnionRect, } from './backgroundLayers.js';
@@ -113,7 +114,7 @@ const defaultLeaderLenDoc = (docWidth) => Math.min(800, Math.max(240, docWidth *
 // inners share this hook; each wraps it with platform-specific event
 // capture and JSX (div + DOM events vs. GestureDetector + RN Views).
 export const useAnnotationCanvasState = (props) => {
-    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
+    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, snapToGeometry, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
     const [viewport, setViewport] = useState(initialViewport ?? DEFAULT_VIEWPORT);
     const [toolState, setToolState] = useState(undefined);
     // Synchronous mirror for the DISPATCHERS. The native tap gesture
@@ -128,6 +129,8 @@ export const useAnnotationCanvasState = (props) => {
         toolStateRef.current = next;
         setToolState(next);
     };
+    // Snap ring position for JS-path drags (see AnnotationCanvasStateApi).
+    const [snapIndicator, setSnapIndicator] = useState(null);
     const [previewPatch, setPreviewPatch] = useState(null);
     const undoStackRef = useRef([]);
     const redoStackRef = useRef([]);
@@ -228,6 +231,11 @@ export const useAnnotationCanvasState = (props) => {
         tileScaleFactor,
         headerTileScaleFactor,
         fileTileScaleFactor,
+        snap: {
+            enabled: snapToGeometry === true,
+            radiusPx: SNAP_RADIUS_PX,
+            setIndicator: setSnapIndicator,
+        },
         preview(patch) {
             setPreviewPatch(patch);
         },
@@ -328,6 +336,7 @@ export const useAnnotationCanvasState = (props) => {
         onSelectionChange,
         pickMeasurement,
         requestTextInput,
+        snapToGeometry,
     ]);
     // Live ctx for imperative handle methods (which are created in an effect and
     // would otherwise capture a stale ctx/viewport).
@@ -353,6 +362,7 @@ export const useAnnotationCanvasState = (props) => {
         activePointerIdRef.current = null;
         updateToolState(undefined);
         setPreviewPatch(null);
+        setSnapIndicator(null);
         // updateToolState is a stable-in-effect helper (ref + setState); the
         // effect only re-runs on a tool identity change.
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -390,6 +400,9 @@ export const useAnnotationCanvasState = (props) => {
         activeTool.onPointerUp?.(event, ctx, toolStateRef.current);
         activePointerIdRef.current = null;
         updateToolState(undefined);
+        // Belt-and-braces: tools clear their own ring on release, but a tool
+        // that forgets must not leave a stale ring on the canvas.
+        setSnapIndicator(null);
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [activeTool, ctx]);
@@ -410,6 +423,7 @@ export const useAnnotationCanvasState = (props) => {
         const prevToolState = toolStateRef.current;
         updateToolState(undefined);
         setPreviewPatch(null);
+        setSnapIndicator(null);
         if (activeTool)
             activeTool.onCancel?.(prevToolState, ctx);
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -903,6 +917,7 @@ export const useAnnotationCanvasState = (props) => {
         fileTileScaleFactor,
         penDrawingStroke,
         customPreviewState: toolState,
+        snapIndicator,
         dispatchPointerDown,
         dispatchPointerMove,
         dispatchPointerUp,

package/dist/exports.d.ts

@@ -28,7 +28,7 @@ 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, ShapeDrawConfig, Tool, ToolContext, ToolState, } from './annotation/canvas/Tool.js';
+export type { CanvasPointerEvent, RequestTextInput, ShapeDrawConfig, Tool, ToolContext, SnapContext, ToolState, } from './annotation/canvas/Tool.js';
 export type { FileRef, MeasurementRef, PickMeasurement, } from './annotation/canvas/measurementPicker.js';
 export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './annotation/canvas/measurementStampOverlay.js';
 export type { CanvasBackgroundSlotArgs, RenderCanvasBackground, } from './annotation/canvas/backgroundSlot.js';
@@ -52,3 +52,4 @@ export { annotationKindFor, hitShapeOutline, shapePointsFromDrag, type ShapeTool
 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';
+export { SNAP_RADIUS_PX, SNAP_RING_PX, SNAP_RING_WIDTH_PX, SNAP_KIND_POINT, SNAP_KIND_MIDPOINT, SNAP_STRIDE, collectSnapTargets, collectSnapTargetsFlat, encodeSnapTargets, snapNearest, snapDelta, snapPoint, type SnapHit, type SnapKind, type SnapTarget, } from './annotation/canvas/snapGeometry.js';

package/dist/exports.js

@@ -56,3 +56,4 @@ export { annotationKindFor, hitShapeOutline, shapePointsFromDrag, } from './anno
 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';
+export { SNAP_RADIUS_PX, SNAP_RING_PX, SNAP_RING_WIDTH_PX, SNAP_KIND_POINT, SNAP_KIND_MIDPOINT, SNAP_STRIDE, collectSnapTargets, collectSnapTargetsFlat, encodeSnapTargets, snapNearest, snapDelta, snapPoint, } from './annotation/canvas/snapGeometry.js';

package/package.json

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

package/dist/canvas/AnnotationCanvas.d.ts

@@ -1,11 +0,0 @@
-import { type ReactNode } from 'react';
-import type { AnnotationCanvasInnerProps } from './AnnotationCanvasInner.js';
-export type { AnnotationCanvasHandle, GestureConfig, PanTrigger, } from './AnnotationCanvasInner.js';
-export interface CanvasKitOpts {
-    locateFile?: (file: string) => string;
-}
-export type AnnotationCanvasProps = AnnotationCanvasInnerProps & {
-    fallback?: ReactNode;
-    canvasKitOpts?: CanvasKitOpts;
-};
-export declare const AnnotationCanvas: ({ fallback, canvasKitOpts, ...rest }: AnnotationCanvasProps) => import("react/jsx-runtime").JSX.Element;

package/dist/canvas/AnnotationCanvas.js

@@ -1,10 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { WithSkiaWeb } from '@shopify/react-native-skia/lib/module/web/index.js';
-// Web-only entry point: lazy-loads CanvasKit wasm via WithSkiaWeb. Imperative
-// API (undo/redo/zoom) is exposed through the `imperativeRef` prop rather
-// than React refs, since WithSkiaWeb can't forward refs through its lazy
-// component boundary. The native build sits in `AnnotationCanvas.native.tsx`
-// and skips WithSkiaWeb entirely (no wasm to load).
-export const AnnotationCanvas = ({ fallback, canvasKitOpts, ...rest }) => (_jsx(WithSkiaWeb, { getComponent: () => import('./AnnotationCanvasInner.js').then((m) => ({
-        default: m.AnnotationCanvasInner,
-    })), fallback: fallback ?? null, componentProps: rest, opts: canvasKitOpts }));

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

@@ -1,8 +0,0 @@
-import type { AnnotationCanvasInnerProps } from './AnnotationCanvasInner.native.js';
-export type { AnnotationCanvasHandle, } from './useAnnotationCanvasState.js';
-export type { GestureConfig, PanTrigger, } from './AnnotationCanvasInner.js';
-export type AnnotationCanvasProps = AnnotationCanvasInnerProps & {
-    fallback?: unknown;
-    canvasKitOpts?: unknown;
-};
-export declare const AnnotationCanvas: (props: AnnotationCanvasProps) => import("react/jsx-runtime").JSX.Element;

package/dist/canvas/AnnotationCanvas.native.js

@@ -1,6 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { AnnotationCanvasInner } from './AnnotationCanvasInner.native.js';
-export const AnnotationCanvas = (props) => {
-    const { fallback: _f, canvasKitOpts: _o, ...rest } = props;
-    return _jsx(AnnotationCanvasInner, { ...rest });
-};

package/dist/canvas/AnnotationCanvasInner.d.ts

@@ -1,39 +0,0 @@
-import { type CSSProperties, type MutableRefObject } from 'react';
-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';
-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;
-    onCommit(patch: AnnotationDocumentPatch): void;
-    tools: Tool[];
-    activeToolId: string;
-    selection: Selection | null;
-    onSelectionChange(selection: Selection | null): void;
-    measurements?: Measurement[];
-    fallbackUnit?: Units;
-    fractionalTolerance?: FractionalTolerance;
-    decimalTolerance?: DecimalTolerance;
-    resolveImageUrl?: (storagePath: string) => Promise<string>;
-    pickMeasurement?: () => Promise<MeasurementRef | null>;
-    renderMeasurementStamp?: RenderMeasurementStamp;
-    stampFontSource?: unknown;
-    stampValueFontSize?: number;
-    stampLabelFontSize?: number;
-    gestures?: GestureConfig;
-    width: number;
-    height: number;
-    initialViewport?: ViewportState;
-    style?: CSSProperties;
-    imperativeRef?: MutableRefObject<AnnotationCanvasHandle | null>;
-}
-export type PanTrigger = 'middleMouse' | 'rightMouse' | 'space';
-export interface GestureConfig {
-    wheel?: 'zoom' | 'pan' | 'auto';
-    panTriggers?: PanTrigger[];
-}
-export declare const AnnotationCanvasInner: (props: AnnotationCanvasInnerProps) => import("react/jsx-runtime").JSX.Element;