@reekon-tools/boldr-utils 1.6.39 → 1.7.1

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

@@ -58,12 +58,20 @@ const LOUPE_CROSSHAIR_ARM = 9; // half-length of each crosshair arm, points
 export const AnnotationCanvasInner = (props) => {
     const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, } = props;
     const valueFont = useFont(stampFontSource, stampValueFontSize);
+    // The animated-viewport implementation needs the Reanimated shared values,
+    // which are created below AFTER the state hook — so the hook gets a stable
+    // trampoline into a ref the implementation fills in each render.
+    const animateViewportImplRef = useRef(null);
+    const animateViewport = useCallback((target, durationMs) => {
+        animateViewportImplRef.current?.(target, durationMs);
+    }, []);
     // This is the native (mobile) renderer, so the canvas reads mobile's
     // tile-scale knob (web and mobile persist separate values — see
     // resolveTileScaleFactor).
     const state = useAnnotationCanvasState({
         ...props,
         tileScalePlatform: 'mobile',
+        animateViewport,
     });
     // Decode the background image ONCE here and share it with both the main
     // canvas and the magnifier loupe. If each canvas loaded its own, the loupe
@@ -620,17 +628,73 @@ export const AnnotationCanvasInner = (props) => {
     // effect so an in-flight gesture's shared values are never clobbered by a
     // late-flushing setViewport from a previous gesture.
     const activeViewportGestures = useRef(0);
+    // >0 while an animated viewport transition (fitContentToRect) is in
+    // flight. Guards the JS→UI sync effect the same way the gesture counter
+    // does: mid-glide re-renders must not snap the shared values back to the
+    // (still-old) JS snapshot.
+    const viewportAnimations = useRef(0);
     // Push JS-originated viewport changes (initial mount, zoomToFit, resetView)
     // onto the UI thread. Gesture-driven changes already live in the shared
     // values, so during a gesture this is skipped; the post-gesture re-sync
-    // writes back identical values (no visual jump).
+    // writes back identical values (no visual jump). Ditto animated transitions.
     useEffect(() => {
         if (activeViewportGestures.current > 0)
             return;
+        if (viewportAnimations.current > 0)
+            return;
         zoom.value = state.viewport.zoom;
         panX.value = state.viewport.pan.x;
         panY.value = state.viewport.pan.y;
     }, [state.viewport, zoom, panX, panY]);
+    // Animated viewport transitions (fitContentToRect with `animated`): a JS
+    // rAF driver eases the same shared values gestures write — DIRECT writes,
+    // three per frame, no React involvement until the single end-of-motion
+    // commit. Direct `.value =` writes are the proven repaint channel for the
+    // Skia consumers (it's exactly how gestures render); driving these values
+    // through reanimated's animation path (withTiming) completed without ever
+    // repainting on device, so it is deliberately not used here. Mid-flight
+    // re-renders can't stomp the drive (the sync effect above is guarded), and
+    // a viewport gesture starting mid-flight ends the drive on its next frame
+    // — before it writes — and owns the viewport from there. A new drive takes
+    // over from the live values, so interrupted transitions resume from where
+    // they actually are.
+    const viewportDriveRef = useRef(null);
+    const cancelViewportDrive = useCallback(() => {
+        if (viewportDriveRef.current != null) {
+            cancelAnimationFrame(viewportDriveRef.current);
+            viewportDriveRef.current = null;
+            viewportAnimations.current = 0;
+        }
+    }, []);
+    useEffect(() => cancelViewportDrive, [cancelViewportDrive]);
+    animateViewportImplRef.current = (target, durationMs) => {
+        cancelViewportDrive();
+        const from = { zoom: zoom.value, panX: panX.value, panY: panY.value };
+        const start = Date.now();
+        const easeInOutCubic = (t) => t < 0.5 ? 4 * t * t * t : 1 - (2 - 2 * t) ** 3 / 2;
+        viewportAnimations.current = 1;
+        const step = () => {
+            if (activeViewportGestures.current > 0) {
+                viewportDriveRef.current = null;
+                viewportAnimations.current = 0;
+                return;
+            }
+            const t = Math.min(1, (Date.now() - start) / durationMs);
+            const eased = easeInOutCubic(t);
+            zoom.value = from.zoom + (target.zoom - from.zoom) * eased;
+            panX.value = from.panX + (target.pan.x - from.panX) * eased;
+            panY.value = from.panY + (target.pan.y - from.panY) * eased;
+            if (t < 1) {
+                viewportDriveRef.current = requestAnimationFrame(step);
+            }
+            else {
+                viewportDriveRef.current = null;
+                viewportAnimations.current = 0;
+                stateRef.current.setViewport(target);
+            }
+        };
+        viewportDriveRef.current = requestAnimationFrame(step);
+    };
     const gesture = useMemo(() => {
         const buildEvent = (pointerId, screen) => ({
             pointerId,
@@ -1427,7 +1491,12 @@ export const AnnotationCanvasInner = (props) => {
     // magnification lives in loupeTransform, applied to `content`).
     const loupeClip = rrect(rect(loupeX, loupeY, loupeSize, loupeSize), LOUPE_RADIUS, LOUPE_RADIUS);
     const loupeWrap = (content) => (_jsxs(_Fragment, { children: [_jsxs(Group, { clip: loupeClip, children: [_jsx(Rect, { x: loupeX, y: loupeY, width: loupeSize, height: loupeSize, color: LOUPE_BG_COLOR }), content] }), _jsx(RoundedRect, { x: loupeX, y: loupeY, width: loupeSize, height: loupeSize, r: LOUPE_RADIUS, color: LOUPE_BORDER_COLOR, style: "stroke", strokeWidth: LOUPE_BORDER_WIDTH }), _jsx(Line, { p1: { x: loupeCx - LOUPE_CROSSHAIR_ARM, y: loupeCy }, p2: { x: loupeCx + LOUPE_CROSSHAIR_ARM, y: loupeCy }, color: LOUPE_CROSSHAIR_COLOR, strokeWidth: 1.5 }), _jsx(Line, { p1: { x: loupeCx, y: loupeCy - LOUPE_CROSSHAIR_ARM }, p2: { x: loupeCx, y: loupeCy + LOUPE_CROSSHAIR_ARM }, color: LOUPE_CROSSHAIR_COLOR, strokeWidth: 1.5 })] }));
-    return (_jsxs(GestureHandlerRootView, { style: [{ width, height }, style], children: [_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
+    return (
+    // overflow hidden mirrors the web container: the Skia surface clips its
+    // drawing to the canvas box by construction, but the stamp overlay is
+    // plain RN views — without clipping, tiles panned past the edge of a
+    // non-fullscreen canvas (e.g. a diagram strip) escape into surrounding UI.
+    _jsxs(GestureHandlerRootView, { style: [{ width, height, overflow: 'hidden' }, style], children: [_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, tileViewportScale: state.tileViewportScale, onStampPress: onMeasurementStampPress, onStampLongPress: onMeasurementStampLongPress, onRemove: onMeasurementStampRemove
                         ? () => {

package/dist/annotation/canvas/tools/measurementLineTool.d.ts

@@ -0,0 +1,12 @@
+import type { PlacedMeasurementRef } from '../../../types/annotation.js';
+import type { Tool } from '../Tool.js';
+export interface MeasurementLineToolOptions {
+    id?: string;
+    label?: string;
+    minDragPx?: number;
+    autoSwitchToSelect?: boolean;
+    selectToolId?: string;
+    onAutoSwitch?: (toToolId: string) => void;
+    onPlaced?: (measurement: PlacedMeasurementRef) => void;
+}
+export declare const createMeasurementLineTool: (options?: MeasurementLineToolOptions) => Tool;

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

@@ -0,0 +1,95 @@
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
+import { DEFAULT_LINE_POS, recomputeAnchor } from '../measurementGeometry.js';
+let counter = 0;
+const makeId = () => `annotation-${Date.now().toString(36)}-${(counter++).toString(36)}`;
+const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
+// Build the blank line-measurement annotation for a drag from `a` to `b`: a
+// 2-point line with a value tile magnetized to its center (linePos 0.5). The
+// payload mirrors useAnnotationCanvasState's placeAnnotationAtCenter so a drawn
+// line and a (legacy) center-placed one are byte-identical once committed.
+const buildLineMeasurement = (opts) => {
+    const line = { a: opts.a, b: opts.b };
+    return {
+        id: opts.id,
+        layerId: opts.layerId,
+        placement: 'line',
+        line,
+        linePos: DEFAULT_LINE_POS,
+        // Center of the line; recomputeAnchor keeps this in sync on edits.
+        anchor: recomputeAnchor(line, 'line', DEFAULT_LINE_POS, {
+            x: (opts.a.x + opts.b.x) / 2,
+            y: (opts.a.y + opts.b.y) / 2,
+        }),
+        showLabel: true,
+        showValue: true,
+        createdAt: Date.now(),
+    };
+};
+// Drag-to-draw measurement-line tool. Press-drag rubber-bands a measurement
+// annotation (a line with a blank value tile at its center); release commits
+// it. Mirrors createShapeTool's interaction so "input lines" are placed the
+// same way as shapes — draw to add, not tap-the-icon-to-add — replacing the
+// old center-place affordance. The annotation stays blank (no measurement
+// associated) until the user fills it via the tile / picker. Skia-free, like
+// every tool factory; it renders its live preview through ctx.preview, so it
+// works on web and (via the generic tool-pan dispatch) on native.
+export const createMeasurementLineTool = (options = {}) => {
+    const minDragPx = options.minDragPx ?? 4;
+    const autoSwitchToSelect = options.autoSwitchToSelect ?? true;
+    const selectToolId = options.selectToolId ?? 'select';
+    return {
+        id: options.id ?? 'measure-line',
+        label: options.label ?? 'Measurement line',
+        cursor: 'crosshair',
+        onPointerDown(event) {
+            return {
+                kind: 'measurement-line-drawing',
+                id: makeId(),
+                startWorld: event.world,
+                startScreen: event.screen,
+                moved: false,
+            };
+        },
+        onPointerMove(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'measurement-line-drawing')
+                return s;
+            const measurement = buildLineMeasurement({
+                id: s.id,
+                layerId: firstLayerId(ctx.document),
+                a: s.startWorld,
+                b: event.world,
+            });
+            ctx.preview({ ops: [{ op: 'addMeasurement', measurement }] });
+            return { ...s, moved: true };
+        },
+        onPointerUp(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'measurement-line-drawing')
+                return;
+            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) {
+                // Accidental tap — discard the rubber-band, commit nothing.
+                ctx.preview({ ops: [] });
+                return;
+            }
+            const measurement = buildLineMeasurement({
+                id: s.id,
+                layerId: firstLayerId(ctx.document),
+                a: s.startWorld,
+                b: event.world,
+            });
+            ctx.commit({ ops: [{ op: 'addMeasurement', measurement }] });
+            // Leave it selected (and hand back to select) so the blank line can be
+            // filled / moved straight away — the same flow as the text tool.
+            ctx.setSelection({ ids: [measurement.id] });
+            options.onPlaced?.(measurement);
+            if (autoSwitchToSelect)
+                options.onAutoSwitch?.(selectToolId);
+        },
+        onCancel(_state, ctx) {
+            ctx.preview({ ops: [] });
+        },
+    };
+};

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

@@ -3,6 +3,12 @@ import { type AnnotationCanvasState, type AnnotationDocumentPatch, type Annotati
 import type { MeasurementRef } from './measurementPicker.js';
 import type { CanvasPointerEvent, RequestTextInput, Tool, ToolContext, ToolState } from './Tool.js';
 import { type ViewportState } from './viewport.js';
+export interface CanvasScreenRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface AnnotationCanvasHandle {
     undo(): void;
     redo(): void;
@@ -10,6 +16,10 @@ export interface AnnotationCanvasHandle {
     canRedo(): boolean;
     zoomToFit(): void;
     resetView(): void;
+    fitContentToRect(rect: CanvasScreenRect, opts?: {
+        animated?: boolean;
+        durationMs?: number;
+    }): void;
     getTileScaleFactor(): number;
     getTileDocSize(factor: number): number;
     ensureMeasurementVisible(id: AnnotationElementId): void;
@@ -49,6 +59,7 @@ export interface UseAnnotationCanvasStateProps {
     height: number;
     initialViewport?: ViewportState;
     tileScalePlatform?: TileScalePlatform;
+    animateViewport?: (target: ViewportState, durationMs: number) => void;
     imperativeRef?: {
         current: AnnotationCanvasHandle | null;
     };

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,24 +1,68 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
-import { resolveTileScaleFactor, stampTileDims, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
+import { resolveTileScaleFactor, stampTileDims, STAMP_TILE_SIZE, 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
-// image is present we fit its rendered rect (so the whole image shows, filling
-// the viewport 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. Shared by the load-time auto-fit and the zoomToFit/resetView
-// handle methods so they stay in lockstep.
-const computeContentFit = (canvas, width, height) => {
-    if (!(width > 0) || !(height > 0))
+// 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
+// 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
+// base rect and every placed tile's doc geometry. Tiles are screen-constant
+// boxes centered on that geometry, so when the union extends past the base
+// rect their half-extent is reserved as screen-space padding; a canvas whose
+// tiles all sit inside the image keeps the exact image fit it had before.
+// Shared by the load-time auto-fit and the zoomToFit/resetView/
+// fitContentToRect handle methods so they stay in lockstep.
+const computeContentFitRect = (canvas, rect) => {
+    if (!(rect.width > 0) || !(rect.height > 0))
         return DEFAULT_VIEWPORT;
     const { viewport } = canvas;
     const bg = viewport.backgroundImage;
-    const rect = bg
+    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 };
-    return fitRectToScreen(rect, width, height);
+    let minX = baseRect.x;
+    let minY = baseRect.y;
+    let maxX = baseRect.x + baseRect.width;
+    let maxY = baseRect.y + baseRect.height;
+    const extend = (p) => {
+        minX = Math.min(minX, p.x);
+        minY = Math.min(minY, p.y);
+        maxX = Math.max(maxX, p.x);
+        maxY = Math.max(maxY, p.y);
+    };
+    for (const placed of canvas.placedMeasurements) {
+        extend(placed.anchor);
+        if (placed.line) {
+            extend(placed.line.a);
+            extend(placed.line.b);
+        }
+        if (placed.rect) {
+            extend(placed.rect.a);
+            extend(placed.rect.b);
+        }
+    }
+    const extended = minX < baseRect.x ||
+        minY < baseRect.y ||
+        maxX > baseRect.x + baseRect.width ||
+        maxY > baseRect.y + baseRect.height;
+    const fit = fitRectToScreen({ x: minX, y: minY, width: maxX - minX, height: maxY - minY }, rect.width, rect.height, extended ? STAMP_TILE_SIZE / 2 : 0);
+    // fitRectToScreen frames within a box anchored at the origin; shift the
+    // window so the framed content lands in the sub-rect instead
+    // (screen = (world − pan) · zoom, so a +x screen offset is −x/zoom of pan).
+    return {
+        zoom: fit.zoom,
+        pan: {
+            x: fit.pan.x - rect.x / fit.zoom,
+            y: fit.pan.y - rect.y / fit.zoom,
+        },
+    };
 };
+const computeContentFit = (canvas, width, height) => computeContentFitRect(canvas, { x: 0, y: 0, width, height });
 // Default leader length (doc units) for a placed measurement when no explicit
 // length is given. A generous fraction of the document width, clamped, so the
 // leader — and its draggable endcaps — stay clear of the fixed-size value tile
@@ -31,7 +75,7 @@ const defaultLeaderLenDoc = (docWidth) => Math.min(800, Math.max(240, docWidth *
 // inners share this hook; each wraps it with platform-specific event
 // capture and JSX (div + DOM events vs. GestureDetector + RN Views).
 export const useAnnotationCanvasState = (props) => {
-    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, width, height, initialViewport, tileScalePlatform, imperativeRef, } = props;
+    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
     const [viewport, setViewport] = useState(initialViewport ?? DEFAULT_VIEWPORT);
     const [toolState, setToolState] = useState(undefined);
     const [previewPatch, setPreviewPatch] = useState(null);
@@ -265,6 +309,32 @@ export const useAnnotationCanvasState = (props) => {
                 ],
             });
         };
+        // Consecutive place-at-center drops would all land dead-center, stacking
+        // each new tile exactly on top of the previous one. Cascade instead: walk
+        // down-right in fixed screen-px steps from center until a slot with no
+        // existing anchor is found. Occupancy is derived from the live placed
+        // measurements (not a drop counter), so moving or deleting a tile frees
+        // its slot automatically. Screen space is the right frame — tiles are
+        // screen-constant boxes — and mirrors the Nutrient file-viewer's cascade.
+        const cascadeCenterWorld = () => {
+            const c = ctxRef.current;
+            const CASCADE_STEP = 30;
+            const anchorsScreen = c.document.placedMeasurements.map((m) => c.viewport.worldToScreen(m.anchor));
+            const slotTaken = (x, y) => anchorsScreen.some((p) => Math.abs(p.x - x) < CASCADE_STEP / 2 &&
+                Math.abs(p.y - y) < CASCADE_STEP / 2);
+            // Stop cascading before the tile's right/bottom edge would leave the
+            // screen (tiles are centered on their anchor).
+            const halfTile = (STAMP_TILE_SIZE / 2) * c.tileScaleFactor * c.tileViewportScale;
+            let cx = width / 2;
+            let cy = height / 2;
+            while (slotTaken(cx, cy) &&
+                cx + halfTile + CASCADE_STEP <= width &&
+                cy + halfTile + CASCADE_STEP <= height) {
+                cx += CASCADE_STEP;
+                cy += CASCADE_STEP;
+            }
+            return c.viewport.screenToWorld({ x: cx, y: cy });
+        };
         imperativeRef.current = {
             undo() {
                 const entry = undoStackRef.current.pop();
@@ -295,6 +365,17 @@ export const useAnnotationCanvasState = (props) => {
                 // for a high-res background is the very crop this is meant to escape.
                 setViewport(computeContentFit(canvas, width, height));
             },
+            fitContentToRect(rect, opts) {
+                if (!(rect.width > 0) || !(rect.height > 0))
+                    return;
+                const target = computeContentFitRect(canvas, rect);
+                if (opts?.animated && animateViewport) {
+                    animateViewport(target, opts.durationMs ?? 300);
+                }
+                else {
+                    setViewport(target);
+                }
+            },
             getTileScaleFactor() {
                 return ctxRef.current.tileScaleFactor;
             },
@@ -328,10 +409,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeMeasurementAtCenter(ref) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 const placed = {
                     id: `measurement-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`,
                     layerId: c.document.layers[0]?.id ?? DEFAULT_LAYER_ID,
@@ -352,10 +430,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeAnnotationAtCenter(opts) {
                 const c = ctxRef.current;
-                const center = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const center = cascadeCenterWorld();
                 // Default line length: a generous fraction of the doc width, clamped,
                 // so the leader and its endcaps clear the fixed-size tile at full-fit.
                 const len = opts?.defaultLengthDoc ?? defaultLeaderLenDoc(canvas.viewport.width);
@@ -492,10 +567,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeColumnTileAtCenter(binding) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 const placed = {
                     id: `measurement-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`,
                     layerId: c.document.layers[0]?.id ?? DEFAULT_LAYER_ID,
@@ -513,10 +585,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeGroupHeaderAtCenter(ref) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 // No showLabel/showValue/placement — a header is not an input; it
                 // renders the group's name/index, resolved live by the consumer.
                 const placed = {

package/dist/annotation/data/AnnotationDataProvider.d.ts

@@ -12,8 +12,13 @@ export interface TemplateScope {
     orgId?: string;
     templateId: string;
 }
-export type AnnotationScope = JobGroupScope | TemplateScope;
+export interface CalculatorScope {
+    kind: 'calculator';
+    calculatorId: string;
+}
+export type AnnotationScope = JobGroupScope | TemplateScope | CalculatorScope;
 export declare const isTemplateScope: (s: AnnotationScope) => s is TemplateScope;
+export declare const isCalculatorScope: (s: AnnotationScope) => s is CalculatorScope;
 export declare const annotationScopeKey: (s: AnnotationScope | null) => string;
 export type Unsubscribe = () => void;
 export type FieldOp = {

package/dist/annotation/data/AnnotationDataProvider.js

@@ -1,11 +1,14 @@
 export const isTemplateScope = (s) => 'kind' in s && s.kind === 'template';
+export const isCalculatorScope = (s) => 'kind' in s && s.kind === 'calculator';
 // Stable string identity for a scope, for React hook dep arrays — scope
 // objects are typically rebuilt every render.
 export const annotationScopeKey = (s) => s == null
     ? ''
     : isTemplateScope(s)
         ? `template/${s.orgId ?? ''}/${s.templateId}`
-        : `job/${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
+        : isCalculatorScope(s)
+            ? `calculator/${s.calculatorId}`
+            : `job/${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
 export const isFieldOp = (v) => !!v &&
     typeof v === 'object' &&
     'kind' in v &&

package/dist/calculator/evaluate.d.ts

@@ -0,0 +1,49 @@
+import type { CalculatorDefinition, CalculatorEquation, CalculatorField, CalculatorFieldValue, CalculatorValues } from './schema.js';
+export type ExpressionResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The unit-agnostic expression core: compile + evaluate + finiteness checks,
+ * no unit coercion. Scope values and the result share whatever unit system
+ * the caller established (canonical, for calculator equations).
+ */
+export declare const evaluateExpression: (expression: string, scope: Record<string, number>) => ExpressionResult;
+/**
+ * The canonical numeric value a field contributes to an equation scope, or
+ * null when the field has no usable value. Select and instructions fields are
+ * non-computational (validation rejects mapping them into equations).
+ */
+export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined) => number | null;
+export type EquationResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: 'missing-inputs';
+    missingFieldIds: string[];
+} | {
+    ok: false;
+    reason: 'error';
+    error: string;
+};
+/**
+ * Evaluate one equation against canonical field values. Variables referencing
+ * other output fields recurse into their equations (cycle-guarded).
+ */
+export declare const evaluateEquation: ({ definition, equation, values, }: {
+    definition: Pick<CalculatorDefinition, "fields" | "equations">;
+    equation: CalculatorEquation;
+    values: CalculatorValues;
+}) => EquationResult;
+/**
+ * Evaluate every equation in the definition. Returns a result per target
+ * field id — the live-preview / runtime "recompute all outputs" entry point.
+ */
+export declare const evaluateOutputs: ({ definition, values, }: {
+    definition: Pick<CalculatorDefinition, "fields" | "equations">;
+    values: CalculatorValues;
+}) => Record<string, EquationResult>;