@reekon-tools/boldr-utils 1.19.5 → 1.20.0

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,12 +30,45 @@ const MEASUREMENT_HANDLE_COLOR = '#0066FF';
 // hit-test the text resize handle, which sits on the padded box corner.
 const SELECTION_COLOR = '#0066FF';
 const SELECTION_STROKE = 1.5;
+// Snap ring (magnetic endpoint snapping, see snapGeometry.ts): drawn around
+// the target the dragged endpoint is currently locked onto. Orange so it reads
+// against both the blue selection chrome and the yellow lock accent.
+const SNAP_INDICATOR_COLOR = '#FF7A00';
+// Outline of a selected LOCKED background layer: the lock accent (the same
+// yellow the selected group-header border uses), distinct from the blue
+// manipulable-selection chrome — locked means "selected, but pinned".
+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
 // a solid-colored handle would camouflage into. `c`/`r`/`ringWidth` may be
 // Reanimated values (native live-drag) or plain numbers (web).
 const Handle = ({ c, r, ringWidth, color = MEASUREMENT_HANDLE_COLOR, }) => (_jsxs(_Fragment, { children: [_jsx(Circle, { c: c, r: r, color: "#FFFFFF" }), _jsx(Circle, { c: c, r: r, color: color, style: "stroke", strokeWidth: ringWidth })] }));
+// The snap indicator: a stroke-only ring (NOT a Handle — its white disc would
+// hide the very pixel being snapped to). Screen-constant like the handles;
+// `opacity` lets the native UI-thread path show/hide it without remounting
+// (a zero radius still paints a strokeWidth-sized dot, so radius can't gate it).
+const SnapRing = ({ c, r, ringWidth, opacity = 1, }) => (_jsx(Circle, { c: c, r: r, color: SNAP_INDICATOR_COLOR, style: "stroke", strokeWidth: ringWidth, opacity: opacity }));
 // Bounds of a flat [x,y,x,y,…] stroke point array, or null if empty.
 const strokeBounds = (points) => {
     if (points.length < 2)
@@ -80,7 +114,7 @@ const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElem
 // since the function-call pattern works identically on native we use it
 // in both Inners for consistency. Don't add hooks here; this is a plain
 // JSX-returning helper, not a component.
-export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, deferBackgroundToResolver, 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, snapIndicator, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale = 1, measurementLineScale = 1, customPreview, wrapContent, canvasRef, }) => {
     // Doc rect a SCALE-mode plane grid covers: the first background layer (the
     // photo being calibrated), else the document rect. Pinned to layer 0 like
     // the tile-sizing reference — adding a second image must not re-span the
@@ -94,7 +128,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,23 +313,42 @@ 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] }));
+            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), snapIndicator && (_jsx(SnapRing, { c: snapIndicator.c, r: snapIndicator.r, ringWidth: snapIndicator.ringWidth, opacity: snapIndicator.opacity })), customPreview] }));
     return (_jsx(Canvas, { ref: canvasRef, style: { width, height }, children: wrapContent ? wrapContent(world) : world }));
 };

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

@@ -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';
@@ -18,6 +19,11 @@ export interface CanvasPointerEvent {
     metaKey?: boolean;
     ctrlKey?: boolean;
 }
+export interface SnapContext {
+    enabled: boolean;
+    radiusPx: number;
+    setIndicator(point: Vec2 | null): void;
+}
 export interface ToolContext {
     document: AnnotationCanvasState;
     selection: Selection | null;
@@ -26,6 +32,7 @@ export interface ToolContext {
     tileScaleFactor: number;
     headerTileScaleFactor: number;
     fileTileScaleFactor: number;
+    snap?: SnapContext | null;
     preview(patch: AnnotationDocumentPatch): void;
     commit(patch: AnnotationDocumentPatch): void;
     setSelection(selection: Selection | null): void;
@@ -90,7 +97,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/snapGeometry.d.ts

@@ -0,0 +1,32 @@
+import type { AnnotationCanvasState, AnnotationElementId, Vec2 } from '../../types/annotation.js';
+export declare const SNAP_RADIUS_PX = 16;
+export declare const SNAP_RING_PX = 11;
+export declare const SNAP_RING_WIDTH_PX = 2;
+export declare const SNAP_KIND_POINT = 0;
+export declare const SNAP_KIND_MIDPOINT = 1;
+export type SnapKind = 0 | 1;
+export declare const SNAP_STRIDE = 3;
+export interface SnapTarget {
+    x: number;
+    y: number;
+    kind: SnapKind;
+    sourceId: AnnotationElementId;
+}
+export interface SnapHit {
+    x: number;
+    y: number;
+    kind: SnapKind;
+    index: number;
+}
+export declare const collectSnapTargets: (doc: AnnotationCanvasState, excludeId?: AnnotationElementId | null) => SnapTarget[];
+export declare const encodeSnapTargets: (targets: readonly SnapTarget[]) => number[];
+export declare const collectSnapTargetsFlat: (doc: AnnotationCanvasState, excludeId?: AnnotationElementId | null) => number[];
+export declare const snapNearest: (x: number, y: number, flat: readonly number[], radiusDoc: number) => SnapHit | null;
+export declare const snapDelta: (base: Vec2, delta: Vec2, flat: readonly number[], radiusDoc: number) => {
+    delta: Vec2;
+    hit: SnapHit | null;
+};
+export declare const snapPoint: (p: Vec2, flat: readonly number[], radiusDoc: number) => {
+    point: Vec2;
+    hit: SnapHit | null;
+};