@reekon-tools/boldr-utils 1.19.5 → 1.20.0

package/dist/annotation/canvas/snapGeometry.js

@@ -0,0 +1,168 @@
+// Magnetic snapping for line endpoints (Asana 1217966180270874). While an
+// endpoint of a measurement line (`placement: 'line'`) or a line/arrow shape is
+// being placed or dragged, it snaps to nearby geometry: other lines' endpoints
+// and midpoints, polygon/rect vertices, and measurement-rectangle corners.
+// Skia-free, safe in tools, hit-tests and unit tests.
+//
+// `snapNearest`/`snapDelta` carry 'worklet' directives: the native Inner calls
+// them per frame on the UI thread (the live endpoint derived values and the
+// shape rubber-band gesture) — the same mechanism planeGeometry's grid
+// generators rely on. Keep them free of closures over non-worklet module
+// functions (numeric constants are fine) so the workletizer can lift them.
+//
+// Targets travel to the UI thread as a FLAT number array (`[x, y, kind, …]`,
+// stride SNAP_STRIDE) written once per drag — see `encodeSnapTargets`.
+import { placementOf, normalizeRect } from './measurementGeometry.js';
+// Screen-px capture radius: the grabbed endpoint jumps to a target once it is
+// within this many pixels of it. Converted to doc space via `/ zoom` at drag
+// begin (frozen for the drag, like the slide detent's SLIDE_SNAP_PX).
+export const SNAP_RADIUS_PX = 16;
+// Screen-px radius / ring width of the snap indicator drawn around the target
+// while a snap is active. Larger than the endpoint handle (HANDLE_RADIUS_PX 7)
+// so the ring frames the handle instead of hiding under it.
+export const SNAP_RING_PX = 11;
+export const SNAP_RING_WIDTH_PX = 2;
+// Target kinds, ordered by priority: on an exact distance tie the LOWER kind
+// wins, so a true endpoint/vertex beats a midpoint sitting on the same pixel.
+export const SNAP_KIND_POINT = 0;
+export const SNAP_KIND_MIDPOINT = 1;
+// Flat encoding stride: [x, y, kind].
+export const SNAP_STRIDE = 3;
+// Every snap target in the document, in doc space. `excludeId` drops the
+// element being edited ENTIRELY (its endpoints and midpoint) — snapping a
+// line's endpoint onto its own other end would collapse it, and onto its own
+// midpoint would halve it. Targets:
+//  - measurement `placement:'line'`: a, b (point) + midpoint. Plane-edge
+//    tiles included — their endpoints are real geometry even though the
+//    select tool refuses to drag them.
+//  - measurement `placement:'rectangle'`: the four normalized corners.
+//  - shape line/arrow: both endpoints + midpoint.
+//  - shape rect: the four normalized corners (stored as two opposite corners).
+//  - shape polygon (triangles included): every vertex.
+//  - ellipse, text, strokes, backgrounds: nothing.
+// Degenerate (zero-length) lines contribute their coincident endpoints but no
+// midpoint.
+export const collectSnapTargets = (doc, excludeId) => {
+    const out = [];
+    const point = (p, sourceId) => out.push({ x: p.x, y: p.y, kind: SNAP_KIND_POINT, sourceId });
+    const segment = (a, b, sourceId) => {
+        point(a, sourceId);
+        point(b, sourceId);
+        if (a.x !== b.x || a.y !== b.y) {
+            out.push({
+                x: (a.x + b.x) / 2,
+                y: (a.y + b.y) / 2,
+                kind: SNAP_KIND_MIDPOINT,
+                sourceId,
+            });
+        }
+    };
+    const corners = (r, sourceId) => {
+        const n = normalizeRect(r);
+        point({ x: n.minX, y: n.minY }, sourceId);
+        point({ x: n.maxX, y: n.minY }, sourceId);
+        point({ x: n.maxX, y: n.maxY }, sourceId);
+        point({ x: n.minX, y: n.maxY }, sourceId);
+    };
+    for (const m of doc.placedMeasurements) {
+        if (excludeId != null && m.id === excludeId)
+            continue;
+        const placement = placementOf(m);
+        if (placement === 'line' && m.line)
+            segment(m.line.a, m.line.b, m.id);
+        else if (placement === 'rectangle' && m.rect)
+            corners(m.rect, m.id);
+    }
+    for (const s of doc.shapes) {
+        if (excludeId != null && s.id === excludeId)
+            continue;
+        const pts = s.geometry.points;
+        switch (s.kind) {
+            case 'line':
+            case 'arrow': {
+                const [a, b] = pts;
+                if (a && b)
+                    segment(a, b, s.id);
+                break;
+            }
+            case 'rect': {
+                const [a, b] = pts;
+                if (a && b)
+                    corners({ a, b }, s.id);
+                break;
+            }
+            case 'polygon':
+                for (const p of pts)
+                    point(p, s.id);
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+};
+// Flat `[x, y, kind, …]` buffer for UI-thread transfer (a plain number[],
+// like the freehand `livePoints` — TypedArrays aren't proven shareable here).
+export const encodeSnapTargets = (targets) => {
+    const flat = new Array(targets.length * SNAP_STRIDE);
+    for (let i = 0; i < targets.length; i++) {
+        const t = targets[i];
+        flat[i * SNAP_STRIDE] = t.x;
+        flat[i * SNAP_STRIDE + 1] = t.y;
+        flat[i * SNAP_STRIDE + 2] = t.kind;
+    }
+    return flat;
+};
+export const collectSnapTargetsFlat = (doc, excludeId) => encodeSnapTargets(collectSnapTargets(doc, excludeId));
+// Nearest target to (x, y) within `radiusDoc` (inclusive), or null. Ties on
+// distance go to the lower kind (point beats midpoint); remaining ties to the
+// earlier target. `radiusDoc <= 0` disables snapping. Worklet-callable.
+export const snapNearest = (x, y, flat, radiusDoc) => {
+    'worklet';
+    if (radiusDoc <= 0)
+        return null;
+    const r2 = radiusDoc * radiusDoc;
+    let bestD2 = Infinity;
+    let bestKind = Infinity;
+    let bestIdx = -1;
+    for (let i = 0; i + 2 < flat.length; i += 3) {
+        const dx = flat[i] - x;
+        const dy = flat[i + 1] - y;
+        const d2 = dx * dx + dy * dy;
+        if (d2 > r2)
+            continue;
+        const kind = flat[i + 2];
+        if (d2 < bestD2 || (d2 === bestD2 && kind < bestKind)) {
+            bestD2 = d2;
+            bestKind = kind;
+            bestIdx = i;
+        }
+    }
+    if (bestIdx < 0)
+        return null;
+    return {
+        x: flat[bestIdx],
+        y: flat[bestIdx + 1],
+        kind: flat[bestIdx + 2] === 1 ? 1 : 0,
+        index: bestIdx / 3,
+    };
+};
+// Snap a DRAG: `base` is the grabbed endpoint's committed position and `delta`
+// the raw world-space drag offset. Returns the effective delta that lands the
+// endpoint exactly on the nearest target (or the raw delta when nothing is in
+// range), so the existing delta-based patch builders stay untouched. Worklet-
+// callable — the native select gesture runs it in onEnd so the commit matches
+// the live preview bit-for-bit.
+export const snapDelta = (base, delta, flat, radiusDoc) => {
+    'worklet';
+    const hit = snapNearest(base.x + delta.x, base.y + delta.y, flat, radiusDoc);
+    if (!hit)
+        return { delta, hit: null };
+    return { delta: { x: hit.x - base.x, y: hit.y - base.y }, hit };
+};
+// Snap an ABSOLUTE point (drag-to-create tools place raw world points).
+export const snapPoint = (p, flat, radiusDoc) => {
+    'worklet';
+    const hit = snapNearest(p.x, p.y, flat, radiusDoc);
+    return hit ? { point: { x: hit.x, y: hit.y }, hit } : { point: p, hit: null };
+};

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/measurementTool.js

@@ -1,5 +1,6 @@
 import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
 import { DEFAULT_LINE_POS, recomputeAnchor, rectCenter, } from '../measurementGeometry.js';
+import { collectSnapTargetsFlat, snapPoint } from '../snapGeometry.js';
 // The `line*` style fields for a placed measurement, built from the tool's
 // style options. Undefined fields are dropped (never emitted) so the render
 // defaults apply and Firestore never sees an `undefined` value.
@@ -22,6 +23,25 @@ const lineStyleFields = (placement, style) => {
     }
     return out;
 };
+// Snap state for a fresh line press. The new annotation isn't in the doc yet,
+// so nothing needs excluding. Empty when snapping is off.
+const snapStateForPress = (ctx, placement) => placement === 'line' && ctx.snap?.enabled
+    ? {
+        snap: {
+            targets: collectSnapTargetsFlat(ctx.document),
+            radiusDoc: ctx.snap.radiusPx / ctx.viewport.state.zoom,
+        },
+    }
+    : {};
+// The world point a drag end should use: snapped when a target is in range.
+// Reports the target (or null) to the indicator.
+const snapEnd = (s, ctx, world) => {
+    if (!s.snap)
+        return world;
+    const r = snapPoint(world, s.snap.targets, s.snap.radiusDoc);
+    ctx.snap?.setIndicator(r.hit ? { x: r.hit.x, y: r.hit.y } : null);
+    return r.point;
+};
 let counter = 0;
 const makeId = () => `annotation-${Date.now().toString(36)}-${(counter++).toString(36)}`;
 const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
@@ -130,13 +150,21 @@ export const createMeasurementTool = (options = {}) => {
         id: options.id ?? defaultId,
         label: options.label ?? defaultLabel,
         cursor: 'crosshair',
-        onPointerDown(event) {
+        onPointerDown(event, ctx) {
+            const snap = snapStateForPress(ctx, placement);
+            // The START of a new line snaps too (a leader that begins exactly on a
+            // corner is the point of the feature); the ring flashes there until the
+            // first move re-evaluates it against the moving end.
+            const startWorld = snap.snap
+                ? snapPoint(event.world, snap.snap.targets, snap.snap.radiusDoc).point
+                : event.world;
             return {
                 kind: 'measurement-drawing',
                 id: makeId(),
-                startWorld: event.world,
+                startWorld,
                 startScreen: event.screen,
                 moved: false,
+                ...snap,
             };
         },
         onPointerMove(event, ctx, state) {
@@ -149,7 +177,7 @@ export const createMeasurementTool = (options = {}) => {
                 placement,
                 linePos,
                 a: s.startWorld,
-                b: event.world,
+                b: snapEnd(s, ctx, event.world),
                 style,
                 valueSource: valueSourceFor(ctx),
             });
@@ -160,6 +188,7 @@ export const createMeasurementTool = (options = {}) => {
             const s = state;
             if (s?.kind !== 'measurement-drawing')
                 return;
+            ctx.snap?.setIndicator(null);
             const dx = event.screen.x - s.startScreen.x;
             const dy = event.screen.y - s.startScreen.y;
             if (!s.moved || dx * dx + dy * dy < minDragPx * minDragPx) {
@@ -167,18 +196,23 @@ export const createMeasurementTool = (options = {}) => {
                 ctx.preview({ ops: [] });
                 return;
             }
+            // Same snap as the last move, so the commit equals the preview.
+            const b = s.snap
+                ? snapPoint(event.world, s.snap.targets, s.snap.radiusDoc).point
+                : event.world;
             place(ctx, buildMeasurement({
                 id: s.id,
                 layerId: firstLayerId(ctx.document),
                 placement,
                 linePos,
                 a: s.startWorld,
-                b: event.world,
+                b,
                 style,
                 valueSource: valueSourceFor(ctx),
             }));
         },
         onCancel(_state, ctx) {
+            ctx.snap?.setIndicator(null);
             ctx.preview({ ops: [] });
         },
     };

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;