@reekon-tools/boldr-utils 1.19.6 → 1.20.1

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

@@ -22,6 +22,7 @@ export interface AnnotationCanvasInnerProps {
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     deferBackgroundToResolver?: boolean;
     hideLinkBadges?: boolean;
+    snapToGeometry?: boolean;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;
     renderBackground?: RenderCanvasBackground;

package/dist/annotation/canvas/AnnotationCanvasInner.js

@@ -6,6 +6,7 @@ import { TEXT_FONT_FAMILY } from './elements/ShapeElement.js';
 import { buildRemoveMeasurementOps, hitPlacedMeasurement, } from './measurementGeometry.js';
 import { useAnnotationCanvasState, } from './useAnnotationCanvasState.js';
 import { stampTileDims } from './stampLayout.js';
+import { SNAP_RING_PX, SNAP_RING_WIDTH_PX } from './snapGeometry.js';
 // Screen-px radius of a measurement-annotation endpoint handle (matches the
 // native HANDLE_RADIUS_PX). Divided by zoom for a constant on-screen size.
 const HANDLE_PX = 7;
@@ -338,6 +339,15 @@ export const AnnotationCanvasInner = (props) => {
                     ? HANDLE_RING_PX / state.viewport.zoom
                     : undefined,
                 showPlaneHandles: activeTool?.planeEditing === true,
+                // Magnetic-snap ring for the JS-path drags (select / measurement /
+                // shape tools report the target through ctx.snap.setIndicator).
+                snapIndicator: state.snapIndicator
+                    ? {
+                        c: state.snapIndicator,
+                        r: SNAP_RING_PX / state.viewport.zoom,
+                        ringWidth: SNAP_RING_WIDTH_PX / state.viewport.zoom,
+                    }
+                    : null,
                 customPreview,
             }), renderMeasurementStamp && (_jsx("div", { style: {
                     position: 'absolute',

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

@@ -23,6 +23,7 @@ export interface AnnotationCanvasInnerProps {
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     deferBackgroundToResolver?: boolean;
     hideLinkBadges?: boolean;
+    snapToGeometry?: boolean;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;
     renderBackground?: RenderCanvasBackground;

package/dist/annotation/canvas/AnnotationCanvasInner.native.js

@@ -11,6 +11,7 @@ import { MIN_BACKGROUND_DOC_EXTENT, backgroundLayersOf, backgroundLayerDocRect,
 import { BackgroundSkImageLoader } from './elements/BackgroundImageElement.js';
 import { buildRemoveMeasurementOps, linePosOf, } from './measurementGeometry.js';
 import { planeEdgeLine, planeGridSegments, planeGridSegmentsForScale, resolvePlaneGridSpacingUm, } from './planeGeometry.js';
+import { SNAP_RADIUS_PX, SNAP_RING_PX, SNAP_RING_WIDTH_PX, collectSnapTargetsFlat, snapDelta, snapNearest, } from './snapGeometry.js';
 import { buildShapeFromDrag } from './tools/shapeTool.js';
 import { SELECTION_PAD } from './textGeometry.js';
 import { useAnnotationCanvasState, } from './useAnnotationCanvasState.js';
@@ -64,7 +65,7 @@ const LOUPE_CROSS_WIDTH_PX = 1.5;
 // is only re-synced once each gesture ends. The tool/tap path still hops to
 // JS (`runOnJS(true)`) since drawing/selection are React-state operations.
 export const AnnotationCanvasInner = (props) => {
-    const { resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, renderBackground, } = props;
+    const { resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, snapToGeometry = false, renderBackground, } = props;
     const valueFont = useFont(stampFontSource, stampValueFontSize);
     // The animated-viewport implementation needs the Reanimated shared values,
     // which are created below AFTER the state hook — so the hook gets a stable
@@ -293,7 +294,10 @@ export const AnnotationCanvasInner = (props) => {
     // owned by the UI thread — the shape twin of `livePoints`. The drag worklet
     // tracks the start/current world points; derived paths below render the
     // live shape. React is untouched until the single commit on release.
-    const liveShape = useSharedValue({ active: false, ax: 0, ay: 0, bx: 0, by: 0 });
+    // `snapR` is the doc-space magnetic-snap radius frozen at press (0 = off)
+    // and `snapped` whether the live end is currently locked onto a target
+    // (drives the snap ring) — see snapGeometry.ts.
+    const liveShape = useSharedValue({ active: false, ax: 0, ay: 0, bx: 0, by: 0, snapR: 0, snapped: false });
     // Released shapes awaiting their committed paint — the shape twin of
     // `handoffStrokes`, with the same lifecycle: appended in the gesture's
     // onEnd worklet tick, released by the paint-watch effect one rAF after the
@@ -317,6 +321,28 @@ export const AnnotationCanvasInner = (props) => {
             width: shapeDraw.width,
         };
     }, [shapeDraw, shapeCfg]);
+    // Magnetic snapping for line endpoints (snapGeometry.ts). `snapCfg` mirrors
+    // the `snapToGeometry` prop for the worklets (derived values and gesture
+    // callbacks are created once and can't close over a changing prop).
+    // `snapTargets` is the flat `[x, y, kind, …]` target buffer, written ONCE
+    // per drag — from JS in beginSelectDrag for endpoint drags (excluding the
+    // grabbed element), and by the effect below for the shape rubber-band,
+    // whose onBegin is a worklet with no doc access. The effect only runs while
+    // a line-kind shape tool is active, so it can never clobber a select drag's
+    // harvest; keyed on the COMMITTED doc so a just-drawn line becomes a target.
+    const snapCfg = useSharedValue({
+        enabled: false,
+        radiusPx: SNAP_RADIUS_PX,
+    });
+    useEffect(() => {
+        snapCfg.value = { enabled: snapToGeometry, radiusPx: SNAP_RADIUS_PX };
+    }, [snapToGeometry, snapCfg]);
+    const snapTargets = useSharedValue([]);
+    useEffect(() => {
+        if (!snapToGeometry || !shapeDraw || shapeDraw.kind !== 'line')
+            return;
+        snapTargets.value = collectSnapTargetsFlat(state.ctx.document);
+    }, [snapToGeometry, shapeDraw, state.ctx.document, snapTargets]);
     // Outline of the live rubber-band + every pending handoff shape, as one
     // stroked path. WORKLET TWIN of shapeGeometry.shapePointsFromDrag +
     // ShapeElement's per-kind rendering — keep in sync. Merging into one path
@@ -456,7 +482,9 @@ export const AnnotationCanvasInner = (props) => {
     // (0 = a, 1 = b) is moving, so the Skia line + overlay tile can be driven on
     // the UI thread from `dragX`/`dragY`.
     const [epDragId, setEpDragId] = useState(null);
-    const epCtx = useSharedValue({ ax: 0, ay: 0, bx: 0, by: 0, t0: 0.5, handle: 0 });
+    // `snapR`: doc-space magnetic-snap radius frozen at grab (0 = off) — see
+    // epLive below and snapGeometry.ts.
+    const epCtx = useSharedValue({ ax: 0, ay: 0, bx: 0, by: 0, t0: 0.5, handle: 0, snapR: 0 });
     const epTargetRef = useRef(null);
     // Endpoint drag of a line/arrow SHAPE (vs. a measurement line above).
     // `shapeEpDragId` (React state) tells the Skia layer to render that shape's
@@ -468,19 +496,32 @@ export const AnnotationCanvasInner = (props) => {
     // Live line endpoints during an endpoint drag: the grabbed handle follows the
     // finger (dragX/dragY); the other stays put. Fed to the Skia <Line> for the
     // dragged annotation.
+    // The grabbed endpoint's live position: base + drag, then magnetically
+    // snapped to the nearest target within epCtx.snapR (0 = off). The SINGLE
+    // source for the live line, the tile overlay's follow math, the loupe
+    // crosshair and the snap ring — and the select gesture's onEnd recomputes
+    // the same snap (snapDelta, same inputs) so the commit matches it exactly.
+    const epLive = useDerivedValue(() => {
+        'worklet';
+        const c = epCtx.value;
+        const mx = (c.handle === 0 ? c.ax : c.bx) + dragX.value;
+        const my = (c.handle === 0 ? c.ay : c.by) + dragY.value;
+        const hit = c.snapR > 0 ? snapNearest(mx, my, snapTargets.value, c.snapR) : null;
+        return hit
+            ? { x: hit.x, y: hit.y, snapped: true }
+            : { x: mx, y: my, snapped: false };
+    });
     const liveLineP1 = useDerivedValue(() => {
         'worklet';
         const c = epCtx.value;
-        return c.handle === 0
-            ? { x: c.ax + dragX.value, y: c.ay + dragY.value }
-            : { x: c.ax, y: c.ay };
+        const e = epLive.value;
+        return c.handle === 0 ? { x: e.x, y: e.y } : { x: c.ax, y: c.ay };
     });
     const liveLineP2 = useDerivedValue(() => {
         'worklet';
         const c = epCtx.value;
-        return c.handle === 1
-            ? { x: c.bx + dragX.value, y: c.by + dragY.value }
-            : { x: c.bx, y: c.by };
+        const e = epLive.value;
+        return c.handle === 1 ? { x: e.x, y: e.y } : { x: c.bx, y: c.by };
     });
     // Screen-constant endpoint handle radius: a fixed pixel size divided by the
     // live zoom (the handles are drawn inside the zoom-scaled world group).
@@ -488,6 +529,45 @@ export const AnnotationCanvasInner = (props) => {
         'worklet';
         return HANDLE_RADIUS_PX / zoom.value;
     });
+    // Snap ring (magnetic endpoint snapping). Three sources, in priority order:
+    // the UI-thread shape rubber-band, the UI-thread endpoint drag (gated off
+    // once the gesture ends or cancels), and the JS-path tools (measurement /
+    // pointer-path drags), whose ctx.snap.setIndicator lands in
+    // state.snapIndicator and is mirrored into a shared value here. Visibility
+    // is an opacity so nothing remounts per frame.
+    const jsSnapIndicator = useSharedValue(null);
+    useEffect(() => {
+        jsSnapIndicator.value = state.snapIndicator;
+    }, [state.snapIndicator, jsSnapIndicator]);
+    const snapIndicatorC = useDerivedValue(() => {
+        'worklet';
+        const sh = liveShape.value;
+        if (sh.active && sh.snapped)
+            return { x: sh.bx, y: sh.by };
+        const e = epLive.value;
+        if (e.snapped && !dragEnded.value)
+            return { x: e.x, y: e.y };
+        const j = jsSnapIndicator.value;
+        return j ? { x: j.x, y: j.y } : { x: 0, y: 0 };
+    });
+    const snapIndicatorOpacity = useDerivedValue(() => {
+        'worklet';
+        const sh = liveShape.value;
+        if (sh.active && sh.snapped)
+            return 1;
+        const e = epLive.value;
+        if (e.snapped && !dragEnded.value)
+            return 1;
+        return jsSnapIndicator.value ? 1 : 0;
+    });
+    const snapRingRadius = useDerivedValue(() => {
+        'worklet';
+        return SNAP_RING_PX / zoom.value;
+    });
+    const snapRingWidth = useDerivedValue(() => {
+        'worklet';
+        return SNAP_RING_WIDTH_PX / zoom.value;
+    });
     const handleRingWidth = useDerivedValue(() => {
         'worklet';
         return HANDLE_RING_PX / zoom.value;
@@ -899,9 +979,9 @@ export const AnnotationCanvasInner = (props) => {
             else if (loupeCrossMode === 'endpoint') {
                 // Measurement-line and shape line/arrow endpoint drags both stage
                 // their line in epCtx; the grabbed end follows the finger.
-                const c = epCtx.value;
-                wx = (c.handle === 0 ? c.ax : c.bx) + dragX.value;
-                wy = (c.handle === 0 ? c.ay : c.by) + dragY.value;
+                const e = epLive.value;
+                wx = e.x;
+                wy = e.y;
             }
             else if (loupeCrossMode === 'rect-corner') {
                 const c = rectCtx.value;
@@ -1402,9 +1482,29 @@ export const AnnotationCanvasInner = (props) => {
                 .maxPointers(1)
                 .onBegin((e) => {
                 'worklet';
-                const wx = e.x / zoom.value + panX.value;
-                const wy = e.y / zoom.value + panY.value;
-                liveShape.value = { active: true, ax: wx, ay: wy, bx: wx, by: wy };
+                let wx = e.x / zoom.value + panX.value;
+                let wy = e.y / zoom.value + panY.value;
+                // Magnetic snap (line tool only): freeze the doc-space radius for
+                // this drag and snap the START point too — the WORKLET counterpart
+                // of shapeTool's snapStateForPress/snapWorld (targets come from the
+                // doc-synced `snapTargets` effect).
+                const snapR = cfg.kind === 'line' && snapCfg.value.enabled
+                    ? snapCfg.value.radiusPx / zoom.value
+                    : 0;
+                const hit = snapR > 0 ? snapNearest(wx, wy, snapTargets.value, snapR) : null;
+                if (hit) {
+                    wx = hit.x;
+                    wy = hit.y;
+                }
+                liveShape.value = {
+                    active: true,
+                    ax: wx,
+                    ay: wy,
+                    bx: wx,
+                    by: wy,
+                    snapR,
+                    snapped: hit !== null,
+                };
                 magTouchX.value = e.x;
                 magTouchY.value = e.y;
                 runOnJS(setMagnifying)(true);
@@ -1416,12 +1516,23 @@ export const AnnotationCanvasInner = (props) => {
                     return;
                 magTouchX.value = e.x;
                 magTouchY.value = e.y;
+                let bx = e.x / zoom.value + panX.value;
+                let by = e.y / zoom.value + panY.value;
+                const hit = s.snapR > 0
+                    ? snapNearest(bx, by, snapTargets.value, s.snapR)
+                    : null;
+                if (hit) {
+                    bx = hit.x;
+                    by = hit.y;
+                }
                 liveShape.value = {
                     active: true,
                     ax: s.ax,
                     ay: s.ay,
-                    bx: e.x / zoom.value + panX.value,
-                    by: e.y / zoom.value + panY.value,
+                    bx,
+                    by,
+                    snapR: s.snapR,
+                    snapped: hit !== null,
                 };
             })
                 .onEnd(() => {
@@ -1434,7 +1545,15 @@ export const AnnotationCanvasInner = (props) => {
                 const dxPx = (s.bx - s.ax) * zoom.value;
                 const dyPx = (s.by - s.ay) * zoom.value;
                 if (dxPx * dxPx + dyPx * dyPx < minDragSq) {
-                    liveShape.value = { active: false, ax: 0, ay: 0, bx: 0, by: 0 };
+                    liveShape.value = {
+                        active: false,
+                        ax: 0,
+                        ay: 0,
+                        bx: 0,
+                        by: 0,
+                        snapR: 0,
+                        snapped: false,
+                    };
                     return;
                 }
                 // Hand off in THIS worklet tick (see the stroke onEnd): the live
@@ -1454,14 +1573,30 @@ export const AnnotationCanvasInner = (props) => {
                         by: s.by,
                     },
                 ];
-                liveShape.value = { active: false, ax: 0, ay: 0, bx: 0, by: 0 };
+                liveShape.value = {
+                    active: false,
+                    ax: 0,
+                    ay: 0,
+                    bx: 0,
+                    by: 0,
+                    snapR: 0,
+                    snapped: false,
+                };
                 runOnJS(commitShape)(id, { x: s.ax, y: s.ay }, { x: s.bx, y: s.by });
             })
                 .onFinalize(() => {
                 'worklet';
                 // Cancel path (no onEnd): drop the in-flight rubber-band. After a
                 // normal end the slot is already inactive, so this is a no-op.
-                liveShape.value = { active: false, ax: 0, ay: 0, bx: 0, by: 0 };
+                liveShape.value = {
+                    active: false,
+                    ax: 0,
+                    ay: 0,
+                    bx: 0,
+                    by: 0,
+                    snapR: 0,
+                    snapped: false,
+                };
                 runOnJS(setMagnifying)(false);
             });
         };
@@ -1487,6 +1622,16 @@ export const AnnotationCanvasInner = (props) => {
                     if (handle) {
                         const m = st.ctx.document.placedMeasurements.find((x) => x.id === selId);
                         if (m?.line) {
+                            // Magnetic snap: harvest every OTHER element's targets once and
+                            // freeze the capture radius in doc space at the grab zoom (the
+                            // JS twin is selectTool's snapStateForGrab). Same JS tick as the
+                            // epCtx write, so both land in the same UI batch.
+                            const snapR = st.ctx.snap?.enabled
+                                ? st.ctx.snap.radiusPx / zoomNow
+                                : 0;
+                            if (snapR > 0) {
+                                snapTargets.value = collectSnapTargetsFlat(st.ctx.document, selId);
+                            }
                             epCtx.value = {
                                 ax: m.line.a.x,
                                 ay: m.line.a.y,
@@ -1494,6 +1639,7 @@ export const AnnotationCanvasInner = (props) => {
                                 by: m.line.b.y,
                                 t0: m.linePos ?? 0.5,
                                 handle: handle === 'a' ? 0 : 1,
+                                snapR,
                             };
                             epTargetRef.current = { id: selId, handle };
                             setEpDragId(selId);
@@ -1509,6 +1655,12 @@ export const AnnotationCanvasInner = (props) => {
                         const a = s?.geometry.points[0];
                         const b = s?.geometry.points[1];
                         if (a && b) {
+                            const snapR = st.ctx.snap?.enabled
+                                ? st.ctx.snap.radiusPx / zoomNow
+                                : 0;
+                            if (snapR > 0) {
+                                snapTargets.value = collectSnapTargetsFlat(st.ctx.document, selId);
+                            }
                             epCtx.value = {
                                 ax: a.x,
                                 ay: a.y,
@@ -1516,6 +1668,7 @@ export const AnnotationCanvasInner = (props) => {
                                 by: b.y,
                                 t0: 0.5,
                                 handle: shapeHandle === 'a' ? 0 : 1,
+                                snapR,
                             };
                             shapeEpTargetRef.current = { id: selId, handle: shapeHandle };
                             setShapeEpDragId(selId);
@@ -1794,6 +1947,10 @@ export const AnnotationCanvasInner = (props) => {
                 dragEnded.value = false;
                 dragX.value = 0;
                 dragY.value = 0;
+                // A stale snap radius from a previous endpoint drag must not bend
+                // a move/slide's delta in onEnd; beginSelectDrag re-arms it below
+                // (queued after this write) when this grab IS an endpoint.
+                epCtx.value = { ...epCtx.value, snapR: 0 };
                 // The loupe (turned on by beginSelectDrag only for precision sub-
                 // drags) follows the live finger, not the hit-test origin.
                 magTouchX.value = e.x;
@@ -1817,12 +1974,27 @@ export const AnnotationCanvasInner = (props) => {
                 .onEnd(() => {
                 'worklet';
                 dragEnded.value = true;
-                runOnJS(endSelectDrag)(dragX.value, dragY.value);
+                let dx = dragX.value;
+                let dy = dragY.value;
+                // Endpoint drag with snapping armed: hand JS the EFFECTIVE delta
+                // (the one landing on the snapped target) — same inputs as epLive,
+                // so the commit matches the live preview and the delta-based patch
+                // builders stay untouched.
+                const c = epCtx.value;
+                if (c.snapR > 0) {
+                    const base = c.handle === 0 ? { x: c.ax, y: c.ay } : { x: c.bx, y: c.by };
+                    const r = snapDelta(base, { x: dx, y: dy }, snapTargets.value, c.snapR);
+                    dx = r.delta.x;
+                    dy = r.delta.y;
+                }
+                runOnJS(endSelectDrag)(dx, dy);
             })
                 .onFinalize(() => {
                 'worklet';
                 if (!dragEnded.value)
                     runOnJS(cancelSelectDrag)();
+                // Also closes the snap-ring gate on the cancel path.
+                dragEnded.value = true;
             });
         };
         // Plane tool: a hybrid pan. Handle drags run on the UI thread (shared
@@ -2022,6 +2194,8 @@ export const AnnotationCanvasInner = (props) => {
         epCtx,
         resizeCtx,
         rectCtx,
+        snapCfg,
+        snapTargets,
     ]);
     const activeTool = props.tools.find((t) => t.id === props.activeToolId) ?? null;
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
@@ -2099,6 +2273,15 @@ export const AnnotationCanvasInner = (props) => {
         shapeEndpointDragId: shapeEpDragId,
         liveLineP1,
         liveLineP2,
+        // Magnetic-snap ring; rides into the loupe pass via the spread below.
+        snapIndicator: snapToGeometry
+            ? {
+                c: snapIndicatorC,
+                r: snapRingRadius,
+                ringWidth: snapRingWidth,
+                opacity: snapIndicatorOpacity,
+            }
+            : null,
         bgCropId,
         liveBgCrop: {
             x: liveBgCropX,
@@ -2157,7 +2340,7 @@ export const AnnotationCanvasInner = (props) => {
     // non-fullscreen canvas (e.g. a diagram strip) escape into surrounding UI.
     _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [backgroundLayers.map((layer) => (_jsx(BackgroundSkImageLoader, { layer: layer, resolveUrl: resolveImageUrl, deferToResolver: deferBackgroundToResolver, onImage: onBackgroundSkImage }, layer.id))), _jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia(skiaProps) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
                         ? (state.measurementsById.get(placed.measurementId) ?? null)
-                        : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, planeEdgeDragging: planeDrag != null && placed.planeId === planeDrag.planeId, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, rectCtx: rectCtx, planeTileCtx: planeTileCtx, planeDragTX: planeDragTX, planeDragTY: planeDragTY, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.tileScaleFactor, headerTileScaleFactor: state.headerTileScaleFactor, fileTileScaleFactor: state.fileTileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
+                        : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, planeEdgeDragging: planeDrag != null && placed.planeId === planeDrag.planeId, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, epLive: epLive, rectCtx: rectCtx, planeTileCtx: planeTileCtx, planeDragTX: planeDragTX, planeDragTY: planeDragTY, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.tileScaleFactor, headerTileScaleFactor: state.headerTileScaleFactor, fileTileScaleFactor: state.fileTileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
                         ? () => {
                             const defaultRemove = () => {
                                 const { ops, keepSelection } = buildRemoveMeasurementOps(placed);
@@ -2184,7 +2367,7 @@ export const AnnotationCanvasInner = (props) => {
                     measurementLineScale: 1 / LOUPE_MAGNIFICATION,
                 }) }))] }));
 };
-const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging, sliding, endpointDragging, rectResizing, zoomSnapshot, zoom, panX, panY, dragX, dragY, slideCtx, epCtx, rectCtx, planeEdgeDragging, planeTileCtx, planeDragTX, planeDragTY, renderMeasurementStamp, tileScaleFactor, headerTileScaleFactor, fileTileScaleFactor, tileViewportScale, onStampPress, onStampLongPress, onRemove, }) => {
+const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging, sliding, endpointDragging, rectResizing, zoomSnapshot, zoom, panX, panY, dragX, dragY, slideCtx, epCtx, epLive, rectCtx, planeEdgeDragging, planeTileCtx, planeDragTX, planeDragTY, renderMeasurementStamp, tileScaleFactor, headerTileScaleFactor, fileTileScaleFactor, tileViewportScale, onStampPress, onStampLongPress, onRemove, }) => {
     // Square tile or wide group-header pill — one footprint source of truth
     // shared with the hit-test (stampTileDims).
     const { width, height } = stampTileDims(placed, tileScaleFactor, tileViewportScale, headerTileScaleFactor ?? tileScaleFactor, fileTileScaleFactor ?? tileScaleFactor);
@@ -2260,13 +2443,15 @@ const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging,
             worldY = c.ay + aby * t;
         }
         else if (endpointDragging) {
-            // Tile stays at its linePos along the LIVE line: fold the drag delta into
-            // the moving endpoint (handle 0 = a, 1 = b), then lerp at t0.
+            // Tile stays at its linePos along the LIVE line: the moving endpoint
+            // (handle 0 = a, 1 = b) comes from epLive — already drag-offset and
+            // magnetically snapped — then lerp at t0.
             const c = epCtx.value;
-            const ax = c.handle === 0 ? c.ax + dragX.value : c.ax;
-            const ay = c.handle === 0 ? c.ay + dragY.value : c.ay;
-            const bx = c.handle === 1 ? c.bx + dragX.value : c.bx;
-            const by = c.handle === 1 ? c.by + dragY.value : c.by;
+            const e = epLive.value;
+            const ax = c.handle === 0 ? e.x : c.ax;
+            const ay = c.handle === 0 ? e.y : c.ay;
+            const bx = c.handle === 1 ? e.x : c.bx;
+            const by = c.handle === 1 ? e.y : c.by;
             worldX = ax + (bx - ax) * c.t0;
             worldY = ay + (by - ay) * c.t0;
         }

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

@@ -111,6 +111,12 @@ export interface AnnotationCanvasSkiaProps {
     handleRingWidth?: number | {
         value: number;
     };
+    snapIndicator?: {
+        c: AnimatedPoint;
+        r: AnimatedNumber;
+        ringWidth: AnimatedNumber;
+        opacity?: AnimatedNumber;
+    } | null;
     showPlaneHandles?: boolean;
     planeDragId?: string | null;
     planeDragIndex?: number | null;
@@ -127,5 +133,5 @@ export interface AnnotationCanvasSkiaProps {
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, bgCropId, liveBgCrop, liveBgCropClip, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale, measurementLineScale, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, bgCropId, liveBgCrop, liveBgCropClip, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, snapIndicator, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale, measurementLineScale, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -30,6 +30,10 @@ const MEASUREMENT_HANDLE_COLOR = '#0066FF';
 // hit-test the text resize handle, which sits on the padded box corner.
 const SELECTION_COLOR = '#0066FF';
 const SELECTION_STROKE = 1.5;
+// Snap ring (magnetic endpoint snapping, see snapGeometry.ts): drawn around
+// the target the dragged endpoint is currently locked onto. Orange so it reads
+// against both the blue selection chrome and the yellow lock accent.
+const SNAP_INDICATOR_COLOR = '#FF7A00';
 // Outline of a selected LOCKED background layer: the lock accent (the same
 // yellow the selected group-header border uses), distinct from the blue
 // manipulable-selection chrome — locked means "selected, but pinned".
@@ -60,6 +64,11 @@ const getLinkedGlyphPath = () => (linkedGlyphPath ?? (linkedGlyphPath = Skia.Pat
 // a solid-colored handle would camouflage into. `c`/`r`/`ringWidth` may be
 // Reanimated values (native live-drag) or plain numbers (web).
 const Handle = ({ c, r, ringWidth, color = MEASUREMENT_HANDLE_COLOR, }) => (_jsxs(_Fragment, { children: [_jsx(Circle, { c: c, r: r, color: "#FFFFFF" }), _jsx(Circle, { c: c, r: r, color: color, style: "stroke", strokeWidth: ringWidth })] }));
+// The snap indicator: a stroke-only ring (NOT a Handle — its white disc would
+// hide the very pixel being snapped to). Screen-constant like the handles;
+// `opacity` lets the native UI-thread path show/hide it without remounting
+// (a zero radius still paints a strokeWidth-sized dot, so radius can't gate it).
+const SnapRing = ({ c, r, ringWidth, opacity = 1, }) => (_jsx(Circle, { c: c, r: r, color: SNAP_INDICATOR_COLOR, style: "stroke", strokeWidth: ringWidth, opacity: opacity }));
 // Bounds of a flat [x,y,x,y,…] stroke point array, or null if empty.
 const strokeBounds = (points) => {
     if (points.length < 2)
@@ -105,7 +114,7 @@ const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElem
 // 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, viewport, resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, bgCropId, liveBgCrop, liveBgCropClip, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale = 1, measurementLineScale = 1, customPreview, wrapContent, canvasRef, }) => {
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, bgCropId, liveBgCrop, liveBgCropClip, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, snapIndicator, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale = 1, measurementLineScale = 1, customPreview, wrapContent, canvasRef, }) => {
     // Doc rect a SCALE-mode plane grid covers: the first background layer (the
     // photo being calibrated), else the document rect. Pinned to layer 0 like
     // the tile-sizing reference — adding a second image must not re-span the
@@ -340,6 +349,6 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                                 corners.map((c, i) => (_jsx(Handle, { c: c, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }, i)))] }));
                 }
                 return null;
-            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), customPreview] }));
+            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), snapIndicator && (_jsx(SnapRing, { c: snapIndicator.c, r: snapIndicator.r, ringWidth: snapIndicator.ringWidth, opacity: snapIndicator.opacity })), customPreview] }));
     return (_jsx(Canvas, { ref: canvasRef, style: { width, height }, children: wrapContent ? wrapContent(world) : world }));
 };

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

@@ -19,6 +19,11 @@ export interface CanvasPointerEvent {
     metaKey?: boolean;
     ctrlKey?: boolean;
 }
+export interface SnapContext {
+    enabled: boolean;
+    radiusPx: number;
+    setIndicator(point: Vec2 | null): void;
+}
 export interface ToolContext {
     document: AnnotationCanvasState;
     selection: Selection | null;
@@ -27,6 +32,7 @@ export interface ToolContext {
     tileScaleFactor: number;
     headerTileScaleFactor: number;
     fileTileScaleFactor: number;
+    snap?: SnapContext | null;
     preview(patch: AnnotationDocumentPatch): void;
     commit(patch: AnnotationDocumentPatch): void;
     setSelection(selection: Selection | null): void;

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

@@ -0,0 +1,32 @@
+import type { AnnotationCanvasState, AnnotationElementId, Vec2 } from '../../types/annotation.js';
+export declare const SNAP_RADIUS_PX = 16;
+export declare const SNAP_RING_PX = 11;
+export declare const SNAP_RING_WIDTH_PX = 2;
+export declare const SNAP_KIND_POINT = 0;
+export declare const SNAP_KIND_MIDPOINT = 1;
+export type SnapKind = 0 | 1;
+export declare const SNAP_STRIDE = 3;
+export interface SnapTarget {
+    x: number;
+    y: number;
+    kind: SnapKind;
+    sourceId: AnnotationElementId;
+}
+export interface SnapHit {
+    x: number;
+    y: number;
+    kind: SnapKind;
+    index: number;
+}
+export declare const collectSnapTargets: (doc: AnnotationCanvasState, excludeId?: AnnotationElementId | null) => SnapTarget[];
+export declare const encodeSnapTargets: (targets: readonly SnapTarget[]) => number[];
+export declare const collectSnapTargetsFlat: (doc: AnnotationCanvasState, excludeId?: AnnotationElementId | null) => number[];
+export declare const snapNearest: (x: number, y: number, flat: readonly number[], radiusDoc: number) => SnapHit | null;
+export declare const snapDelta: (base: Vec2, delta: Vec2, flat: readonly number[], radiusDoc: number) => {
+    delta: Vec2;
+    hit: SnapHit | null;
+};
+export declare const snapPoint: (p: Vec2, flat: readonly number[], radiusDoc: number) => {
+    point: Vec2;
+    hit: SnapHit | null;
+};

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/dist/types/firestore.d.ts

@@ -96,6 +96,7 @@ export interface Template extends Timestamps {
     formulas?: Formula[];
     sharedOrgIds?: string[];
     starred?: boolean;
+    thumbnailUrl?: string;
 }
 export interface SelectedTemplate extends FirestoreDoc {
     count: number;

package/package.json

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