@reekon-tools/boldr-utils 1.11.0 → 1.12.0

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

@@ -1,3 +1,4 @@
+import { backgroundLayerDocRect, backgroundLayersOf, } 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';
@@ -16,6 +17,12 @@ const isTextShape = (doc, id) => doc.shapes.some((s) => s.id === id && s.kind ==
 // tap (shape not yet selected) leaves this null, so it only selects; the second
 // tap edits. Cleared on drag, release, and cancel.
 let pendingTextEditId = null;
+// Tap-toggle for background layers, latched the same way (and for the same
+// native synchronous down+up reason) as pendingTextEditId: a pointer-down on
+// an ALREADY-selected background records its id here; a release with no
+// movement then deselects it. Movement disarms it — the gesture was a body
+// drag, not a toggle. Cleared on drag, release, and cancel.
+let pendingBackgroundDeselectId = null;
 // Hit-test in doc-space. Crude but fast — good enough for v1; tools can
 // override via `hitTest` for more precision later.
 const hitStroke = (stroke, p) => {
@@ -100,6 +107,25 @@ tileScaleFactor = doc.tileScaleFactor) => {
     return null;
 };
 const translatePatch = (elementKind, id, doc, delta) => {
+    if (elementKind === 'background') {
+        // Looked up through the normalized view so a legacy single-image doc's
+        // synthesized layer is draggable too — the dedicated op materializes the
+        // array on apply.
+        const layer = backgroundLayerById(doc, id);
+        if (!layer)
+            return null;
+        return {
+            op: 'updateBackgroundImage',
+            id,
+            patch: {
+                transform: {
+                    ...layer.transform,
+                    x: layer.transform.x + delta.x,
+                    y: layer.transform.y + delta.y,
+                },
+            },
+        };
+    }
     if (elementKind === 'measurement') {
         const m = doc.placedMeasurements.find((x) => x.id === id);
         if (!m)
@@ -417,17 +443,83 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
         ],
     };
 };
+// --- Background layers (shared by the native UI-thread drag via
+// DragSelectionConfig AND the web pointer handlers — one source of truth).
+// Backgrounds can cover the whole document, so they never join the general
+// hit-test: a tap selects one only when every stroke/shape/measurement
+// misses, and a drag translates one only when it is ALREADY selected — the
+// layout tool's two-step model, which keeps a full-bleed background from
+// hijacking pan/marquee gestures. ---
+// 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;
+const backgroundLayerById = (doc, id) => backgroundLayersOf(doc.viewport).find((l) => l.id === id) ?? null;
+const pointInBackgroundLayer = (layer, p) => {
+    const r = backgroundLayerDocRect(layer);
+    return (p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height);
+};
+// Topmost background layer under a world point (reverse array order — later
+// layers draw on top). Point-in-doc-rect, no padding: a background is a big
+// target already.
+const findBackgroundHit = (doc, world) => {
+    const layers = backgroundLayersOf(doc.viewport);
+    for (let i = layers.length - 1; i >= 0; i--) {
+        if (pointInBackgroundLayer(layers[i], world)) {
+            return { id: layers[i].id };
+        }
+    }
+    return null;
+};
+// Topmost ALREADY-selected background layer under a world point. The drag
+// paths call this only after the general hit-test misses, so annotation
+// elements always win a grab over the background beneath them.
+const findSelectedBackgroundHit = (doc, world, selectedIds) => {
+    const layers = backgroundLayersOf(doc.viewport);
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (!selectedIds.includes(layer.id))
+            continue;
+        if (pointInBackgroundLayer(layer, world)) {
+            return { id: layer.id, kind: 'background' };
+        }
+    }
+    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) => {
+    const r = backgroundLayerDocRect(layer);
+    const maxDim = Math.max(r.width, r.height);
+    if (!(maxDim > 0))
+        return null;
+    return {
+        pivot: { x: r.x, y: r.y },
+        handle: { x: r.x + r.width, y: r.y + r.height },
+        minScale: MIN_BACKGROUND_DOC_EXTENT / maxDim,
+        maxScale: MAX_BACKGROUND_DOC_EXTENT / maxDim,
+    };
+};
 // --- Text-shape resize (corner-scale about the top-left anchor; shared by the
 // native UI-thread drag via DragSelectionConfig AND the web pointer handlers) ---
