@reekon-tools/boldr-utils 1.6.23 → 1.6.25

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

@@ -1,4 +1,4 @@
-import { type SkFont, type SkPath, type SkTypefaceFontProvider, type Transforms3d } from '@shopify/react-native-skia';
+import { type SkFont, type SkImage, type SkPath, type SkTypefaceFontProvider, type Transforms3d } from '@shopify/react-native-skia';
 import type { ReactNode } from 'react';
 import type { AnnotationCanvasState, AnnotationStroke, StrokeCap } from '../../types/annotation.js';
 type AnimatedPoint = {
@@ -21,6 +21,7 @@ export interface AnnotationCanvasSkiaProps {
         value: Transforms3d;
     };
     resolveImageUrl?: (storagePath: string) => Promise<string>;
+    backgroundSkImage?: SkImage | null;
     valueFont: SkFont | null;
     textFontMgr?: SkTypefaceFontProvider | null;
     penDrawingStroke: AnnotationStroke | null;
@@ -69,6 +70,16 @@ export interface AnnotationCanvasSkiaProps {
         width: AnimatedNumber;
         height: AnimatedNumber;
     };
+    shapeResizeId?: string | null;
+    shapeResizePath?: SkPath | {
+        value: SkPath;
+    };
+    shapeResizeBox?: {
+        x: AnimatedNumber;
+        y: AnimatedNumber;
+        width: AnimatedNumber;
+        height: AnimatedNumber;
+    };
     handleRadius?: number | {
         value: number;
     };
@@ -76,6 +87,7 @@ export interface AnnotationCanvasSkiaProps {
         value: number;
     };
     customPreview?: ReactNode;
+    wrapContent?: (content: ReactNode) => ReactNode;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, handleRadius, handleRingWidth, customPreview, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, backgroundSkImage, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -3,6 +3,7 @@ import { Canvas, Circle, DashPathEffect, Group, Line, Path, Rect, Skia, } from '
 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 { BackgroundImageElement } from './elements/BackgroundImageElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
 import { StrokeElement } from './elements/StrokeElement.js';
@@ -50,25 +51,6 @@ const strokeBounds = (points) => {
     }
     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.
@@ -92,7 +74,8 @@ 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, resolveImageUrl, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, handleRadius, handleRingWidth, 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) => {
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, resolveImageUrl, backgroundSkImage, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, customPreview, wrapContent, }) => {
+    const world = (_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, skImage: backgroundSkImage })), effectiveCanvas.strokes.map((stroke) => (_jsx(DraggableElement, { isDragging: stroke.id === draggingId, transform: dragTransform, children: _jsx(StrokeElement, { stroke: stroke }) }, stroke.id))), effectiveCanvas.shapes.map((shape) => {
                 // Line/arrow shapes support endpoint editing. When selected they show
                 // grab handles at both ends; during an endpoint drag the line renders
                 // from the live endpoints (one following the finger) — the shape twin
@@ -114,22 +97,33 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                         // but idle: reuse ShapeElement for the body (caps/arrowhead/dash)
                         // and overlay the handles, both wrapped so a group move tracks.
                         if (isEndpointDrag) {
-                            const arrowPath = (() => {
-                                if (!hasArrow)
-                                    return null;
-                                const [apex, baseL, baseR] = arrowheadTriangle(b, a, strokeWidth);
+                            const headPath = (tip, from) => {
+                                const [apex, baseL, baseR] = arrowheadTriangle(tip, from, strokeWidth);
                                 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;
-                            })();
-                            return (_jsxs(Group, { children: [_jsx(Line, { p1: liveLineP1 ?? a, p2: liveLineP2 ?? b, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(shape.style.cap), children: shape.style.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(strokeWidth) })) }), handles, arrowPath && (_jsx(Path, { path: arrowPath, color: stroke, style: "fill" }))] }, shape.id));
+                            };
+                            const endArrow = hasArrow ? headPath(b, a) : null;
+                            const startArrow = shape.style.startCap === 'arrow' ? headPath(a, b) : null;
+                            return (_jsxs(Group, { children: [_jsx(Line, { p1: liveLineP1 ?? a, p2: liveLineP2 ?? b, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(shape.style.cap), children: shape.style.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(strokeWidth) })) }), handles, startArrow && (_jsx(Path, { path: startArrow, color: stroke, style: "fill" })), endArrow && (_jsx(Path, { path: endArrow, color: stroke, style: "fill" }))] }, shape.id));
                         }
                         return (_jsxs(DraggableElement, { isDragging: shape.id === draggingId, transform: dragTransform, children: [_jsx(ShapeElement, { shape: shape, font: valueFont, textFontMgr: textFontMgr }), handles] }, shape.id));
                     }
                 }
