@reekon-tools/boldr-utils 1.6.11 → 1.6.12

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

@@ -0,0 +1,46 @@
+import { type SkFont, type SkPath, type Transforms3d } from '@shopify/react-native-skia';
+import type { ReactNode } from 'react';
+import type { AnnotationCanvasState, AnnotationStroke, StrokeCap } from '../../types/annotation.js';
+type AnimatedPoint = {
+    x: number;
+    y: number;
+} | {
+    value: {
+        x: number;
+        y: number;
+    };
+};
+export interface AnnotationCanvasSkiaProps {
+    width: number;
+    height: number;
+    effectiveCanvas: AnnotationCanvasState;
+    worldTransform: Transforms3d | {
+        value: Transforms3d;
+    };
+    resolveImageUrl?: (storagePath: string) => Promise<string>;
+    valueFont: SkFont | null;
+    penDrawingStroke: AnnotationStroke | null;
+    livePreview?: {
+        path: SkPath | {
+            value: SkPath;
+        };
+        color: string;
+        width: number;
+        cap?: StrokeCap;
+        opacity: number;
+    } | null;
+    draggingId?: string | null;
+    dragTransform?: Transforms3d | {
+        value: Transforms3d;
+    };
+    selectedId?: string | null;
+    endpointDragId?: string | null;
+    liveLineP1?: AnimatedPoint;
+    liveLineP2?: AnimatedPoint;
+    handleRadius?: number | {
+        value: number;
+    };
+    customPreview?: ReactNode;
+}
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, valueFont, penDrawingStroke, livePreview, draggingId, dragTransform, selectedId, endpointDragId, liveLineP1, liveLineP2, handleRadius, customPreview, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Canvas, Circle, Group, Line, Path, Rect, Skia, } from '@shopify/react-native-skia';
+import { placementOf } from './measurementGeometry.js';
+import { arrowheadTriangle, toSkiaStrokeCap } from './strokeGeometry.js';
+import { BackgroundImageElement } from './elements/BackgroundImageElement.js';
+import { ShapeElement } from './elements/ShapeElement.js';
+import { StrokeElement } from './elements/StrokeElement.js';
+// Default visual constants for the measurement-annotation line (the tile itself
+// is a fixed-size overlay; only the line lives in Skia). Width is in doc units,
+// so it scales with zoom like the drawn line/arrow shapes. These are fallbacks:
+// a placed annotation may override them via `lineColor`/`lineWidth`/`lineCap`.
+const MEASUREMENT_LINE_COLOR = '#0066FF';
+const MEASUREMENT_LINE_WIDTH = 2;
+// Endpoint handle color — constant selection chrome, independent of the (now
+// editable) line color so the handles stay legible on any line color.
+const MEASUREMENT_HANDLE_COLOR = '#0066FF';
+// Selection bounding box for strokes/shapes (measurements get handles instead).
+// Padding + stroke width are in doc units (scale with zoom) — simple and clear;
+// the box is only a "this is selected" affordance, not a precise gizmo.
+const SELECTION_COLOR = '#0066FF';
+const SELECTION_PAD = 6;
+const SELECTION_STROKE = 1.5;
+// Bounds of a flat [x,y,x,y,…] stroke point array, or null if empty.
+const strokeBounds = (points) => {
+    if (points.length < 2)
+        return null;
+    let minX = points[0];
+    let maxX = points[0];
+    let minY = points[1];
+    let maxY = points[1];
+    for (let i = 2; i < points.length; i += 2) {
+        const x = points[i];
+        const y = points[i + 1];
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    return { minX, minY, maxX, maxY };
+};
+// Bounds of a Vec2[] (shape geometry), or null if empty.
+const pointsBounds = (pts) => {
+    if (pts.length === 0)
+        return null;
+    let { x: minX, y: minY } = pts[0];
+    let { x: maxX, y: maxY } = pts[0];
+    for (let i = 1; i < pts.length; i++) {
+        const p = pts[i];
+        if (p.x < minX)
+            minX = p.x;
+        if (p.x > maxX)
+            maxX = p.x;
+        if (p.y < minY)
+            minY = p.y;
+        if (p.y > maxY)
+            maxY = p.y;
+    }
+    return { minX, minY, maxX, maxY };
+};
+// Wraps a single element in the live drag transform while it's being dragged
+// (native, UI-thread). When not dragging it renders the element untouched, so
+// the element's React.memo still bails out on unrelated re-renders.
+const DraggableElement = ({ isDragging, transform, children, }) => isDragging && transform ? (_jsx(Group, { transform: transform, children: children })) : (_jsx(_Fragment, { children: children }));
+// Bounding-box outline around a selected stroke/shape. Padded in doc space and
+// wrapped in DraggableElement so it tracks the element during a group drag.
+const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElement, { isDragging: isDragging, transform: transform, children: _jsx(Rect, { x: bounds.minX - SELECTION_PAD, y: bounds.minY - SELECTION_PAD, width: bounds.maxX - bounds.minX + SELECTION_PAD * 2, height: bounds.maxY - bounds.minY + SELECTION_PAD * 2, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }) }));
+// Platform-agnostic Skia subtree shared by web and native Inners.
+//
+// Placed measurements are NOT drawn here — they render as a non-interactive
+// RN/DOM overlay of real tile components (`renderMeasurementStamp`) positioned
+// over this canvas by the Inner. This subtree owns only the vector content
+// (background, strokes, shapes) and the live tool previews.
+//
+// Call this as a FUNCTION (`AnnotationCanvasSkia({ ... })`), not as a JSX
+// component (`<AnnotationCanvasSkia ... />`). Used as a component, it adds
+// a React component boundary between the parent and Skia's `<Canvas>` that
+// breaks Skia's reconciler when the page first calls `useFont` — the JS
+// thread hangs in `MakeFreeTypeFaceFromData`. Symptoms only appeared on
+// Vite's dev server with a symlinked boldr-utils + React Refresh, but
+// 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, resolveImageUrl, valueFont, penDrawingStroke, livePreview, draggingId, dragTransform, selectedId, endpointDragId, liveLineP1, liveLineP2, handleRadius, customPreview, }) => (_jsx(Canvas, { style: { width, height }, children: _jsxs(Group, { transform: worldTransform, children: [effectiveCanvas.viewport.backgroundImage && (_jsx(BackgroundImageElement, { image: effectiveCanvas.viewport.backgroundImage, docWidth: effectiveCanvas.viewport.width, docHeight: effectiveCanvas.viewport.height, fit: effectiveCanvas.viewport.backgroundFit ?? 'contain', resolveUrl: resolveImageUrl })), effectiveCanvas.strokes.map((stroke) => (_jsx(DraggableElement, { isDragging: stroke.id === draggingId, transform: dragTransform, children: _jsx(StrokeElement, { stroke: stroke }) }, stroke.id))), effectiveCanvas.shapes.map((shape) => (_jsx(DraggableElement, { isDragging: shape.id === draggingId, transform: dragTransform, children: _jsx(ShapeElement, { shape: shape, font: valueFont }) }, shape.id))), effectiveCanvas.placedMeasurements.map((placed) => {
+                if (placementOf(placed) !== 'line' || !placed.line)
+                    return null;
+                const isEndpointDrag = placed.id === endpointDragId;
+                const isSelected = placed.id === selectedId;
+                const p1 = isEndpointDrag && liveLineP1 ? liveLineP1 : placed.line.a;
+                const p2 = isEndpointDrag && liveLineP2 ? liveLineP2 : placed.line.b;
+                const lineColor = placed.lineColor ?? MEASUREMENT_LINE_COLOR;
+                const lineWidth = placed.lineWidth ?? MEASUREMENT_LINE_WIDTH;
+                // Solid filled-triangle arrowhead at endpoint b (the line's "end").
+                // Built from the static endpoints, so it's skipped during a live
+                // endpoint drag (it reappears on release) rather than lagging the
+                // moving finger.
+                const arrowPath = (() => {
+                    if (placed.lineCap !== 'arrow' || isEndpointDrag || !placed.line) {
+                        return null;
+                    }
+                    const [apex, baseL, baseR] = arrowheadTriangle(placed.line.b, placed.line.a, lineWidth);
+                    const p = Skia.Path.Make();
+                    p.moveTo(apex.x, apex.y);
+                    p.lineTo(baseL.x, baseL.y);
+                    p.lineTo(baseR.x, baseR.y);
+                    p.close();
+                    return p;
+                })();
+                const content = (_jsxs(_Fragment, { children: [_jsx(Line, { p1: p1, p2: p2, color: lineColor, style: "stroke", strokeWidth: lineWidth, strokeCap: toSkiaStrokeCap(placed.lineCap) }), arrowPath && (_jsx(Path, { path: arrowPath, color: lineColor, style: "fill" })), isSelected && handleRadius != null && (_jsxs(_Fragment, { children: [_jsx(Circle, { c: p1, r: handleRadius, color: MEASUREMENT_HANDLE_COLOR }), _jsx(Circle, { c: p2, r: handleRadius, color: MEASUREMENT_HANDLE_COLOR })] }))] }));
+                return isEndpointDrag ? (_jsx(Group, { children: content }, placed.id)) : (_jsx(DraggableElement, { isDragging: placed.id === draggingId, transform: dragTransform, children: content }, placed.id));
+            }), (() => {
+                if (!selectedId)
+                    return null;
+                const isDragging = selectedId === draggingId;
+                const stroke = effectiveCanvas.strokes.find((s) => s.id === selectedId);
+                if (stroke) {
+                    const b = strokeBounds(stroke.points);
+                    return b ? (_jsx(SelectionBox, { bounds: b, isDragging: isDragging, transform: dragTransform })) : null;
+                }
+                const shape = effectiveCanvas.shapes.find((s) => s.id === selectedId);
+                if (shape) {
+                    const b = pointsBounds(shape.geometry.points);
+                    return b ? (_jsx(SelectionBox, { bounds: b, isDragging: isDragging, transform: dragTransform })) : null;
+                }
+                return null;
+            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity })), customPreview] }) }));

