@reekon-tools/boldr-utils 1.19.5 → 1.20.0

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

@@ -7,10 +7,11 @@ import Animated, { runOnJS, runOnUI, useAnimatedStyle, useDerivedValue, useShare
 import { stampTileDims } from './stampLayout.js';
 import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
-import { backgroundLayersOf, backgroundLayerDocRect, } from './backgroundLayers.js';
+import { MIN_BACKGROUND_DOC_EXTENT, backgroundLayersOf, backgroundLayerDocRect, backgroundLayerFullDocRect, } from './backgroundLayers.js';
 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, 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;
@@ -661,6 +741,9 @@ export const AnnotationCanvasInner = (props) => {
     // goes through buildResizePatch, which clamps identically.
     const [resizingId, setResizingId] = useState(null);
     const resizeCtx = useSharedValue({ px: 0, py: 0, hx: 0, hy: 0, minS: 1, maxS: 1 });
+    // The grab-start geometry rides along to the commit: a background offers
+    // four corner handles, each scaling about its opposite corner, so the patch
+    // must reuse whichever geometry the grab's hit-test chose.
     const resizeTargetRef = useRef(null);
     const resizeTransform = useDerivedValue(() => {
         'worklet';
@@ -684,6 +767,60 @@ export const AnnotationCanvasInner = (props) => {
             { translateY: -c.py },
         ];
     });
+    // Background crop-bar drag. `bgCropId` (React state) gates which layer
+    // clips to the live rect; `bgCropCtx` carries the grabbed edge (0 top ·
+    // 1 bottom · 2 left · 3 right), the visible doc rect at grab-start and the
+    // full (uncropped) image's doc rect it may expand back out to — so the
+    // preview is a pure UI-thread rect rebuild driven by dragX/dragY. The
+    // commit on release goes through buildBackgroundCropPatch, which clamps
+    // identically.
+    const [bgCropId, setBgCropId] = useState(null);
+    const bgCropTargetRef = useRef(null);
+    const bgCropCtx = useSharedValue({ edge: 0, x: 0, y: 0, w: 0, h: 0, bx: 0, by: 0, bw: 0, bh: 0 });
+    const liveBgCropRect = useDerivedValue(() => {
+        'worklet';
+        // WORKLET TWIN of selectTool's cropDragVisibleRect — keep in sync.
+        const c = bgCropCtx.value;
+        let x = c.x;
+        let y = c.y;
+        let w = c.w;
+        let h = c.h;
+        if (c.edge === 0) {
+            const newY = Math.min(Math.max(c.y + dragY.value, c.by), c.y + c.h - MIN_BACKGROUND_DOC_EXTENT);
+            h = c.y + c.h - newY;
+            y = newY;
+        }
+        else if (c.edge === 1) {
+            h = Math.min(Math.max(c.h + dragY.value, MIN_BACKGROUND_DOC_EXTENT), c.by + c.bh - c.y);
+        }
+        else if (c.edge === 2) {
+            const newX = Math.min(Math.max(c.x + dragX.value, c.bx), c.x + c.w - MIN_BACKGROUND_DOC_EXTENT);
+            w = c.x + c.w - newX;
+            x = newX;
+        }
+        else {
+            w = Math.min(Math.max(c.w + dragX.value, MIN_BACKGROUND_DOC_EXTENT), c.bx + c.bw - c.x);
+        }
+        return { x, y, width: w, height: h };
+    });
+    // Per-component slices for the live outline (Skia props take one animated
+    // value each; the clip takes the whole rect).
+    const liveBgCropX = useDerivedValue(() => {
+        'worklet';
+        return liveBgCropRect.value.x;
+    });
+    const liveBgCropY = useDerivedValue(() => {
+        'worklet';
+        return liveBgCropRect.value.y;
+    });
+    const liveBgCropW = useDerivedValue(() => {
+        'worklet';
+        return liveBgCropRect.value.width;
+    });
+    const liveBgCropH = useDerivedValue(() => {
+        'worklet';
+        return liveBgCropRect.value.height;
+    });
     // Geometric-shape corner resize (rect/ellipse/polygon). `shapeResizeId`
     // (React state) gates which shape renders live; `shapeResizeCtx` carries the
     // fixed (opposite) corner and the grabbed corner's start position (from
@@ -842,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;
@@ -1345,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);
@@ -1359,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(() => {
@@ -1377,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
@@ -1397,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);
             });
         };
@@ -1430,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,
@@ -1437,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);
@@ -1452,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,
@@ -1459,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);
@@ -1477,11 +1687,42 @@ export const AnnotationCanvasInner = (props) => {
                             minS: resizeGeom.minScale,
                             maxS: resizeGeom.maxScale,
                         };
-                        resizeTargetRef.current = { id: selId };
+                        resizeTargetRef.current = { id: selId, geom: resizeGeom };
                         setResizingId(selId);
                         setMagnifying(true);
                         return;
                     }
