@reekon-tools/boldr-utils 1.19.5 → 1.19.6

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

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

package/dist/annotation/canvas/AnnotationCanvasInner.js

@@ -27,7 +27,7 @@ const DEFAULT_PAN_TRIGGERS = ['middleMouse', 'space'];
 // (SSR / the vitest environment), where 1 is the right answer.
 const devicePixelRatioOf = () => typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
 export const AnnotationCanvasInner = (props) => {
-    const { resolveImageUrl, deferBackgroundToResolver, stampFontSource, stampValueFontSize = 14, gestures, width, height, style, activeToolId, tools, snapshotRef, renderBackground, } = props;
+    const { resolveImageUrl, deferBackgroundToResolver, hideLinkBadges, stampFontSource, stampValueFontSize = 14, gestures, width, height, style, activeToolId, tools, snapshotRef, renderBackground, } = props;
     // Snapshot plumbing for thumbnail capture: hold the <Canvas> ref and publish
     // a capture fn on the consumer's snapshotRef. encodeToBytes() yields PNG.
     const canvasRef = useCanvasRef();
@@ -316,6 +316,7 @@ export const AnnotationCanvasInner = (props) => {
                 viewport: state.viewport,
                 resolveImageUrl,
                 deferBackgroundToResolver,
+                hideLinkBadges,
                 backgroundContent,
                 canvasRef,
                 valueFont,

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

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

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

@@ -7,7 +7,7 @@ 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';
@@ -64,7 +64,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, 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
@@ -661,6 +661,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 +687,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
@@ -1477,11 +1534,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 +1668,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 +1676,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 +1776,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 +1784,7 @@ export const AnnotationCanvasInner = (props) => {
                 setResizingId(null);
                 setRectDragId(null);
                 setShapeResizeId(null);
+                setBgCropId(null);
             };
             return Gesture.Pan()
                 .minPointers(1)
@@ -1950,6 +2050,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 +2099,14 @@ export const AnnotationCanvasInner = (props) => {
         shapeEndpointDragId: shapeEpDragId,
         liveLineP1,
         liveLineP2,
+        bgCropId,
+        liveBgCrop: {
+            x: liveBgCropX,
+            y: liveBgCropY,
+            width: liveBgCropW,
+            height: liveBgCropH,
+        },
+        liveBgCropClip: liveBgCropRect,
         rectDragId,
         liveRect: {
             x: liveRectX,

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;
@@ -106,5 +127,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, 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

@@ -1,10 +1,11 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Canvas, Circle, DashPathEffect, Group, Line, Path, Rect, Skia, } from '@shopify/react-native-skia';
+import { Canvas, Circle, DashPathEffect, Group, Line, Path, Rect, RoundedRect, Skia, } from '@shopify/react-native-skia';
 import { normalizeRect, placementOf } from './measurementGeometry.js';
 import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeometry.js';
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
-import { backgroundLayerDocRect, backgroundLayersOf, isBackgroundLayerLocked, } from './backgroundLayers.js';
+import { backgroundCropBars, backgroundLayerDocRect, backgroundLayersOf, isBackgroundLayerLocked, } from './backgroundLayers.js';
+import { YellowColors } from '../../theme/colors.js';
 import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
 import { PlaneElement, PLANE_CHROME_COLOR, PLANE_GRID_COLOR, PLANE_GRID_OPACITY, PLANE_GRID_WIDTH, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
@@ -29,6 +30,30 @@ 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;
+// 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".
+const BACKGROUND_LOCKED_COLOR = YellowColors.mainYellow;
+// Link badge on a LINKED background layer (layer.fileId — an expanded file
+// tile, see fileTileSwap.ts): a chain glyph in a white disc at the layer's
+// top-right, saying "this is a group file's image, not a plain background".
+// Always on (selected or not) so the link is legible at a glance — which
+// makes it the one piece of chrome selection-clearing does NOT strip before a
+// capture: hosts must pass `hideLinkBadges` while snapshotting for
+// thumbnails/share/export, or the badge bakes into the output image.
+// Doc-space sized off the visible rect, like the selection stroke and bars.
+const LINKED_BADGE_BG = '#FFFFFF';
+const LINKED_BADGE_INK = '#181A1C';
+const LINKED_BADGE_RADIUS_RATIO = 0.05;
+// Lucide `link` (24-unit viewBox, stroke-width 2) — drawn stroked inside a
+// scale-to-badge Group, so the stroke width scales with the glyph.
+const LINKED_GLYPH_SVG = 'M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71' +
+    'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71';
+// Lazy + cached: on web this module is only evaluated after CanvasKit loads
+// (WithSkiaWeb gates the import), but deferring to first draw costs nothing
+// and can't regress if that ever changes.
+let linkedGlyphPath = null;
+const getLinkedGlyphPath = () => (linkedGlyphPath ?? (linkedGlyphPath = Skia.Path.MakeFromSVGString(LINKED_GLYPH_SVG)));
 // A draggable selection handle (line endpoints, rect corners, text resize):
 // a white disc with a colored ring, so it reads as a distinct, grabbable knob
 // over a line of ANY color — including the default measurement-line blue, which
@@ -80,7 +105,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, 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 = 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, 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
@@ -94,7 +119,39 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
             width: effectiveCanvas.viewport.width,
             height: effectiveCanvas.viewport.height,
         };
-    const world = (_jsxs(Group, { transform: worldTransform, children: [backgroundContent, backgroundLayersOf(effectiveCanvas.viewport).map((layer) => (_jsx(DraggableElement, { isDragging: layer.id === draggingId || layer.id === resizingId, transform: layer.id === resizingId ? resizeTransform : dragTransform, children: _jsx(BackgroundLayerElement, { layer: layer, resolveUrl: resolveImageUrl, deferToResolver: deferBackgroundToResolver, skImage: backgroundSkImages?.[layer.id], viewport: viewport, screenWidth: width, screenHeight: height }) }, layer.id))), (effectiveCanvas.planes ?? []).map((plane) => {
+    const world = (_jsxs(Group, { transform: worldTransform, children: [backgroundContent, backgroundLayersOf(effectiveCanvas.viewport).map((layer) => {
+                // Native crop-bar drag: clip to the LIVE visible rect (doc space)
+                // instead of the committed crop window, which is suppressed so a bar
+                // dragged outward reveals what the window hid.
+                const isCropDrag = layer.id === bgCropId && liveBgCropClip != null;
+                const element = (_jsx(BackgroundLayerElement, { layer: layer, resolveUrl: resolveImageUrl, deferToResolver: deferBackgroundToResolver, skImage: backgroundSkImages?.[layer.id], viewport: viewport, screenWidth: width, screenHeight: height, suppressCrop: isCropDrag }));
+                // Link badge on a LINKED layer (an expanded file tile) — always on,
+                // selected or not, locked or not: the link is a fact about the layer,
+                // not an affordance. A sibling of the (possibly live-clipped) image
+                // inside the same DraggableElement, so it rides drags and resizes;
+                // hidden during a live crop drag (it would sit on stale committed
+                // edges) and under `hideLinkBadges` (capture/export renders).
+                const badge = layer.fileId && !isCropDrag && !hideLinkBadges
+                    ? (() => {
+                        const glyph = getLinkedGlyphPath();
+                        if (!glyph)
+                            return null;
+                        const r = backgroundLayerDocRect(layer);
+                        const badgeR = Math.min(r.width, r.height) * LINKED_BADGE_RADIUS_RATIO;
+                        const bc = {
+                            x: r.x + r.width - 2 * badgeR,
+                            y: r.y + 2 * badgeR,
+                        };
+                        const glyphSize = badgeR * 1.2;
+                        return (_jsxs(_Fragment, { children: [_jsx(Circle, { c: bc, r: badgeR, color: LINKED_BADGE_BG }), _jsx(Group, { transform: [
+                                        { translateX: bc.x - glyphSize / 2 },
+                                        { translateY: bc.y - glyphSize / 2 },
+                                        { scale: glyphSize / 24 },
+                                    ], children: _jsx(Path, { path: glyph, color: LINKED_BADGE_INK, style: "stroke", strokeWidth: 2, strokeCap: "round", strokeJoin: "round" }) })] }));
+                    })()
+                    : null;
+                return (_jsxs(DraggableElement, { isDragging: layer.id === draggingId || layer.id === resizingId, transform: layer.id === resizingId ? resizeTransform : dragTransform, children: [isCropDrag ? (_jsx(Group, { clip: liveBgCropClip, children: element })) : (element), badge] }, layer.id));
+            }), (effectiveCanvas.planes ?? []).map((plane) => {
                 if (plane.id === planeDragId && planeDragPath) {
                     const statics = plane.mode === 'perspective'
                         ? plane.corners
@@ -247,21 +304,40 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                         shape.kind === 'polygon';
                     return (_jsxs(_Fragment, { children: [_jsx(SelectionBox, { bounds: b, isDragging: isLive, transform: liveTransform }), resizeGeom && handleRadius != null && (_jsx(DraggableElement, { isDragging: isLive, transform: liveTransform, children: _jsx(Handle, { c: resizeGeom.handle, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }) })), cornerResizable && handleRadius != null && (_jsxs(DraggableElement, { isDragging: isDragging, transform: dragTransform, children: [_jsx(Handle, { c: { x: b.minX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.minX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR })] }))] }));
                 }
-                // A selected background layer: outline its doc rect and offer ONE
-                // bottom-right handle — backgrounds scale uniformly about their
-                // top-left corner (the transform origin), so a single opposite-corner
-                // grab is the whole gizmo. Chrome tracks the live drag/resize
-                // transform the same way the layer itself does above. A LOCKED layer
-                // (backgroundLayerIsLocked) keeps the outline — it is selected, and
-                // the host's chrome offers the lock toggle — but gets no handle: it
-                // cannot scale, so a grabbable corner would lie.
+                // A selected background layer: outline its VISIBLE (cropped) doc rect
+                // and, when unlocked, offer FOUR corner handles (each scales about
+                // its opposite corner) plus four edge crop bars (raster layers only —
+                // dragging a bar windows the image non-destructively). Chrome tracks
+                // the live drag/resize transform the same way the layer itself does
+                // above. A LOCKED layer (backgroundLayerIsLocked) keeps the outline —
+                // it is selected, and the host's chrome offers the lock toggle — but
+                // recolored to the lock yellow and with no handles: it cannot scale
+                // or crop, so a grabbable gizmo would lie. During a native crop-bar
+                // drag the chrome is just the LIVE outline — handles and bars would
+                // sit on stale committed edges.
                 const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
                 if (layer) {
+                    if (layer.id === bgCropId && liveBgCrop) {
+                        return (_jsx(Rect, { x: liveBgCrop.x, y: liveBgCrop.y, width: liveBgCrop.width, height: liveBgCrop.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }));
+                    }
                     const locked = isBackgroundLayerLocked(effectiveCanvas.viewport, layer.id);
                     const r = backgroundLayerDocRect(layer);
                     const isResizing = layer.id === resizingId;
                     const liveTransform = isResizing ? resizeTransform : dragTransform;
-                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }), handleRadius != null && !locked && (_jsx(Handle, { c: { x: r.x + r.width, y: r.y + r.height }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }))] }));
+                    const corners = [
+                        { x: r.x, y: r.y },
+                        { x: r.x + r.width, y: r.y },
+                        { x: r.x, y: r.y + r.height },
+                        { x: r.x + r.width, y: r.y + r.height },
+                    ];
+                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: locked ? BACKGROUND_LOCKED_COLOR : SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }), !locked &&
+                                layer.format !== 'svg' &&
+                                backgroundCropBars(layer).map((bar) => {
+                                    const inset = Math.min(bar.width, bar.height) * 0.18;
+                                    return (_jsxs(Group, { children: [_jsx(RoundedRect, { x: bar.x, y: bar.y, width: bar.width, height: bar.height, r: Math.min(bar.width, bar.height) / 2, color: "#FFFFFF" }), _jsx(RoundedRect, { x: bar.x + inset, y: bar.y + inset, width: bar.width - 2 * inset, height: bar.height - 2 * inset, r: (Math.min(bar.width, bar.height) - 2 * inset) / 2, color: SELECTION_COLOR })] }, bar.edge));
+                                }), handleRadius != null &&
+                                !locked &&
+                                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] }));

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

@@ -1,5 +1,6 @@
 import type { ReactNode, ComponentType } from 'react';
 import type { AnnotationCanvasState, AnnotationDocumentPatch, AnnotationElement, AnnotationElementId, Selection, StrokeCap, Vec2 } from '../../types/annotation.js';
+import type { BackgroundCropEdge } from './backgroundLayers.js';
 import type { MeasurementRef } from './measurementPicker.js';
 import type { RectCorner } from './measurementGeometry.js';
 import type { ShapeToolKind } from './shapeGeometry.js';
@@ -90,7 +91,9 @@ export interface DragSelectionConfig {
         locked: boolean;
     } | null;
     hitTestResizeHandle?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): ResizeGeometry | null;
-    buildResizePatch?(doc: AnnotationCanvasState, id: AnnotationElementId, delta: Vec2): AnnotationDocumentPatch | null;
+    buildResizePatch?(doc: AnnotationCanvasState, id: AnnotationElementId, delta: Vec2, geom?: ResizeGeometry): AnnotationDocumentPatch | null;
+    hitTestBackgroundCropBar?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): BackgroundCropEdge | null;
+    buildBackgroundCropPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, edge: BackgroundCropEdge, delta: Vec2): AnnotationDocumentPatch | null;
 }
 export interface PlaneEditConfig {
     hitHandle(doc: AnnotationCanvasState, world: Vec2, zoom: number): number | null;

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

@@ -1,16 +1,35 @@
-import type { AnnotationBackgroundLayer, AnnotationViewport, BackgroundLayerTransform } from '../../types/annotation.js';
+import type { AnnotationBackgroundLayer, AnnotationViewport, BackgroundLayerCrop, BackgroundLayerTransform } from '../../types/annotation.js';
 export declare const LEGACY_BACKGROUND_LAYER_ID = "background-legacy";
 export declare const BACKGROUND_PLACEMENT_GAP_RATIO = 0.02;
 export declare const backgroundLayersOf: (viewport: AnnotationViewport) => AnnotationBackgroundLayer[];
 export declare const backgroundLayerIsLocked: (layer: AnnotationBackgroundLayer, index: number) => boolean;
 export declare const isBackgroundLayerLocked: (viewport: AnnotationViewport, id: string) => boolean;
 export declare const defaultBackgroundLayerLocked: (existing: AnnotationBackgroundLayer[]) => boolean;
+export declare const backgroundLayerCropRect: (layer: AnnotationBackgroundLayer) => BackgroundLayerCrop;
 export declare const backgroundLayerDocRect: (layer: AnnotationBackgroundLayer) => {
     x: number;
     y: number;
     width: number;
     height: number;
 };
+export declare const backgroundLayerFullDocRect: (layer: AnnotationBackgroundLayer) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare const MIN_BACKGROUND_DOC_EXTENT = 16;
+export declare const MAX_BACKGROUND_DOC_EXTENT = 65536;
+export type BackgroundCropEdge = 'top' | 'bottom' | 'left' | 'right';
+export declare const BACKGROUND_CROP_EDGES: readonly BackgroundCropEdge[];
+export interface BackgroundCropBar {
+    edge: BackgroundCropEdge;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const backgroundCropBars: (layer: AnnotationBackgroundLayer) => BackgroundCropBar[];
 export declare const backgroundLayersUnionRect: (layers: AnnotationBackgroundLayer[]) => {
     x: number;
     y: number;

package/dist/annotation/canvas/backgroundLayers.js

@@ -69,14 +69,105 @@ export const isBackgroundLayerLocked = (viewport, id) => {
 // against it. Written explicitly onto the new layer so the state survives
 // later removals — a second image stays free even once it is the only one.
 export const defaultBackgroundLayerLocked = (existing) => existing.length === 0;
-// The doc-space rectangle a layer occupies: the intrinsic pixel grid under
-// the layer's translate+scale.
-export const backgroundLayerDocRect = (layer) => ({
+// The layer's crop window in intrinsic pixels, clamped defensively into the
+// image bounds (a hand-edited or future-client doc must not push the visible
+// rect outside the bytes). Absent crop = the full image.
+export const backgroundLayerCropRect = (layer) => {
+    const c = layer.crop;
+    if (!c)
+        return { x: 0, y: 0, width: layer.widthPx, height: layer.heightPx };
+    const x = Math.min(Math.max(c.x, 0), layer.widthPx);
+    const y = Math.min(Math.max(c.y, 0), layer.heightPx);
+    return {
+        x,
+        y,
+        width: Math.min(Math.max(c.width, 0), layer.widthPx - x),
+        height: Math.min(Math.max(c.height, 0), layer.heightPx - y),
+    };
+};
+// The doc-space rectangle a layer occupies: its VISIBLE (crop-windowed)
+// pixel grid under the layer's translate+scale. Everything that treats "the
+// layer" as a rect — selection chrome, hit-tests, fit/union math, new-layer
+// placement — reads this, so a crop moves all of them together; only the
+// renderer additionally knows the full image extends past it (clipped, see
+// BackgroundLayerElement).
+export const backgroundLayerDocRect = (layer) => {
+    const c = backgroundLayerCropRect(layer);
+    return {
+        x: layer.transform.x + c.x * layer.transform.scaleX,
+        y: layer.transform.y + c.y * layer.transform.scaleY,
+        width: c.width * layer.transform.scaleX,
+        height: c.height * layer.transform.scaleY,
+    };
+};
+// The full (uncropped) image's doc rect — the bounds a crop edge can expand
+// back out to.
+export const backgroundLayerFullDocRect = (layer) => ({
     x: layer.transform.x,
     y: layer.transform.y,
     width: layer.widthPx * layer.transform.scaleX,
     height: layer.heightPx * layer.transform.scaleY,
 });
+// Doc-space clamp on a background layer's larger doc dimension (corner
+// resize) and on its visible extent (crop). The floor keeps a 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. Here rather than in selectTool because the native
+// crop preview worklet needs the floor too.
+export const MIN_BACKGROUND_DOC_EXTENT = 16;
+export const MAX_BACKGROUND_DOC_EXTENT = 65536;
+export const BACKGROUND_CROP_EDGES = [
+    'top',
+    'bottom',
+    'left',
+    'right',
+];
+// Bar proportions relative to the visible rect. Doc-space sizing, like the
+// selection box stroke — the bars belong to the rect they crop, so they zoom
+// with it; grab tolerance stays screen-constant in the hit-test instead.
+const CROP_BAR_LENGTH_RATIO = 0.15;
+const CROP_BAR_THICKNESS_RATIO = 0.22;
+// The four crop bars for a layer's visible rect: pill-shaped grabs centered on
+// each edge midpoint, long side along the edge.
+export const backgroundCropBars = (layer) => {
+    const r = backgroundLayerDocRect(layer);
+    const midX = r.x + r.width / 2;
+    const midY = r.y + r.height / 2;
+    const hLen = r.width * CROP_BAR_LENGTH_RATIO;
+    const hThick = hLen * CROP_BAR_THICKNESS_RATIO;
+    const vLen = r.height * CROP_BAR_LENGTH_RATIO;
+    const vThick = vLen * CROP_BAR_THICKNESS_RATIO;
+    return [
+        {
+            edge: 'top',
+            x: midX - hLen / 2,
+            y: r.y - hThick / 2,
+            width: hLen,
+            height: hThick,
+        },
+        {
+            edge: 'bottom',
+            x: midX - hLen / 2,
+            y: r.y + r.height - hThick / 2,
+            width: hLen,
+            height: hThick,
+        },
+        {
+            edge: 'left',
+            x: r.x - vThick / 2,
+            y: midY - vLen / 2,
+            width: vThick,
+            height: vLen,
+        },
+        {
+            edge: 'right',
+            x: r.x + r.width - vThick / 2,
+            y: midY - vLen / 2,
+            width: vThick,
+            height: vLen,
+        },
+    ];
+};
 // Bounding box of every layer's doc rect. Null when there are no layers —
 // callers fall back to the document rect.
 export const backgroundLayersUnionRect = (layers) => {

package/dist/annotation/canvas/elements/BackgroundImageElement.d.ts

@@ -17,5 +17,6 @@ export interface BackgroundLayerElementProps {
     viewport?: ViewportState;
     screenWidth?: number;
     screenHeight?: number;
+    suppressCrop?: boolean;
 }
-export declare const BackgroundLayerElement: import("react").MemoExoticComponent<({ layer, resolveUrl, deferToResolver, skImage: skImageProp, viewport, screenWidth, screenHeight, }: BackgroundLayerElementProps) => import("react/jsx-runtime").JSX.Element | null>;
+export declare const BackgroundLayerElement: import("react").MemoExoticComponent<({ layer, resolveUrl, deferToResolver, skImage: skImageProp, viewport, screenWidth, screenHeight, suppressCrop, }: BackgroundLayerElementProps) => import("react/jsx-runtime").JSX.Element | null>;

package/dist/annotation/canvas/elements/BackgroundImageElement.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Group, Image, useImage, } from '@shopify/react-native-skia';
+import { Group, Image, rect, useImage, } from '@shopify/react-native-skia';
 import { memo, useEffect, useRef } from 'react';
 import { backgroundLayerDocRect } from '../backgroundLayers.js';
 import { useBackgroundUrl } from './backgroundUrl.js';
@@ -38,7 +38,7 @@ export const BackgroundSkImageLoader = ({ layer, resolveUrl, deferToResolver, on
 // A component (not inlined into the scene helper) because each layer owns
 // per-image hooks — URL resolution and raster decode — and AnnotationCanvasSkia
 // is a hook-free plain function.
-export const BackgroundLayerElement = memo(({ layer, resolveUrl, deferToResolver, skImage: skImageProp, viewport, screenWidth, screenHeight, }) => {
+export const BackgroundLayerElement = memo(({ layer, resolveUrl, deferToResolver, skImage: skImageProp, viewport, screenWidth, screenHeight, suppressCrop, }) => {
     const isSvg = layer.format === 'svg';
     // Self-load only when no pre-decoded image is provided; the hook still runs
     // unconditionally (with a null source, so it no-ops) to satisfy hook rules.
@@ -60,6 +60,14 @@ export const BackgroundLayerElement = memo(({ layer, resolveUrl, deferToResolver
     }
     if (!content)
         return null;
+    // Committed crop window: clip in the layer's intrinsic pixel space (inside
+    // the transform, so it scales with the image). Non-destructive — the full
+    // image is drawn, the clip just windows it. See suppressCrop for the one
+    // case that skips it.
+    const crop = !suppressCrop && layer.crop ? layer.crop : null;
+    if (crop) {
+        content = (_jsx(Group, { clip: rect(crop.x, crop.y, crop.width, crop.height), children: content }));
+    }
     return (_jsx(Group, { transform: [
             { translateX: t.x },
             { translateY: t.y },

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

@@ -0,0 +1,12 @@
+import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationElementId } from '../../types/annotation.js';
+import type { FileUpload } from '../../types/firestore.js';
+export interface FileTileImageSource {
+    storagePath: string;
+    downloadUrl: string;
+    widthPx: number;
+    heightPx: number;
+    format?: 'raster' | 'svg';
+}
+export declare const fileTileImageSource: (file: Pick<FileUpload, "type" | "fileData"> | null | undefined) => FileTileImageSource | null;
+export declare const expandFileTileToBackground: (doc: AnnotationCanvasState, placedId: AnnotationElementId, layerId: AnnotationElementId, image: FileTileImageSource) => AnnotationDocumentPatch | null;
+export declare const collapseBackgroundToFileTile: (doc: AnnotationCanvasState, layerId: AnnotationElementId, tileId: AnnotationElementId, now?: number) => AnnotationDocumentPatch | null;

package/dist/annotation/canvas/fileTileSwap.js

@@ -0,0 +1,87 @@
+import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
+import { backgroundLayerDocRect, backgroundLayersOf, } from './backgroundLayers.js';
+import { imageDocRect } from './viewport.js';
+export const fileTileImageSource = (file) => {
+    if (!file)
+        return null;
+    // Structural, not type-switched: Canvas, Annotation and Template docs all
+    // carry AnnotationFileData; anything else (Label, Note, Calculator, …) has
+    // no `canvas` key and falls out here.
+    const data = file.fileData;
+    if (!data?.canvas || data.isLabel)
+        return null;
+    if (data.canvas.viewport.pdfDocument)
+        return null;
+    const raster = backgroundLayersOf(data.canvas.viewport).find((l) => l.format !== 'svg' && l.storagePath && l.widthPx > 0);
+    if (!raster)
+        return null;
+    return {
+        storagePath: raster.storagePath,
+        downloadUrl: raster.downloadUrl,
+        widthPx: raster.widthPx,
+        heightPx: raster.heightPx,
+        ...(raster.format ? { format: raster.format } : {}),
+    };
+};
+// Patch that replaces the object tile `placedId` with a background layer
+// showing `image`: the image contain-fits the document rect (the size a
+// first-placed background gets) and centers on the tile's anchor, so it
+// appears where the tile was. The layer starts FREE — the point of expanding
+// is to arrange the photo, and the pill's lock is one tap away. Null when the
+// tile is missing or isn't an object tile.
+export const expandFileTileToBackground = (doc, placedId, layerId, image) => {
+    const placed = doc.placedMeasurements.find((m) => m.id === placedId);
+    if (!placed?.fileId)
+        return null;
+    const fitted = imageDocRect(image.widthPx, image.heightPx, doc.viewport.width, doc.viewport.height, 'contain');
+    const layer = {
+        id: layerId,
+        storagePath: image.storagePath,
+        downloadUrl: image.downloadUrl,
+        widthPx: image.widthPx,
+        heightPx: image.heightPx,
+        ...(image.format ? { format: image.format } : {}),
+        transform: {
+            x: placed.anchor.x - fitted.width / 2,
+            y: placed.anchor.y - fitted.height / 2,
+            scaleX: image.widthPx > 0 ? fitted.width / image.widthPx : 1,
+            scaleY: image.heightPx > 0 ? fitted.height / image.heightPx : 1,
+        },
+        locked: false,
+        fileId: placed.fileId,
+        ...(placed.filePath ? { filePath: placed.filePath } : {}),
+        ...(placed.groupId ? { fileGroupId: placed.groupId } : {}),
+    };
+    return {
+        ops: [
+            { op: 'removeMeasurement', id: placedId },
+            { op: 'addBackgroundImage', image: layer },
+        ],
+    };
+};
+// Patch that replaces the linked background layer `layerId` with an object
+// tile at the layer's visible center — the inverse switch. The tile's fields
+// come back off the layer (see the fileId trio on AnnotationBackgroundLayer),
+// at the default tile scale; the crop window, if any, is simply dropped (a
+// tile is a thumbnail, not a window). Null for a layer that isn't linked.
+export const collapseBackgroundToFileTile = (doc, layerId, tileId, now = Date.now()) => {
+    const layer = backgroundLayersOf(doc.viewport).find((l) => l.id === layerId);
+    if (!layer?.fileId)
+        return null;
+    const r = backgroundLayerDocRect(layer);
+    const tile = {
+        id: tileId,
+        layerId: doc.layers[0]?.id ?? DEFAULT_LAYER_ID,
+        fileId: layer.fileId,
+        ...(layer.filePath ? { filePath: layer.filePath } : {}),
+        ...(layer.fileGroupId ? { groupId: layer.fileGroupId } : {}),
+        anchor: { x: r.x + r.width / 2, y: r.y + r.height / 2 },
+        createdAt: now,
+    };
+    return {
+        ops: [
+            { op: 'removeBackgroundImage', id: layerId },
+            { op: 'addMeasurement', measurement: tile },
+        ],
+    };
+};

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

@@ -20,7 +20,7 @@ export declare const TILE_SCALE_MIN = 0.05;
 export declare const TILE_SCALE_MAX = 2;
 export declare const resolveTileScaleFactor: (canvas: Pick<AnnotationCanvasState, "tileScaleFactor" | "tileScaleFactorMobile">, platform: TileScalePlatform) => number;
 export declare const resolveHeaderTileScaleFactor: (canvas: Pick<AnnotationCanvasState, "tileScaleFactor" | "tileScaleFactorMobile" | "headerTileScaleFactor" | "headerTileScaleFactorMobile">, platform: TileScalePlatform) => number;
-export declare const resolveFileTileScaleFactor: (canvas: Pick<AnnotationCanvasState, "tileScaleFactor" | "tileScaleFactorMobile" | "fileTileScaleFactor" | "fileTileScaleFactorMobile">, platform: TileScalePlatform) => number;
+export declare const resolveFileTileScaleFactor: (canvas: Pick<AnnotationCanvasState, "tileScaleFactor" | "tileScaleFactorMobile">, platform: TileScalePlatform) => number;
 export declare const clampTileScale: (v: number) => number;
 export declare const tileDocSizeForFactor: (factor: number, zoom: number) => number;
 export declare const tileScaleFromDocSize: (docSize: number, zoom: number) => number;

package/dist/annotation/canvas/stampLayout.js

@@ -97,14 +97,16 @@ export const resolveTileScaleFactor = (canvas, platform) => (platform === 'mobil
 export const resolveHeaderTileScaleFactor = (canvas, platform) => (platform === 'mobile'
     ? (canvas.headerTileScaleFactorMobile ?? canvas.headerTileScaleFactor)
     : canvas.headerTileScaleFactor) ?? resolveTileScaleFactor(canvas, platform);
-// Resolve the document-wide OBJECT-tile-scale knob for a platform — the third
-// knob (Asana 1217570500895545), resolved exactly like the header knob: own
-// platform value → web value → the MEASUREMENT factor, so an object tile
-// placed before its knob was ever moved matches the measurement tiles beside
-// it. The ONE read path for the file fields.
-export const resolveFileTileScaleFactor = (canvas, platform) => (platform === 'mobile'
-    ? (canvas.fileTileScaleFactorMobile ?? canvas.fileTileScaleFactor)
-    : canvas.fileTileScaleFactor) ?? resolveTileScaleFactor(canvas, platform);
+// Resolve the OBJECT-tile scale for a platform: the MEASUREMENT factor.
+// Object tiles briefly had their own third knob (Asana 1217570500895545), but
+// it was retired — an object thumbnail must size consistently with the
+// measurement tiles beside it, so its slider now drives (and follows) the one
+// shared factor. The `fileTileScaleFactor(Mobile)` fields it wrote persist on
+// old documents and old undo payloads still write them; they are deliberately
+// IGNORED here — resolving them would let a stale divergent value shadow the
+// shared knob forever. Kept as a named resolver (not inlined at call sites)
+// so the read path stays greppable and the retirement is documented once.
+export const resolveFileTileScaleFactor = (canvas, platform) => resolveTileScaleFactor(canvas, platform);
 // Clamp a tile-scale-factor candidate to the supported range. The single guard
 // for the value before it lands in the document (slider input, restored docs).
 export const clampTileScale = (v) => v < TILE_SCALE_MIN ? TILE_SCALE_MIN : v > TILE_SCALE_MAX ? TILE_SCALE_MAX : v;

package/dist/annotation/canvas/tools/selectTool.d.ts

@@ -1,5 +1,23 @@
+import type { Vec2 } from '../../../types/annotation.js';
+import { type BackgroundCropEdge } from '../backgroundLayers.js';
 import type { Tool } from '../Tool.js';
 export interface SelectToolOptions {
     panOnEmptyDrag?: boolean;
 }
+export declare const cropDragVisibleRect: (start: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, full: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, edge: BackgroundCropEdge, delta: Vec2) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 export declare const createSelectTool: (options?: SelectToolOptions) => Tool;

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

@@ -1,4 +1,4 @@
-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';
@@ -468,12 +468,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 +507,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 +539,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 +594,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 +615,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 +703,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 +740,8 @@ export const createSelectTool = (options = {}) => ({
         buildResizePatch: resizePatch,
         hitTestBackground: findBackgroundHit,
         hitTestSelectedBackground: findSelectedBackgroundHit,
+        hitTestBackgroundCropBar: findBackgroundCropBarHit,
+        buildBackgroundCropPatch: backgroundCropPatch,
         hitTestRectCorner: findRectCornerHit,
         buildRectCornerPatch: rectCornerPatch,
         hitTestShapeCorner: findShapeCornerHit,
@@ -693,7 +792,8 @@ export const createSelectTool = (options = {}) => ({
                     delta: { x: 0, y: 0 },
                 };
             }
-            if (findResizeHandleHit(ctx.document, selId, world, zoom)) {
+            const resizeGeom = findResizeHandleHit(ctx.document, selId, world, zoom);
+            if (resizeGeom) {
                 return {
                     kind: 'dragging',
                     id: selId,
@@ -704,6 +804,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 },
                 };

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -194,7 +194,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 &&

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

@@ -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';

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';

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.19.6",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",