package/dist/{canvas → annotation/canvas}/Tool.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode, ComponentType } from 'react';
-import type { AnnotationCanvasState, AnnotationDocumentPatch, AnnotationElement, Selection, Vec2 } from '../types/annotation.js';
+import type { AnnotationCanvasState, AnnotationDocumentPatch, AnnotationElement, AnnotationElementId, Selection, StrokeCap, Vec2 } from '../../types/annotation.js';
 import type { MeasurementRef } from './measurementPicker.js';
 import type { ViewportApi } from './viewport.js';
 export interface CanvasPointerEvent {
@@ -24,11 +24,33 @@ export interface ToolContext {
     applyZoom(focalScreen: Vec2, nextZoom: number): void;
 }
 export type ToolState = unknown;
+export interface FreehandConfig {
+    variant: 'pen' | 'marker' | 'highlighter';
+    color: string;
+    width: number;
+    cap?: StrokeCap;
+    minSampleDistance: number;
+}
+export type DragElementKind = 'stroke' | 'shape' | 'measurement';
+export interface DragSelectionConfig {
+    hitTest(doc: AnnotationCanvasState, world: Vec2, zoom: number): {
+        id: AnnotationElementId;
+        kind: DragElementKind;
+    } | null;
+    buildTranslatePatch(doc: AnnotationCanvasState, id: AnnotationElementId, kind: DragElementKind, delta: Vec2): AnnotationDocumentPatch | null;
+    classifyMeasurementGrab?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): 'slide' | 'move';
+    buildSlidePatch?(doc: AnnotationCanvasState, id: AnnotationElementId, delta: Vec2, zoom: number): AnnotationDocumentPatch | null;
+    hitTestHandle?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): 'a' | 'b' | null;
+    buildEndpointPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, handle: 'a' | 'b', delta: Vec2): AnnotationDocumentPatch | null;
+}
 export interface Tool {
     id: string;
     label: string;
     icon?: ComponentType;
     cursor?: string;
+    freehand?: FreehandConfig;
+    panViewport?: boolean;
+    dragSelection?: DragSelectionConfig;
     onPointerDown?(event: CanvasPointerEvent, ctx: ToolContext, state: ToolState): ToolState | void;
     onPointerMove?(event: CanvasPointerEvent, ctx: ToolContext, state: ToolState): ToolState | void;
     onPointerUp?(event: CanvasPointerEvent, ctx: ToolContext, state: ToolState): ToolState | void;

package/dist/{canvas → annotation/canvas}/elements/BackgroundImageElement.d.ts

@@ -1,4 +1,4 @@
-import type { AnnotationBackgroundImage, BackgroundFit } from '../../types/annotation.js';
+import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
 export interface BackgroundImageElementProps {
     image: AnnotationBackgroundImage;
     docWidth: number;
@@ -6,4 +6,4 @@ export interface BackgroundImageElementProps {
     fit?: BackgroundFit;
     resolveUrl?: (path: string) => Promise<string>;
 }
-export declare const BackgroundImageElement: ({ image, docWidth, docHeight, fit, resolveUrl, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const BackgroundImageElement: import("react").MemoExoticComponent<({ image, docWidth, docHeight, fit, resolveUrl, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;

package/dist/{canvas → annotation/canvas}/elements/BackgroundImageElement.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Image, useImage } from '@shopify/react-native-skia';
-import { useEffect, useState } from 'react';
+import { memo, useEffect, useRef, useState } from 'react';
 const computeFit = (imgW, imgH, docW, docH, fit) => {
     if (fit === 'stretch') {
         return { x: 0, y: 0, width: docW, height: docH };
@@ -12,12 +12,19 @@ const computeFit = (imgW, imgH, docW, docH, fit) => {
     const h = imgH * scale;
     return { x: (docW - w) / 2, y: (docH - h) / 2, width: w, height: h };
 };
-export const BackgroundImageElement = ({ image, docWidth, docHeight, fit = 'contain', resolveUrl, }) => {
+export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, }) => {
     const [url, setUrl] = useState(image.downloadUrl);
+    // Hold resolveUrl in a ref so re-resolution is keyed only on the image
+    // identity, not the function's. Consumers commonly pass an inline closure
+    // (a new reference each render); depending on it directly would re-run a
+    // network URL resolve on every render.
+    const resolveUrlRef = useRef(resolveUrl);
+    resolveUrlRef.current = resolveUrl;
     useEffect(() => {
         let cancelled = false;
-        if (resolveUrl) {
-            resolveUrl(image.storagePath).then((next) => {
+        const resolve = resolveUrlRef.current;
+        if (resolve) {
+            resolve(image.storagePath).then((next) => {
                 if (!cancelled)
                     setUrl(next);
             });
@@ -28,10 +35,10 @@ export const BackgroundImageElement = ({ image, docWidth, docHeight, fit = 'cont
         return () => {
             cancelled = true;
         };
-    }, [image.downloadUrl, image.storagePath, resolveUrl]);
+    }, [image.downloadUrl, image.storagePath]);
     const skImage = useImage(url);
     if (!skImage)
         return null;
     const dims = computeFit(image.widthPx, image.heightPx, docWidth, docHeight, fit);
     return (_jsx(Image, { image: skImage, x: dims.x, y: dims.y, width: dims.width, height: dims.height, fit: "fill" }));
-};
+});

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

@@ -0,0 +1,7 @@
+import { type SkFont } from '@shopify/react-native-skia';
+import type { AnnotationShape } from '../../../types/annotation.js';
+export interface ShapeElementProps {
+    shape: AnnotationShape;
+    font?: SkFont | null;
+}
+export declare const ShapeElement: import("react").MemoExoticComponent<({ shape, font }: ShapeElementProps) => import("react/jsx-runtime").JSX.Element | null>;

package/dist/{canvas → annotation/canvas}/elements/ShapeElement.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Circle, Line, Path, Rect, Skia, Text, } from '@shopify/react-native-skia';
-import { useMemo } from 'react';
+import { memo, useMemo } from 'react';
 const polygonPath = (points) => {
     const path = Skia.Path.Make();
     if (points.length === 0)
@@ -12,7 +12,9 @@ const polygonPath = (points) => {
     path.close();
     return path;
 };
-export const ShapeElement = ({ shape, font }) => {
+// Memoized — see StrokeElement. Unchanged shapes keep their identity across
+// applyPatch, so only the edited shape (and the shared font) re-render.
+export const ShapeElement = memo(({ shape, font }) => {
     const { kind, geometry, style, text } = shape;
     const stroke = style.stroke ?? '#000000';
     const fill = style.fill;
@@ -59,4 +61,4 @@ export const ShapeElement = ({ shape, font }) => {
             return (_jsx(Text, { x: origin.x, y: origin.y, text: text, font: font, color: stroke }));
         }
     }
-};
+});

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

@@ -0,0 +1,7 @@
+import { type SkPath } from '@shopify/react-native-skia';
+import type { AnnotationStroke } from '../../../types/annotation.js';
+export declare const pointsToSkPath: (points: number[]) => SkPath;
+export interface StrokeElementProps {
+    stroke: AnnotationStroke;
+}
+export declare const StrokeElement: import("react").MemoExoticComponent<({ stroke }: StrokeElementProps) => import("react/jsx-runtime").JSX.Element>;

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

@@ -0,0 +1,40 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Path, Skia } from '@shopify/react-native-skia';
+import { memo, useMemo } from 'react';
+import { arrowheadTriangle, toSkiaStrokeCap } from '../strokeGeometry.js';
+export const pointsToSkPath = (points) => {
+    const path = Skia.Path.Make();
+    if (points.length < 2)
+        return path;
+    path.moveTo(points[0], points[1]);
+    for (let i = 2; i < points.length; i += 2) {
+        path.lineTo(points[i], points[i + 1]);
+    }
+    return path;
+};
+// A solid filled-triangle arrowhead at the stroke's end (vertex at the last
+// point, base corners back along the final segment), or null when the cap isn't
+// 'arrow'. Rendered as a separate filled <Path> on top of the stroked line.
+const arrowheadPath = (stroke) => {
+    const n = stroke.points.length;
+    if (stroke.cap !== 'arrow' || n < 4)
+        return null;
+    const end = { x: stroke.points[n - 2], y: stroke.points[n - 1] };
+    const from = { x: stroke.points[n - 4], y: stroke.points[n - 3] };
+    const [apex, baseL, baseR] = arrowheadTriangle(end, from, stroke.width);
+    const path = Skia.Path.Make();
+    path.moveTo(apex.x, apex.y);
+    path.lineTo(baseL.x, baseL.y);
+    path.lineTo(baseR.x, baseR.y);
+    path.close();
+    return path;
+};
+// Memoized: the canvas re-renders the whole element list on every commit,
+// preview, and selection change, but applyPatch preserves the identity of
+// unchanged strokes — so memo lets all but the changed stroke bail out.
+export const StrokeElement = memo(({ stroke }) => {
+    const path = useMemo(() => pointsToSkPath(stroke.points), [stroke.points]);
+    const arrow = useMemo(() => arrowheadPath(stroke), [stroke.points, stroke.cap, stroke.width]);
+    const opacity = stroke.tool === 'highlighter' ? 0.3 : 1;
+    return (_jsxs(_Fragment, { children: [_jsx(Path, { path: path, color: stroke.color, style: "stroke", strokeWidth: stroke.width, strokeCap: toSkiaStrokeCap(stroke.cap), strokeJoin: "round", opacity: opacity }), arrow && (_jsx(Path, { path: arrow, color: stroke.color, style: "fill", opacity: opacity }))] }));
+});

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

@@ -0,0 +1,23 @@
+import type { AnnotationPatchOp, MeasurementPlacement, PlacedMeasurementRef, Vec2 } from '../../types/annotation.js';
+export declare const DEFAULT_LINE_POS = 0.5;
+export declare const lerp: (a: Vec2, b: Vec2, t: number) => Vec2;
+export declare const placementOf: (m: Pick<PlacedMeasurementRef, "placement">) => MeasurementPlacement;
+export declare const linePosOf: (m: Pick<PlacedMeasurementRef, "linePos">) => number;
+export declare const recomputeAnchor: (line: {
+    a: Vec2;
+    b: Vec2;
+} | undefined, placement: MeasurementPlacement, linePos: number, fallbackAnchor: Vec2) => Vec2;
+export declare const projectToLinePos: (line: {
+    a: Vec2;
+    b: Vec2;
+}, world: Vec2) => number;
+export declare const snapLinePos: (t: number, threshold?: number) => number;
+export declare const lineLength: (line: {
+    a: Vec2;
+    b: Vec2;
+}) => number;
+export interface RemoveMeasurementResult {
+    ops: AnnotationPatchOp[];
+    keepSelection: boolean;
+}
+export declare const buildRemoveMeasurementOps: (placed: PlacedMeasurementRef) => RemoveMeasurementResult;

package/dist/annotation/canvas/measurementGeometry.js

@@ -0,0 +1,74 @@
+// Pure geometry for measurement annotations (the `placement: 'line'` variant
+// of PlacedMeasurementRef). Skia-free and dependency-free so it's safe in tools,
+// hit-tests, and unit tests.
+//
+// NOTE: the native overlay's `useAnimatedStyle` and the live-line derived values
+// run on the UI thread and CANNOT call these functions across the worklet
+// boundary, so they inline the same math. Those inlined copies are the "worklet
+// twins" of these helpers — if you change the math here, change them too (they
+// are commented as such in AnnotationCanvasInner.native.tsx).
+// Default position of the tile along its line when `linePos` is absent: center.
+export const DEFAULT_LINE_POS = 0.5;
+export const lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+});
+// Back-compat accessors: a stamp persisted before this feature has neither
+// field, and reads as a bare 'none' stamp centered on its line (if any).
+export const placementOf = (m) => m.placement ?? 'none';
+export const linePosOf = (m) => m.linePos ?? DEFAULT_LINE_POS;
+// The tile anchor implied by a line + placement. For 'line', the tile sits at
+// lerp(a, b, linePos); for everything else the stored anchor stands. Callers
+// must write the result into `anchor` in the same patch that changes
+// `line`/`placement`/`linePos` so the two never drift.
+export const recomputeAnchor = (line, placement, linePos, fallbackAnchor) => {
+    if (placement === 'line' && line)
+        return lerp(line.a, line.b, linePos);
+    return fallbackAnchor;
+};
+// Project a world point onto segment a→b and return the clamped parameter
+// t ∈ [0, 1] (0 = a, 1 = b). A zero-length line returns 0.
+export const projectToLinePos = (line, world) => {
+    const abx = line.b.x - line.a.x;
+    const aby = line.b.y - line.a.y;
+    const lenSq = abx * abx + aby * aby;
+    if (lenSq === 0)
+        return 0;
+    const t = ((world.x - line.a.x) * abx + (world.y - line.a.y) * aby) / lenSq;
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+};
+// Snap t to center (0.5) when within `threshold` of it. `threshold` is in
+// t-space; for a consistent on-screen detent, callers convert a screen-px
+// radius to t via (radiusPx / zoom) / lineLengthDoc.
+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).
+export const lineLength = (line) => {
+    const dx = line.b.x - line.a.x;
+    const dy = line.b.y - line.a.y;
+    return Math.sqrt(dx * dx + dy * dy);
+};
+export const buildRemoveMeasurementOps = (placed) => {
+    if (placementOf(placed) === 'line' && placed.measurementId) {
+        return {
+            ops: [
+                {
+                    op: 'updateMeasurement',
+                    id: placed.id,
+                    patch: {
+                        measurementId: undefined,
+                        measurementPath: undefined,
+                        groupId: undefined,
+                        labelOverride: undefined,
+                        unitOverride: undefined,
+                    },
+                },
+            ],
+            keepSelection: true,
+        };
+    }
+    return {
+        ops: [{ op: 'removeMeasurement', id: placed.id }],
+        keepSelection: false,
+    };
+};

package/dist/{canvas → annotation/canvas}/measurementPicker.d.ts

@@ -1,4 +1,4 @@
-import type { Units } from '../types/firestore.js';
+import type { Units } from '../../types/firestore.js';
 export interface MeasurementRef {
     measurementId: string;
     measurementPath: string;

package/dist/{canvas → annotation/canvas}/measurementStampOverlay.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
-import type { PlacedMeasurementRef } from '../types/annotation.js';
-import type { Measurement } from '../types/firestore.js';
+import type { PlacedMeasurementRef } from '../../types/annotation.js';
+import type { Measurement } from '../../types/firestore.js';
 export interface MeasurementStampRenderArgs {
     placed: PlacedMeasurementRef;
     measurement: Measurement | null;

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

@@ -0,0 +1 @@
+export declare const STAMP_TILE_SIZE = 96;

package/dist/annotation/canvas/stampLayout.js

@@ -0,0 +1,11 @@
+// Shared layout constant for the placed measurement stamp. Lives in a
+// Skia-free module so both the render path (the `renderMeasurementStamp`
+// overlay — see measurementStampOverlay.ts) and the hit-test (selectTool)
+// can import it without dragging @shopify/react-native-skia into the
+// consumer's static import graph.
+// Constant SCREEN-space edge length of a placed measurement rendered as a
+// square tile. The tile is a fixed-size pin: its on-screen size is this times
+// `placed.scale` and does NOT change with zoom (only its position tracks the
+// canvas). Also drives the select-tool hit box, which converts it back to doc
+// space via the zoom.
+export const STAMP_TILE_SIZE = 96;

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

@@ -0,0 +1,4 @@
+import type { StrokeCap, Vec2 } from '../../types/annotation.js';
+export declare const toSkiaStrokeCap: (cap: StrokeCap | undefined) => "butt" | "round" | "square";
+export declare const arrowheadLength: (width: number) => number;
+export declare const arrowheadTriangle: (end: Vec2, from: Vec2, width: number) => [Vec2, Vec2, Vec2];

package/dist/annotation/canvas/strokeGeometry.js

@@ -0,0 +1,33 @@
+// Pure helpers for stroke end-cap rendering. Skia-free and dependency-free so
+// they're safe in element renderers, the measurement-line pass, and unit tests.
+// Map our end-cap style to a Skia-valid strokeCap. 'arrow' is NOT a Skia cap
+// (we draw an arrowhead separately), so the base line uses a 'round' cap.
+// Absent === 'round'.
+export const toSkiaStrokeCap = (cap) => cap === 'butt' || cap === 'square' ? cap : 'round';
+// Forward length of the arrowhead (line end → apex), as a multiple of stroke
+// width (clamped to a minimum so thin strokes still get a visible head). Doc
+// units. Kept small since the head is a solid filled triangle.
+export const arrowheadLength = (width) => Math.max(width * 2, 6);
+// Half the arrowhead's base width. Kept >= the round-cap radius (width / 2) so
+// the triangle fully covers the shaft's end cap.
+const arrowheadHalfBase = (width) => Math.max(width * 0.9, 4);
+// A solid-triangle arrowhead pointing in the travel direction (from `from`
+// toward `end`). Returns [apex, baseLeft, baseRight]: the apex sits FORWARD of
+// the line end (so the point isn't swallowed by the shaft or its end cap), and
+// the base straddles the end point (so the triangle hides the cap bulge).
+export const arrowheadTriangle = (end, from, width) => {
+    const dx = end.x - from.x;
+    const dy = end.y - from.y;
+    const len = Math.hypot(dx, dy) || 1;
+    const ux = dx / len; // unit travel direction
+    const uy = dy / len;
+    const px = -uy; // unit perpendicular
+    const py = ux;
+    const head = arrowheadLength(width);
+    const half = arrowheadHalfBase(width);
+    return [
+        { x: end.x + ux * head, y: end.y + uy * head }, // apex, forward of the end
+        { x: end.x + px * half, y: end.y + py * half }, // base left
+        { x: end.x - px * half, y: end.y - py * half }, // base right
+    ];
+};

package/dist/{canvas → annotation/canvas}/tools/measurementStampTool.d.ts

@@ -1,4 +1,4 @@
-import type { PlacedMeasurementRef } from '../../types/annotation.js';
+import type { PlacedMeasurementRef } from '../../../types/annotation.js';
 import type { Tool } from '../Tool.js';
 export interface MeasurementStampToolOptions {
     autoSwitchToSelect?: boolean;

package/dist/{canvas → annotation/canvas}/tools/measurementStampTool.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LAYER_ID } from '../../types/annotation.js';
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
 let counter = 0;
 const makeId = () => `measurement-${Date.now().toString(36)}-${(counter++).toString(36)}`;
 const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;

package/dist/{canvas → annotation/canvas}/tools/panTool.js

@@ -5,6 +5,9 @@ export const createPanTool = (options = {}) => ({
     id: 'pan',
     label: 'Hand',
     cursor: options.cursor ?? 'grab',
+    // Native pans the viewport on the UI thread (see Tool.panViewport). The
+    // onPointer* handlers below remain the web/parity implementation.
+    panViewport: true,
     onPointerDown(event, _ctx, _state) {
         return { kind: 'panning', lastScreen: event.screen };
     },

package/dist/{canvas → annotation/canvas}/tools/penTool.d.ts

@@ -1,8 +1,9 @@
-import type { AnnotationStroke } from '../../types/annotation.js';
+import type { AnnotationStroke, StrokeCap } from '../../../types/annotation.js';
 import type { Tool } from '../Tool.js';
 export interface PenToolOptions {
     color?: string;
     width?: number;
+    cap?: StrokeCap;
     minSampleDistance?: number;
     variant?: 'pen' | 'marker' | 'highlighter';
 }

package/dist/{canvas → annotation/canvas}/tools/penTool.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LAYER_ID } from '../../types/annotation.js';
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
 const distSq = (ax, ay, bx, by) => {
     const dx = ax - bx;
     const dy = ay - by;
@@ -9,13 +9,21 @@ const makeId = (prefix) => `${prefix}-${Date.now().toString(36)}-${(counter++).t
 export const createPenTool = (options = {}) => {
     const color = options.color ?? '#111827';
     const width = options.width ?? 2;
+    const cap = options.cap ?? 'round';
     const variant = options.variant ?? 'pen';
     const minSampleDistance = options.minSampleDistance ?? 1.5;
     const minSampleDistanceSq = minSampleDistance * minSampleDistance;
+    // A degenerate single-point dot has no direction (so 'arrow' is meaningless)
+    // and is invisible with a 'butt' cap (zero-length path), so a dot falls back
+    // to a visible, directionless cap.
+    const dotCap = cap === 'butt' || cap === 'arrow' ? 'round' : cap;
     return {
         id: variant,
         label: variant === 'pen' ? 'Pen' : variant === 'marker' ? 'Marker' : 'Highlighter',
         cursor: 'crosshair',
+        // Drives UI-thread drawing on native (see FreehandConfig). The
+        // onPointerDown/Move/Up below remain the web/parity implementation.
+        freehand: { variant, color, width, cap, minSampleDistance },
         onPointerDown(event, ctx) {
             const stroke = {
                 id: makeId('stroke'),
@@ -23,6 +31,7 @@ export const createPenTool = (options = {}) => {
                 tool: variant,
                 color,
                 width,
+                cap,
                 points: [event.world.x, event.world.y],
                 pressure: event.pressure !== undefined ? [event.pressure] : undefined,
                 createdAt: Date.now(),
@@ -54,10 +63,28 @@ export const createPenTool = (options = {}) => {
             const s = state;
             if (s?.kind !== 'pen-drawing')
                 return;
-            // Need at least two distinct samples to be a stroke.
-            if (s.stroke.points.length < 4)
-                return;
-            ctx.commit({ ops: [{ op: 'addStroke', stroke: s.stroke }] });
+            const pts = s.stroke.points;
+            if (pts.length >= 4) {
+                // Two or more distinct samples → a normal stroke.
+                ctx.commit({ ops: [{ op: 'addStroke', stroke: s.stroke }] });
+            }
+            else if (pts.length === 2) {
+                // A click with no drag → a single dot. Duplicate the point so the
+                // stroke renders as a filled dot of diameter = width. A 'butt' cap
+                // would make the zero-length path invisible, so the dot uses dotCap.
+                ctx.commit({
+                    ops: [
+                        {
+                            op: 'addStroke',
+                            stroke: {
+                                ...s.stroke,
+                                cap: dotCap,
+                                points: [pts[0], pts[1], pts[0], pts[1]],
+                            },
+                        },
+                    ],
+                });
+            }
         },
         // No renderPreview. The canvas inner detects PenDrawingState in
         // toolState and renders the in-flight stroke directly with its own