@reekon-tools/boldr-utils 1.18.2 → 1.19.0

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

@@ -1,6 +1,7 @@
 import { type CSSProperties, type MutableRefObject } from 'react';
 import type { DecimalTolerance, FractionalTolerance, Measurement, Units } from '../../types/firestore.js';
 import type { AnnotationCanvasState, AnnotationDocumentPatch, PlacedMeasurementRef, Selection } from '../../types/annotation.js';
+import type { RenderCanvasBackground } from './backgroundSlot.js';
 import type { MeasurementRef } from './measurementPicker.js';
 import type { RequestTextInput, Tool } from './Tool.js';
 import { type AnnotationCanvasHandle } from './useAnnotationCanvasState.js';
@@ -21,6 +22,7 @@ export interface AnnotationCanvasInnerProps {
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;
+    renderBackground?: RenderCanvasBackground;
     renderMeasurementStamp?: RenderMeasurementStamp;
     onMeasurementStampPress?: (placed: PlacedMeasurementRef) => void;
     onMeasurementStampLongPress?: (placed: PlacedMeasurementRef) => void;

package/dist/annotation/canvas/AnnotationCanvasInner.js

@@ -20,8 +20,14 @@ const HANDLE_RING_PX = 2;
 const LONG_PRESS_MS = 500;
 const LONG_PRESS_SLOP_PX = 10;
 const DEFAULT_PAN_TRIGGERS = ['middleMouse', 'space'];
+// Device pixel ratio handed to the background slot (a host rasterizing its own
+// doc content needs device px per doc point = zoom × pixelRatio). Read per
+// render rather than tracked: it only changes with browser zoom or a monitor
+// switch, both of which also resize the canvas. Guarded for non-DOM renders
+// (SSR / the vitest environment), where 1 is the right answer.
+const devicePixelRatioOf = () => typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
 export const AnnotationCanvasInner = (props) => {
-    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, gestures, width, height, style, activeToolId, tools, snapshotRef, } = props;
+    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, gestures, width, height, style, activeToolId, tools, snapshotRef, renderBackground, } = props;
     // Snapshot plumbing for thumbnail capture: hold the <Canvas> ref and publish
     // a capture fn on the consumer's snapshotRef. encodeToBytes() yields PNG.
     const canvasRef = useCanvasRef();
@@ -200,14 +206,19 @@ export const AnnotationCanvasInner = (props) => {
             x: event.clientX - (rect?.left ?? 0),
             y: event.clientY - (rect?.top ?? 0),
         };
