@reekon-tools/boldr-utils 1.11.0 → 1.12.0

package/dist/exports.js

@@ -36,6 +36,7 @@ export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.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, } from './annotation/canvas/stampLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } 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, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './annotation/canvas/tools/measurementStampTool.js';

package/dist/types/annotation.d.ts

@@ -96,11 +96,27 @@ export interface AnnotationBackgroundImage {
     heightPx: number;
     format?: 'raster' | 'svg';
 }
+export interface BackgroundLayerTransform {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+}
+export interface AnnotationBackgroundLayer {
+    id: AnnotationElementId;
+    storagePath: string;
+    downloadUrl: string;
+    widthPx: number;
+    heightPx: number;
+    format?: 'raster' | 'svg';
+    transform: BackgroundLayerTransform;
+}
 export interface AnnotationViewport {
     width: number;
     height: number;
     backgroundImage?: AnnotationBackgroundImage;
     backgroundFit?: BackgroundFit;
+    backgroundImages?: AnnotationBackgroundLayer[];
 }
 export type TileScalePlatform = 'web' | 'mobile';
 export interface AnnotationCanvasState {
@@ -155,6 +171,17 @@ export type AnnotationPatchOp = {
 } | {
     op: 'removeMeasurement';
     id: AnnotationElementId;
+} | {
+    op: 'addBackgroundImage';
+    image: AnnotationBackgroundLayer;
+    index?: number;
+} | {
+    op: 'updateBackgroundImage';
+    id: AnnotationElementId;
+    patch: Partial<Omit<AnnotationBackgroundLayer, 'id'>>;
+} | {
+    op: 'removeBackgroundImage';
+    id: AnnotationElementId;
 } | {
     op: 'setViewport';
     patch: Partial<AnnotationViewport>;

package/dist/types/annotation.js

@@ -1,3 +1,4 @@
+import { backgroundLayersOf } from '../annotation/canvas/backgroundLayers.js';
 export const DEFAULT_LAYER_ID = 'default';
 export const createDefaultLayer = () => ({
     id: DEFAULT_LAYER_ID,
@@ -20,11 +21,40 @@ export const createEmptyCanvasState = (viewport) => ({
         ...(viewport?.backgroundFit !== undefined
             ? { backgroundFit: viewport.backgroundFit }
             : {}),
+        ...(viewport?.backgroundImages !== undefined
+            ? { backgroundImages: viewport.backgroundImages }
+            : {}),
     },
     strokes: [],
     shapes: [],
     placedMeasurements: [],
 });
+// Layer 0 projected into the legacy single-slot shape. The transform is
+// dropped — old clients draw the legacy field fit-centered, an accepted
+// degradation. `format` is included only when defined so the mirror survives
+// the write path's JSON round-trip without changing shape.
+const legacyBackgroundOf = (layer) => ({
+    storagePath: layer.storagePath,
+    downloadUrl: layer.downloadUrl,
+    widthPx: layer.widthPx,
+    heightPx: layer.heightPx,
+    ...(layer.format ? { format: layer.format } : {}),
+});
+// Every background mutation lands here: it writes the (already-normalized)
+// layer array and mirrors layer 0 into the legacy slot, so old clients —
+// which read only `backgroundImage` and rewrite the whole canvas on save —
+// keep rendering the first image instead of persisting its loss. An empty
+// stack sets BOTH fields to explicit `undefined`: the write path's JSON
+// round-trip strips those keys (Firestore rejects undefined values).
+// `backgroundFit` is left alone — it belongs to the legacy render path.
+const withBackgroundLayers = (state, layers) => ({
+    ...state,
+    viewport: {
+        ...state.viewport,
+        backgroundImages: layers.length > 0 ? layers : undefined,
+        backgroundImage: layers.length > 0 ? legacyBackgroundOf(layers[0]) : undefined,
+    },
+});
 // Apply an in-memory patch to a canvas state. Pure — returns a new object.
 // Used by the canvas reducer and by InMemoryAnnotationProvider; consumers
 // can also call this when they receive a patch from the canvas to compute
@@ -71,6 +101,22 @@ const applyOp = (state, op) => {
                 ...state,
                 placedMeasurements: state.placedMeasurements.filter((m) => m.id !== op.id),
             };
+        case 'addBackgroundImage': {
+            const layers = backgroundLayersOf(state.viewport);
+            // Clamp so a stale index (e.g. an undo replayed after a concurrent
+            // removal) can never create a sparse array — a hole becomes `null`
+            // through the write path's JSON round-trip and corrupts the doc.
+            const index = Math.max(0, Math.min(op.index ?? layers.length, layers.length));
+            return withBackgroundLayers(state, [
+                ...layers.slice(0, index),
+                op.image,
+                ...layers.slice(index),
+            ]);
+        }
+        case 'updateBackgroundImage':
+            return withBackgroundLayers(state, backgroundLayersOf(state.viewport).map((l) => l.id === op.id ? { ...l, ...op.patch } : l));
+        case 'removeBackgroundImage':
+            return withBackgroundLayers(state, backgroundLayersOf(state.viewport).filter((l) => l.id !== op.id));
         case 'setViewport':
             return { ...state, viewport: { ...state.viewport, ...op.patch } };
         case 'setTileScaleFactor':
@@ -148,6 +194,28 @@ const invertOp = (before, op) => {
             }
             return { op: 'updateMeasurement', id: op.id, patch: inversePatch };
         }
+        case 'addBackgroundImage':
+            return { op: 'removeBackgroundImage', id: op.image.id };
+        case 'removeBackgroundImage': {
+            // Invert against the NORMALIZED stack: the before-state may hold only
+            // the legacy single field (the op being inverted is what materialized
+            // the array), and undo must still restore that layer — at its index.
+            const layers = backgroundLayersOf(before.viewport);
+            const index = layers.findIndex((l) => l.id === op.id);
+            return index >= 0
+                ? { op: 'addBackgroundImage', image: layers[index], index }
+                : null;
+        }
+        case 'updateBackgroundImage': {
+            const prev = backgroundLayersOf(before.viewport).find((l) => l.id === op.id);
+            if (!prev)
+                return null;
+            const inversePatch = {};
+            for (const k of Object.keys(op.patch)) {
+                inversePatch[k] = prev[k];
+            }
+            return { op: 'updateBackgroundImage', id: op.id, patch: inversePatch };
+        }
         case 'setViewport': {
             const inversePatch = {};
             for (const k of Object.keys(op.patch)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",