@reekon-tools/boldr-utils 1.15.4 → 1.16.0

package/dist/annotation/canvas/AnnotationCanvasInner.native.js

@@ -7,9 +7,10 @@ import Animated, { runOnJS, runOnUI, useAnimatedStyle, useDerivedValue, useShare
 import { stampTileDims } from './stampLayout.js';
 import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { AnnotationCanvasSkia } from './AnnotationCanvasSkia.js';
-import { backgroundLayersOf } from './backgroundLayers.js';
+import { backgroundLayersOf, backgroundLayerDocRect, } from './backgroundLayers.js';
 import { BackgroundSkImageLoader } from './elements/BackgroundImageElement.js';
-import { buildRemoveMeasurementOps, } from './measurementGeometry.js';
+import { buildRemoveMeasurementOps, linePosOf, } from './measurementGeometry.js';
+import { planeEdgeLine, planeGridSegments, planeGridSegmentsForScale, resolvePlaneGridSpacingUm, } from './planeGeometry.js';
 import { buildShapeFromDrag } from './tools/shapeTool.js';
 import { SELECTION_PAD } from './textGeometry.js';
 import { useAnnotationCanvasState, } from './useAnnotationCanvasState.js';
@@ -481,10 +482,13 @@ export const AnnotationCanvasInner = (props) => {
     // The plane tool's JS preview path re-rendered the whole canvas (and
     // recomputed the photo-spanning grid) per pointer-move, dropping JS frames
     // on device. Instead the drag runs like the select tool's: the gesture
-    // begin hit-tests once on JS, the translation lives in shared values
-    // driving a live outline (worklet twin of PlaneElement's outline path), and
-    // the drop commits exactly once. The grid + dimension tiles freeze/hide
-    // until the commit lands.
+    // begin hit-tests once on JS, the translation lives in shared values, and
+    // the drop commits exactly once. Everything the drag visually moves is
+    // rebuilt per frame on the UI thread: the outline (worklet twin of
+    // PlaneElement's path), the grid (planeGeometry's generators are worklets),
+    // and the dimension-tile chips (a plane branch in the RN overlay's animated
+    // style, driven by planeTileCtx). Only the tiles' computed VALUES wait for
+    // the commit — they're user-entered dims, which a corner drag can't change.
     // planeDragMode: 0 idle · 1 handle drag (UI thread) · 2 everything else
     // (marking / blocked-creation), which streams JS pointer events like
     // toolPan would have.
@@ -541,6 +545,67 @@ export const AnnotationCanvasInner = (props) => {
         path.lineTo(b.x, b.y);
         return path;
     });
+    // Live grid during the drag. Spacing and bounds are start-of-drag constants
+    // computed on JS (the dims a corner drag can't change decide the spacing;
+    // the photo rect decides the bounds — both mirror PlaneElement's inputs),
+    // captured into the derived value; the segments themselves recompute per
+    // frame on the UI thread from the live corner — planeGeometry's generators
+    // carry 'worklet' directives for exactly this call site. Scale mode's doc
+    // spacing tracks the live reference line, which is correct: stretching the
+    // line IS changing the calibration's ratio.
+    const planeDragGridBounds = useMemo(() => {
+        const first = backgroundLayers[0];
+        return first
+            ? backgroundLayerDocRect(first)
+            : {
+                x: 0,
+                y: 0,
+                width: state.effectiveCanvas.viewport.width,
+                height: state.effectiveCanvas.viewport.height,
+            };
+    }, [backgroundLayers, state.effectiveCanvas.viewport]);
+    const planeDragGridSpacing = planeDragPlane && planeDragPlane.gridVisible !== false
+        ? resolvePlaneGridSpacingUm(planeDragPlane, 'metric', {
+            width: planeDragGridBounds.width,
+            height: planeDragGridBounds.height,
+        })
+        : null;
+    const planeDragGridPath = useDerivedValue(() => {
+        'worklet';
+        const path = Skia.Path.Make();
+        if (!planeDragPlane ||
+            planeDragGridSpacing == null ||
+            planeDragMode.value !== 1) {
+            return path;
+        }
+        const lx = planeDragStartX.value + planeDragTX.value / zoom.value;
+        const ly = planeDragStartY.value + planeDragTY.value / zoom.value;
+        let segments;
+        if (planeDragPlane.mode === 'perspective') {
+            const c = planeDragPlane.corners;
+            const live = [0, 1, 2, 3].map((i) => i === planeDragIndexVal ? { x: lx, y: ly } : c[i]);
+            // A mid-drag non-convex quad yields a null homography → empty grid for
+            // that frame; the outline keeps tracking and the drop snaps back.
+            segments = planeGridSegments({ ...planeDragPlane, corners: live }, planeDragGridSpacing, planeDragGridBounds);
+        }
+        else {
+            const a = planeDragIndexVal === 0 ? { x: lx, y: ly } : planeDragPlane.refLine.a;
+            const b = planeDragIndexVal === 1 ? { x: lx, y: ly } : planeDragPlane.refLine.b;
+            segments = planeGridSegmentsForScale({ ...planeDragPlane, refLine: { a, b } }, planeDragGridSpacing, planeDragGridBounds);
+        }
+        for (const s of segments) {
+            path.moveTo(s.a.x, s.a.y);
+            path.lineTo(s.b.x, s.b.y);
+        }
+        return path;
+    });
+    // Per-tile follow data for the dragged plane's dimension chips, written
+    // once at drag begin (see beginPlaneDrag): the committed edge endpoints,
+    // whether each end follows the dragged handle, and the tile's linePos.
+    // The overlay's animated style lerps along the live edge at that same
+    // linePos — the exact anchor syncDimensionTileOps recomputes on commit,
+    // so the chip lands where it already is.
+    const planeTileCtx = useSharedValue({});
     // Rectangle-annotation corner drag. `rectDragId` (React state) marks which
     // annotation's rect renders from the live geometry; `rectCtx` carries the
     // fixed (opposite) corner and the grabbed corner's start position so the
@@ -1568,6 +1633,32 @@ export const AnnotationCanvasInner = (props) => {
                     if (start) {
                         planeDragStartX.value = start.x;
                         planeDragStartY.value = start.y;
+                        // Follow data for the plane's dimension chips: each tile's edge
+                        // (planeEdgeLine — the committed geometry its line mirrors), which
+                        // endpoint(s) track the grabbed handle (coordinate equality with
+                        // the handle's start — both values come from the same committed
+                        // plane, so exact comparison is sound), and its linePos.
+                        const plane = st.ctx.document.planes?.find((p) => p.id === planeId);
+                        const follow = {};
+                        if (plane) {
+                            for (const m of st.ctx.document.placedMeasurements) {
+                                if (m.planeId !== planeId || !m.planeEdge)
+                                    continue;
+                                const edge = planeEdgeLine(plane, m.planeEdge);
+                                if (!edge)
+                                    continue;
+                                follow[m.id] = {
+                                    ax: edge.a.x,
+                                    ay: edge.a.y,
+                                    bx: edge.b.x,
+                                    by: edge.b.y,
+                                    ma: edge.a.x === start.x && edge.a.y === start.y ? 1 : 0,
+                                    mb: edge.b.x === start.x && edge.b.y === start.y ? 1 : 0,
+                                    t: linePosOf(m),
+                                };
+                            }
+                        }
+                        planeTileCtx.value = follow;
                         planeDragMode.value = 1;
                         const drag = { planeId, index };
                         planeDragRef.current = drag;
@@ -1588,7 +1679,7 @@ export const AnnotationCanvasInner = (props) => {
                 if (f)
                     stateRef.current.dispatchPointerMove(buildEvent(f.id, screen));
             };
-            const endPlaneDrag = (screen) => {
+            const endPlaneDrag = (screen, translation) => {
                 const st = stateRef.current;
                 if (planeDragMode.value === 2) {
                     const f = planeJsPointerRef.current;
@@ -1596,7 +1687,17 @@ export const AnnotationCanvasInner = (props) => {
                         st.dispatchPointerUp(buildEvent(f.id, screen));
                 }
                 else if (planeDragMode.value === 1 && planeDragRef.current) {
-                    const world = st.ctx.viewport.screenToWorld(screen);
+                    // Commit the position the live outline showed: handle start + the
+                    // finger's translation. NOT screenToWorld(finger) — the hit-test
+                    // accepts a grab anywhere inside the handle's radius, so the
+                    // finger's absolute position is off the handle by that grab offset,
+                    // and committing it made the corner visibly shift on release.
+                    // Zoom can't change mid-drag (this pan won the gesture race, so the
+                    // pinch never activated), so reading it at drop matches every frame.
+                    const world = {
+                        x: planeDragStartX.value + translation.x / zoom.value,
+                        y: planeDragStartY.value + translation.y / zoom.value,
+                    };
                     const patch = cfg.buildHandleDropPatch(st.ctx.document, planeDragRef.current.index, world);
                     // Null = invalid drop (non-convex) — clearing the drag state below
                     // snaps the outline back to the committed plane.
@@ -1650,7 +1751,10 @@ export const AnnotationCanvasInner = (props) => {
                 .onEnd((e) => {
                 'worklet';
                 planeDragEnded.value = true;
-                runOnJS(endPlaneDrag)({ x: e.x, y: e.y });
+                // The final translation travels as an argument rather than being
+                // read back from the shared values on JS: the last onChange isn't
+                // guaranteed to have carried it, and onEnd doesn't write them.
+                runOnJS(endPlaneDrag)({ x: e.x, y: e.y }, { x: e.translationX, y: e.translationY });
             })
                 .onFinalize(() => {
                 'worklet';
@@ -1701,6 +1805,7 @@ export const AnnotationCanvasInner = (props) => {
         planeDragTY,
         planeDragStartX,
         planeDragStartY,
+        planeTileCtx,
         longPressEnabled,
         dragX,
         dragY,
@@ -1799,6 +1904,7 @@ export const AnnotationCanvasInner = (props) => {
         planeDragId: planeDrag?.planeId ?? null,
         planeDragIndex: planeDrag?.index ?? null,
         planeDragPath,
+        planeDragGridPath,
         planeDragHandle,
         customPreview,
     };
@@ -1815,7 +1921,7 @@ export const AnnotationCanvasInner = (props) => {
     // non-fullscreen canvas (e.g. a diagram strip) escape into surrounding UI.
     _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [backgroundLayers.map((layer) => (_jsx(BackgroundSkImageLoader, { layer: layer, resolveUrl: resolveImageUrl, onImage: onBackgroundSkImage }, layer.id))), _jsx(GestureDetector, { gesture: gesture, children: _jsx(View, { style: { width, height }, collapsable: false, children: AnnotationCanvasSkia(skiaProps) }) }), renderMeasurementStamp && (_jsx(View, { pointerEvents: "box-none", style: StyleSheet.absoluteFill, children: state.effectiveCanvas.placedMeasurements.map((placed) => (_jsx(MeasurementStampOverlayItem, { placed: placed, measurement: placed.measurementId
                         ? (state.measurementsById.get(placed.measurementId) ?? null)
-                        : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, rectCtx: rectCtx, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.tileScaleFactor, headerTileScaleFactor: state.headerTileScaleFactor, fileTileScaleFactor: state.fileTileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
+                        : (resolveStampMeasurement?.(placed) ?? null), selected: selection?.ids.includes(placed.id) ?? false, dragging: draggingId === placed.id, sliding: slidingId === placed.id, endpointDragging: epDragId === placed.id, rectResizing: rectDragId === placed.id, planeEdgeDragging: planeDrag != null && placed.planeId === planeDrag.planeId, zoomSnapshot: state.viewport.zoom, zoom: zoom, panX: panX, panY: panY, dragX: dragX, dragY: dragY, slideCtx: slideCtx, epCtx: epCtx, rectCtx: rectCtx, planeTileCtx: planeTileCtx, planeDragTX: planeDragTX, planeDragTY: planeDragTY, renderMeasurementStamp: renderMeasurementStamp, tileScaleFactor: state.tileScaleFactor, headerTileScaleFactor: state.headerTileScaleFactor, fileTileScaleFactor: state.fileTileScaleFactor, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
                         ? () => {
                             const defaultRemove = () => {
                                 const { ops, keepSelection } = buildRemoveMeasurementOps(placed);
@@ -1831,7 +1937,7 @@ export const AnnotationCanvasInner = (props) => {
                     wrapContent: loupeWrap,
                 }) }))] }));
 };
-const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging, sliding, endpointDragging, rectResizing, zoomSnapshot, zoom, panX, panY, dragX, dragY, slideCtx, epCtx, rectCtx, renderMeasurementStamp, tileScaleFactor, headerTileScaleFactor, fileTileScaleFactor, tileViewportScale, onStampPress, onStampLongPress, onRemove, }) => {
+const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging, sliding, endpointDragging, rectResizing, zoomSnapshot, zoom, panX, panY, dragX, dragY, slideCtx, epCtx, rectCtx, planeEdgeDragging, planeTileCtx, planeDragTX, planeDragTY, renderMeasurementStamp, tileScaleFactor, headerTileScaleFactor, fileTileScaleFactor, tileViewportScale, onStampPress, onStampLongPress, onRemove, }) => {
     // Square tile or wide group-header pill — one footprint source of truth
     // shared with the hit-test (stampTileDims).
     const { width, height } = stampTileDims(placed, tileScaleFactor, tileViewportScale, headerTileScaleFactor ?? tileScaleFactor, fileTileScaleFactor ?? tileScaleFactor);
@@ -1845,6 +1951,7 @@ const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging,
     const removeSize = Math.min(36, Math.min(width, height) * 0.4);
     const anchorX = placed.anchor.x;
     const anchorY = placed.anchor.y;
+    const placedId = placed.id;
     // doc → screen each frame, on the UI thread. Position is a translate
     // transform (cheap, no layout) so the tile stays glued to its anchor. While
     // dragging, the world-space drag offset is folded in; while sliding, the
@@ -1923,6 +2030,22 @@ const MeasurementStampOverlayItem = ({ placed, measurement, selected, dragging,
             worldX = (c.fx + c.mx + dragX.value) / 2;
             worldY = (c.fy + c.my + dragY.value) / 2;
         }
+        else if (planeEdgeDragging) {
+            // Tile stays at its linePos along the LIVE plane edge. The plane drag's
+            // translation is screen px (unlike dragX/dragY's world units), so it
+            // converts through the live zoom, same as the outline twin.
+            const c = planeTileCtx.value[placedId];
+            if (c) {
+                const dx = planeDragTX.value / zoom.value;
+                const dy = planeDragTY.value / zoom.value;
+                const ax = c.ma === 1 ? c.ax + dx : c.ax;
+                const ay = c.ma === 1 ? c.ay + dy : c.ay;
+                const bx = c.mb === 1 ? c.bx + dx : c.bx;
+                const by = c.mb === 1 ? c.by + dy : c.by;
+                worldX = ax + (bx - ax) * c.t;
+                worldY = ay + (by - ay) * c.t;
+            }
+        }
         else if (dragging) {
             worldX = anchorX + dragX.value;
             worldY = anchorY + dragY.value;

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

@@ -94,10 +94,13 @@ export interface AnnotationCanvasSkiaProps {
     planeDragPath?: SkPath | {
         value: SkPath;
     };
+    planeDragGridPath?: SkPath | {
+        value: SkPath;
+    };
     planeDragHandle?: AnimatedPoint;
     customPreview?: ReactNode;
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragHandle, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -4,9 +4,9 @@ import { normalizeRect, placementOf } from './measurementGeometry.js';
 import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeometry.js';
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
-import { backgroundLayerDocRect, backgroundLayersOf, } from './backgroundLayers.js';
+import { backgroundLayerDocRect, backgroundLayersOf, canEditBackgroundLayers, } from './backgroundLayers.js';
 import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
-import { PlaneElement, PLANE_CHROME_COLOR, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
+import { PlaneElement, PLANE_CHROME_COLOR, PLANE_GRID_COLOR, PLANE_GRID_OPACITY, PLANE_GRID_WIDTH, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
 import { StrokeElement } from './elements/StrokeElement.js';
 // Default visual constants for the measurement-annotation line (the tile itself
@@ -80,7 +80,7 @@ const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElem
 // since the function-call pattern works identically on native we use it
 // in both Inners for consistency. Don't add hooks here; this is a plain
 // JSX-returning helper, not a component.
-export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragHandle, customPreview, wrapContent, canvasRef, }) => {
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, customPreview, wrapContent, canvasRef, }) => {
     // Doc rect a SCALE-mode plane grid covers: the first background layer (the
     // photo being calibrated), else the document rect. Pinned to layer 0 like
     // the tile-sizing reference — adding a second image must not re-span the
@@ -99,7 +99,7 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                     const statics = plane.mode === 'perspective'
                         ? plane.corners
                         : [plane.refLine.a, plane.refLine.b];
-                    return (_jsxs(Group, { children: [_jsx(Path, { path: planeDragPath, color: PLANE_CHROME_COLOR, style: "stroke", strokeWidth: PLANE_OUTLINE_WIDTH, strokeJoin: "round" }), handleRadius != null &&
+                    return (_jsxs(Group, { children: [planeDragGridPath && (_jsx(Path, { path: planeDragGridPath, color: PLANE_GRID_COLOR, style: "stroke", strokeWidth: PLANE_GRID_WIDTH, opacity: PLANE_GRID_OPACITY })), _jsx(Path, { path: planeDragPath, color: PLANE_CHROME_COLOR, style: "stroke", strokeWidth: PLANE_OUTLINE_WIDTH, strokeJoin: "round" }), handleRadius != null &&
                                 statics.map((p, i) => i === planeDragIndex ? null : (_jsxs(Group, { children: [_jsx(Circle, { c: p, r: handleRadius, color: PLANE_CHROME_COLOR }), _jsx(Circle, { c: p, r: handleRadius, color: "#FFFFFF", style: "stroke", strokeWidth: handleRingWidth })] }, i))), handleRadius != null && planeDragHandle && (_jsxs(_Fragment, { children: [_jsx(Circle, { c: planeDragHandle, r: handleRadius, color: PLANE_CHROME_COLOR }), _jsx(Circle, { c: planeDragHandle, r: handleRadius, color: "#FFFFFF", style: "stroke", strokeWidth: handleRingWidth })] }))] }, plane.id));
                 }
                 return (_jsx(PlaneElement, { plane: plane, scaleBounds: planeScaleBounds, showHandles: showPlaneHandles === true, handleRadius: showPlaneHandles ? handleRadius : undefined, handleRingWidth: showPlaneHandles ? handleRingWidth : undefined }, plane.id));
@@ -251,8 +251,13 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                 // bottom-right handle — backgrounds scale uniformly about their
                 // top-left corner (the transform origin), so a single opposite-corner
                 // grab is the whole gizmo. Chrome tracks the live drag/resize
-                // transform the same way the layer itself does above.
-                const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
+                // transform the same way the layer itself does above. A lone
+                // background is never editable (canEditBackgroundLayers), so it gets
+                // no chrome even when a stale selection still names it — e.g. right
+                // after the other layer of a pair was removed.
+                const layer = canEditBackgroundLayers(effectiveCanvas.viewport)
+                    ? backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId)
+                    : undefined;
                 if (layer) {
                     const r = backgroundLayerDocRect(layer);
                     const isResizing = layer.id === resizingId;

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

@@ -2,6 +2,7 @@ import type { AnnotationBackgroundLayer, AnnotationViewport, BackgroundLayerTran
 export declare const LEGACY_BACKGROUND_LAYER_ID = "background-legacy";
 export declare const BACKGROUND_PLACEMENT_GAP_RATIO = 0.02;
 export declare const backgroundLayersOf: (viewport: AnnotationViewport) => AnnotationBackgroundLayer[];
+export declare const canEditBackgroundLayers: (viewport: AnnotationViewport) => boolean;
 export declare const backgroundLayerDocRect: (layer: AnnotationBackgroundLayer) => {
     x: number;
     y: number;

package/dist/annotation/canvas/backgroundLayers.js

@@ -46,6 +46,14 @@ export const backgroundLayersOf = (viewport) => {
         },
     ];
 };
+// Whether the background stack is user-editable at all — selectable, draggable,
+// corner-scalable. A lone image IS the canvas: there is nothing to arrange it
+// against, so it exposes no selection chrome and never moves; taps and drags
+// on it fall through to the ordinary empty-canvas behavior (deselect / pan).
+// Only once a second image exists does arranging make sense, and then every
+// layer becomes editable. Shared by the select tool's hit-tests and the
+// selection chrome so both platforms agree on the rule.
+export const canEditBackgroundLayers = (viewport) => backgroundLayersOf(viewport).length > 1;
 // The doc-space rectangle a layer occupies: the intrinsic pixel grid under
 // the layer's translate+scale.
 export const backgroundLayerDocRect = (layer) => ({

package/dist/annotation/canvas/elements/PlaneElement.d.ts

@@ -1,6 +1,9 @@
 import type { PlaneCalibration } from '../../../types/annotation.js';
 export declare const PLANE_CHROME_COLOR: "#BD30A8";
 export declare const PLANE_OUTLINE_WIDTH = 14;
+export declare const PLANE_GRID_COLOR = "#FFD1F8";
+export declare const PLANE_GRID_OPACITY = 0.9;
+export declare const PLANE_GRID_WIDTH = 2.5;
 type AnimatedNumber = number | {
     value: number;
 };

package/dist/annotation/canvas/elements/PlaneElement.js

@@ -8,15 +8,15 @@ import { FormulaColors } from '../../../theme/colors.js';
 // information: the formula purple outlines the calibrated quad / reference
 // line (and inks its handles and dimension-tile lines — see planeTool), while
 // the grid it casts gets its own pale pink so the two never blur.
-// Exported for the live UI-thread handle drag, which redraws the outline in
-// AnnotationCanvasSkia while this element is hidden.
+// Exported for the live UI-thread handle drag, which redraws the outline and
+// grid in AnnotationCanvasSkia while this element is hidden.
 export const PLANE_CHROME_COLOR = FormulaColors.purple;
 export const PLANE_OUTLINE_WIDTH = 14;
 const PLANE_COLOR = PLANE_CHROME_COLOR;
-const PLANE_GRID_COLOR = '#FFD1F8';
-const PLANE_GRID_OPACITY = 0.9;
+export const PLANE_GRID_COLOR = '#FFD1F8';
+export const PLANE_GRID_OPACITY = 0.9;
 // Doc-space stroke widths (scale with zoom, like the drawn shapes).
-const PLANE_GRID_WIDTH = 2.5;
+export const PLANE_GRID_WIDTH = 2.5;
 // Cross-tick half-length (doc units) marking the ends of a scale-mode
 // reference line, so it reads as "a measured span", not just a line.
 const REF_TICK_LEN = 18;

package/dist/annotation/canvas/measurementGeometry.js

@@ -44,7 +44,10 @@ export const projectToLinePos = (line, world) => {
 export const snapLinePos = (t, threshold = 0.06) => Math.abs(t - 0.5) <= threshold ? 0.5 : t;
 // Euclidean length of a line in doc space (used to convert a screen-px snap
 // radius into a t-space threshold).
+// 'worklet': called from planeGeometry's grid generators, which run per-frame
+// on the UI thread during a plane handle drag. Inert everywhere else.
 export const lineLength = (line) => {
+    'worklet';
     const dx = line.b.x - line.a.x;
     const dy = line.b.y - line.a.y;
     return Math.sqrt(dx * dx + dy * dy);

package/dist/annotation/canvas/planeGeometry.js

@@ -7,15 +7,17 @@
 // SIZING (stampLayout.ts). Everything here is plane calibration — mapping
 // DOC-space geometry to physical lengths in micrometers.
 //
-// v1 keeps all of this on the JS thread (values recompute on commit, not
-// per-frame), so there are no worklet twins of these functions yet. If live
-// drag readouts are ever needed, the twin goes next to the existing geometry
-// twins in AnnotationCanvasInner.native.tsx.
+// The homography/grid chain carries 'worklet' directives (inert everywhere
+// but a Reanimated build): AnnotationCanvasInner.native.tsx rebuilds the grid
+// per frame on the UI thread during a plane handle drag, calling these
+// directly rather than maintaining an inline twin of ~200 lines of math.
+// Values (planeDistanceUm etc.) still recompute on commit, JS-side.
 import { lineLength } from './measurementGeometry.js';
 // Degeneracy guards are scaled to the quad's own extent — doc coordinates are
 // arbitrary (a photo canvas is typically ~1000 units across), so a fixed
 // epsilon would misfire on very small or very large documents.
 const relativeEps = (corners) => {
+    'worklet';
     let span = 1;
     for (const p of corners) {
         span = Math.max(span, Math.abs(p.x), Math.abs(p.y));
@@ -27,6 +29,7 @@ const relativeEps = (corners) => {
 // (collinear/coincident corners). Corners must already be in TL,TR,BR,BL order
 // (see normalizeQuadOrder).
 export const homographyFromQuad = (corners) => {
+    'worklet';
     const [p0, p1, p2, p3] = corners;
     const eps = relativeEps(corners);
     const sx = p0.x - p1.x + p2.x - p3.x;
@@ -71,6 +74,7 @@ export const homographyFromQuad = (corners) => {
 // Returns null when that entry (a·e − b·d) is ~zero — the inverse would put
 // the whole doc plane on the vanishing line.
 export const invertHomography = (m) => {
+    'worklet';
     const norm = m.a * m.e - m.b * m.d;
     if (Math.abs(norm) < 1e-12)
         return null;
@@ -88,6 +92,7 @@ export const invertHomography = (m) => {
 // Apply a homography to a point. Null when the point sits (numerically) on the
 // vanishing line — the plane there is at infinity.
 export const applyHomography = (m, p) => {
+    'worklet';
     const w = m.g * p.x + m.h * p.y + 1;
     if (Math.abs(w) < 1e-12)
         return null;
@@ -148,12 +153,15 @@ export const normalizeQuadOrder = (pts) => {
 // The dimensions a calibration has been given so far. Null until the user has
 // entered them all (through the plane's dimension tiles) — an incomplete
 // calibration renders its geometry but computes nothing.
-const perspectiveDims = (cal) => cal.widthUm != null &&
-    cal.widthUm > 0 &&
-    cal.heightUm != null &&
-    cal.heightUm > 0
-    ? { widthUm: cal.widthUm, heightUm: cal.heightUm }
-    : null;
+const perspectiveDims = (cal) => {
+    'worklet';
+    return cal.widthUm != null &&
+        cal.widthUm > 0 &&
+        cal.heightUm != null &&
+        cal.heightUm > 0
+        ? { widthUm: cal.widthUm, heightUm: cal.heightUm }
+        : null;
+};
 // Doc-space point → plane coordinates in micrometers (x across the rectangle's
 // width, y down its height; the TL corner is the origin). Null when the
 // calibration's quad is degenerate, its dimensions aren't entered yet, or the
@@ -333,6 +341,7 @@ export const resolvePlaneGridSpacingUm = (cal, system, scaleBounds) => {
 const GRID_EXTENT_CAP = 12;
 // Liang–Barsky segment/rect clip, DOC space. Null when fully outside.
 const clipSegmentToRect = (a, b, rect) => {
+    'worklet';
     const dx = b.x - a.x;
     const dy = b.y - a.y;
     let t0 = 0;
@@ -385,6 +394,7 @@ const clipSegmentToRect = (a, b, rect) => {
 // far side of the horizon are dropped (w stays positive across a segment
 // only when it's positive at both ends — w is affine on the plane).
 export const planeGridSegments = (cal, spacingUm, bounds) => {
+    'worklet';
     const dims = perspectiveDims(cal);
     const h = homographyFromQuad(cal.corners);
     if (!dims ||
@@ -476,6 +486,7 @@ export const planeGridSegments = (cal, spacingUm, bounds) => {
 // rect, or the document rect when there's no background), DOC space. Lines
 // anchor at the bounds origin.
 export const planeGridSegmentsForScale = (cal, spacingUm, bounds) => {
+    'worklet';
     const refDoc = lineLength(cal.refLine);
     const lengthUm = cal.lengthUm ?? 0;
     if (!(refDoc > 0) ||

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

@@ -1,4 +1,4 @@
-import { backgroundLayerDocRect, backgroundLayersOf, } from '../backgroundLayers.js';
+import { backgroundLayerDocRect, backgroundLayersOf, canEditBackgroundLayers, } 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';
@@ -462,7 +462,10 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
 // 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. ---
+// hijacking pan/marquee gestures. And none of it applies to a LONE image: with
+// a single background there is nothing to arrange, so it is not selectable,
+// draggable, or scalable at all (canEditBackgroundLayers) — every hit-test
+// below misses, and the gesture falls through to deselect / pan. ---
 // 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
@@ -478,6 +481,8 @@ const pointInBackgroundLayer = (layer, p) => {
 // layers draw on top). Point-in-doc-rect, no padding: a background is a big
 // target already.
 const findBackgroundHit = (doc, world) => {
+    if (!canEditBackgroundLayers(doc.viewport))
+        return null;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         if (pointInBackgroundLayer(layers[i], world)) {
@@ -490,6 +495,8 @@ const findBackgroundHit = (doc, world) => {
 // 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) => {
+    if (!canEditBackgroundLayers(doc.viewport))
+        return null;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         const layer = layers[i];
@@ -527,7 +534,11 @@ const backgroundResizeGeometry = (layer) => {
 // endpoint handles either way.
 const findResizeHandleHit = (doc, id, world, zoom) => {
     const s = doc.shapes.find((x) => x.id === id);
-    const layer = s ? null : backgroundLayerById(doc, id);
+    // A lone background is not editable at all (canEditBackgroundLayers), so
+    // its corner offers no handle — even to a stale selection naming it.
+    const layer = s || !canEditBackgroundLayers(doc.viewport)
+        ? null
+        : backgroundLayerById(doc, id);
     const geom = s
         ? textResizeGeometry(s)
         : layer

package/dist/calculator/index.d.ts

@@ -9,4 +9,5 @@ export * from './instance.js';
 export * from './runtime.js';
 export * from './display.js';
 export * from './chips.js';
+export * from './preview.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, type IssueSeverity, type ValidationIssue, type ValidationResult, } from './validate.js';

package/dist/calculator/index.js

@@ -15,4 +15,5 @@ export * from './instance.js';
 export * from './runtime.js';
 export * from './display.js';
 export * from './chips.js';
+export * from './preview.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, } from './validate.js';

package/dist/calculator/preview.d.ts

@@ -0,0 +1,22 @@
+import { type CalculatorDefinition, type CalculatorField } from './schema.js';
+import type { CalculatorInstanceFileData } from './instance.js';
+/**
+ * The field a thumbnail headlines, per CalculatorDefinition.previewFieldId's
+ * tri-state: an explicit id (when it names a numeric output), null for none,
+ * absent for auto — the sole numeric output, if there is exactly one.
+ */
+export declare const previewFieldFor: (definition: Pick<CalculatorDefinition, "fields" | "previewFieldId">) => CalculatorField | null;
+export interface PreviewValue {
+    field: CalculatorField;
+    /** Display string in `unit` — fractional inches etc., same as the runtime. */
+    value: string;
+    /** Unit label; empty for unit-less numbers. */
+    unit: string;
+}
+/**
+ * The headline value for an instance, or null when there is nothing to show:
+ * no preview field, the field is unresolved (inputs missing), or it is in
+ * conflict (the runtime withholds conflicted values behind a dash — a tile
+ * should show nothing rather than a dash).
+ */
+export declare const previewValueFor: (fileData: Pick<CalculatorInstanceFileData, "definition" | "entries" | "displayUnitOverrides">) => PreviewValue | null;

package/dist/calculator/preview.js

@@ -0,0 +1,43 @@
+// Thumbnail headline for a saved calculator instance (Asana
+// 1217881404454870): which output a tile shows, and its formatted value.
+// Shared by boldr-pro's FilePreview and rock-desktop so both platforms pick
+// the same field and print the same string. Pure — runs the same
+// deriveRuntime pass the runtime and the T1R drift check use, so it needs no
+// stored result (computed values are never persisted; see instance.ts).
+import { isEquationTargetKind, } from './schema.js';
+import { deriveRuntime } from './runtime.js';
+import { displayUnitFor, formatFieldValue } from './display.js';
+/** Outputs eligible to headline a thumbnail: numeric, equation-target kinds. */
+const numericOutputs = (definition) => definition.fields.filter((field) => field.role === 'output' && isEquationTargetKind(field.kind));
+/**
+ * The field a thumbnail headlines, per CalculatorDefinition.previewFieldId's
+ * tri-state: an explicit id (when it names a numeric output), null for none,
+ * absent for auto — the sole numeric output, if there is exactly one.
+ */
+export const previewFieldFor = (definition) => {
+    if (definition.previewFieldId === null)
+        return null;
+    const candidates = numericOutputs(definition);
+    if (typeof definition.previewFieldId === 'string') {
+        return (candidates.find((field) => field.id === definition.previewFieldId) ?? null);
+    }
+    return candidates.length === 1 ? candidates[0] : null;
+};
+/**
+ * The headline value for an instance, or null when there is nothing to show:
+ * no preview field, the field is unresolved (inputs missing), or it is in
+ * conflict (the runtime withholds conflicted values behind a dash — a tile
+ * should show nothing rather than a dash).
+ */
+export const previewValueFor = (fileData) => {
+    const field = previewFieldFor(fileData.definition);
+    if (!field)
+        return null;
+    const resolved = deriveRuntime(fileData.definition, fileData.entries ?? {})
+        .resolved[field.id];
+    if (!resolved || resolved.conflict || typeof resolved.value !== 'number') {
+        return null;
+    }
+    const unit = displayUnitFor(field, fileData.displayUnitOverrides ?? {});
+    return { field, ...formatFieldValue(field, unit, resolved.value) };
+};

package/dist/calculator/schema.d.ts

@@ -190,6 +190,20 @@ export interface CalculatorDefinition {
     /** Inputs + outputs in one list, discriminated by `role`. */
     fields: CalculatorField[];
     equations: CalculatorEquation[];
+    /**
+     * The output whose resolved value a saved instance's THUMBNAIL headlines
+     * (Asana 1217881404454870 — Area/Volume and every T1R function calculator
+     * are impractical to open one by one just to read the result). Tri-state:
+     *   - absent (undefined): AUTO — the sole numeric output when the
+     *     calculator has exactly one, nothing when it has several. This is also
+     *     what instances frozen before the field existed resolve to, so they
+     *     gain a headline without being re-saved.
+     *   - null: explicitly none — the author opted a single-output calc out.
+     *   - id: that output. Must be role 'output' and an equation-target kind;
+     *     anything else is validated as a warning and ignored at runtime.
+     * Always resolve through previewFieldFor() — never read this raw.
+     */
+    previewFieldId?: string | null;
     /** Diagram file (files subcollection doc carrying the Skia canvas). */
     diagramFileId?: string | null;
     /** Public calculators are readable by everyone; rules/query key. */

package/dist/calculator/schema.js

@@ -208,6 +208,8 @@ export const createEmptyCalculatorDefinition = (id) => ({
     category: null,
     fields: [],
     equations: [],
+    // previewFieldId is deliberately ABSENT, not null: absent means "auto"
+    // (headline the sole numeric output), null means the author opted out.
     diagramFileId: null,
     isPublic: false,
 });