@reekon-tools/boldr-utils 1.11.0 → 1.13.0

package/dist/annotation/canvas/groupHeaderLayout.js

@@ -0,0 +1,115 @@
+// Presentation model for the group-header chip placed on an annotation canvas
+// (`PlacedMeasurementRef.isGroupHeader`), shared by mobile and web.
+//
+// The chip itself can't be shared — this package ships DOM and React Native
+// forks of the canvas host, and there is no react-native-web in the graph, so
+// a single component would only render on one of them. What CAN be shared is
+// everything that isn't a view node: which badges a header shows, what they
+// say, what colour they are, and every measurement in the Figma frames. Both
+// hosts render the SAME descriptor into ~40 lines of platform view code, so a
+// change to the header's content or metrics lands in one place.
+//
+// Figma (BOLDR PRO / APP STRUCTURE, "HEADER SETTINGS - MVP" 490:4189):
+//   491:5371 expanded group · 491:5654 collapsed group
+//   491:5381 expanded form  · 491:5659 collapsed form
+// Asana 1217382797393698.
+import { GroupType } from '../../types/firestore.js';
+import { GeneralColors, TileColors, YellowColors } from '../../theme/colors.js';
+import { GROUP_HEADER_DESIGN } from './stampLayout.js';
+// Every length here is in the DESIGN space the frames were drawn in — the
+// 200×56 / 90×65 boxes of GROUP_HEADER_DESIGN. Hosts lay the chip out at that
+// natural size and uniformly transform-scale it into the overlay box
+// stampTileDims hands them, so these numbers never need scaling by hand.
+export const GROUP_HEADER_STYLE = {
+    // Outer chip.
+    background: GeneralColors.grey2,
+    radius: 8,
+    padding: 5,
+    // Selection ring. Drawn INSIDE the chip's box (the footprint is the
+    // hit-test box too, so an outset ring would lie about what is grabbable).
+    selectedBorderWidth: 3,
+    selectedBorderColor: YellowColors.mainYellow,
+    // Index badges.
+    badgeHeight: 25,
+    badgeRadius: 4,
+    badgeFontSize: 13,
+    badgeTextColor: GeneralColors.white,
+    // Gap between the two badges of a form header: horizontal when expanded
+    // (they sit side by side), vertical when collapsed (they stack).
+    badgeGapExpanded: 5,
+    badgeGapCollapsed: 5,
+    // Group name, expanded only.
+    nameGap: 3,
+    nameFontSize: 15,
+    nameColor: GeneralColors.white,
+    // Globe glyph that stands in for the index badge on the default group.
+    globeSize: 17,
+    globeColor: GeneralColors.white,
+};
+/**
+ * Resolve what a header chip shows. `group` is looked up live by the host from
+ * `placed.groupId` so renames and re-indexes appear without touching the
+ * canvas document; `section` is that group's section, needed only for a FORM
+ * header's "# Table N". Both may be undefined — a group deleted after its
+ * header was placed still has to render something rather than crash.
+ */
+export const describeGroupHeader = ({ group, section, collapsed = false, }) => {
+    const design = collapsed
+        ? GROUP_HEADER_DESIGN.collapsed
+        : GROUP_HEADER_DESIGN.expanded;
+    const base = {
+        collapsed,
+        name: collapsed ? null : (group?.name ?? 'Group'),
+        design,
+    };
+    if (!group)
+        return { ...base, badges: [], showGlobe: false };
+    // Default group (index 0): no number to show — the globe chip stands in.
+    if (group.groupIndex === 0) {
+        return {
+            ...base,
+            showGlobe: true,
+            badges: [{ key: 'group', text: '', background: TileColors.darkBlue }],
+        };
+    }
+    const badges = [];
+    if (group.type === GroupType.FORM) {
+        // "# Table N" only when the section resolved — a form header with a
+        // missing section drops to its "# Form N" badge alone rather than
+        // rendering an empty chip.
+        if (typeof section?.index === 'number') {
+            badges.push({
+                key: 'table',
+                text: `# Table ${section.index + 1}`,
+                background: TileColors.lightBlue1,
+            });
+        }
+        badges.push({
+            key: 'form',
+            text: `# Form ${group.groupIndex + 1}`,
+            background: TileColors.activeBlue,
+        });
+    }
+    else {
+        badges.push({
+            key: 'group',
+            text: `# Group ${group.groupIndex + 1}`,
+            background: TileColors.darkBlue,
+        });
+    }
+    return { ...base, badges, showGlobe: false };
+};
+/**
+ * Signature of everything `describeGroupHeader` would render, for hosts that
+ * cache on tile content (mobile re-bakes its canvas thumbnail when this
+ * changes). Kept beside the resolver so the two can't drift.
+ */
+export const groupHeaderSignature = (input) => {
+    const d = describeGroupHeader(input);
+    return [
+        d.collapsed ? 'c' : 'e',
+        d.showGlobe ? 'globe' : '',
+        d.badges.map((b) => `${b.key}:${b.text}`).join(','),
+        d.name ?? '',
+    ].join('~');
+};

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

