@reekon-tools/boldr-utils 1.19.5 → 1.20.0

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

@@ -1,7 +1,8 @@
-import { backgroundLayerDocRect, backgroundLayerIsLocked, backgroundLayersOf, isBackgroundLayerLocked, } from '../backgroundLayers.js';
+import { MAX_BACKGROUND_DOC_EXTENT, MIN_BACKGROUND_DOC_EXTENT, backgroundCropBars, backgroundLayerDocRect, backgroundLayerFullDocRect, backgroundLayerIsLocked, backgroundLayersOf, isBackgroundLayerLocked, } from '../backgroundLayers.js';
 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) => {
@@ -468,12 +495,8 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
 // other, but never moves or scales:
 // the drag/resize hit-tests below refuse it, and a gesture on it behaves like
 // empty canvas (pan) while leaving the selection in place. ---
-// Doc-space clamp on a resized background's larger doc dimension. The floor
-// keeps a corner drag from collapsing a layer below grabbable size; the
-// ceiling keeps the doc rect (which feeds fit math and the web SVG raster
-// planner) from exploding to numerically silly sizes.
-const MIN_BACKGROUND_DOC_EXTENT = 16;
-const MAX_BACKGROUND_DOC_EXTENT = 65536;
+// Doc-space size clamps live in backgroundLayers.ts (the native crop preview
+// worklet shares the floor).
 const backgroundLayerById = (doc, id) => backgroundLayersOf(doc.viewport).find((l) => l.id === id) ?? null;
 const pointInBackgroundLayer = (layer, p) => {
     const r = backgroundLayerDocRect(layer);
@@ -511,19 +534,30 @@ const findSelectedBackgroundHit = (doc, world, selectedIds) => {
     }
     return null;
 };
-// Corner-scale geometry for a background layer: pivot = the doc rect's
-// top-left — the layer's transform origin, so scaling about it multiplies
-// scaleX/scaleY while x/y stay put — and handle = the EXACT bottom-right
-// corner (the selection chrome draws it un-padded, unlike the padded text
-// box; the grab tolerance lives in the hit radius, not the geometry).
-const backgroundResizeGeometry = (layer) => {
+// Corner-scale geometry for a background layer: handle = the grabbed corner
+// of its VISIBLE (cropped) doc rect, pivot = the opposite corner, which stays
+// put — so the patch scales scaleX/scaleY AND repositions transform.x/y about
+// the pivot (unlike text, whose top-left anchor is always the pivot). The
+// chrome draws all four handles un-padded on the exact rect corners; the grab
+// tolerance lives in the hit radius, not the geometry.
+const BACKGROUND_RESIZE_CORNERS = [
+    'tl',
+    'tr',
+    'bl',
+    'br',
+];
+const backgroundResizeGeometry = (layer, corner) => {
     const r = backgroundLayerDocRect(layer);
     const maxDim = Math.max(r.width, r.height);
     if (!(maxDim > 0))
         return null;
+    const cornerPoint = (c) => ({
+        x: c === 'tl' || c === 'bl' ? r.x : r.x + r.width,
+        y: c === 'tl' || c === 'tr' ? r.y : r.y + r.height,
+    });
     return {
-        pivot: { x: r.x, y: r.y },
-        handle: { x: r.x + r.width, y: r.y + r.height },
+        pivot: cornerPoint(oppositeRectCorner(corner)),
+        handle: cornerPoint(corner),
         minScale: MIN_BACKGROUND_DOC_EXTENT / maxDim,
         maxScale: MAX_BACKGROUND_DOC_EXTENT / maxDim,
     };
@@ -532,41 +566,51 @@ const backgroundResizeGeometry = (layer) => {
 // native UI-thread drag via DragSelectionConfig AND the web pointer handlers) ---
 // Resize geometry when the (selected) text shape's or background layer's
 // corner handle is under `world`, else null. A text handle sits on the padded
-// selection box's bottom-right corner, a background handle on its exact doc
-// rect corner (see AnnotationCanvasSkia); grab radius matches the measurement
-// endpoint handles either way.
+// selection box's bottom-right corner; a background offers all FOUR exact doc
+// rect corners, each scaling about its opposite (see AnnotationCanvasSkia);
+// grab radius matches the measurement endpoint handles either way.
 const findResizeHandleHit = (doc, id, world, zoom) => {
+    const r2 = (HANDLE_GRAB_PX / zoom) ** 2;
+    const within = (geom) => {
+        const dx = world.x - geom.handle.x;
+        const dy = world.y - geom.handle.y;
+        return dx * dx + dy * dy <= r2;
+    };
     const s = doc.shapes.find((x) => x.id === id);
-    // A locked background cannot scale, so its corner offers no handle (the
+    if (s) {
+        const geom = textResizeGeometry(s);
+        return geom && within(geom) ? geom : null;
+    }
+    // A locked background cannot scale, so its corners offer no handles (the
     // chrome draws none either — see AnnotationCanvasSkia).
-    const layer = s || isBackgroundLayerLocked(doc.viewport, id)
-        ? null
-        : backgroundLayerById(doc, id);
-    const geom = s
-        ? textResizeGeometry(s)
-        : layer
-            ? backgroundResizeGeometry(layer)
-            : null;
-    if (!geom)
+    if (isBackgroundLayerLocked(doc.viewport, id))
         return null;
-    const r2 = (HANDLE_GRAB_PX / zoom) ** 2;
-    const dx = world.x - geom.handle.x;
-    const dy = world.y - geom.handle.y;
-    return dx * dx + dy * dy <= r2 ? geom : null;
+    const layer = backgroundLayerById(doc, id);
+    if (!layer)
+        return null;
+    for (const corner of BACKGROUND_RESIZE_CORNERS) {
+        const geom = backgroundResizeGeometry(layer, corner);
+        if (geom && within(geom))
+            return geom;
+    }
+    return null;
 };
 // Scale the element by the drag (clamped to the geometry's scale range, so it
-// matches the native live preview exactly). The pivot is untouched: a text
-// shape keeps its anchor and bakes the scale into fontSize; a background keeps
-// transform.x/y — its top-left IS the scale pivot — and bakes the scale into
-// scaleX/scaleY (both axes, so the aspect ratio is preserved even on layers
-// synthesized from a legacy 'stretch' fit).
-const resizePatch = (doc, id, delta) => {
+// matches the native live preview exactly). A text shape keeps its top-left
+// anchor (the pivot) and bakes the scale into fontSize. A background scales
+// uniformly about `geom.pivot` — the corner OPPOSITE the grabbed one — so
+// scaleX/scaleY multiply AND transform.x/y move to keep the pivot fixed
+// (both axes scale together, preserving the aspect ratio even on layers
+// synthesized from a legacy 'stretch' fit). `geom` is the grab-start geometry
+// the hit-test chose; without it (defensive) the bottom-right corner's
+// geometry is assumed, which reproduces the pre-four-corner behavior.
+const resizePatch = (doc, id, delta, grabGeom) => {
     const s = doc.shapes.find((x) => x.id === id);
     if (!s) {
         const layer = backgroundLayerById(doc, id);
         if (!layer || isBackgroundLayerLocked(doc.viewport, id))
             return null;
-        const geom = backgroundResizeGeometry(layer);
+        const geom = grabGeom ?? backgroundResizeGeometry(layer, 'br');
         if (!geom)
             return null;
         const scale = resizeScaleFromDrag(geom, delta);
@@ -577,7 +621,8 @@ const resizePatch = (doc, id, delta) => {
                     id,
                     patch: {
                         transform: {
-                            ...layer.transform,
+                            x: geom.pivot.x + (layer.transform.x - geom.pivot.x) * scale,
+                            y: geom.pivot.y + (layer.transform.y - geom.pivot.y) * scale,
                             scaleX: layer.transform.scaleX * scale,
                             scaleY: layer.transform.scaleY * scale,
                         },
@@ -597,6 +642,82 @@ const resizePatch = (doc, id, delta) => {
         ],
     };
 };
+// --- Background crop (the four edge bars on a selected, unlocked layer) ----
+// Which crop bar of the given (selected) background layer is under `world`,
+// or null. Bars exist only on an unlocked RASTER layer (an SVG layer's
+// doc-rect math — the web rasterizer — never sees a crop). The bar rect is
+// the drawn gizmo (backgroundCropBars) padded by the standard screen-constant
+// grab tolerance.
+const findBackgroundCropBarHit = (doc, id, world, zoom) => {
+    if (isBackgroundLayerLocked(doc.viewport, id))
+        return null;
+    const layer = backgroundLayerById(doc, id);
+    if (!layer || layer.format === 'svg')
+        return null;
+    const pad = HANDLE_GRAB_PX / zoom;
+    for (const bar of backgroundCropBars(layer)) {
+        if (world.x >= bar.x - pad &&
+            world.x <= bar.x + bar.width + pad &&
+            world.y >= bar.y - pad &&
+            world.y <= bar.y + bar.height + pad) {
+            return bar.edge;
+        }
+    }
+    return null;
+};
+// New VISIBLE doc rect for a crop-bar drag: the grabbed edge follows the
+// delta, clamped so the rect never leaves the full image's bounds (dragging
+// back out un-crops — the bytes were never touched) and never collapses below
+// the same doc-extent floor a corner resize enforces. The native live-preview
+// worklet in AnnotationCanvasInner.native.tsx is a WORKLET TWIN of this math
+// — keep them in sync.
+export const cropDragVisibleRect = (start, full, edge, delta) => {
+    let { x, y, width, height } = start;
+    if (edge === 'top') {
+        const newY = Math.min(Math.max(start.y + delta.y, full.y), start.y + start.height - MIN_BACKGROUND_DOC_EXTENT);
+        height = start.y + start.height - newY;
+        y = newY;
+    }
+    else if (edge === 'bottom') {
+        height = Math.min(Math.max(start.height + delta.y, MIN_BACKGROUND_DOC_EXTENT), full.y + full.height - start.y);
+    }
+    else if (edge === 'left') {
+        const newX = Math.min(Math.max(start.x + delta.x, full.x), start.x + start.width - MIN_BACKGROUND_DOC_EXTENT);
+        width = start.x + start.width - newX;
+        x = newX;
+    }
+    else {
+        width = Math.min(Math.max(start.width + delta.x, MIN_BACKGROUND_DOC_EXTENT), full.x + full.width - start.x);
+    }
+    return { x, y, width, height };
+};
+// Patch that commits a crop-bar drag: the new visible rect (clamped exactly
+// like the live preview) converted back to an intrinsic-pixel crop window.
+const backgroundCropPatch = (doc, id, edge, delta) => {
+    const layer = backgroundLayerById(doc, id);
+    if (!layer || isBackgroundLayerLocked(doc.viewport, id))
+        return null;
+    const { scaleX, scaleY } = layer.transform;
+    if (!(scaleX > 0) || !(scaleY > 0))
+        return null;
+    const visible = cropDragVisibleRect(backgroundLayerDocRect(layer), backgroundLayerFullDocRect(layer), edge, delta);
+    return {
+        ops: [
+            {
+                op: 'updateBackgroundImage',
+                id,
+                patch: {
+                    crop: {
+                        x: (visible.x - layer.transform.x) / scaleX,
+                        y: (visible.y - layer.transform.y) / scaleY,
+                        width: visible.width / scaleX,
+                        height: visible.height / scaleY,
+                    },
+                },
+            },
+        ],
+    };
+};
 // Patch for the current drag mode (web pointer path), from a world-space delta.
 const dragPatch = (s, doc, delta, zoom) => {
     if (s.mode === 'endpoint' && s.handle) {
@@ -609,7 +730,10 @@ const dragPatch = (s, doc, delta, zoom) => {
     if (s.mode === 'slide')
         return slidePatch(doc, s.id, delta, zoom);
     if (s.mode === 'resize')
-        return resizePatch(doc, s.id, delta);
+        return resizePatch(doc, s.id, delta, s.geom);
+    if (s.mode === 'bg-crop' && s.cropEdge) {
+        return backgroundCropPatch(doc, s.id, s.cropEdge, delta);
+    }
     if (s.mode === 'rect-corner' && s.corner) {
         return rectCornerPatch(doc, s.id, s.corner, delta);
     }
@@ -643,6 +767,8 @@ export const createSelectTool = (options = {}) => ({
         buildResizePatch: resizePatch,
         hitTestBackground: findBackgroundHit,
         hitTestSelectedBackground: findSelectedBackgroundHit,
+        hitTestBackgroundCropBar: findBackgroundCropBarHit,
+        buildBackgroundCropPatch: backgroundCropPatch,
         hitTestRectCorner: findRectCornerHit,
         buildRectCornerPatch: rectCornerPatch,
         hitTestShapeCorner: findShapeCornerHit,
@@ -678,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);
@@ -691,9 +818,11 @@ export const createSelectTool = (options = {}) => ({
                     handle: shapeHandle,
                     start: world,
                     delta: { x: 0, y: 0 },
+                    ...snapStateForGrab(ctx, selId, zoom),
                 };
             }
-            if (findResizeHandleHit(ctx.document, selId, world, zoom)) {
+            const resizeGeom = findResizeHandleHit(ctx.document, selId, world, zoom);
+            if (resizeGeom) {
                 return {
                     kind: 'dragging',
                     id: selId,
@@ -704,6 +833,22 @@ export const createSelectTool = (options = {}) => ({
                         ? 'background'
                         : 'shape',
                     mode: 'resize',
+                    // The grabbed corner's geometry — a background scales about the
+                    // OPPOSITE corner, so the patch must reuse what the grab chose.
+                    geom: resizeGeom,
+                    start: world,
+                    delta: { x: 0, y: 0 },
+                };
+            }
+            // Crop bar on a selected, unlocked background layer.
+            const cropEdge = findBackgroundCropBarHit(ctx.document, selId, world, zoom);
+            if (cropEdge) {
+                return {
+                    kind: 'dragging',
+                    id: selId,
+                    elementKind: 'background',
+                    mode: 'bg-crop',
+                    cropEdge,
                     start: world,
                     delta: { x: 0, y: 0 },
                 };
@@ -819,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,
         };
@@ -829,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;
@@ -868,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([]);
@@ -194,7 +197,9 @@ export const useAnnotationCanvasState = (props) => {
     // equals the measurement factor (resolveHeaderTileScaleFactor's fallback) —
     // the pre-split one-knob behavior.
     let headerTileScaleFactor = resolveHeaderTileScaleFactor(effectiveCanvas, tileScalePlatformResolved);
-    // Object tiles: the third knob, same fallback (Asana 1217570500895545).
+    // Object tiles share the measurement factor — their own knob was retired
+    // (see resolveFileTileScaleFactor), so this always equals tileScaleFactor
+    // and rides the same calibration below.
     let fileTileScaleFactor = resolveFileTileScaleFactor(effectiveCanvas, tileScalePlatformResolved);
     if (tileScalePlatformResolved === 'mobile' &&
         effectiveCanvas.tileScaleFactorMobile == null &&
@@ -226,6 +231,11 @@ export const useAnnotationCanvasState = (props) => {
         tileScaleFactor,
         headerTileScaleFactor,
         fileTileScaleFactor,
+        snap: {
+            enabled: snapToGeometry === true,
+            radiusPx: SNAP_RADIUS_PX,
+            setIndicator: setSnapIndicator,
+        },
         preview(patch) {
             setPreviewPatch(patch);
         },
@@ -326,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).
@@ -351,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
@@ -388,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]);
@@ -408,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
@@ -901,6 +917,7 @@ export const useAnnotationCanvasState = (props) => {
         fileTileScaleFactor,
         penDrawingStroke,
         customPreviewState: toolState,
+        snapIndicator,
         dispatchPointerDown,
         dispatchPointerMove,
         dispatchPointerUp,

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

@@ -429,7 +429,11 @@ export const useAnnotationCanvasDoc = (options) => {
             ? backgroundLayersOf(viewport).find((l) => l.id === id)
             : undefined;
         const fileId = fileIdRef.current ?? createdIdRef.current;
-        if (layer && fileId) {
+        // A LINKED layer (an expanded file tile — see fileTileSwap.ts) does not
+        // own its Storage object: its storagePath points into the SOURCE file's
+        // folder, and deleting it would destroy that file's photo. Remove the
+        // layer only.
+        if (layer && fileId && !layer.fileId) {
             try {
                 await deleteImage(fileId, layer.storagePath);
             }

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';
@@ -37,6 +37,7 @@ export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, type Gro
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, type ViewportApi, type ViewportState, type ZoomLimits, } from './annotation/canvas/viewport.js';
 export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, type PdfDocRect, } from './annotation/canvas/pdfDocument.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
+export { fileTileImageSource, expandFileTileToBackground, collapseBackgroundToFileTile, type FileTileImageSource, } from './annotation/canvas/fileTileSwap.js';
 export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, type SelectToolOptions, } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, type MeasurementStampToolOptions, } from './annotation/canvas/tools/measurementStampTool.js';
@@ -51,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

@@ -41,6 +41,7 @@ export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, } from '
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './annotation/canvas/viewport.js';
 export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, } from './annotation/canvas/pdfDocument.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
+export { fileTileImageSource, expandFileTileToBackground, collapseBackgroundToFileTile, } from './annotation/canvas/fileTileSwap.js';
 export { createPenTool, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './annotation/canvas/tools/measurementStampTool.js';
@@ -55,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/annotation.d.ts

@@ -135,6 +135,12 @@ export interface BackgroundLayerTransform {
     scaleX: number;
     scaleY: number;
 }
+export interface BackgroundLayerCrop {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface AnnotationBackgroundLayer {
     id: AnnotationElementId;
     storagePath: string;
@@ -143,6 +149,10 @@ export interface AnnotationBackgroundLayer {
     heightPx: number;
     format?: 'raster' | 'svg';
     transform: BackgroundLayerTransform;
+    crop?: BackgroundLayerCrop;
+    fileId?: string;
+    filePath?: string;
+    fileGroupId?: string;
     locked?: boolean;
 }
 export interface AnnotationPdfPageSize {

package/package.json

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