+                    // Crop bar on a selected, unlocked background layer — the edge
+                    // windows the image (non-destructively) instead of scaling it.
+                    const cropEdge = cfg.hitTestBackgroundCropBar?.(st.ctx.document, selId, world, zoomNow);
+                    if (cropEdge) {
+                        const cropLayer = backgroundLayersOf(st.ctx.document.viewport).find((l) => l.id === selId);
+                        if (cropLayer) {
+                            const visible = backgroundLayerDocRect(cropLayer);
+                            const full = backgroundLayerFullDocRect(cropLayer);
+                            bgCropCtx.value = {
+                                edge: cropEdge === 'top'
+                                    ? 0
+                                    : cropEdge === 'bottom'
+                                        ? 1
+                                        : cropEdge === 'left'
+                                            ? 2
+                                            : 3,
+                                x: visible.x,
+                                y: visible.y,
+                                w: visible.width,
+                                h: visible.height,
+                                bx: full.x,
+                                by: full.y,
+                                bw: full.width,
+                                bh: full.height,
+                            };
+                            bgCropTargetRef.current = { id: selId, edge: cropEdge };
+                            setBgCropId(selId);
+                            setMagnifying(true);
+                            return;
+                        }
+                    }
                     // Rectangle-annotation corner handle — also selected-element-only.
                     const rectCornerHit = cfg.hitTestRectCorner?.(st.ctx.document, selId, world, zoomNow);
                     if (rectCornerHit) {
@@ -1580,10 +1821,7 @@ export const AnnotationCanvasInner = (props) => {
                 const rT = resizeTargetRef.current;
                 if (rT) {
                     if (dx !== 0 || dy !== 0) {
-                        const patch = cfg.buildResizePatch?.(st.ctx.document, rT.id, {
-                            x: dx,
-                            y: dy,
-                        });
+                        const patch = cfg.buildResizePatch?.(st.ctx.document, rT.id, { x: dx, y: dy }, rT.geom);
                         if (patch)
                             st.ctx.commit(patch);
                     }
@@ -1591,6 +1829,19 @@ export const AnnotationCanvasInner = (props) => {
                     setResizingId(null);
                     return;
                 }
+                // Crop commit: window the layer to the live rect's final edges
+                // (clamped in buildBackgroundCropPatch exactly like the live preview).
+                const cropT = bgCropTargetRef.current;
+                if (cropT) {
+                    if (dx !== 0 || dy !== 0) {
+                        const patch = cfg.buildBackgroundCropPatch?.(st.ctx.document, cropT.id, cropT.edge, { x: dx, y: dy });
+                        if (patch)
+                            st.ctx.commit(patch);
+                    }
+                    bgCropTargetRef.current = null;
+                    setBgCropId(null);
+                    return;
+                }
                 // Rect-corner commit: drag the grabbed corner by the world delta
                 // (opposite corner fixed); anchor re-centers in the same patch.
                 const rectT = rectTargetRef.current;
@@ -1678,6 +1929,7 @@ export const AnnotationCanvasInner = (props) => {
                 resizeTargetRef.current = null;
                 rectTargetRef.current = null;
                 shapeResizeTargetRef.current = null;
+                bgCropTargetRef.current = null;
                 setDraggingId(null);
                 setSlidingId(null);
                 setEpDragId(null);
@@ -1685,6 +1937,7 @@ export const AnnotationCanvasInner = (props) => {
                 setResizingId(null);
                 setRectDragId(null);
                 setShapeResizeId(null);
+                setBgCropId(null);
             };
             return Gesture.Pan()
                 .minPointers(1)
@@ -1694,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;
@@ -1717,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
@@ -1922,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);
@@ -1950,6 +2224,7 @@ export const AnnotationCanvasInner = (props) => {
         worldTransform,
         resolveImageUrl,
         deferBackgroundToResolver,
+        hideLinkBadges,
         backgroundSkImages,
         // Shared with the loupe overlay below (it re-runs this same scene through a
         // magnifying transform), so the lens shows the substrate magnified instead
@@ -1998,6 +2273,23 @@ 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,
+            y: liveBgCropY,
+            width: liveBgCropW,
+            height: liveBgCropH,
+        },
+        liveBgCropClip: liveBgCropRect,
         rectDragId,
         liveRect: {
             x: liveRectX,
@@ -2048,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);
@@ -2075,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);
@@ -2151,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

@@ -24,6 +24,7 @@ export interface AnnotationCanvasSkiaProps {
     viewport?: ViewportState;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     deferBackgroundToResolver?: boolean;
+    hideLinkBadges?: boolean;
     backgroundSkImages?: Record<string, SkImage | null>;
     backgroundContent?: ReactNode;
     valueFont: SkFont | null;
@@ -74,6 +75,26 @@ export interface AnnotationCanvasSkiaProps {
         width: AnimatedNumber;
         height: AnimatedNumber;
     };
+    bgCropId?: string | null;
+    liveBgCrop?: {
+        x: AnimatedNumber;
+        y: AnimatedNumber;
+        width: AnimatedNumber;
+        height: AnimatedNumber;
+    };
+    liveBgCropClip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | {
+        value: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
     shapeResizeId?: string | null;
     shapeResizePath?: SkPath | {
         value: SkPath;
@@ -90,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;
@@ -106,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, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, 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 {};