@reekon-tools/boldr-utils 1.19.4 → 1.19.6

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';
@@ -11,8 +11,8 @@ import { BackgroundSvgElement } from './BackgroundSvg.js';
 // re-decodes. Returns null until loaded, or when `image` is null/undefined.
 // Hooks run unconditionally regardless of `image`. Raster only — SVG
 // backgrounds self-load in BackgroundSvgElement (parsing an SVG is cheap).
-export const useBackgroundSkImage = (image, resolveUrl) => {
-    const url = useBackgroundUrl(image, resolveUrl);
+export const useBackgroundSkImage = (image, resolveUrl, deferToResolver) => {
+    const url = useBackgroundUrl(image, resolveUrl, deferToResolver);
     return useImage(url || null);
 };
 // Null-rendering decode host: one mounted instance per background layer, so a
@@ -20,10 +20,10 @@ export const useBackgroundSkImage = (image, resolveUrl) => {
 // mapping over hooks. The consumer (the native Inner) mounts one per layer,
 // accumulates the reported images into a Record keyed by layer id, and feeds
 // that to every canvas sharing the decode (main + magnifier loupe).
-export const BackgroundSkImageLoader = ({ layer, resolveUrl, onImage, }) => {
+export const BackgroundSkImageLoader = ({ layer, resolveUrl, deferToResolver, onImage, }) => {
     // SVG layers never draw through an SkImage (BackgroundSvgElement owns its
     // own vector pipeline), so skip the decode and report null.
-    const image = useBackgroundSkImage(layer.format === 'svg' ? null : layer, resolveUrl);
+    const image = useBackgroundSkImage(layer.format === 'svg' ? null : layer, resolveUrl, deferToResolver);
     // The callback rides a ref so an inline consumer closure doesn't re-report
     // (and re-render the collector) every render.
     const onImageRef = useRef(onImage);
@@ -38,12 +38,12 @@ export const BackgroundSkImageLoader = ({ layer, resolveUrl, onImage, }) => {
 // 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, 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.
     const provided = skImageProp !== undefined;
-    const loaded = useBackgroundSkImage(provided || isSvg ? null : layer, resolveUrl);
+    const loaded = useBackgroundSkImage(provided || isSvg ? null : layer, resolveUrl, deferToResolver);
     const skImage = provided ? skImageProp : loaded;
     const t = layer.transform;
     let content = null;
@@ -53,13 +53,21 @@ export const BackgroundLayerElement = memo(({ layer, resolveUrl, skImage: skImag
         // through the browser at viewport resolution. Both draw at intrinsic
         // size — the Group below owns the placement — but the web rasterizer
         // still needs the doc rect to crop against the visible region.
-        content = (_jsx(BackgroundSvgElement, { image: layer, dims: backgroundLayerDocRect(layer), resolveUrl: resolveUrl, viewport: viewport, screenWidth: screenWidth, screenHeight: screenHeight }));
+        content = (_jsx(BackgroundSvgElement, { image: layer, dims: backgroundLayerDocRect(layer), resolveUrl: resolveUrl, deferToResolver: deferToResolver, viewport: viewport, screenWidth: screenWidth, screenHeight: screenHeight }));
     }
     else if (skImage) {
         content = (_jsx(Image, { image: skImage, x: 0, y: 0, width: layer.widthPx, height: layer.heightPx, fit: "fill" }));
     }
     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/elements/BackgroundSvg.d.ts

@@ -5,6 +5,7 @@ export interface BackgroundSvgProps {
     image: AnnotationBackgroundImage;
     dims: RectPx;
     resolveUrl?: (path: string) => Promise<string>;
+    deferToResolver?: boolean;
     viewport?: ViewportState;
     screenWidth?: number;
     screenHeight?: number;

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

@@ -116,8 +116,8 @@ const useBackgroundSkSvg = (url) => {
     }, []);
     return svg;
 };
-const SkSvgBackground = ({ image, resolveUrl }) => {
-    const url = useBackgroundUrl(image, resolveUrl);
+const SkSvgBackground = ({ image, resolveUrl, deferToResolver, }) => {
+    const url = useBackgroundUrl(image, resolveUrl, deferToResolver);
     const svg = useBackgroundSkSvg(url);
     if (!svg)
         return null;
@@ -169,8 +169,8 @@ const loadSvgImage = (xml) => new Promise((resolve, reject) => {
     };
     img.src = objectUrl;
 });
-const BrowserSvgBackground = ({ image, dims, resolveUrl, viewport, screenWidth, screenHeight, }) => {
-    const url = useBackgroundUrl(image, resolveUrl);
+const BrowserSvgBackground = ({ image, dims, resolveUrl, deferToResolver, viewport, screenWidth, screenHeight, }) => {
+    const url = useBackgroundUrl(image, resolveUrl, deferToResolver);
     const [svgText, setSvgText] = useState(null);
     useEffect(() => {
         if (!url) {

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

@@ -1,2 +1,3 @@
 import type { AnnotationBackgroundImage } from '../../../types/annotation.js';
-export declare const useBackgroundUrl: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>) => string;
+export declare const initialBackgroundUrl: (image: AnnotationBackgroundImage | null | undefined, resolveUrl: ((path: string) => Promise<string>) | undefined, deferToResolver: boolean | undefined) => string;
+export declare const useBackgroundUrl: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>, deferToResolver?: boolean) => string;

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

@@ -2,8 +2,21 @@ import { useEffect, useRef, useState } from 'react';
 // Resolve a background image's (possibly expired) storage URL. Shared by the
 // raster loader (BackgroundLayerElement / BackgroundSkImageLoader) and both
 // SVG render paths (BackgroundSvg).
-export const useBackgroundUrl = (image, resolveUrl) => {
-    const [url, setUrl] = useState(image?.downloadUrl ?? '');
+//
+// `deferToResolver` — start from '' instead of seeding the doc's stored
+// `downloadUrl` while the resolver runs. A consumer whose resolver is
+// LOCAL-FIRST (a cached copy on disk answers without the network) must set
+// this: the seed is handed to the image loader on the very first render, so
+// it starts a full-resolution download from Storage that the local answer
+// then races — wasted bandwidth at best, and the loader keeps whichever
+// result lands LAST, so the remote fetch can override the local decode.
+// A consumer whose resolver is network-only (web/desktop re-resolving a
+// possibly-expired URL) should leave it off: there the seed is a warm start —
+// the resolver normally confirms the same URL, and the early fetch is the
+// image download it would have started anyway.
+export const initialBackgroundUrl = (image, resolveUrl, deferToResolver) => (deferToResolver && resolveUrl ? '' : (image?.downloadUrl ?? ''));
+export const useBackgroundUrl = (image, resolveUrl, deferToResolver) => {
+    const [url, setUrl] = useState(() => initialBackgroundUrl(image, resolveUrl, deferToResolver));
     // Hold resolveUrl in a ref so re-resolution is keyed only on the image
     // identity, not the function's. Consumers commonly pass an inline closure
     // (a new reference each render); depending on it directly would re-run a

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