@@ -1,7 +1,20 @@
 import type { AnnotationCanvasState, PlacedMeasurementRef, TileScalePlatform } from '../../types/annotation.js';
 export declare const STAMP_TILE_SIZE = 96;
 export declare const GROUP_HEADER_TILE_WIDTH = 240;
-export declare const GROUP_HEADER_TILE_HEIGHT = 64;
+export declare const GROUP_HEADER_TILE_HEIGHT = 67.2;
+export declare const GROUP_HEADER_DESIGN: {
+    readonly expanded: {
+        readonly width: 200;
+        readonly height: 56;
+    };
+    readonly collapsed: {
+        readonly width: 90;
+        readonly height: 65;
+    };
+};
+export declare const GROUP_HEADER_COLLAPSED_WIDTH: number;
+export declare const GROUP_HEADER_COLLAPSED_HEIGHT: number;
+export declare const groupHeaderBaseDims: (collapsed?: boolean) => StampTileDims;
 export declare const DEFAULT_TILE_SCALE = 1;
 export declare const TILE_SCALE_MIN = 0.4;
 export declare const TILE_SCALE_MAX = 2;
@@ -15,4 +28,4 @@ export interface StampTileDims {
     width: number;
     height: number;
 }
-export declare const stampTileDims: (m: Pick<PlacedMeasurementRef, "scale" | "isGroupHeader">, tileScaleFactor?: number, viewportScale?: number) => StampTileDims;
+export declare const stampTileDims: (m: Pick<PlacedMeasurementRef, "scale" | "isGroupHeader" | "collapsed">, tileScaleFactor?: number, viewportScale?: number) => StampTileDims;

package/dist/annotation/canvas/stampLayout.js

@@ -15,13 +15,48 @@
 // tile-scale slider against blank tiles saw their tiles balloon once
 // populated (Asana 1216233394800417).
 export const STAMP_TILE_SIZE = 96;
-// Base footprint of a group-header chip (`isGroupHeader`) — a wide pill
-// rather than the square tile, same 3.75:1 ratio as the legacy Nutrient
-// header stamp (150×40). Sized exactly like STAMP_TILE_SIZE: `placed.scale`
-// × the document-wide tile-scale factor, scaling with zoom from the
-// content-fit reference.
+// Base footprint of an EXPANDED group-header chip (`isGroupHeader`) — a wide
+// pill rather than the square tile. Sized exactly like STAMP_TILE_SIZE:
+// `placed.scale` × the document-wide tile-scale factor, scaling with zoom from
+// the content-fit reference. The width is the header's established base and
+// does not change; the height now follows the design's 200×56 proportion
+// (see GROUP_HEADER_DESIGN below) rather than the legacy Nutrient stamp's
+// 150×40, a ~5% difference on existing documents.
 export const GROUP_HEADER_TILE_WIDTH = 240;
