@reekon-tools/boldr-utils 1.19.6 → 1.20.0

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;
+};