@reekon-tools/boldr-utils 1.6.34 → 1.6.36

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

@@ -5,5 +5,7 @@ export declare const TILE_SCALE_MIN = 0.4;
 export declare const TILE_SCALE_MAX = 2;
 export declare const resolveTileScaleFactor: (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;
 export declare const isUnassociatedStamp: (m: Pick<PlacedMeasurementRef, "measurementId" | "measurementPath" | "columnId">) => boolean;
 export declare const stampTileSize: (m: Pick<PlacedMeasurementRef, "scale">, tileScaleFactor?: number, viewportScale?: number) => number;

package/dist/annotation/canvas/stampLayout.js

@@ -37,6 +37,24 @@ export const resolveTileScaleFactor = (canvas, platform) => (platform === 'mobil
 // 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;
+// --- Cross-platform initial-size calibration ---------------------------------
+// The platform knobs are screen-space multipliers, so the same value covers a
+// very different share of the DRAWING on a phone than on a desktop pane. To
+// hand mobile a sensible starting size, web persists the doc-space edge length
+// a scale-1 tile covered as the user saw it (`tileDocSize`, stamped on tile
+// placement and web slider commits); a mobile canvas with no own knob yet
+// inverts that at its content-fit zoom so its tiles cover the SAME area of the
+// image. Two inverses of one identity: screenSize = docSize × zoom.
+// Doc-space edge length a scale-1 tile covers at `zoom` under `factor` — the
+// web write side of the calibration. Non-positive zoom yields 0, which the
+// setTileDocSize op ignores.
+export const tileDocSizeForFactor = (factor, zoom) => zoom > 0 ? (STAMP_TILE_SIZE * factor) / zoom : 0;
+// Tile-scale factor that makes a scale-1 tile cover `docSize` doc units at
+// `zoom` — the mobile read side of the calibration. Deliberately NOT clamped
+// to the slider range: faithfully matching the web look can land below
+// TILE_SCALE_MIN on a phone, and rendering/hit-testing handle any positive
+// value. The clamp applies once the user drives the slider themselves.
+export const tileScaleFromDocSize = (docSize, zoom) => (docSize * zoom) / STAMP_TILE_SIZE;
 // --- Tile sizing is independent of canvas size ------------------------------
 // A measurement tile's footprint is base × per-tile `scale` × the document-wide
 // `tileScaleFactor` (below) — and NOTHING tied to the canvas's pixel size, so

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

@@ -10,6 +10,9 @@ export interface AnnotationCanvasHandle {
     canRedo(): boolean;
     zoomToFit(): void;
     resetView(): void;
+    getTileScaleFactor(): number;
+    getTileDocSize(factor: number): number;
+    ensureMeasurementVisible(id: AnnotationElementId): void;
     placeMeasurementAtCenter(ref: MeasurementRef): void;
     placeAnnotationAtCenter(opts?: {
         defaultLengthDoc?: number;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
-import { resolveTileScaleFactor } from './stampLayout.js';
+import { resolveTileScaleFactor, stampTileSize, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
 import { createViewportApi, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
 import { buildRemoveMeasurementOps, recomputeAnchor, rectCenter, DEFAULT_LINE_POS, } from './measurementGeometry.js';
 // The viewport that frames the document's content on screen. When a background
@@ -76,7 +76,21 @@ export const useAnnotationCanvasState = (props) => {
     // tools (hit boxes) and overlays (drawn size) share one value. Uses the
     // effective (preview-applied) canvas for parity with what is on screen; the
     // slider only ever commits, so this matches ctx.document in practice.
-    const tileScaleFactor = resolveTileScaleFactor(effectiveCanvas, tileScalePlatform ?? 'web');
+    // A mobile canvas whose own knob is still unset derives its factor from the
+    // web-stamped doc-space calibration (tileDocSize) instead of web's raw
+    // screen-space value: at the initial content-fit view its tiles then cover
+    // the same area of the image the web user saw. The first mobile slider
+    // commit writes tileScaleFactorMobile and takes over for good.
+    const tileScalePlatformResolved = tileScalePlatform ?? 'web';
+    let tileScaleFactor = resolveTileScaleFactor(effectiveCanvas, tileScalePlatformResolved);
+    if (tileScalePlatformResolved === 'mobile' &&
+        effectiveCanvas.tileScaleFactorMobile == null &&
+        effectiveCanvas.tileDocSize != null &&
+        effectiveCanvas.tileDocSize > 0 &&
+        width > 0 &&
+        height > 0) {
+        tileScaleFactor = tileScaleFromDocSize(effectiveCanvas.tileDocSize, computeContentFit(effectiveCanvas, width, height).zoom);
+    }
     const ctx = useMemo(() => ({
         document: canvas,
         selection,
@@ -87,11 +101,27 @@ export const useAnnotationCanvasState = (props) => {
             setPreviewPatch(patch);
         },
         commit(patch) {
-            const inverse = invertPatch(canvas, patch);
-            undoStackRef.current.push({ forward: patch, inverse });
+            // Placing a tile on WEB stamps the doc-space calibration: the area of
+            // the drawing a scale-1 tile covers at the zoom the user is looking
+            // at, right when they judged the size against the image. Mobile
+            // derives its initial factor from it (see tileScaleFactor above).
+            // Appended into the same patch so placement + calibration are one
+            // undo step.
+            let effective = patch;
+            if (tileScalePlatformResolved !== 'mobile' &&
+                patch.ops.some((o) => o.op === 'addMeasurement')) {
+                const docSize = tileDocSizeForFactor(tileScaleFactor, viewportApi.state.zoom);
+                if (docSize > 0) {
+                    effective = {
+                        ops: [...patch.ops, { op: 'setTileDocSize', value: docSize }],
+                    };
+                }
+            }
+            const inverse = invertPatch(canvas, effective);
+            undoStackRef.current.push({ forward: effective, inverse });
             redoStackRef.current = [];
             setPreviewPatch(null);
-            onCommit(patch);
+            onCommit(effective);
         },
         setSelection(s) {
             onSelectionChange(s);
@@ -116,6 +146,7 @@ export const useAnnotationCanvasState = (props) => {
         viewportApi,
         tileViewportScale,
         tileScaleFactor,
+        tileScalePlatformResolved,
         onCommit,
         onSelectionChange,
         pickMeasurement,
@@ -264,6 +295,35 @@ export const useAnnotationCanvasState = (props) => {
                 // for a high-res background is the very crop this is meant to escape.
                 setViewport(computeContentFit(canvas, width, height));
             },
+            getTileScaleFactor() {
+                return ctxRef.current.tileScaleFactor;
+            },
+            getTileDocSize(factor) {
+                return tileDocSizeForFactor(factor, ctxRef.current.viewport.state.zoom);
+            },
+            ensureMeasurementVisible(id) {
+                const c = ctxRef.current;
+                const m = c.document.placedMeasurements.find((x) => x.id === id);
+                if (!m)
+                    return;
+                // The tile is a screen-constant square centered on its anchor, so its
+                // half-edge is screen px regardless of zoom (stampTileSize).
+                const half = stampTileSize(m, c.tileScaleFactor, c.tileViewportScale) / 2;
+                const s = c.viewport.worldToScreen(m.anchor);
+                if (s.x - half >= 0 &&
+                    s.x + half <= width &&
+                    s.y - half >= 0 &&
+                    s.y + half <= height) {
+                    return;
+                }
+                setViewport((v) => ({
+                    zoom: v.zoom,
+                    pan: {
+                        x: m.anchor.x - width / (2 * v.zoom),
+                        y: m.anchor.y - height / (2 * v.zoom),
+                    },
+                }));
+            },
             placeMeasurementAtCenter(ref) {
                 const c = ctxRef.current;
                 const anchor = c.viewport.screenToWorld({

package/dist/exports.d.ts

@@ -23,7 +23,7 @@ export type { GestureConfig, PanTrigger, AnnotationCanvasInnerProps, } from './a
 export type { CanvasPointerEvent, RequestTextInput, ShapeDrawConfig, Tool, ToolContext, ToolState, } from './annotation/canvas/Tool.js';
 export type { MeasurementRef, PickMeasurement, } from './annotation/canvas/measurementPicker.js';
 export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './annotation/canvas/measurementStampOverlay.js';
-export { STAMP_TILE_SIZE, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, stampTileSize, isUnassociatedStamp, } from './annotation/canvas/stampLayout.js';
+export { STAMP_TILE_SIZE, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, isUnassociatedStamp, } from './annotation/canvas/stampLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './annotation/canvas/viewport.js';
 export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, type SelectToolOptions, } from './annotation/canvas/tools/selectTool.js';

package/dist/exports.js

@@ -23,7 +23,7 @@ export { useAnnotationMutations, } from './annotation/data/hooks/useAnnotationMu
 export { useAnnotationCanvasDoc, } from './annotation/data/hooks/useAnnotationCanvasDoc.js';
 export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
-export { STAMP_TILE_SIZE, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, stampTileSize, isUnassociatedStamp, } from './annotation/canvas/stampLayout.js';
+export { STAMP_TILE_SIZE, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, isUnassociatedStamp, } from './annotation/canvas/stampLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './annotation/canvas/viewport.js';
 export { createPenTool, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, } from './annotation/canvas/tools/selectTool.js';

package/dist/types/annotation.d.ts

@@ -111,6 +111,7 @@ export interface AnnotationCanvasState {
     placedMeasurements: PlacedMeasurementRef[];
     tileScaleFactor?: number;
     tileScaleFactorMobile?: number;
+    tileDocSize?: number;
     externalPayloadPath?: string;
 }
 export type AnnotationElement = (AnnotationStroke & {
@@ -160,6 +161,9 @@ export type AnnotationPatchOp = {
     op: 'setTileScaleFactor';
     value: number;
     platform?: TileScalePlatform;
+} | {
+    op: 'setTileDocSize';
+    value: number;
 } | {
     op: 'setLayers';
     layers: AnnotationLayer[];

package/dist/types/annotation.js

@@ -77,6 +77,10 @@ const applyOp = (state, op) => {
             return op.platform === 'mobile'
                 ? { ...state, tileScaleFactorMobile: op.value }
                 : { ...state, tileScaleFactor: op.value };
+        case 'setTileDocSize':
+            // Guard nonsense values (a zero/negative doc size would derive a
+            // zero/negative mobile factor) — keep the existing calibration instead.
+            return op.value > 0 ? { ...state, tileDocSize: op.value } : state;
         case 'setLayers':
             return { ...state, layers: op.layers };
     }
@@ -163,6 +167,14 @@ const invertOp = (before, op) => {
                     : before.tileScaleFactor) ?? 1,
                 ...(op.platform && { platform: op.platform }),
             };
+        case 'setTileDocSize':
+            // Restore the prior calibration when there was one. A doc that never
+            // had a calibration can't be reverted to "absent" through this op
+            // (applyOp ignores non-positive values), so the stamp survives undo —
+            // benign, since it still describes what the web user last saw.
+            return before.tileDocSize != null && before.tileDocSize > 0
+                ? { op: 'setTileDocSize', value: before.tileDocSize }
+                : null;
         case 'setLayers':
             return { op: 'setLayers', layers: before.layers };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.6.34",
+  "version": "1.6.36",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",
@@ -24,6 +24,7 @@
   "scripts": {
     "build": "tsc",
     "prepack": "yarn run build",
+    "sync:local": "./scripts/sync-local.sh",
     "test": "vitest",
     "coverage": "vitest run --coverage",
     "format": "prettier --write .",