-export const GROUP_HEADER_TILE_HEIGHT = 64;
+export const GROUP_HEADER_TILE_HEIGHT = 67.2;
+// Natural design-space size of each header state, straight off the Figma
+// frames (491:5371 expanded / 491:5654 collapsed — the two form variants,
+// 491:5381 / 491:5659, use the same boxes). Renderers lay the chip out at
+// THESE dimensions and uniformly transform-scale it into the overlay box, the
+// same natural-size-then-scale pattern the measurement tiles use, so type and
+// badges keep their proportions under the tile-scale slider. Collapsed is one
+// fixed box for both group and form headers — a form stacks its two badges to
+// fill it, a group centers its single badge — so a canvas of collapsed
+// headers reads as a tidy row of equal chips.
+export const GROUP_HEADER_DESIGN = {
+    expanded: { width: 200, height: 56 },
+    collapsed: { width: 90, height: 65 },
+};
+// Design units → base units. Pinned by the expanded header keeping its
+// established 240-unit width, and applied to BOTH states so the two share one
+// scale: a badge is the same size whether its header is expanded or collapsed.
+const HEADER_BASE_SCALE = GROUP_HEADER_TILE_WIDTH / GROUP_HEADER_DESIGN.expanded.width;
+// Base footprint of a COLLAPSED group-header chip — the design's 90×65 at the
+// same scale. Wider-than-tall no longer holds here: a collapsed header is
+// slightly TALLER than an expanded one (it stacks badges where the expanded
+// one puts them side by side and hangs the name underneath).
+export const GROUP_HEADER_COLLAPSED_WIDTH = GROUP_HEADER_DESIGN.collapsed.width * HEADER_BASE_SCALE;
+export const GROUP_HEADER_COLLAPSED_HEIGHT = GROUP_HEADER_DESIGN.collapsed.height * HEADER_BASE_SCALE;
+// Unscaled footprint of a group header in each state — the one place the
+// expanded/collapsed box choice is made. Callers that already hold a
+// PlacedMeasurementRef should go through stampTileDims instead, which folds in
+// `scale`, the document-wide factor and the zoom.
+export const groupHeaderBaseDims = (collapsed) => collapsed
+    ? {
+        width: GROUP_HEADER_COLLAPSED_WIDTH,
+        height: GROUP_HEADER_COLLAPSED_HEIGHT,
+    }
+    : { width: GROUP_HEADER_TILE_WIDTH, height: GROUP_HEADER_TILE_HEIGHT };
 // Document-wide tile scale factor: one knob that shrinks/grows EVERY
 // measurement tile on the canvas at once, on top of each tile's own `scale`.
 // Lets a user pull tiles down on a dense drawing where lines crowd together,
@@ -103,10 +138,9 @@ export const isUnassociatedStamp = (m) => !m.isGroupHeader && !m.measurementId &
 export const stampTileSize = (m, tileScaleFactor = DEFAULT_TILE_SCALE, viewportScale = 1) => STAMP_TILE_SIZE * (m.scale ?? 1) * tileScaleFactor * viewportScale;
 export const stampTileDims = (m, tileScaleFactor = DEFAULT_TILE_SCALE, viewportScale = 1) => {
     const k = (m.scale ?? 1) * tileScaleFactor * viewportScale;
-    return m.isGroupHeader
-        ? {
-            width: GROUP_HEADER_TILE_WIDTH * k,
-            height: GROUP_HEADER_TILE_HEIGHT * k,
-        }
-        : { width: STAMP_TILE_SIZE * k, height: STAMP_TILE_SIZE * k };
+    if (!m.isGroupHeader) {
+        return { width: STAMP_TILE_SIZE * k, height: STAMP_TILE_SIZE * k };
+    }
+    const base = groupHeaderBaseDims(m.collapsed);
+    return { width: base.width * k, height: base.height * k };
 };

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.d.ts

@@ -46,6 +46,7 @@ export interface AnnotationCanvasHandle {
     placeGroupHeaderAtCenter(ref: {
         groupId: string;
     }): AnnotationElementId;
+    setGroupHeaderCollapsed(id: AnnotationElementId, collapsed: boolean): void;
     deleteSelected(): void;
 }
 export interface UseAnnotationCanvasStateProps {

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;
@@ -652,6 +661,17 @@ export const useAnnotationCanvasState = (props) => {
                 c.setSelection({ ids: [placed.id] });
                 return placed.id;
             },
+            setGroupHeaderCollapsed(id, collapsed) {
+                const c = ctxRef.current;
+                const target = c.document.placedMeasurements.find((m) => m.id === id);
+                if (!target?.isGroupHeader)
+                    return;
+                if (!!target.collapsed === collapsed)
+                    return;
+                c.commit({
+                    ops: [{ op: 'updateMeasurement', id, patch: { collapsed } }],
+                });
+            },
             deleteSelected() {
                 const c = ctxRef.current;
                 const ids = c.selection?.ids;

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