+                // Non-line shapes track the live transform of whichever resize is in
+                // flight: text scales uniformly via a transform (`resizingId`); a
+                // group move translates (`draggingId`). A rect/ellipse/polygon corner
+                // resize instead re-renders the SCALED OUTLINE live (`shapeResizePath`)
+                // at a constant stroke — a non-uniform scale transform would warp the
+                // stroke width (top/bottom edges thicken with scaleY).
+                if (shape.id === shapeResizeId && shapeResizePath) {
+                    const stroke = shape.style.stroke ?? '#000000';
+                    const strokeWidth = shape.style.strokeWidth ?? 2;
+                    return (_jsxs(Group, { children: [shape.style.fill && (_jsx(Path, { path: shapeResizePath, color: shape.style.fill, style: "fill" })), _jsx(Path, { path: shapeResizePath, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeJoin: "round", children: shape.style.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(strokeWidth) })) })] }, shape.id));
+                }
                 return (_jsx(DraggableElement, { isDragging: shape.id === draggingId || shape.id === resizingId, transform: shape.id === resizingId ? resizeTransform : dragTransform, children: _jsx(ShapeElement, { shape: shape, font: valueFont, textFontMgr: textFontMgr }) }, shape.id));
             }), effectiveCanvas.placedMeasurements.map((placed) => {
                 // Rectangle annotation: a stroked border whose center carries the
@@ -155,23 +149,26 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                 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);
+                // Solid filled-triangle arrowheads at endpoint b (the "end", lineCap)
+                // and/or endpoint a (the "start", lineStartCap). Built from the static
+                // endpoints, so they're skipped during a live endpoint drag (they
+                // reappear on release) rather than lagging the moving finger.
+                const headPath = (tip, from) => {
+                    const [apex, baseL, baseR] = arrowheadTriangle(tip, from, 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), children: placed.lineDash && (_jsx(DashPathEffect, { intervals: dashIntervals(lineWidth) })) }), arrowPath && (_jsx(Path, { path: arrowPath, color: lineColor, style: "fill" })), isSelected && handleRadius != null && (_jsxs(_Fragment, { children: [_jsx(Handle, { c: p1, r: handleRadius, ringWidth: handleRingWidth }), _jsx(Handle, { c: p2, r: handleRadius, ringWidth: handleRingWidth })] }))] }));
+                };
+                const endArrow = placed.line && !isEndpointDrag && placed.lineCap === 'arrow'
+                    ? headPath(placed.line.b, placed.line.a)
+                    : null;
+                const startArrow = placed.line && !isEndpointDrag && placed.lineStartCap === 'arrow'
+                    ? headPath(placed.line.a, placed.line.b)
+                    : null;
+                const content = (_jsxs(_Fragment, { children: [_jsx(Line, { p1: p1, p2: p2, color: lineColor, style: "stroke", strokeWidth: lineWidth, strokeCap: toSkiaStrokeCap(placed.lineCap), children: placed.lineDash && (_jsx(DashPathEffect, { intervals: dashIntervals(lineWidth) })) }), startArrow && (_jsx(Path, { path: startArrow, color: lineColor, style: "fill" })), endArrow && (_jsx(Path, { path: endArrow, color: lineColor, style: "fill" })), isSelected && handleRadius != null && (_jsxs(_Fragment, { children: [_jsx(Handle, { c: p1, r: handleRadius, ringWidth: handleRingWidth }), _jsx(Handle, { c: p2, r: handleRadius, ringWidth: handleRingWidth })] }))] }));
                 return isEndpointDrag ? (_jsx(Group, { children: content }, placed.id)) : (_jsx(DraggableElement, { isDragging: placed.id === draggingId, transform: dragTransform, children: content }, placed.id));
             }), (() => {
                 if (!selectedId)
@@ -188,20 +185,36 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                     // above), not a bounding box — matching the measurement-line UX.
                     if (shape.kind === 'line' || shape.kind === 'arrow')
                         return null;
+                    // During a corner resize the box tracks the live scaled bounds
+                    // (`shapeResizeBox`) at a constant stroke — a transform would warp it
+                    // like the shape — and the corner handles hide (they'd warp into
+                    // ellipses under a non-uniform scale; the rect annotation hides its
+                    // handles mid-drag for the same reason).
+                    if (shape.id === shapeResizeId && shapeResizeBox) {
+                        return (_jsx(Rect, { x: shapeResizeBox.x, y: shapeResizeBox.y, width: shapeResizeBox.width, height: shapeResizeBox.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }));
+                    }
                     // Text shapes derive their box from the estimated text bounds (the
                     // stored geometry is just the top-left anchor) and add a corner
                     // resize handle; both track the live resize transform so the chrome
                     // scales with the shape during a native UI-thread resize.
                     const isText = shape.kind === 'text';
-                    const b = isText
-                        ? textShapeBounds(shape)
-                        : pointsBounds(shape.geometry.points);
+                    const b = isText ? textShapeBounds(shape) : visualShapeBounds(shape);
                     if (!b)
                         return null;
                     const isResizing = shape.id === resizingId;
                     const liveTransform = isResizing ? resizeTransform : dragTransform;
+                    const isLive = isDragging || isResizing;
                     const resizeGeom = isText ? textResizeGeometry(shape) : null;
-                    return (_jsxs(_Fragment, { children: [_jsx(SelectionBox, { bounds: b, isDragging: isDragging || isResizing, transform: liveTransform }), resizeGeom && handleRadius != null && (_jsx(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: _jsx(Handle, { c: resizeGeom.handle, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }) }))] }));
+                    // Rect/ellipse/polygon shapes get four bounding-box corner handles
+                    // (drawn at the un-padded visual-bounds corners so they line up with
+                    // the hit-test) to scale length and width — the shape twin of the
+                    // rectangle-annotation corner handles.
+                    const cornerResizable = shape.kind === 'rect' ||
+                        shape.kind === 'ellipse' ||
+                        shape.kind === 'polygon';
+                    return (_jsxs(_Fragment, { children: [_jsx(SelectionBox, { bounds: b, isDragging: isLive, transform: liveTransform }), resizeGeom && handleRadius != null && (_jsx(DraggableElement, { isDragging: isLive, transform: liveTransform, children: _jsx(Handle, { c: resizeGeom.handle, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }) })), cornerResizable && handleRadius != null && (_jsxs(DraggableElement, { isDragging: isDragging, transform: dragTransform, children: [_jsx(Handle, { c: { x: b.minX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.minY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.minX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR }), _jsx(Handle, { c: { x: b.maxX, y: b.maxY }, r: handleRadius, ringWidth: handleRingWidth, color: SELECTION_COLOR })] }))] }));
                 }
                 return null;
-            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), customPreview] }) }));
+            })(), penDrawingStroke && _jsx(StrokeElement, { stroke: penDrawingStroke }), shapePreview && (_jsxs(_Fragment, { children: [_jsx(Path, { path: shapePreview.path, color: shapePreview.color, style: "stroke", strokeWidth: shapePreview.width, strokeCap: toSkiaStrokeCap(shapePreview.cap), strokeJoin: "round", children: shapePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(shapePreview.width) })) }), _jsx(Path, { path: shapePreview.headPath, color: shapePreview.color, style: "fill" })] })), livePreview?.handoffPaths?.map((p, i) => (_jsx(Path, { path: p, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) }, i))), livePreview && (_jsx(Path, { path: livePreview.path, color: livePreview.color, style: "stroke", strokeWidth: livePreview.width, strokeCap: toSkiaStrokeCap(livePreview.cap), strokeJoin: "round", opacity: livePreview.opacity, children: livePreview.dash && (_jsx(DashPathEffect, { intervals: dashIntervals(livePreview.width) })) })), customPreview] }));
+    return (_jsx(Canvas, { style: { width, height }, children: wrapContent ? wrapContent(world) : world }));
+};

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