-// Resize geometry when the (selected) text shape's corner handle is under
-// `world`, else null. The handle is drawn on the padded selection box's
-// bottom-right corner (see AnnotationCanvasSkia); grab radius matches the
-// measurement endpoint handles.
+// 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.
 const findResizeHandleHit = (doc, id, world, zoom) => {
     const s = doc.shapes.find((x) => x.id === id);
-    if (!s)
-        return null;
-    const geom = textResizeGeometry(s);
+    const layer = s ? null : backgroundLayerById(doc, id);
+    const geom = s
+        ? textResizeGeometry(s)
+        : layer
+            ? backgroundResizeGeometry(layer)
+            : null;
     if (!geom)
         return null;
     const r2 = (HANDLE_GRAB_PX / zoom) ** 2;
@@ -435,13 +527,38 @@ const findResizeHandleHit = (doc, id, world, zoom) => {
     const dy = world.y - geom.handle.y;
     return dx * dx + dy * dy <= r2 ? geom : null;
 };
-// Scale the text shape's fontSize by the drag (clamped to the geometry's
-// scale range, so it matches the native live preview exactly). The anchor —
-// the scale pivot — is untouched.
+// 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) => {
     const s = doc.shapes.find((x) => x.id === id);
-    if (!s)
-        return null;
+    if (!s) {
+        const layer = backgroundLayerById(doc, id);
+        if (!layer)
+            return null;
+        const geom = backgroundResizeGeometry(layer);
+        if (!geom)
+            return null;
+        const scale = resizeScaleFromDrag(geom, delta);
+        return {
+            ops: [
+                {
+                    op: 'updateBackgroundImage',
+                    id,
+                    patch: {
+                        transform: {
+                            ...layer.transform,
+                            scaleX: layer.transform.scaleX * scale,
+                            scaleY: layer.transform.scaleY * scale,
+                        },
+                    },
+                },
+            ],
+        };
+    }
     const geom = textResizeGeometry(s);
     if (!geom)
         return null;
@@ -497,6 +614,8 @@ export const createSelectTool = (options = {}) => ({
         buildShapeEndpointPatch: shapeEndpointPatch,
         hitTestResizeHandle: findResizeHandleHit,
         buildResizePatch: resizePatch,
+        hitTestBackground: findBackgroundHit,
+        hitTestSelectedBackground: findSelectedBackgroundHit,
         hitTestRectCorner: findRectCornerHit,
         buildRectCornerPatch: rectCornerPatch,
         hitTestShapeCorner: findShapeCornerHit,
@@ -508,10 +627,12 @@ export const createSelectTool = (options = {}) => ({
     onPointerDown(event, ctx) {
         const { world } = event;
         const zoom = ctx.viewport.state.zoom;
-        // Reset the re-tap-to-edit latch; only a body grab of an already-selected
-        // text shape (below) re-arms it. Grabbing a handle or empty canvas leaves
-        // it cleared, so neither can leak an edit into the next release.
+        // Reset the re-tap latches; only a body grab of an already-selected text
+        // shape / background layer (below) re-arms them. Grabbing a handle or
+        // empty canvas leaves them cleared, so neither can leak an edit or a
+        // deselect into the next release.
         pendingTextEditId = null;
+        pendingBackgroundDeselectId = null;
         // Endpoint/resize handles show only on the selected element — check first,
         // UNLESS the grab is on that element's tile: the tile is the move/slide
         // affordance and must win over a handle sitting under it, so a selected
@@ -549,7 +670,12 @@ export const createSelectTool = (options = {}) => ({
                 return {
                     kind: 'dragging',
                     id: selId,
-                    elementKind: 'shape',
+                    // findResizeHandleHit serves both text shapes and background
+                    // layers; only the state's bookkeeping cares which one this is
+                    // (dragPatch keys 'resize' off the mode alone).
+                    elementKind: backgroundLayerById(ctx.document, selId)
+                        ? 'background'
+                        : 'shape',
                     mode: 'resize',
                     start: world,
                     delta: { x: 0, y: 0 },
@@ -584,6 +710,30 @@ export const createSelectTool = (options = {}) => ({
         }
         const hit = findHit(ctx.document, world, zoom, ctx.tileViewportScale, ctx.tileScaleFactor);
         if (!hit) {
+            // Background layers only get a look-in when every annotation element
+            // misses — they can cover the whole document, so elements above always
+            // win. An already-selected background grabs as a body drag (and arms
+            // the tap-toggle: a release with no movement deselects it).
+            const selectedBg = findSelectedBackgroundHit(ctx.document, world, ctx.selection?.ids ?? []);
+            if (selectedBg) {
+                pendingBackgroundDeselectId = selectedBg.id;
+                return {
+                    kind: 'dragging',
+                    id: selectedBg.id,
+                    elementKind: 'background',
+                    mode: 'move',
+                    start: world,
+                    delta: { x: 0, y: 0 },
+                };
+            }
+            // An unselected background selects only — the gesture is consumed (no
+            // pan, no drag): translating it takes a second gesture once selected,
+            // the layout tool's two-step model.
+            const bg = findBackgroundHit(ctx.document, world);
+            if (bg) {
+                ctx.setSelection({ ids: [bg.id] });
+                return { kind: 'idle' };
+            }
             ctx.setSelection(null);
             // Nothing under the pointer: with panOnEmptyDrag the gesture pans the
             // viewport instead of dead-ending, so bare drags navigate the canvas.
@@ -630,9 +780,12 @@ export const createSelectTool = (options = {}) => ({
             x: event.world.x - s.start.x,
             y: event.world.y - s.start.y,
         };
-        // Any real movement turns this into a drag, not a re-tap — disarm the edit.
-        if (delta.x !== 0 || delta.y !== 0)
+        // Any real movement turns this into a drag, not a re-tap — disarm the
+        // edit and the background deselect toggle.
+        if (delta.x !== 0 || delta.y !== 0) {
             pendingTextEditId = null;
+            pendingBackgroundDeselectId = null;
+        }
         const patch = dragPatch(s, ctx.document, delta, ctx.viewport.state.zoom);
         if (patch)
             ctx.preview(patch);
@@ -641,14 +794,24 @@ export const createSelectTool = (options = {}) => ({
     onPointerUp(_event, ctx, state) {
         const editId = pendingTextEditId;
         pendingTextEditId = null;
+        const deselectId = pendingBackgroundDeselectId;
+        pendingBackgroundDeselectId = null;
         const s = state;
-        // A moved selection commits its drag and is never a tap-to-edit.
+        // A moved selection commits its drag and is never a tap-to-edit/-toggle.
         if (s?.kind === 'dragging' && (s.delta.x !== 0 || s.delta.y !== 0)) {
             const patch = dragPatch(s, ctx.document, s.delta, ctx.viewport.state.zoom);
             if (patch)
                 ctx.commit(patch);
             return;
         }
+        // No movement on an already-selected background: the tap toggles it back
+        // off. `deselectId` was latched on the down for the same synchronous
+        // native down+up reason as `editId` below.
+        if (deselectId) {
+            if (ctx.selection?.ids.includes(deselectId))
+                ctx.setSelection(null);
+            return;
+        }
         // No movement: re-tapping an already-selected text shape re-opens its
         // editor (the same edit flow as tapping it with the text tool, via the
         // shared editTextShape). `editId` was latched on the down, so this survives
@@ -661,6 +824,7 @@ export const createSelectTool = (options = {}) => ({
     },
     onCancel(_state, ctx) {
         pendingTextEditId = null;
+        pendingBackgroundDeselectId = null;
         ctx.preview({ ops: [] });
     },
     hitTest(element, p) {

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,13 +1,15 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { resolveTileScaleFactor, stampTileDims, STAMP_TILE_SIZE, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
-import { createViewportApi, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
+import { createViewportApi, fitRectToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
+import { backgroundLayerDocRect, backgroundLayersOf, backgroundLayersUnionRect, } from './backgroundLayers.js';
 import { buildRemoveMeasurementOps, recomputeAnchor, rectCenter, DEFAULT_LINE_POS, } from './measurementGeometry.js';
 // The viewport that frames the document's content inside a screen rect of the
-// canvas box. When a background image is present we fit its rendered rect (so
-// the whole image shows, filling the rect regardless of its pixel resolution —
-// never the native-resolution top-left crop a 1:1 viewport gives a high-res
-// image); otherwise we fit the document rect. Placed tiles count as content
+// canvas box. When background images are present we fit the union of their
+// rendered rects (so every image shows whole, filling the rect regardless of
+// pixel resolution — never the native-resolution top-left crop a 1:1 viewport
+// gives a high-res image); otherwise we fit the document rect. Placed tiles
+// count as content
 // too: authors routinely drop them AROUND the image (dimension labels sit
 // outside the object they measure), and a fit framed on the image alone opens
 // with those tiles off-screen — so the rect is widened to the union of the
@@ -22,10 +24,12 @@ const computeContentFitRect = (canvas, rect) => {
     if (!(rect.width > 0) || !(rect.height > 0))
         return DEFAULT_VIEWPORT;
     const { viewport } = canvas;
-    const bg = viewport.backgroundImage;
-    const baseRect = bg
-        ? imageDocRect(bg.widthPx, bg.heightPx, viewport.width, viewport.height, viewport.backgroundFit ?? 'contain')
-        : { x: 0, y: 0, width: viewport.width, height: viewport.height };
+    const baseRect = backgroundLayersUnionRect(backgroundLayersOf(viewport)) ?? {
+        x: 0,
+        y: 0,
+        width: viewport.width,
+        height: viewport.height,
+    };
     let minX = baseRect.x;
     let minY = baseRect.y;
     let maxX = baseRect.x + baseRect.width;
@@ -64,20 +68,25 @@ const computeContentFitRect = (canvas, rect) => {
     };
 };
 const computeContentFit = (canvas, width, height) => computeContentFitRect(canvas, { x: 0, y: 0, width, height });
-// Content-fit zoom of the DOCUMENT alone — the background image's rendered
-// rect when present, the document rect otherwise, deliberately ignoring
-// placed tiles — into the full canvas box. This is the stable reference zoom
-// for tile sizing (see tileViewportScale below): at this zoom a tile renders
-// at exactly its slider size. computeContentFitRect's tile-extended union
-// would make the reference move whenever a tile is dragged outside the image
-// (every tile on the canvas would resize); the document rect can't.
+// Content-fit zoom of the DOCUMENT alone — the FIRST background layer's
+// rendered rect when present, the document rect otherwise, deliberately
+// ignoring placed tiles — into the full canvas box. This is the stable
+// reference zoom for tile sizing (see tileViewportScale below): at this zoom
+// a tile renders at exactly its slider size. computeContentFitRect's
+// tile-extended union would make the reference move whenever a tile is
+// dragged outside the image (every tile on the canvas would resize); the
+// document rect can't. The reference is pinned to the first layer — never
+// the layer union — for the same reason: adding, dragging, or scaling a
+// SECOND image must not silently resize (and re-hit-test) every placed tile
+// on the canvas. For a single-image doc the first layer's rect is exactly
+// the legacy fit rect, so existing canvases keep their tile sizes.
 const computeBaseFitZoom = (canvas, width, height) => {
     if (!(width > 0) || !(height > 0))
         return 1;
     const { viewport } = canvas;
-    const bg = viewport.backgroundImage;
-    const baseRect = bg
-        ? imageDocRect(bg.widthPx, bg.heightPx, viewport.width, viewport.height, viewport.backgroundFit ?? 'contain')
+    const first = backgroundLayersOf(viewport)[0];
+    const baseRect = first
+        ? backgroundLayerDocRect(first)
         : { x: 0, y: 0, width: viewport.width, height: viewport.height };
     return fitRectToScreen(baseRect, width, height).zoom;
 };
@@ -120,7 +129,7 @@ export const useAnnotationCanvasState = (props) => {
     useEffect(() => {
         if (didInitialFitRef.current)
             return;
-        if (!canvas.viewport.backgroundImage)
+        if (backgroundLayersOf(canvas.viewport).length === 0)
             return;
         if (!(width > 0) || !(height > 0))
             return;

package/dist/annotation/canvas/viewport.js

@@ -29,13 +29,14 @@ export const fitToScreen = (docWidth, docHeight, screenWidth, screenHeight, padd
         pan: { x: -offsetX / zoom, y: -offsetY / zoom },
     };
 };
-// The doc-space rectangle a background image occupies, given the image's
-// intrinsic pixel size, the document dimensions, and the fit mode. This mirrors
-// the math in BackgroundImageElement (which renders the image into this rect),
-// so "fit the image to the screen" lines up exactly with what is drawn.
+// The doc-space rectangle a legacy fit-placed background image occupies,
+// given the image's intrinsic pixel size, the document dimensions, and the
+// fit mode. backgroundLayersOf synthesizes the legacy slot's layer transform
+// from this rect, so "fit the image to the screen" lines up exactly with what
+// is drawn.
 export const imageDocRect = (imgW, imgH, docW, docH, fit = 'contain') => {
-    // Unknown/zero image dimensions (or an explicit stretch) fill the doc — the
-    // same guard BackgroundImageElement uses to avoid NaN geometry.
+    // Unknown/zero image dimensions (or an explicit stretch) fill the doc,
+    // avoiding NaN geometry from a division by zero.
     if (!(imgW > 0) || !(imgH > 0) || fit === 'stretch') {
         return { x: 0, y: 0, width: docW, height: docH };
     }

package/dist/annotation/data/AnnotationDataProvider.d.ts

@@ -75,7 +75,7 @@ export interface AnnotationDataProvider {
     list(scope: AnnotationScope, onNext: (files: AnnotationFileSummary[]) => void, onError?: (err: Error) => void): Unsubscribe;
     subscribeGroupMeasurements(scope: JobGroupScope, onNext: (measurements: Measurement[]) => void, onError?: (err: Error) => void): Unsubscribe;
     subscribeJobMeasurements(scope: JobScope, onNext: (measurements: Measurement[]) => void, onError?: (err: Error) => void): Unsubscribe;
-    uploadImage(scope: AnnotationScope, fileId: string, role: 'background' | 'thumbnail', blob: ImageBlob): Promise<UploadedImageRef>;
+    uploadImage(scope: AnnotationScope, fileId: string, role: string, blob: ImageBlob): Promise<UploadedImageRef>;
     getImageUrl(scope: AnnotationScope, fileId: string, storagePath: string): Promise<string>;
     deleteImage(scope: AnnotationScope, fileId: string, storagePath: string): Promise<void>;
 }

package/dist/annotation/data/InMemoryAnnotationProvider.d.ts

@@ -18,7 +18,7 @@ export declare class InMemoryAnnotationProvider implements AnnotationDataProvide
     list(scope: AnnotationScope, onNext: (files: AnnotationFileSummary[]) => void): Unsubscribe;
     subscribeGroupMeasurements(scope: JobGroupScope, onNext: (measurements: Measurement[]) => void): Unsubscribe;
     subscribeJobMeasurements(scope: JobScope, onNext: (measurements: Measurement[]) => void): Unsubscribe;
-    uploadImage(scope: AnnotationScope, fileId: string, role: 'background' | 'thumbnail', blob: ImageBlob): Promise<UploadedImageRef>;
+    uploadImage(scope: AnnotationScope, fileId: string, role: string, blob: ImageBlob): Promise<UploadedImageRef>;
     getImageUrl(_scope: AnnotationScope, fileId: string, storagePath: string): Promise<string>;
     deleteImage(_scope: AnnotationScope, fileId: string, storagePath: string): Promise<void>;
     private getBucket;

package/dist/annotation/data/hooks/useAnnotationCanvasDoc.d.ts

@@ -1,4 +1,4 @@
-import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport, type BackgroundFit } from '../../../types/annotation.js';
+import { type AnnotationBackgroundLayer, type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport, type BackgroundFit } from '../../../types/annotation.js';
 import type { AnnotationScope, ImageBlob } from '../AnnotationDataProvider.js';
 export type SaveStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error';
 export interface UseAnnotationCanvasDocOptions {
@@ -26,6 +26,12 @@ export interface UseAnnotationCanvasDocResult {
     save: () => Promise<void>;
     refreshThumbnail: () => Promise<void>;
     ensureFileId: () => Promise<string>;
+    addBackgroundImage: (blob: ImageBlob, dims: {
+        width: number;
+        height: number;
+    }) => Promise<string>;
+    updateBackgroundImage: (id: string, patch: Partial<Omit<AnnotationBackgroundLayer, 'id'>>) => void;
+    removeBackgroundImage: (id: string) => Promise<void>;
     setBackgroundImage: (blob: ImageBlob, dims: {
         width: number;
         height: number;

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

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, createEmptyCanvasState, } from '../../../types/annotation.js';
+import { backgroundLayersOf, placeNewBackgroundLayer, } from '../../canvas/backgroundLayers.js';
+import { imageDocRect } from '../../canvas/viewport.js';
 import { FileUploadType } from '../../../types/firestore.js';
 import { useAnnotationDoc } from './useAnnotationDoc.js';
 import { useAnnotationMutations } from './useAnnotationMutations.js';
@@ -26,6 +28,15 @@ const buildFileData = (fileType, isLabel, canvas, canvasRev) => ({
 // AnnotationFileData). Uniqueness only needs to hold across the handful of
 // clients that ever touch one annotation doc.
 const makeClientId = () => `${Date.now().toString(36)}-${Math.floor(Math.random() * 0x100000000).toString(36)}`;
+// Background layer ids carry the same uniqueness contract as the tools'
+// stroke/shape ids (timestamp + module counter): unique within one document
+// across the handful of clients that touch it. Never 'background-legacy' —
+// that id is reserved for the layer synthesized from the legacy single slot.
+let backgroundIdCounter = 0;
+const makeBackgroundLayerId = () => `background-${Date.now().toString(36)}-${(backgroundIdCounter++).toString(36)}`;
+// The renderer decodes 'svg' via Skia's SVG module and everything else via
+// the bitmap decoder, so an SVG left unstamped silently fails to draw.
+const backgroundFormatOf = (blob) => blob.contentType === 'image/svg+xml' ? 'svg' : 'raster';
 // Orchestrates load + auto-save for the annotation canvas. Hydrates the working
 // state from the persisted doc, applies commits optimistically, and persists
 // (debounced) through the data provider — creating the file on first save when
@@ -354,45 +365,133 @@ export const useAnnotationCanvasDoc = (options) => {
         }
         return id;
     }, [flush, fallbackViewport]);
-    const setBackgroundImage = useCallback(async (blob, dims, fit = 'contain') => {
-        const id = await ensureFileId();
-        const ref = await uploadImage(id, 'background', blob);
+    const addBackgroundImage = useCallback(async (blob, dims) => {
+        const fileId = await ensureFileId();
+        const layerId = makeBackgroundLayerId();
+        const ref = await uploadImage(fileId, `backgrounds/${layerId}`, blob);
+        // ensureFileId seeds the working state for a never-saved canvas, but a
+        // still-hydrating existing doc can reach here with no working state —
+        // fall back to the same empty canvas hydration would start from.
+        const { viewport } = workingRef.current ?? createEmptyCanvasState(fallbackViewport);
         onCommit({
             ops: [
                 {
-                    op: 'setViewport',
-                    patch: {
-                        backgroundImage: {
-                            storagePath: ref.storagePath,
-                            downloadUrl: ref.downloadUrl,
-                            widthPx: dims.width,
-                            heightPx: dims.height,
-                        },
-                        backgroundFit: fit,
+                    op: 'addBackgroundImage',
+                    image: {
+                        id: layerId,
+                        storagePath: ref.storagePath,
+                        downloadUrl: ref.downloadUrl,
+                        widthPx: dims.width,
+                        heightPx: dims.height,
+                        format: backgroundFormatOf(blob),
+                        transform: placeNewBackgroundLayer(backgroundLayersOf(viewport), dims, viewport),
                     },
                 },
             ],
         });
-    }, [ensureFileId, uploadImage, onCommit]);
-    const clearBackgroundImage = useCallback(async () => {
-        const bg = workingRef.current?.viewport.backgroundImage;
-        const id = fileIdRef.current ?? createdIdRef.current;
-        if (bg && id) {
+        return layerId;
+    }, [ensureFileId, uploadImage, onCommit, fallbackViewport]);
+    const updateBackgroundImage = useCallback((id, patch) => {
+        onCommit({ ops: [{ op: 'updateBackgroundImage', id, patch }] });
+    }, [onCommit]);
+    const removeBackgroundImage = useCallback(async (id) => {
+        const viewport = workingRef.current?.viewport;
+        const layer = viewport
+            ? backgroundLayersOf(viewport).find((l) => l.id === id)
+            : undefined;
+        const fileId = fileIdRef.current ?? createdIdRef.current;
+        if (layer && fileId) {
             try {
-                await deleteImage(id, bg.storagePath);
+                await deleteImage(fileId, layer.storagePath);
             }
             catch (e) {
-                // Non-fatal: still clear the viewport reference even if the storage
-                // object is already gone.
+                // Non-fatal: still remove the layer even if the storage object is
+                // already gone.
                 console.warn('[useAnnotationCanvasDoc] failed to delete background image', e);
             }
         }
+        onCommit({ ops: [{ op: 'removeBackgroundImage', id }] });
+    }, [deleteImage, onCommit]);
+    const setBackgroundImage = useCallback(async (blob, dims, fit = 'contain') => {
+        const fileId = await ensureFileId();
+        const prior = workingRef.current
+            ? backgroundLayersOf(workingRef.current.viewport)
+            : [];
+        // Upload before touching the prior layers' objects: a failed upload
+        // must leave the doc — and every object it references — intact. The
+        // prior objects are deleted only after the replacement is committed.
+        const layerId = makeBackgroundLayerId();
+        const ref = await uploadImage(fileId, `backgrounds/${layerId}`, blob);
+        const { viewport } = workingRef.current ?? createEmptyCanvasState(fallbackViewport);
+        // The fit argument still decides where the replacement lands (the same
+        // imageDocRect placement the legacy single slot rendered at), so
+        // existing callers keep their visual behavior. `backgroundFit` is also
+        // still written: old clients render the mirrored legacy slot with it.
+        const rect = imageDocRect(dims.width, dims.height, viewport.width, viewport.height, fit);
         onCommit({
             ops: [
+                ...prior.map((l) => ({
+                    op: 'removeBackgroundImage',
+                    id: l.id,
+                })),
                 {
-                    op: 'setViewport',
-                    patch: { backgroundImage: undefined, backgroundFit: undefined },
+                    op: 'addBackgroundImage',
+                    image: {
+                        id: layerId,
+                        storagePath: ref.storagePath,
+                        downloadUrl: ref.downloadUrl,
+                        widthPx: dims.width,
+                        heightPx: dims.height,
+                        format: backgroundFormatOf(blob),
+                        transform: {
+                            x: rect.x,
+                            y: rect.y,
+                            scaleX: dims.width > 0 ? rect.width / dims.width : 1,
+                            scaleY: dims.height > 0 ? rect.height / dims.height : 1,
+                        },
+                    },
                 },
+                { op: 'setViewport', patch: { backgroundFit: fit } },
+            ],
+        });
+        for (const layer of prior) {
+            try {
+                await deleteImage(fileId, layer.storagePath);
+            }
+            catch (e) {
+                // Non-fatal: the replacement is already committed; an undeleted
+                // prior object is merely orphaned.
+                console.warn('[useAnnotationCanvasDoc] failed to delete background image', e);
+            }
+        }
+    }, [ensureFileId, uploadImage, deleteImage, onCommit, fallbackViewport]);
+    const clearBackgroundImage = useCallback(async () => {
+        const layers = workingRef.current
+            ? backgroundLayersOf(workingRef.current.viewport)
+            : [];
+        const id = fileIdRef.current ?? createdIdRef.current;
+        if (id) {
+            for (const layer of layers) {
+                try {
+                    await deleteImage(id, layer.storagePath);
+                }
+                catch (e) {
+                    // Non-fatal: still clear the viewport reference even if the storage
+                    // object is already gone.
+                    console.warn('[useAnnotationCanvasDoc] failed to delete background image', e);
+                }
+            }
+        }
+        onCommit({
+            ops: [
+                ...layers.map((l) => ({
+                    op: 'removeBackgroundImage',
+                    id: l.id,
+                })),
+                // A fit means nothing without a background; clearing it preserves
+                // this method's original contract. The explicit `undefined` is
+                // stripped by the write path's JSON round-trip.
+                { op: 'setViewport', patch: { backgroundFit: undefined } },
             ],
         });
     }, [deleteImage, onCommit]);
@@ -414,6 +513,9 @@ export const useAnnotationCanvasDoc = (options) => {
         save,
         refreshThumbnail,
         ensureFileId,
+        addBackgroundImage,
+        updateBackgroundImage,
+        removeBackgroundImage,
         setBackgroundImage,
         clearBackgroundImage,
     };

package/dist/annotation/data/hooks/useAnnotationMutations.d.ts

@@ -3,7 +3,7 @@ export interface AnnotationMutations {
     create(seed: Partial<AnnotationFile>): Promise<string>;
     update(fileId: string, patch: AnnotationFilePatch): Promise<void>;
     remove(fileId: string): Promise<void>;
-    uploadImage(fileId: string, role: 'background' | 'thumbnail', blob: ImageBlob): Promise<UploadedImageRef>;
+    uploadImage(fileId: string, role: string, blob: ImageBlob): Promise<UploadedImageRef>;
     deleteImage(fileId: string, storagePath: string): Promise<void>;
 }
 export declare const useAnnotationMutations: (scope: AnnotationScope) => AnnotationMutations;

package/dist/exports.d.ts

@@ -31,6 +31,7 @@ export type { MeasurementRef, PickMeasurement, } from './annotation/canvas/measu
 export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './annotation/canvas/measurementStampOverlay.js';
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, type StampTileDims, } from './annotation/canvas/stampLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './annotation/canvas/viewport.js';
+export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.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';