@reekon-tools/boldr-utils 1.19.4 → 1.19.6

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

@@ -20,6 +20,8 @@ export interface AnnotationCanvasInnerProps {
     fractionalTolerance?: FractionalTolerance;
     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, 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();
@@ -315,6 +315,8 @@ export const AnnotationCanvasInner = (props) => {
                 worldTransform: state.worldTransform,
                 viewport: state.viewport,
                 resolveImageUrl,
+                deferBackgroundToResolver,
+                hideLinkBadges,
                 backgroundContent,
                 canvasRef,
                 valueFont,

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

@@ -21,6 +21,8 @@ export interface AnnotationCanvasInnerProps {
     fractionalTolerance?: FractionalTolerance;
     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, 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)
@@ -1949,6 +2049,8 @@ export const AnnotationCanvasInner = (props) => {
         effectiveCanvas: state.effectiveCanvas,
         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
@@ -1997,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,
@@ -2045,7 +2155,7 @@ export const AnnotationCanvasInner = (props) => {
     // drawing to the canvas box by construction, but the stamp overlay is
     // plain RN views — without clipping, tiles panned past the edge of a
     // non-fullscreen canvas (e.g. a diagram strip) escape into surrounding UI.
-    _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [backgroundLayers.map((layer) => (_jsx(BackgroundSkImageLoader, { layer: layer, resolveUrl: resolveImageUrl, onImage: onBackgroundSkImage }, layer.id))), _jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia(skiaProps) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
+    _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [backgroundLayers.map((layer) => (_jsx(BackgroundSkImageLoader, { layer: layer, resolveUrl: resolveImageUrl, deferToResolver: deferBackgroundToResolver, onImage: onBackgroundSkImage }, layer.id))), _jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia(skiaProps) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
                         ? (state.measurementsById.get(placed.measurementId) ?? null)
                         : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, planeEdgeDragging: planeDrag != null && placed.planeId === planeDrag.planeId, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, rectCtx: rectCtx, planeTileCtx: planeTileCtx, planeDragTX: planeDragTX, planeDragTY: planeDragTY, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.tileScaleFactor, headerTileScaleFactor: state.headerTileScaleFactor, fileTileScaleFactor: state.fileTileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
                         ? () => {

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

@@ -23,6 +23,8 @@ export interface AnnotationCanvasSkiaProps {
     };
     viewport?: ViewportState;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
+    deferBackgroundToResolver?: boolean;
+    hideLinkBadges?: boolean;
     backgroundSkImages?: Record<string, SkImage | null>;
     backgroundContent?: ReactNode;
     valueFont: SkFont | null;
@@ -73,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;
@@ -105,5 +127,5 @@ export interface AnnotationCanvasSkiaProps {
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, 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, 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, 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

@@ -1,19 +1,22 @@
 import { type SkImage } from '@shopify/react-native-skia';
 import type { AnnotationBackgroundImage, AnnotationBackgroundLayer } from '../../../types/annotation.js';
 import type { ViewportState } from '../viewport.js';
-export declare const useBackgroundSkImage: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>) => SkImage | null;
+export declare const useBackgroundSkImage: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>, deferToResolver?: boolean) => SkImage | null;
 export interface BackgroundSkImageLoaderProps {
     layer: AnnotationBackgroundLayer;
     resolveUrl?: (path: string) => Promise<string>;
+    deferToResolver?: boolean;
     onImage: (id: string, image: SkImage | null) => void;
 }
-export declare const BackgroundSkImageLoader: ({ layer, resolveUrl, onImage, }: BackgroundSkImageLoaderProps) => null;
+export declare const BackgroundSkImageLoader: ({ layer, resolveUrl, deferToResolver, onImage, }: BackgroundSkImageLoaderProps) => null;
 export interface BackgroundLayerElementProps {
     layer: AnnotationBackgroundLayer;
     resolveUrl?: (path: string) => Promise<string>;
+    deferToResolver?: boolean;
     skImage?: SkImage | null;
     viewport?: ViewportState;
     screenWidth?: number;
     screenHeight?: number;
+    suppressCrop?: boolean;
 }
-export declare const BackgroundLayerElement: import("react").MemoExoticComponent<({ layer, resolveUrl, 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>;