@@ -39,6 +39,7 @@ export interface FreehandConfig {
     color: string;
     width: number;
     cap?: StrokeCap;
+    startCap?: StrokeCap;
     dash?: boolean;
     minSampleDistance: number;
 }
@@ -47,6 +48,7 @@ export interface ShapeDrawConfig {
     color: string;
     width: number;
     cap?: StrokeCap;
+    startCap?: StrokeCap;
     dash?: boolean;
 }
 export type DragElementKind = 'stroke' | 'shape' | 'measurement';
@@ -68,6 +70,12 @@ export interface DragSelectionConfig {
         fixed: Vec2;
     } | null;
     buildRectCornerPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, corner: RectCorner, delta: Vec2): AnnotationDocumentPatch | null;
+    hitTestShapeCorner?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): {
+        corner: RectCorner;
+        moving: Vec2;
+        fixed: Vec2;
+    } | null;
+    buildShapeCornerPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, corner: RectCorner, delta: Vec2): AnnotationDocumentPatch | null;
     isSelectedTileGrab?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number, viewportTileScale?: number): boolean;
     hitTestResizeHandle?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number): ResizeGeometry | null;
     buildResizePatch?(doc: AnnotationCanvasState, id: AnnotationElementId, delta: Vec2): AnnotationDocumentPatch | null;

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