+        // `zoomBy`, not `zoom`: the factor has to compose against the viewport
+        // React is about to commit. Wheel events arrive in bursts and React
+        // batches them, so computing an absolute target here from
+        // `state.ctx.viewport.state.zoom` — a render-stale read — made every
+        // event in a batch aim at the same zoom and `zoomAt` no-op for all but
+        // the last. Measured: ten same-task wheel events moved the view x1.49
+        // where their deltas asked for x54.6.
         if (event.ctrlKey || event.metaKey) {
-            const factor = Math.exp(-event.deltaY / 200);
-            state.zoom(focal, state.ctx.viewport.state.zoom * factor);
+            state.zoomBy(focal, Math.exp(-event.deltaY / 200));
             return;
         }
         if (wheelMode === 'zoom') {
-            const factor = Math.exp(-event.deltaY / 300);
-            state.zoom(focal, state.ctx.viewport.state.zoom * factor);
+            state.zoomBy(focal, Math.exp(-event.deltaY / 300));
             return;
         }
         if (event.shiftKey) {
@@ -267,6 +278,15 @@ export const AnnotationCanvasInner = (props) => {
         ...style,
     };
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
+    // Host substrate (see renderBackground). `state.viewport` IS the committed
+    // viewport on web — the whole viewport lives in React state here, so every
+    // wheel/pan step is already a commit and there is no per-frame channel to
+    // accidentally hand over.
+    const backgroundContent = useMemo(() => renderBackground?.({
+        viewport: state.viewport,
+        screen: { width, height },
+        pixelRatio: devicePixelRatioOf(),
+    }), [renderBackground, state.viewport, width, height]);
     const { renderMeasurementStamp, onMeasurementStampPress, onMeasurementStampLongPress, onMeasurementStampDoubleTap, resolveStampMeasurement, onMeasurementStampRemove, selection, } = props;
     // Double-click a stamp → fire the consumer callback (e.g. open its value
     // editor). Runs the SAME hit-test the select tool uses (top-of-z-order), on
@@ -295,6 +315,7 @@ export const AnnotationCanvasInner = (props) => {
                 worldTransform: state.worldTransform,
                 viewport: state.viewport,
                 resolveImageUrl,
+                backgroundContent,
                 canvasRef,
                 valueFont,
                 textFontMgr,

package/dist/annotation/canvas/AnnotationCanvasInner.native.d.ts

@@ -3,6 +3,7 @@ import { type ViewStyle } from 'react-native';
 import type { RenderMeasurementStamp } from './measurementStampOverlay.js';
 import type { DecimalTolerance, FractionalTolerance, Measurement, Units } from '../../types/firestore.js';
 import { type AnnotationCanvasState, type AnnotationDocumentPatch, type PlacedMeasurementRef, type Selection } from '../../types/annotation.js';
+import type { RenderCanvasBackground } from './backgroundSlot.js';
 import type { MeasurementRef } from './measurementPicker.js';
 import type { RequestTextInput, Tool } from './Tool.js';
 import { type AnnotationCanvasHandle } from './useAnnotationCanvasState.js';
@@ -22,6 +23,7 @@ export interface AnnotationCanvasInnerProps {
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;
+    renderBackground?: RenderCanvasBackground;
     renderMeasurementStamp?: RenderMeasurementStamp;
     onMeasurementStampPress?: (placed: PlacedMeasurementRef) => void;
     onMeasurementStampLongPress?: (placed: PlacedMeasurementRef) => void;

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

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Group, Path, Rect, RoundedRect, Skia, rect, rrect, useFont, } from '@shopify/react-native-skia';
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { StyleSheet, TouchableOpacity, View, } from 'react-native';
+import { PixelRatio, StyleSheet, TouchableOpacity, View, } from 'react-native';
 import { Gesture, GestureDetector, GestureHandlerRootView, } from 'react-native-gesture-handler';
 import Animated, { runOnJS, runOnUI, useAnimatedStyle, useDerivedValue, useSharedValue, } from 'react-native-reanimated';
 import { stampTileDims } from './stampLayout.js';
@@ -64,7 +64,7 @@ const LOUPE_CROSS_WIDTH_PX = 1.5;
 // is only re-synced once each gesture ends. The tool/tap path still hops to
 // JS (`runOnJS(true)`) since drawing/selection are React-state operations.
 export const AnnotationCanvasInner = (props) => {
-    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, } = props;
+    const { resolveImageUrl, stampFontSource, stampValueFontSize = 14, width, height, style, magnifierTopOffset = 0, renderBackground, } = 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
@@ -128,6 +128,14 @@ export const AnnotationCanvasInner = (props) => {
     const zoom = useSharedValue(state.viewport.zoom);
     const panX = useSharedValue(state.viewport.pan.x);
     const panY = useSharedValue(state.viewport.pan.y);
+    // Document-derived pinch floor (see computeZoomFloor). A shared value rather
+    // than a captured number so the gesture memo below needn't rebuild — and
+    // can't be caught mid-pinch holding a stale floor — when the document's
+    // extent changes.
+    const zoomMin = useSharedValue(state.zoomMin);
+    useEffect(() => {
+        zoomMin.value = state.zoomMin;
+    }, [zoomMin, state.zoomMin]);
     // Set by the viewport gestures' onChange, consumed by their onFinalize: the
     // post-gesture sync to React state happens iff a gesture actually moved the
     // viewport, and in onFinalize rather than onEnd because on Android the
@@ -1135,7 +1143,7 @@ export const AnnotationCanvasInner = (props) => {
             const ratio = e.scaleChange;
             if (!Number.isFinite(ratio) || ratio <= 0)
                 return;
-            const next = Math.min(50, Math.max(0.05, zoom.value * ratio));
+            const next = Math.min(50, Math.max(zoomMin.value, zoom.value * ratio));
             if (next === zoom.value)
                 return; // clamped at a bound, or ratio 1
             // World point currently under the focal screen point (using the live
@@ -1863,6 +1871,19 @@ export const AnnotationCanvasInner = (props) => {
     ]);
     const activeTool = props.tools.find((t) => t.id === props.activeToolId) ?? null;
     const customPreview = activeTool?.renderPreview?.(state.customPreviewState, state.ctx);
+    // Host substrate (see renderBackground). It is handed `state.viewport` — the
+    // JS/React snapshot the state hook owns — NOT `zoom`/`panX`/`panY`. Those
+    // shared values move every frame of a pan/pinch and never touch React; the
+    // snapshot is written only by setViewport, i.e. at the end of a viewport
+    // gesture (syncViewport), at the end of an animated glide, on the initial
+    // content fit, and from the imperative view methods. So this memo re-runs
+    // strictly on commit — there is no useAnimatedReaction/runOnJS bridging the
+    // live values into it, by design.
+    const backgroundContent = useMemo(() => renderBackground?.({
+        viewport: state.viewport,
+        screen: { width, height },
+        pixelRatio: PixelRatio.get(),
+    }), [renderBackground, state.viewport, width, height]);
     const { renderMeasurementStamp, onMeasurementStampPress, onMeasurementStampLongPress, resolveStampMeasurement, onMeasurementStampRemove, selection, } = props;
     // The Skia scene props, shared by the main canvas and the loupe overlay. The
     // loupe re-runs the SAME scene with a magnifying world transform + a lens
@@ -1875,6 +1896,11 @@ export const AnnotationCanvasInner = (props) => {
         worldTransform,
         resolveImageUrl,
         backgroundSkImages,
+        // Shared with the loupe overlay below (it re-runs this same scene through a
+        // magnifying transform), so the lens shows the substrate magnified instead
+        // of a hole where the page should be. The node is rendered in both trees —
+        // fine for a draw-only slot, which is what the doc-space contract implies.
+        backgroundContent,
         valueFont,
         // Freehand drawing runs on the UI thread via `livePreview`, so the
         // JS-state pen preview is unused on native.

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

@@ -24,6 +24,7 @@ export interface AnnotationCanvasSkiaProps {
     viewport?: ViewportState;
     resolveImageUrl?: (storagePath: string) => Promise<string>;
     backgroundSkImages?: Record<string, SkImage | null>;
+    backgroundContent?: ReactNode;
     valueFont: SkFont | null;
     textFontMgr?: SkTypefaceFontProvider | null;
     penDrawingStroke: AnnotationStroke | null;
@@ -104,5 +105,5 @@ export interface AnnotationCanvasSkiaProps {
     wrapContent?: (content: ReactNode) => ReactNode;
     canvasRef?: RefObject<CanvasRef | null>;
 }
-export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale, planeDragHandleHidden, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AnnotationCanvasSkia: ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale, planeDragHandleHidden, customPreview, wrapContent, canvasRef, }: AnnotationCanvasSkiaProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -80,7 +80,7 @@ const SelectionBox = ({ bounds, isDragging, transform, }) => (_jsx(DraggableElem
 // since the function-call pattern works identically on native we use it
 // in both Inners for consistency. Don't add hooks here; this is a plain
 // JSX-returning helper, not a component.
-export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale = 1, planeDragHandleHidden, customPreview, wrapContent, canvasRef, }) => {
+export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTransform, viewport, resolveImageUrl, backgroundSkImages, backgroundContent, valueFont, textFontMgr, penDrawingStroke, livePreview, shapePreview, draggingId, dragTransform, resizingId, resizeTransform, selectedId, endpointDragId, shapeEndpointDragId, liveLineP1, liveLineP2, rectDragId, liveRect, shapeResizeId, shapeResizePath, shapeResizeBox, handleRadius, handleRingWidth, showPlaneHandles, planeDragId, planeDragIndex, planeDragPath, planeDragGridPath, planeDragHandle, planeOutlineScale = 1, planeDragHandleHidden, customPreview, wrapContent, canvasRef, }) => {
     // Doc rect a SCALE-mode plane grid covers: the first background layer (the
     // photo being calibrated), else the document rect. Pinned to layer 0 like
     // the tile-sizing reference — adding a second image must not re-span the
@@ -94,7 +94,7 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
             width: effectiveCanvas.viewport.width,
             height: effectiveCanvas.viewport.height,
         };
-    const world = (_jsxs(Group, { transform: worldTransform, children: [backgroundLayersOf(effectiveCanvas.viewport).map((layer) => (_jsx(DraggableElement, { isDragging: layer.id === draggingId || layer.id === resizingId, transform: layer.id === resizingId ? resizeTransform : dragTransform, children: _jsx(BackgroundLayerElement, { layer: layer, resolveUrl: resolveImageUrl, skImage: backgroundSkImages?.[layer.id], viewport: viewport, screenWidth: width, screenHeight: height }) }, layer.id))), (effectiveCanvas.planes ?? []).map((plane) => {
+    const world = (_jsxs(Group, { transform: worldTransform, children: [backgroundContent, backgroundLayersOf(effectiveCanvas.viewport).map((layer) => (_jsx(DraggableElement, { isDragging: layer.id === draggingId || layer.id === resizingId, transform: layer.id === resizingId ? resizeTransform : dragTransform, children: _jsx(BackgroundLayerElement, { layer: layer, resolveUrl: resolveImageUrl, skImage: backgroundSkImages?.[layer.id], viewport: viewport, screenWidth: width, screenHeight: height }) }, layer.id))), (effectiveCanvas.planes ?? []).map((plane) => {
                 if (plane.id === planeDragId && planeDragPath) {
                     const statics = plane.mode === 'perspective'
                         ? plane.corners

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

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import type { ViewportState } from './viewport.js';
+export interface CanvasBackgroundSlotArgs {
+    viewport: ViewportState;
+    screen: {
+        width: number;
+        height: number;
+    };
+    pixelRatio: number;
+}
+export type RenderCanvasBackground = (args: CanvasBackgroundSlotArgs) => ReactNode;

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

@@ -0,0 +1,25 @@
+import type { AnnotationCanvasState, AnnotationPdfDocument, AnnotationPdfPageSize } from '../../types/annotation.js';
+export interface PdfDocRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const DEFAULT_PDF_PAGE_GAP = 12;
+export declare const makePdfDocumentId: () => string;
+export declare const pdfPageDocRects: (doc: Pick<AnnotationPdfDocument, "pages" | "layout" | "gap">) => PdfDocRect[];
+export declare const pdfDocumentExtent: (doc: Pick<AnnotationPdfDocument, "pages" | "layout" | "gap">) => {
+    width: number;
+    height: number;
+};
+export declare const pdfFirstPageDocRect: (doc: Pick<AnnotationPdfDocument, "pages" | "layout" | "gap">) => PdfDocRect | null;
+export declare const createPdfDocument: (args: {
+    id: string;
+    storagePath: string;
+    pages: AnnotationPdfPageSize[];
+    fileName?: string;
+    gap?: number;
+}) => AnnotationPdfDocument;
+export declare const DEFAULT_MIN_ZOOM = 0.05;
+export declare const DEFAULT_MAX_ZOOM = 50;
+export declare const computeZoomFloor: (canvas: Pick<AnnotationCanvasState, "viewport">, width: number, height: number) => number;

package/dist/annotation/canvas/pdfDocument.js

@@ -0,0 +1,83 @@
+import { fitRectToScreen } from './viewport.js';
+// Doc-space geometry of a PDF substrate, derived from the persisted descriptor
+// alone — no rasterizer, no file. The rules here MUST match the layout the
+// host hands its PDF rasterizer for the same `layout` value (the package's
+// `continuousVertical(gap)`): pages stacked top to bottom, horizontally centred
+// on the widest page, `gap` between consecutive pages, no trailing gap. If the
+// two ever disagree the pages draw offset from where the fit, the thumbnail
+// crop and the tile-scale reference think they are.
+// Default doc-space (PDF point) gap between pages. Same as the package's.
+export const DEFAULT_PDF_PAGE_GAP = 12;
+// Unique within a document across the clients that touch it — same contract
+// as background layer ids (timestamp + module counter). The `pdf-` prefix
+// keeps it distinguishable from `background-*` in the shared backgrounds slot.
+let pdfIdCounter = 0;
+export const makePdfDocumentId = () => `pdf-${Date.now().toString(36)}-${(pdfIdCounter++).toString(36)}`;
+export const pdfPageDocRects = (doc) => {
+    // Only one layout exists; a switch keeps the exhaustiveness check honest for
+    // the day a second one lands.
+    switch (doc.layout) {
+        case 'continuousVertical':
+        default: {
+            let maxWidth = 0;
+            for (const p of doc.pages)
+                maxWidth = Math.max(maxWidth, p.width);
+            const rects = [];
+            let y = 0;
+            for (const p of doc.pages) {
+                rects.push({
+                    x: (maxWidth - p.width) / 2,
+                    y,
+                    width: p.width,
+                    height: p.height,
+                });
+                y += p.height + doc.gap;
+            }
+            return rects;
+        }
+    }
+};
+// The union of the page rects — what `viewport.width/height` is set to when
+// the document is attached. Never degenerate: a zero-page document would
+// otherwise hand fitRectToScreen a divide-by-zero.
+export const pdfDocumentExtent = (doc) => {
+    let width = 0;
+    let height = 0;
+    for (const r of pdfPageDocRects(doc)) {
+        width = Math.max(width, r.x + r.width);
+        height = Math.max(height, r.y + r.height);
+    }
+    return { width: Math.max(1, width), height: Math.max(1, height) };
+};
+// The first page's rect: the tile-scale reference for a PDF-backed canvas
+// (see computeBaseFitZoom). Fitting the WHOLE filmstrip instead would make a
+// tile's footprint ~N× smaller on an N-page document at the same visual zoom
+// — and would grow every existing tile the moment a page is appended.
+export const pdfFirstPageDocRect = (doc) => pdfPageDocRects(doc)[0] ?? null;
+// Build the descriptor from what a host learns by opening the file.
+export const createPdfDocument = (args) => ({
+    id: args.id,
+    storagePath: args.storagePath,
+    ...(args.fileName ? { fileName: args.fileName } : {}),
+    pageCount: args.pages.length,
+    pages: args.pages.map((p) => ({ width: p.width, height: p.height })),
+    layout: 'continuousVertical',
+    gap: args.gap ?? DEFAULT_PDF_PAGE_GAP,
+});
+// The zoom floor for a canvas. The historical floor (0.05) predates multi-page
+// documents: a 40-page letter filmstrip is ~32,000 points tall and fits an
+// 800pt screen at zoom ~0.025, so with a fixed floor the opening fit is legal
+// but the first pinch snaps 2× in. The floor therefore follows the document:
+// half the content-fit zoom of the doc rect, never above the historical value
+// (so single-image canvases behave exactly as before).
+export const DEFAULT_MIN_ZOOM = 0.05;
+export const DEFAULT_MAX_ZOOM = 50;
+export const computeZoomFloor = (canvas, width, height) => {
+    if (!(width > 0) || !(height > 0))
+        return DEFAULT_MIN_ZOOM;
+    const { viewport } = canvas;
+    const fit = fitRectToScreen({ x: 0, y: 0, width: viewport.width, height: viewport.height }, width, height);
+    return fit.zoom > 0
+        ? Math.min(DEFAULT_MIN_ZOOM, fit.zoom / 2)
+        : DEFAULT_MIN_ZOOM;
+};

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

@@ -83,6 +83,7 @@ export interface AnnotationCanvasStateApi {
         translateY: number;
     }>;
     viewport: ViewportState;
+    zoomMin: number;
     measurementsById: Map<string, Measurement>;
     activeTool: Tool | null;
     toolState: ToolState;
@@ -100,6 +101,31 @@ export interface AnnotationCanvasStateApi {
     dispatchLongPress(event: CanvasPointerEvent): void;
     pan(deltaScreen: Vec2): void;
     zoom(focalScreen: Vec2, nextZoom: number): void;
+    /**
+     * Zoom by a MULTIPLICATIVE FACTOR about a focal screen point.
+     *
+     * Same anchoring as `zoom`, but the target zoom is derived INSIDE the
+     * functional update, so the factor composes against the viewport React is
+     * about to commit rather than against whatever was on screen when the event
+     * handler ran.
+     *
+     * WHY THIS EXISTS. `zoom` takes an absolute target, so a caller has to read
+     * the current zoom to compute one — and a read during an event handler is a
+     * RENDER-STALE read. Wheel and pinch events arrive in bursts that React
+     * batches into a single commit, so every event in the batch computes its
+     * target from the SAME committed zoom; `zoomAt` is then handed a zoom it has
+     * already reached and no-ops, silently discarding the earlier events' steps.
+     * Measured on the web PDF probe: ten wheel events dispatched in one task
+     * produced x1.49 where the deltas asked for x54.6 — nine of ten steps lost.
+     * (The ANCHOR was never the problem; it is exact to 5e-4 CSS px for whatever
+     * pair `zoomAt` is handed.)
+     *
+     * `zoom` is deliberately left alone: an absolute target is the right shape for
+     * a slider, a zoom-to-fit or a native gesture that already tracks its own
+     * cumulative scale, and the seven production canvas screens keep their
+     * behaviour untouched.
+     */
+    zoomBy(focalScreen: Vec2, factor: number): void;
     setViewport(next: ViewportState): void;
 }
 export declare const useAnnotationCanvasState: (props: UseAnnotationCanvasStateProps) => AnnotationCanvasStateApi;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
 import { resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, resolveTileScaleFactor, stampTileDims, STAMP_TILE_SIZE, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
-import { createViewportApi, fitRectToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
+import { createViewportApi, fitRectToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './viewport.js';
+import { computeZoomFloor, pdfFirstPageDocRect } from './pdfDocument.js';
 import { backgroundLayerDocRect, backgroundLayersOf, backgroundLayersUnionRect, } from './backgroundLayers.js';
 import { buildRemoveMeasurementOps, recomputeAnchor, rectCenter, DEFAULT_LINE_POS, } from './measurementGeometry.js';
 // The viewport that frames the document's content inside a screen rect of the
@@ -85,9 +86,19 @@ const computeBaseFitZoom = (canvas, width, height) => {
         return 1;
     const { viewport } = canvas;
     const first = backgroundLayersOf(viewport)[0];
+    // A PDF-backed canvas with no image layers references its FIRST PAGE, not
+    // the whole filmstrip — see pdfFirstPageDocRect for why.
+    const pdfFirstPage = viewport.pdfDocument
+        ? pdfFirstPageDocRect(viewport.pdfDocument)
+        : null;
     const baseRect = first
         ? backgroundLayerDocRect(first)
-        : { x: 0, y: 0, width: viewport.width, height: viewport.height };
+        : (pdfFirstPage ?? {
+            x: 0,
+            y: 0,
+            width: viewport.width,
+            height: viewport.height,
+        });
     return fitRectToScreen(baseRect, width, height).zoom;
 };
 // Default leader length (doc units) for a placed measurement when no explicit
@@ -129,6 +140,13 @@ export const useAnnotationCanvasState = (props) => {
         return map;
     }, [measurements]);
     const viewportApi = useMemo(() => createViewportApi(viewport), [viewport]);
+    // Document-derived zoom floor (see computeZoomFloor). Behind a ref so the
+    // pan/zoom callbacks below stay referentially stable; the native Inner reads
+    // `zoomMin` from the returned state and mirrors it into a shared value for
+    // the pinch worklet.
+    const zoomMin = useMemo(() => computeZoomFloor(effectiveCanvas, width, height), [effectiveCanvas, width, height]);
+    const zoomLimitsRef = useRef({ min: zoomMin, max: DEFAULT_ZOOM_LIMITS.max });
+    zoomLimitsRef.current = { min: zoomMin, max: DEFAULT_ZOOM_LIMITS.max };
     // Frame the document the first time it carries a background image. The doc
     // hydrates asynchronously (it opens empty, then the persisted canvas — with
     // its background — arrives), and a high-res image at the 1:1 default viewport
@@ -141,8 +159,10 @@ export const useAnnotationCanvasState = (props) => {
     useEffect(() => {
         if (didInitialFitRef.current)
             return;
-        if (backgroundLayersOf(canvas.viewport).length === 0)
+        if (backgroundLayersOf(canvas.viewport).length === 0 &&
+            !canvas.viewport.pdfDocument) {
             return;
+        }
         if (!(width > 0) || !(height > 0))
             return;
         didInitialFitRef.current = true;
@@ -290,7 +310,7 @@ export const useAnnotationCanvasState = (props) => {
             setViewport((v) => panBy(v, deltaScreen));
         },
         applyZoom(focalScreen, nextZoom) {
-            setViewport((v) => zoomAt(v, focalScreen, nextZoom));
+            setViewport((v) => zoomAt(v, focalScreen, nextZoom, zoomLimitsRef.current));
         },
     }), [
         canvas,
@@ -396,7 +416,15 @@ export const useAnnotationCanvasState = (props) => {
         setViewport((v) => panBy(v, deltaScreen));
     }, []);
     const zoom = useCallback((focalScreen, nextZoom) => {
-        setViewport((v) => zoomAt(v, focalScreen, nextZoom));
+        setViewport((v) => zoomAt(v, focalScreen, nextZoom, zoomLimitsRef.current));
+    }, []);
+    // `v.zoom * factor` inside the updater, so a burst of events that React
+    // batches into one commit composes instead of each recomputing the same
+    // target from the same stale base. See `zoomBy` on the API type.
+    const zoomBy = useCallback((focalScreen, factor) => {
+        if (!Number.isFinite(factor) || factor <= 0)
+            return;
+        setViewport((v) => zoomAt(v, focalScreen, v.zoom * factor));
     }, []);
     // Imperative API mirror — set via prop so it survives WithSkiaWeb's lazy
     // boundary on web.
@@ -862,6 +890,7 @@ export const useAnnotationCanvasState = (props) => {
         effectiveCanvas,
         worldTransform,
         viewport,
+        zoomMin,
         measurementsById,
         activeTool,
         toolState,
@@ -879,6 +908,7 @@ export const useAnnotationCanvasState = (props) => {
         dispatchLongPress,
         pan,
         zoom,
+        zoomBy,
         setViewport,
     };
 };

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

@@ -24,5 +24,13 @@ export declare const fitRectToScreen: (rect: {
     width: number;
     height: number;
 }, screenWidth: number, screenHeight: number, padding?: number) => ViewportState;
-export declare const zoomAt: (state: ViewportState, focalScreen: Vec2, nextZoom: number) => ViewportState;
+export declare const DEFAULT_ZOOM_LIMITS: {
+    readonly min: 0.05;
+    readonly max: 50;
+};
+export interface ZoomLimits {
+    min: number;
+    max: number;
+}
+export declare const zoomAt: (state: ViewportState, focalScreen: Vec2, nextZoom: number, limits?: ZoomLimits) => ViewportState;
 export declare const panBy: (state: ViewportState, deltaScreen: Vec2) => ViewportState;

package/dist/annotation/canvas/viewport.js

@@ -64,8 +64,13 @@ export const fitRectToScreen = (rect, screenWidth, screenHeight, padding = 0) =>
 };
 // Zoom toward a focal screen point so the world point under the cursor stays
 // fixed. Used for wheel-zoom on web and pinch on native.
-export const zoomAt = (state, focalScreen, nextZoom) => {
-    const clampedZoom = Math.max(0.05, Math.min(50, nextZoom));
+//
+// `limits` defaults to the historical fixed bounds. A canvas whose document
+// fits below the historical floor (a multi-page PDF filmstrip) passes its own
+// floor — see computeZoomFloor in pdfDocument.ts.
+export const DEFAULT_ZOOM_LIMITS = { min: 0.05, max: 50 };
+export const zoomAt = (state, focalScreen, nextZoom, limits = DEFAULT_ZOOM_LIMITS) => {
+    const clampedZoom = Math.max(limits.min, Math.min(limits.max, nextZoom));
     const focalWorld = {
         x: focalScreen.x / state.zoom + state.pan.x,
         y: focalScreen.y / state.zoom + state.pan.y,

package/dist/annotation/data/hooks/useAnnotationCanvasDoc.d.ts

@@ -1,4 +1,4 @@
-import { type AnnotationBackgroundLayer, type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport, type BackgroundFit } from '../../../types/annotation.js';
+import { type AnnotationBackgroundLayer, type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationPdfPageSize, type AnnotationViewport, type BackgroundFit } from '../../../types/annotation.js';
 import type { AnnotationScope, ImageBlob } from '../AnnotationDataProvider.js';
 export type SaveStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error';
 export interface UseAnnotationCanvasDocOptions {
@@ -30,6 +30,10 @@ export interface UseAnnotationCanvasDocResult {
         width: number;
         height: number;
     }) => Promise<string>;
+    addPdfDocument: (blob: ImageBlob, meta: {
+        pages: AnnotationPdfPageSize[];
+        fileName?: string;
+    }) => Promise<string>;
     updateBackgroundImage: (id: string, patch: Partial<Omit<AnnotationBackgroundLayer, 'id'>>) => void;
     removeBackgroundImage: (id: string) => Promise<void>;
     setBackgroundImage: (blob: ImageBlob, dims: {

package/dist/annotation/data/hooks/useAnnotationCanvasDoc.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, createEmptyCanvasState, } from '../../../types/annotation.js';
+import { createPdfDocument, makePdfDocumentId, pdfDocumentExtent, } from '../../canvas/pdfDocument.js';
 import { backgroundLayersOf, placeNewBackgroundLayer, defaultBackgroundLayerLocked, } from '../../canvas/backgroundLayers.js';
 import { imageDocRect } from '../../canvas/viewport.js';
 import { FileUploadType } from '../../../types/firestore.js';
@@ -395,6 +396,30 @@ export const useAnnotationCanvasDoc = (options) => {
         });
         return layerId;
     }, [ensureFileId, uploadImage, onCommit, fallbackViewport]);
+    const addPdfDocument = useCallback(async (blob, meta) => {
+        if (meta.pages.length === 0) {
+            throw new Error('Cannot attach a PDF with no pages');
+        }
+        const fileId = await ensureFileId();
+        const id = makePdfDocumentId();
+        const ref = await uploadImage(fileId, `backgrounds/${id}`, blob);
+        const document = createPdfDocument({
+            id,
+            storagePath: ref.storagePath,
+            pages: meta.pages,
+            fileName: meta.fileName,
+        });
+        // One patch, two ops: the extent must land WITH the document so no
+        // render sees pages laid out past the doc rect (or a doc rect with no
+        // pages behind it). Undo reverts both together.
+        onCommit({
+            ops: [
+                { op: 'setPdfDocument', document },
+                { op: 'setViewport', patch: pdfDocumentExtent(document) },
+            ],
+        });
+        return id;
+    }, [ensureFileId, uploadImage, onCommit]);
     const updateBackgroundImage = useCallback((id, patch) => {
         onCommit({ ops: [{ op: 'updateBackgroundImage', id, patch }] });
     }, [onCommit]);
@@ -521,6 +546,7 @@ export const useAnnotationCanvasDoc = (options) => {
         refreshThumbnail,
         ensureFileId,
         addBackgroundImage,
+        addPdfDocument,
         updateBackgroundImage,
         removeBackgroundImage,
         setBackgroundImage,

package/dist/exports.d.ts

@@ -31,9 +31,11 @@ export type { GestureConfig, PanTrigger, AnnotationCanvasInnerProps, } from './a
 export type { CanvasPointerEvent, RequestTextInput, ShapeDrawConfig, Tool, ToolContext, ToolState, } from './annotation/canvas/Tool.js';
 export type { FileRef, MeasurementRef, PickMeasurement, } from './annotation/canvas/measurementPicker.js';
 export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './annotation/canvas/measurementStampOverlay.js';
+export type { CanvasBackgroundSlotArgs, RenderCanvasBackground, } from './annotation/canvas/backgroundSlot.js';
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, type StampTileDims, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, type GroupHeaderBadge, type GroupHeaderDescriptor, } from './annotation/canvas/groupHeaderLayout.js';
-export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './annotation/canvas/viewport.js';
+export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, type ViewportApi, type ViewportState, type ZoomLimits, } from './annotation/canvas/viewport.js';
+export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, type PdfDocRect, } from './annotation/canvas/pdfDocument.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, type SelectToolOptions, } from './annotation/canvas/tools/selectTool.js';

package/dist/exports.js

@@ -38,7 +38,8 @@ export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, } from './annotation/canvas/groupHeaderLayout.js';
-export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './annotation/canvas/viewport.js';
+export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './annotation/canvas/viewport.js';
+export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, } from './annotation/canvas/pdfDocument.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { createPenTool, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, } from './annotation/canvas/tools/selectTool.js';

package/dist/types/annotation.d.ts

@@ -145,12 +145,27 @@ export interface AnnotationBackgroundLayer {
     transform: BackgroundLayerTransform;
     locked?: boolean;
 }
+export interface AnnotationPdfPageSize {
+    width: number;
+    height: number;
+}
+export type AnnotationPdfLayout = 'continuousVertical';
+export interface AnnotationPdfDocument {
+    id: AnnotationElementId;
+    storagePath: string;
+    fileName?: string;
+    pageCount: number;
+    pages: AnnotationPdfPageSize[];
+    layout: AnnotationPdfLayout;
+    gap: number;
+}
 export interface AnnotationViewport {
     width: number;
     height: number;
     backgroundImage?: AnnotationBackgroundImage;
     backgroundFit?: BackgroundFit;
     backgroundImages?: AnnotationBackgroundLayer[];
+    pdfDocument?: AnnotationPdfDocument;
 }
 export type TileScalePlatform = 'web' | 'mobile';
 export type TileScaleTarget = 'measurement' | 'header' | 'file';
@@ -225,6 +240,9 @@ export type AnnotationPatchOp = {
 } | {
     op: 'setViewport';
     patch: Partial<AnnotationViewport>;
+} | {
+    op: 'setPdfDocument';
+    document: AnnotationPdfDocument | null;
 } | {
     op: 'setTileScaleFactor';
     value: number;