@@ -1,9 +1,12 @@
+import { type SkImage } from '@shopify/react-native-skia';
 import type { AnnotationBackgroundImage, BackgroundFit } from '../../../types/annotation.js';
+export declare const useBackgroundSkImage: (image: AnnotationBackgroundImage | null | undefined, resolveUrl?: (path: string) => Promise<string>) => SkImage | null;
 export interface BackgroundImageElementProps {
     image: AnnotationBackgroundImage;
     docWidth: number;
     docHeight: number;
     fit?: BackgroundFit;
     resolveUrl?: (path: string) => Promise<string>;
+    skImage?: SkImage | null;
 }
-export declare const BackgroundImageElement: import("react").MemoExoticComponent<({ 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, skImage: skImageProp, }: BackgroundImageElementProps) => import("react/jsx-runtime").JSX.Element | null>;

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

@@ -1,22 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Image, useImage } from '@shopify/react-native-skia';
 import { memo, useEffect, useRef, useState } from 'react';
-const computeFit = (imgW, imgH, docW, docH, fit) => {
-    // Guard against unknown/zero image dimensions: dividing by them yields
-    // Infinity → NaN geometry, and a <Image> with NaN bounds renders nothing
-    // (a silent "background never appears"). Fall back to filling the doc.
-    if (!(imgW > 0) || !(imgH > 0) || fit === 'stretch') {
-        return { x: 0, y: 0, width: docW, height: docH };
-    }
-    const scale = fit === 'cover'
-        ? Math.max(docW / imgW, docH / imgH)
-        : Math.min(docW / imgW, docH / imgH);
-    const w = imgW * scale;
-    const h = imgH * scale;
-    return { x: (docW - w) / 2, y: (docH - h) / 2, width: w, height: h };
-};
-export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, }) => {
-    const [url, setUrl] = useState(image.downloadUrl);
+import { imageDocRect } from '../viewport.js';
+// Resolve a background image's (possibly expired) storage URL and decode it to
+// an SkImage. Exported so a consumer can hoist the decode ABOVE the canvas and
+// share one SkImage across multiple canvases (e.g. the main canvas + a
+// magnifier overlay) — otherwise each canvas mounts its own loader and flashes
+// a blank while it re-resolves + re-decodes. Returns null until loaded, or when
+// `image` is null/undefined. Hooks run unconditionally regardless of `image`.
+export const useBackgroundSkImage = (image, 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
@@ -24,6 +17,8 @@ export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit =
     const resolveUrlRef = useRef(resolveUrl);
     resolveUrlRef.current = resolveUrl;
     useEffect(() => {
+        if (!image)
+            return;
         let cancelled = false;
         const resolve = resolveUrlRef.current;
         if (resolve) {
@@ -38,10 +33,17 @@ export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit =
         return () => {
             cancelled = true;
         };
-    }, [image.downloadUrl, image.storagePath]);
-    const skImage = useImage(url);
+    }, [image?.downloadUrl, image?.storagePath]);
+    return useImage(url || null);
+};
+export const BackgroundImageElement = memo(({ image, docWidth, docHeight, fit = 'contain', resolveUrl, skImage: skImageProp, }) => {
+    // Self-load only when no pre-decoded image is provided; the hook still runs
+    // unconditionally (with a null image, so it no-ops) to satisfy hook rules.
+    const provided = skImageProp !== undefined;
+    const loaded = useBackgroundSkImage(provided ? null : image, resolveUrl);
+    const skImage = provided ? skImageProp : loaded;
     if (!skImage)
         return null;
-    const dims = computeFit(image.widthPx, image.heightPx, docWidth, docHeight, fit);
+    const dims = imageDocRect(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.js

@@ -45,34 +45,54 @@ export const ShapeElement = memo(({ shape, font, textFontMgr }) => {
     // historical behavior).
     const closed = geometry.closed !== false;
     const polyPath = useMemo(() => (kind === 'polygon' ? polygonPath(geometry.points, closed) : null), [kind, geometry.points, closed]);
-    // Solid filled-triangle arrowhead at the shape's end point. Drawn for the
-    // legacy 'arrow' kind, for a 'line' with cap === 'arrow' (the arrow tool and
-    // the end-cap editor both produce this), and for an OPEN polygon with cap
-    // === 'arrow' (its last segment has a direction). Mirrors StrokeElement.
-    const arrowHead = useMemo(() => {
-        let from;
-        let end;
-        if ((kind === 'line' || kind === 'arrow') &&
-            (kind === 'arrow' || style.cap === 'arrow')) {
-            [from, end] = geometry.points;
+    // Solid filled-triangle arrowheads. The END head is drawn for the legacy
+    // 'arrow' kind, for a 'line' with cap === 'arrow' (the arrow tool and the
+    // end-cap editor both produce this), and for an OPEN polygon with cap ===
+    // 'arrow'. The START head is drawn for a 'line'/'arrow' or open polygon with
+    // startCap === 'arrow' (so a line can be headed at either end or both).
+    // Mirrors StrokeElement.
+    const arrowHeads = useMemo(() => {
+        // The two anchor segments: [endTip, endFrom] points the end head, and
+        // [startTip, startFrom] points the start head (pointing back out of the
+        // first point). For an open polygon those are the last/first segments.
+        let endTip;
+        let endFrom;
+        let startTip;
+        let startFrom;
+        if (kind === 'line' || kind === 'arrow') {
+            const [a, b] = geometry.points;
+            endTip = b;
+            endFrom = a;
+            startTip = a;
+            startFrom = b;
         }
-        else if (kind === 'polygon' && !closed && style.cap === 'arrow') {
+        else if (kind === 'polygon' && !closed) {
             const n = geometry.points.length;
             if (n >= 2) {
-                from = geometry.points[n - 2];
-                end = geometry.points[n - 1];
+                endTip = geometry.points[n - 1];
+                endFrom = geometry.points[n - 2];
+                startTip = geometry.points[0];
+                startFrom = geometry.points[1];
             }
         }
-        if (!from || !end || (from.x === end.x && from.y === end.y))
-            return null;
-        const [apex, baseL, baseR] = arrowheadTriangle(end, from, strokeWidth);
-        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;
-    }, [kind, geometry.points, closed, style.cap, strokeWidth]);
+        const head = (tip, from) => {
+            if (!tip || !from || (tip.x === from.x && tip.y === from.y))
+                return null;
+            const [apex, baseL, baseR] = arrowheadTriangle(tip, from, strokeWidth);
+            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 wantEnd = kind === 'arrow' || style.cap === 'arrow';
+        const wantStart = style.startCap === 'arrow';
+        return {
+            end: wantEnd ? head(endTip, endFrom) : null,
+            start: wantStart ? head(startTip, startFrom) : null,
+        };
+    }, [kind, geometry.points, closed, style.cap, style.startCap, strokeWidth]);
     // Text shapes render through the Skia Paragraph API so decorations (solid
     // underline / wavy squiggle / highlight band) paint natively. The loaded font
     // is registered into a provider so the Paragraph draws with the same typeface
@@ -171,12 +191,12 @@ export const ShapeElement = memo(({ shape, font, textFontMgr }) => {
             const [a, b] = geometry.points;
             if (!a || !b)
                 return null;
-            return (_jsxs(_Fragment, { children: [_jsx(Line, { p1: a, p2: b, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(style.cap), children: dashEffect }), arrowHead && _jsx(Path, { path: arrowHead, color: stroke, style: "fill" })] }));
+            return (_jsxs(_Fragment, { children: [_jsx(Line, { p1: a, p2: b, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(style.cap), children: dashEffect }), arrowHeads.start && (_jsx(Path, { path: arrowHeads.start, color: stroke, style: "fill" })), arrowHeads.end && (_jsx(Path, { path: arrowHeads.end, color: stroke, style: "fill" }))] }));
         }
         case 'polygon': {
             if (!polyPath)
                 return null;
-            return (_jsxs(_Fragment, { children: [fill && closed && _jsx(Path, { path: polyPath, color: fill }), _jsx(Path, { path: polyPath, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(style.cap), strokeJoin: "round", children: dashEffect }), arrowHead && _jsx(Path, { path: arrowHead, color: stroke, style: "fill" })] }));
+            return (_jsxs(_Fragment, { children: [fill && closed && _jsx(Path, { path: polyPath, color: fill }), _jsx(Path, { path: polyPath, color: stroke, style: "stroke", strokeWidth: strokeWidth, strokeCap: toSkiaStrokeCap(style.cap), strokeJoin: "round", children: dashEffect }), arrowHeads.start && (_jsx(Path, { path: arrowHeads.start, color: stroke, style: "fill" })), arrowHeads.end && (_jsx(Path, { path: arrowHeads.end, color: stroke, style: "fill" }))] }));
         }
         case 'text': {
             // `origin` is the TOP-LEFT of the text block; textGeometry derives the

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

@@ -12,16 +12,13 @@ export const pointsToSkPath = (points) => {
     }
     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)
+// A solid filled-triangle arrowhead at `tip`, with its base back toward `from`,
+// rendered as a separate filled <Path> on top of the stroked line. Null when
+// the two points coincide (e.g. a tap-dot), which has no direction to point.
+const headPath = (tip, from, width) => {
+    if (tip.x === from.x && tip.y === from.y)
         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 [apex, baseL, baseR] = arrowheadTriangle(tip, from, width);
     const path = Skia.Path.Make();
     path.moveTo(apex.x, apex.y);
     path.lineTo(baseL.x, baseL.y);
@@ -29,17 +26,35 @@ const arrowheadPath = (stroke) => {
     path.close();
     return path;
 };
+// Arrowheads at the stroke's end (cap) and/or start (startCap). Each is null
+// unless the corresponding cap is 'arrow'. The start head points back out of
+// the first point (base toward the second).
+const arrowheadPaths = (stroke) => {
+    const n = stroke.points.length;
+    if (n < 4)
+        return { start: null, end: null };
+    const first = { x: stroke.points[0], y: stroke.points[1] };
+    const second = { x: stroke.points[2], y: stroke.points[3] };
+    const last = { x: stroke.points[n - 2], y: stroke.points[n - 1] };
+    const penult = { x: stroke.points[n - 4], y: stroke.points[n - 3] };
+    return {
+        end: stroke.cap === 'arrow' ? headPath(last, penult, stroke.width) : null,
+        start: stroke.startCap === 'arrow'
+            ? headPath(first, second, stroke.width)
+            : null,
+    };
+};
 // 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 arrows = useMemo(() => arrowheadPaths(stroke), [stroke.points, stroke.cap, stroke.startCap, stroke.width]);
     const opacity = stroke.tool === 'highlighter' ? 0.3 : 1;
     // A tap-dot is a zero-length two-point path; a dash effect would erase it
     // (the contour has no length to dash), so dots always render solid.
     const isDot = stroke.points.length === 4 &&
         stroke.points[0] === stroke.points[2] &&
         stroke.points[1] === stroke.points[3];
-    return (_jsxs(_Fragment, { children: [_jsx(Path, { path: path, color: stroke.color, style: "stroke", strokeWidth: stroke.width, strokeCap: toSkiaStrokeCap(stroke.cap), strokeJoin: "round", opacity: opacity, children: stroke.dash && !isDot && (_jsx(DashPathEffect, { intervals: dashIntervals(stroke.width) })) }), arrow && (_jsx(Path, { path: arrow, color: stroke.color, style: "fill", opacity: opacity }))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(Path, { path: path, color: stroke.color, style: "stroke", strokeWidth: stroke.width, strokeCap: toSkiaStrokeCap(stroke.cap), strokeJoin: "round", opacity: opacity, children: stroke.dash && !isDot && (_jsx(DashPathEffect, { intervals: dashIntervals(stroke.width) })) }), arrows.start && (_jsx(Path, { path: arrows.start, color: stroke.color, style: "fill", opacity: opacity })), arrows.end && (_jsx(Path, { path: arrows.end, color: stroke.color, style: "fill", opacity: opacity }))] }));
 });

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

@@ -3,3 +3,10 @@ export type ShapeToolKind = 'line' | 'rect' | 'triangle' | 'ellipse';
 export declare const annotationKindFor: (kind: ShapeToolKind) => AnnotationShapeKind;
 export declare const shapePointsFromDrag: (kind: ShapeToolKind, a: Vec2, b: Vec2) => Vec2[];
 export declare const hitShapeOutline: (shape: AnnotationShape, p: Vec2, tol: number) => boolean;
+export interface ShapeBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export declare const visualShapeBounds: (shape: AnnotationShape) => ShapeBounds | null;

package/dist/annotation/canvas/shapeGeometry.js

@@ -114,3 +114,39 @@ export const hitShapeOutline = (shape, p, tol) => {
             return false;
     }
 };
+// Axis-aligned bounds of a shape AS RENDERED — the source of truth for the
+// selection box, its corner-resize handles, and the corner hit-test, so all
+// three agree on where the shape's edges are. For most kinds this is just the
+// bounding box of the geometry points, but an ellipse renders as a CIRCLE
+// (radius = half its larger extent, centered on the drag midpoint), so its
+// visual bounds are the square that circle inscribes — otherwise the selection
+// box hugs the raw (often non-square) drag rect instead of the visible circle.
+// Returns null for text and degenerate (< 2 point) geometry; text shapes box
+// from textGeometry's estimated bounds and lines draw handles on their
+// endpoints, so neither routes through here.
+export const visualShapeBounds = (shape) => {
+    const pts = shape.geometry.points;
+    if (pts.length < 2)
+        return null;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of pts) {
+        if (p.x < minX)
+            minX = p.x;
+        if (p.y < minY)
+            minY = p.y;
+        if (p.x > maxX)
+            maxX = p.x;
+        if (p.y > maxY)
+            maxY = p.y;
+    }
+    if (shape.kind === 'ellipse') {
+        const cx = (minX + maxX) / 2;
+        const cy = (minY + maxY) / 2;
+        const r = Math.max(maxX - minX, maxY - minY) / 2;
+        return { minX: cx - r, minY: cy - r, maxX: cx + r, maxY: cy + r };
+    }
+    return { minX, minY, maxX, maxY };
+};

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

@@ -4,6 +4,7 @@ export interface PenToolOptions {
     color?: string;
     width?: number;
     cap?: StrokeCap;
+    startCap?: StrokeCap;
     dash?: boolean;
     minSampleDistance?: number;
     variant?: 'pen' | 'marker' | 'highlighter';

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

@@ -10,6 +10,7 @@ export const createPenTool = (options = {}) => {
     const color = options.color ?? '#111827';
     const width = options.width ?? 2;
     const cap = options.cap ?? 'round';
+    const startCap = options.startCap ?? 'round';
     const dash = options.dash ?? false;
     const variant = options.variant ?? 'pen';
     const minSampleDistance = options.minSampleDistance ?? 1.5;
@@ -28,7 +29,15 @@ export const createPenTool = (options = {}) => {
         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, dash, minSampleDistance },
+        freehand: {
+            variant,
+            color,
+            width,
+            cap,
+            ...(startCap === 'arrow' && { startCap: 'arrow' }),
+            dash,
+            minSampleDistance,
+        },
         onPointerDown(event, ctx) {
             const stroke = {
                 id: makeId('stroke'),
@@ -37,6 +46,7 @@ export const createPenTool = (options = {}) => {
                 color,
                 width,
                 cap,
+                ...(startCap === 'arrow' && { startCap: 'arrow' }),
                 ...(dash && { dash }),
                 points: [event.world.x, event.world.y],
                 pressure: event.pressure !== undefined ? [event.pressure] : undefined,