@reekon-tools/boldr-utils 1.26.2 → 1.28.0

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

@@ -15,6 +15,7 @@ export interface AnnotationCanvasInnerProps {
     activeToolId: string;
     selection: Selection | null;
     onSelectionChange(selection: Selection | null): void;
+    onViewportChange?(viewport: ViewportState): void;
     measurements?: Measurement[];
     fallbackUnit?: Units;
     fractionalTolerance?: FractionalTolerance;

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -5,7 +5,6 @@ import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeom
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
 import { backgroundCropBars, backgroundLayerDocRect, backgroundLayersOf, isBackgroundLayerLocked, } from './backgroundLayers.js';
-import { YellowColors } from '../../theme/colors.js';
 import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
 import { PlaneElement, PLANE_CHROME_COLOR, PLANE_GRID_COLOR, PLANE_GRID_OPACITY, PLANE_GRID_WIDTH, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
@@ -26,10 +25,6 @@ const SELECTION_STROKE = 1.5;
 // the target the dragged endpoint is currently locked onto. Orange so it reads
 // against both the blue selection chrome and the yellow lock accent.
 const SNAP_INDICATOR_COLOR = '#FF7A00';
-// Outline of a selected LOCKED background layer: the lock accent (the same
-// yellow the selected group-header border uses), distinct from the blue
-// manipulable-selection chrome — locked means "selected, but pinned".
-const BACKGROUND_LOCKED_COLOR = YellowColors.mainYellow;
 // Link badge on a LINKED background layer (layer.fileId — an expanded file
 // tile, see fileTileSwap.ts): a chain glyph in a white disc at the layer's
 // top-right, saying "this is a group file's image, not a plain background".
@@ -310,16 +305,24 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                 // its opposite corner) plus four edge crop bars (raster layers only —
                 // dragging a bar windows the image non-destructively). Chrome tracks
                 // the live drag/resize transform the same way the layer itself does
-                // above. A LOCKED layer (backgroundLayerIsLocked) keeps the outline —
-                // it is selected, and the host's chrome offers the lock toggle — but
-                // recolored to the lock yellow and with no handles: it cannot scale
-                // or crop, so a grabbable gizmo would lie. During a native crop-bar
+                // above. A LOCKED layer (backgroundLayerIsLocked) keeps the same blue
+                // outline — it is selected, and the host's chrome offers the lock
+                // toggle — but no handles or bars: it cannot move, scale or crop, so
+                // a grabbable gizmo would lie. During a native crop-bar
                 // drag the chrome is just the LIVE outline — handles and bars would
                 // sit on stale committed edges.
                 const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
                 if (layer) {
+                    // The outline is screen-constant (the handle ring width — 2px /
+                    // zoom, a number on web and a derived value on native), not the
+                    // doc-unit SELECTION_STROKE: a background is often huge in doc
+                    // space and viewed zoomed out, where a doc-unit stroke thins to
+                    // nothing — and for a LOCKED layer this border is the only
+                    // selected indicator. Doc units only when the host passes no
+                    // handle sizing (no drag-select tool).
+                    const outlineWidth = handleRingWidth ?? SELECTION_STROKE;
                     if (layer.id === bgCropId && liveBgCrop) {
-                        return (_jsx(Rect, { x: liveBgCrop.x, y: liveBgCrop.y, width: liveBgCrop.width, height: liveBgCrop.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }));
+                        return (_jsx(Rect, { x: liveBgCrop.x, y: liveBgCrop.y, width: liveBgCrop.width, height: liveBgCrop.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: outlineWidth }));
                     }
                     const locked = isBackgroundLayerLocked(effectiveCanvas.viewport, layer.id);
                     const r = backgroundLayerDocRect(layer);
@@ -331,7 +334,7 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                         { x: r.x, y: r.y + r.height },
                         { x: r.x + r.width, y: r.y + r.height },
                     ];
-                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: locked ? BACKGROUND_LOCKED_COLOR : SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }), !locked &&
+                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: outlineWidth }), !locked &&
                                 layer.format !== 'svg' &&
                                 backgroundCropBars(layer).map((bar) => {
                                     const inset = Math.min(bar.width, bar.height) * 0.18;

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

@@ -87,7 +87,7 @@ export interface DragSelectionConfig {
     } | null;
     buildShapeCornerPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, corner: RectCorner, delta: Vec2): AnnotationDocumentPatch | null;
     isSelectedTileGrab?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number, viewportTileScale?: number, tileScaleFactor?: number, headerTileScaleFactor?: number, fileTileScaleFactor?: number): boolean;
-    hitTestBackground?(doc: AnnotationCanvasState, world: Vec2): {
+    hitTestBackground?(doc: AnnotationCanvasState, world: Vec2, zoom: number): {
         id: AnnotationElementId;
         locked: boolean;
     } | null;

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

@@ -488,7 +488,7 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
 // DragSelectionConfig AND the web pointer handlers — one source of truth).
 // Backgrounds can cover the whole document, so they never join the general
 // hit-test: a tap selects one only when every stroke/shape/measurement
-// misses, and a drag translates one only when it is ALREADY selected — the
+// misses AND it lands on the layer's perimeter (findBackgroundHit), and a drag translates one only when it is ALREADY selected — the
 // layout tool's two-step model, which keeps a full-bleed background from
 // hijacking pan/marquee gestures. A LOCKED layer (backgroundLayerIsLocked —
 // by default the first image, which IS the canvas) is selectable like any
@@ -502,16 +502,38 @@ const pointInBackgroundLayer = (layer, p) => {
     const r = backgroundLayerDocRect(layer);
     return (p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height);
 };
-// Topmost background layer under a world point (reverse array order — later
-// layers draw on top). Point-in-doc-rect, no padding: a background is a big
-// target already.
-const findBackgroundHit = (doc, world) => {
+// Screen-px half-width of the edge band that selects an UNSELECTED background
+// (converted to doc space via zoom). A zoomed-in background often fills the
+// whole viewport, so a tap anywhere on it selecting the image made selection
+// accidental — and a selected background's chrome gets in the way of placing
+// more objects. Selecting now takes a deliberate tap on the image's perimeter:
+// within this distance of the visible (cropped) rect's outline, inside or out.
+// Once selected, the whole rect is live again (findSelectedBackgroundHit), so
+// body drags and the tap-toggle deselect are unchanged.
+const BACKGROUND_EDGE_GRAB_PX = 24;
+// Topmost background layer whose perimeter band contains a world point
+// (reverse array order — later layers draw on top). A point in a layer's
+// interior (past the band) is occluded by that layer: it never falls through
+// to the edge of a layer drawn beneath it, whose outline is hidden there. A
+// layer smaller than two band-widths on screen is all band, so it stays
+// selectable anywhere on it.
+const findBackgroundHit = (doc, world, zoom) => {
+    const band = BACKGROUND_EDGE_GRAB_PX / zoom;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         const layer = layers[i];
-        if (pointInBackgroundLayer(layer, world)) {
-            return { id: layer.id, locked: backgroundLayerIsLocked(layer, i) };
-        }
+        const r = backgroundLayerDocRect(layer);
+        const left = world.x - r.x;
+        const right = r.x + r.width - world.x;
+        const top = world.y - r.y;
+        const bottom = r.y + r.height - world.y;
+        // Outside the band-expanded rect: this layer is not under the point.
+        if (Math.min(left, right, top, bottom) < -band)
+            continue;
+        // Inside the band-inset rect: the layer's interior covers the point.
+        if (Math.min(left, right, top, bottom) > band)
+            return null;
+        return { id: layer.id, locked: backgroundLayerIsLocked(layer, i) };
     }
     return null;
 };
@@ -907,11 +929,14 @@ export const createSelectTool = (options = {}) => ({
                     delta: { x: 0, y: 0 },
                 };
             }
-            // An unselected background selects. A free one consumes the gesture
+            // An unselected background selects — but only from its perimeter
+            // band (findBackgroundHit); its interior behaves like empty canvas,
+            // so a full-bleed image never gets selected by accident. A free one
+            // consumes the gesture
             // (no pan, no drag): translating it takes a second gesture once
             // selected, the layout tool's two-step model. A locked one is the
             // canvas: it selects AND the drag pans, as on empty canvas.
-            const bg = findBackgroundHit(ctx.document, world);
+            const bg = findBackgroundHit(ctx.document, world, zoom);
             if (bg) {
                 ctx.setSelection({ ids: [bg.id] });
                 if (bg.locked && options.panOnEmptyDrag) {

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

@@ -14,6 +14,8 @@ export interface AnnotationCanvasHandle {
     redo(): void;
     canUndo(): boolean;
     canRedo(): boolean;
+    zoomBy(factor: number, focalScreen?: Vec2): void;
+    getZoom(): number;
     zoomToFit(opts?: {
         animated?: boolean;
         durationMs?: number;
@@ -72,6 +74,7 @@ export interface UseAnnotationCanvasStateProps {
     activeToolId: string;
     selection: Selection | null;
     onSelectionChange(selection: Selection | null): void;
+    onViewportChange?(viewport: ViewportState): void;
     measurements?: Measurement[];
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -83,7 +83,7 @@ const defaultLeaderLenDoc = (docWidth) => Math.min(800, Math.max(240, docWidth *
 // inners share this hook; each wraps it with platform-specific event
 // capture and JSX (div + DOM events vs. GestureDetector + RN Views).
 export const useAnnotationCanvasState = (props) => {
-    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, snapToGeometry, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
+    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, onViewportChange, measurements, pickMeasurement, requestTextInput, snapToGeometry, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
     const [viewport, setViewport] = useState(initialViewport ?? DEFAULT_VIEWPORT);
     const [toolState, setToolState] = useState(undefined);
     // Synchronous mirror for the DISPATCHERS. The native tap gesture
@@ -127,7 +127,17 @@ export const useAnnotationCanvasState = (props) => {
     // (Adding a background mid-session also fits it, so you see the whole image
     // you just dropped in.) Canvases that never gain a background keep the 1:1
     // default — for a screen-sized document that already frames it correctly.
-    const didInitialFitRef = useRef(false);
+    //
+    // Pre-latched in two cases, both "someone already framed the view":
+    // - The host passed `initialViewport` — it owns framing (the paged PDF
+    //   editor fits each page from the file record at mount, long before the
+    //   page's annotation doc hydrates).
+    // - The user (or the host, through the handle) has already moved the
+    //   viewport this mount. The doc can hydrate mid-gesture — a page turn's
+    //   snapshot lands while the user is already wheel-zooming — and a late fit
+    //   here would stomp that viewport, which reads as zoom pivoting around a
+    //   broken focal point. Every pan/zoom/fit path below latches the ref.
+    const didInitialFitRef = useRef(!!initialViewport);
     useEffect(() => {
         if (didInitialFitRef.current)
             return;
@@ -257,9 +267,11 @@ export const useAnnotationCanvasState = (props) => {
                 : Promise.resolve(null);
         },
         applyPan(deltaScreen) {
+            didInitialFitRef.current = true;
             setViewport((v) => panBy(v, deltaScreen));
         },
         applyZoom(focalScreen, nextZoom) {
+            didInitialFitRef.current = true;
             setViewport((v) => zoomAt(v, focalScreen, nextZoom, zoomLimitsRef.current));
         },
     }), [
@@ -369,18 +381,23 @@ export const useAnnotationCanvasState = (props) => {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [activeTool, ctx]);
     const pan = useCallback((deltaScreen) => {
+        didInitialFitRef.current = true;
         setViewport((v) => panBy(v, deltaScreen));
     }, []);
     const zoom = useCallback((focalScreen, nextZoom) => {
+        didInitialFitRef.current = true;
         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.
+    // target from the same stale base. See `zoomBy` on the API type. Clamped
+    // like the other zoom paths — an unclamped wheel burst could sail past the
+    // document floor/ceiling.
     const zoomBy = useCallback((focalScreen, factor) => {
         if (!Number.isFinite(factor) || factor <= 0)
             return;
-        setViewport((v) => zoomAt(v, focalScreen, v.zoom * factor));
+        didInitialFitRef.current = true;
+        setViewport((v) => zoomAt(v, focalScreen, v.zoom * factor, zoomLimitsRef.current));
     }, []);
     // Imperative API mirror — set via prop so it survives WithSkiaWeb's lazy
     // boundary on web.
@@ -445,6 +462,12 @@ export const useAnnotationCanvasState = (props) => {
             return c.viewport.screenToWorld({ x: cx, y: cy });
         };
         imperativeRef.current = {
+            zoomBy(factor, focalScreen) {
+                zoomBy(focalScreen ?? { x: width / 2, y: height / 2 }, factor);
+            },
+            getZoom() {
+                return ctxRef.current.viewport.state.zoom;
+            },
             undo() {
                 const entry = undoStackRef.current.pop();
                 if (!entry)
@@ -466,6 +489,7 @@ export const useAnnotationCanvasState = (props) => {
                 return redoStackRef.current.length > 0;
             },
             zoomToFit(opts) {
+                didInitialFitRef.current = true;
                 // The document is read through ctxRef, not the effect closure: this
                 // effect's deps deliberately exclude `canvas`, so the closed-over
                 // binding can predate tiles that landed or moved since — and the fit
@@ -479,6 +503,7 @@ export const useAnnotationCanvasState = (props) => {
                 }
             },
             resetView() {
+                didInitialFitRef.current = true;
                 // "Reset view" frames the whole document/image again — the same fit the
                 // canvas opens with — rather than snapping to a 1:1 top-left view, which
                 // for a high-res background is the very crop this is meant to escape.
@@ -487,6 +512,7 @@ export const useAnnotationCanvasState = (props) => {
             fitContentToRect(rect, opts) {
                 if (!(rect.width > 0) || !(rect.height > 0))
                     return;
+                didInitialFitRef.current = true;
                 const target = computeContentFitRect(ctxRef.current.document, rect);
                 if (opts?.animated && animateViewport) {
                     animateViewport(target, opts.durationMs ?? 450);
@@ -498,6 +524,7 @@ export const useAnnotationCanvasState = (props) => {
             fitDocRect(rect, opts) {
                 if (!(width > 0) || !(height > 0))
                     return;
+                didInitialFitRef.current = true;
                 const limits = zoomLimitsRef.current;
                 const target = fitDocRectViewport(rect, width, height, {
                     paddingPx: opts?.paddingPx,
@@ -844,7 +871,16 @@ export const useAnnotationCanvasState = (props) => {
         canvas.viewport.height,
         width,
         height,
+        zoomBy,
     ]);
+    // Viewport subscription for hosts (zoom readouts and the like). A ref keeps
+    // the effect off the callback identity — hosts often pass a fresh closure
+    // every render.
+    const onViewportChangeRef = useRef(onViewportChange);
+    onViewportChangeRef.current = onViewportChange;
+    useEffect(() => {
+        onViewportChangeRef.current?.(viewport);
+    }, [viewport]);
     const worldTransform = useMemo(() => [
         { scale: viewport.zoom },
         { translateX: -viewport.pan.x },

package/dist/export/nutrient/instantJsonToPdfCanvas.d.ts

@@ -0,0 +1,39 @@
+import type { PdfCanvasPage, PdfCanvasPageState } from '../../types/pdfCanvas.js';
+/**
+ * `tileDocSize` for a converted file. At STAMP_TILE_SIZE the renderer's
+ * doc-per-base-unit factor is 1, so a tile's `scale` reads directly as
+ * "Nutrient tile edge ÷ 96".
+ */
+export declare const NUTRIENT_TILE_DOC_SIZE = 96;
+export interface NutrientSkippedAnnotation {
+    /** Instant JSON id / name, or `#index` when it has neither. */
+    id: string;
+    /** Instant JSON `type`, e.g. `pspdfkit/note`. */
+    type: string;
+    pageIndex?: number;
+    reason: string;
+    /** Text the annotation carried (notes, comments), so nothing is lost silently. */
+    text?: string;
+}
+export interface InstantJsonConversion {
+    /** Page states by page index; only pages that received content appear. */
+    pageStates: Record<number, PdfCanvasPageState>;
+    /** Value for `PdfCanvasData.tileDocSize` on the converted file. */
+    tileDocSize: number;
+    /** Annotations converted, by Instant JSON type. */
+    converted: Record<string, number>;
+    /** Derived tile images dropped (they are re-rendered from live data). */
+    droppedTileImages: number;
+    skipped: NutrientSkippedAnnotation[];
+    /** Converted, but with a known fidelity loss (e.g. text that won't wrap). */
+    warnings: NutrientSkippedAnnotation[];
+}
+export interface InstantJsonToPdfCanvasInput {
+    /** Parsed `annotations.json`. */
+    instantJson: unknown;
+    /** The source PDF's pages (describePdfPages), index-aligned. */
+    pages: readonly PdfCanvasPage[];
+    /** Epoch millis stamped as `updatedAt` on every page state. */
+    now?: number;
+}
+export declare const instantJsonToPdfCanvas: (input: InstantJsonToPdfCanvasInput) => InstantJsonConversion;

package/dist/export/nutrient/instantJsonToPdfCanvas.js

@@ -0,0 +1,631 @@
+// Nutrient (PSPDFKit) Instant JSON → PdfCanvas page states.
+//
+// Legacy PDF files were annotated in the Nutrient viewer, which saves its
+// annotations as Instant JSON in `${folderPath}/annotations.json` next to the
+// untouched source PDF. This converts that payload into the Skia canvas model
+// (one PdfCanvasPageState per page) so the file can be exported by
+// renderPdfCanvasToPdf — and later edited — without any Nutrient runtime.
+//
+// Pure: no Firestore, no Storage, no rendering. The caller supplies the PDF's
+// page sizes (describePdfPages) and resolves tile content itself.
+//
+// Coordinate space. Instant JSON geometry is in PDF points on the DISPLAYED
+// page (after its own /Rotate), origin top-left, y down — the same space a
+// PdfCanvas page's doc space uses at user rotation 0, so points copy across
+// unchanged.
+//
+// Two families of annotation live in the payload:
+//  - REEKON measurement tiles. Every annotation carrying `customData.groupId`
+//    belongs to a tile: an ANCHOR (line / rectangle / polygon / ellipse) that
+//    holds the binding and geometry, and on files last saved by the web viewer
+//    or by old app builds, the rendered tile IMAGE too. Tile images are always
+//    derived, so they are dropped; anchors become PlacedMeasurementRefs that
+//    resolve live against the job's measurements, exactly like a Skia tile.
+//    Mirrors boldr-pro lib/annotation/schema.ts (computeTileBbox,
+//    groupHeaderBannerSize, buildAnchorAnnotation).
+//  - Everything the user drew with Nutrient's tools (ink, shapes, text,
+//    text markup, stamps). These map onto Skia strokes and shapes where the
+//    model can express them; the rest is reported in `skipped`.
+import { DEFAULT_LAYER_ID, } from '../../types/annotation.js';
+import { emptyPdfCanvasPageState } from '../../annotation/canvas/pdfCanvasPages.js';
+import { GROUP_HEADER_TILE_WIDTH, STAMP_TILE_SIZE, } from '../../annotation/canvas/stampLayout.js';
+/**
+ * `tileDocSize` for a converted file. At STAMP_TILE_SIZE the renderer's
+ * doc-per-base-unit factor is 1, so a tile's `scale` reads directly as
+ * "Nutrient tile edge ÷ 96".
+ */
+export const NUTRIENT_TILE_DOC_SIZE = STAMP_TILE_SIZE;
+// Nutrient-side tile defaults (boldr-pro lib/annotation/schema.ts).
+const NUTRIENT_DEFAULT_TILE_SCALE = 100;
+const NUTRIENT_ANCHOR_COLOR = '#2492FB';
+const NUTRIENT_ANCHOR_LINE_WIDTH = 8;
+/** Segments used to approximate a Nutrient ellipse (the Skia `ellipse` shape
+ * renders as a circle, so true ellipses are emitted as closed polygons). */
+const ELLIPSE_SEGMENTS = 48;
+/** Alpha given to text-markup highlights and multiply-blended ink, which
+ * Nutrient draws opaque but multiplied into the page. */
+const MULTIPLY_ALPHA = 0.4;
+/* ------------------------------------------------------------------ *
+ * Small helpers
+ * ------------------------------------------------------------------ */
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const toPoint = (v) => {
+    if (Array.isArray(v) && isNum(v[0]) && isNum(v[1]))
+        return [v[0], v[1]];
+    if (v && typeof v === 'object') {
+        const { x, y } = v;
+        if (isNum(x) && isNum(y))
+            return [x, y];
+    }
+    return null;
+};
+const toPoints = (v) => Array.isArray(v) ? v.map(toPoint).filter((p) => p !== null) : [];
+const toBbox = (v) => Array.isArray(v) && v.length >= 4 && v.slice(0, 4).every(isNum)
+    ? [v[0], v[1], v[2], v[3]]
+    : null;
+const vec = ([x, y]) => ({ x, y });
+/** `#RRGGBB` + opacity → `#RRGGBBAA` (the renderer splits the alpha out). */
+const withAlpha = (color, alpha) => {
+    const hex = color.trim().replace(/^#/, '');
+    const six = hex.length === 3 || hex.length === 4
+        ? hex
+            .slice(0, 3)
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    if (!/^[0-9a-fA-F]{6}$/.test(six))
+        return color;
+    const a = Math.max(0, Math.min(1, alpha));
+    if (a >= 1)
+        return `#${six}`;
+    return `#${six}${Math.round(a * 255)
+        .toString(16)
+        .padStart(2, '0')}`;
+};
+const opacityOf = (a) => isNum(a.opacity) ? Math.max(0, Math.min(1, a.opacity)) : 1;
+const isHidden = (a) => Array.isArray(a.flags) &&
+    (a.flags.includes('hidden') || a.flags.includes('noView'));
+/** Nutrient line caps that draw an arrowhead. The Skia model has one arrow
+ * style, so every arrow variant maps to it; other caps render plain. */
+const capOf = (cap) => typeof cap === 'string' && /arrow/i.test(cap) ? 'arrow' : undefined;
+const createdAtOf = (a) => {
+    const t = typeof a.createdAt === 'string' ? Date.parse(a.createdAt) : NaN;
+    return Number.isFinite(t) ? t : 0;
+};
+/** Plain text of a text annotation: Instant JSON v1 carries
+ * `{format: 'plain' | 'xhtml', value}`; older payloads a bare string. */
+const textOf = (raw) => {
+    if (typeof raw === 'string')
+        return raw;
+    if (!raw || typeof raw !== 'object')
+        return '';
+    const { format, value } = raw;
+    if (typeof value !== 'string')
+        return '';
+    if (format !== 'xhtml')
+        return value;
+    return value
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/p>\s*<p[^>]*>/gi, '\n')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .trim();
+};
+/** Rough width of a line of text; only used to flag boxes that relied on
+ * Nutrient's word wrap (the Skia text shape breaks on newlines only). */
+const estimatedTextWidth = (line, fontSize) => line.length * fontSize * 0.55;
+const ellipsePolygon = (bbox, inset) => {
+    const [left, top, w, h] = bbox;
+    const cx = left + w / 2;
+    const cy = top + h / 2;
+    const rx = Math.max(0, w / 2 - inset);
+    const ry = Math.max(0, h / 2 - inset);
+    const pts = [];
+    for (let i = 0; i < ELLIPSE_SEGMENTS; i++) {
+        const t = (i / ELLIPSE_SEGMENTS) * Math.PI * 2;
+        pts.push({ x: cx + rx * Math.cos(t), y: cy + ry * Math.sin(t) });
+    }
+    return pts;
+};
+/** Nutrient strokes a rectangle / ellipse INSIDE its bbox; the Skia shape
+ * strokes centred on the path, so the path is inset by half the width. */
+const insetRect = (bbox, inset) => {
+    const [left, top, w, h] = bbox;
+    const dx = Math.min(inset, w / 2);
+    const dy = Math.min(inset, h / 2);
+    return [
+        { x: left + dx, y: top + dy },
+        { x: left + w - dx, y: top + h - dy },
+    ];
+};
+/** Style for a fill-only shape. The renderer always strokes, so the stroke is
+ * made fully transparent. */
+const fillOnlyStyle = (fill) => ({
+    fill,
+    stroke: withAlpha(fill, 0),
+    strokeWidth: 0.01,
+});
+/* ------------------------------------------------------------------ *
+ * Tiles
+ * ------------------------------------------------------------------ */
+const tileCustomDataOf = (a) => {
+    const cd = a.customData;
+    if (!cd || typeof cd !== 'object')
+        return null;
+    const { groupId } = cd;
+    return typeof groupId === 'string' && groupId ? cd : null;
+};
+/** Tile edge in PDF points as the mobile app renders it (tileScale()). */
+const nutrientTileEdge = (cd) => {
+    const s = isNum(cd.mobileScale) ? cd.mobileScale : cd.scale;
+    return isNum(s) && s > 0 ? s : NUTRIENT_DEFAULT_TILE_SCALE;
+};
+/** Skia `scale` reproducing the Nutrient footprint at NUTRIENT_TILE_DOC_SIZE:
+ * a square tile is `edge` wide; an expanded header banner is `2 × edge` wide
+ * (groupHeaderBannerSize) against a 240-unit Skia header base. Collapsed
+ * headers use the same factor — both apps derive the collapsed box from the
+ * expanded one by the same 90/200 design ratio. */
+const skiaTileScale = (cd) => {
+    const edge = nutrientTileEdge(cd);
+    return cd.isGroupHeader
+        ? (2 * edge) / GROUP_HEADER_TILE_WIDTH
+        : edge / STAMP_TILE_SIZE;
+};
+const convertTileAnchor = (a, cd, elementId) => {
+    const createdAt = createdAtOf(a);
+    const base = {
+        id: elementId,
+        layerId: DEFAULT_LAYER_ID,
+        groupId: cd.groupId,
+        ...(typeof cd.columnId === 'string' && cd.columnId && !cd.isBlank
+            ? { columnId: cd.columnId }
+            : {}),
+        ...(cd.isGroupHeader ? { isGroupHeader: true } : {}),
+        ...(cd.isGroupHeader && cd.collapsed ? { collapsed: true } : {}),
+        anchor: { x: 0, y: 0 },
+        scale: skiaTileScale(cd),
+        createdAt,
+    };
+    const lineColor = withAlpha(a.strokeColor || NUTRIENT_ANCHOR_COLOR, opacityOf(a));
+    const lineWidth = isNum(a.strokeWidth)
+        ? a.strokeWidth
+        : NUTRIENT_ANCHOR_LINE_WIDTH;
+    const hidden = isHidden(a) || cd.measurementMode === 'none';
+    if (a.type === 'pspdfkit/shape/line') {
+        const start = toPoint(a.startPoint);
+        const end = toPoint(a.endPoint);
+        if (!start || !end)
+            return null;
+        // computeTileBbox: a `left` tile sits on the end point, others centre.
+        const linePos = cd.measurementMode === 'left' ? 1 : 0.5;
+        const anchor = {
+            x: start[0] + (end[0] - start[0]) * linePos,
+            y: start[1] + (end[1] - start[1]) * linePos,
+        };
+        if (cd.isGroupHeader || hidden) {
+            const placed = { ...base, anchor };
+            if (!cd.isGroupHeader || hidden)
+                return { placed };
+            return {
+                placed,
+                leader: {
+                    id: `${elementId}-leader`,
+                    layerId: DEFAULT_LAYER_ID,
+                    kind: 'line',
+                    geometry: { points: [vec(start), vec(end)] },
+                    style: { stroke: lineColor, strokeWidth: lineWidth },
+                    createdAt,
+                },
+            };
+        }
+        return {
+            placed: {
+                ...base,
+                anchor,
+                placement: 'line',
+                line: { a: vec(start), b: vec(end) },
+                linePos,
+                lineColor,
+                lineWidth,
+            },
+        };
+    }
+    const bbox = toBbox(a.bbox);
+    if (!bbox)
+        return null;
+    const [left, top, w, h] = bbox;
+    const anchor = { x: left + w / 2, y: top + h / 2 };
+    // Headers centre their banner in the (hidden) grab rect; `none` tiles are a
+    // bare stamp; polygon / ellipse anchors have no Skia placement, so the
+    // outline is emitted separately (see convert()) and the tile sits bare.
+    if (cd.isGroupHeader || hidden || a.type !== 'pspdfkit/shape/rectangle') {
+        return { placed: { ...base, anchor } };
+    }
+    return {
+        placed: {
+            ...base,
+            anchor,
+            placement: 'rectangle',
+            rect: { a: { x: left, y: top }, b: { x: left + w, y: top + h } },
+            lineColor,
+            lineWidth,
+        },
+    };
+};
+const strokeStyleOf = (a) => {
+    const opacity = opacityOf(a);
+    const style = {
+        stroke: withAlpha(a.strokeColor || '#000000', opacity),
+        strokeWidth: isNum(a.strokeWidth) ? a.strokeWidth : 1,
+    };
+    if (Array.isArray(a.strokeDashArray) && a.strokeDashArray.length > 0) {
+        style.dash = true;
+    }
+    if (a.fillColor)
+        style.fill = withAlpha(a.fillColor, opacity);
+    return style;
+};
+const shape = (id, kind, points, style, createdAt, extra = {}) => ({
+    id,
+    layerId: DEFAULT_LAYER_ID,
+    kind,
+    geometry: { points },
+    style,
+    createdAt,
+    ...extra,
+});
+const convertDrawn = (a, id) => {
+    const createdAt = createdAtOf(a);
+    const opacity = opacityOf(a);
+    switch (a.type) {
+        case 'pspdfkit/ink': {
+            const segments = Array.isArray(a.lines?.points) ? a.lines.points : [];
+            const multiply = a.blendMode === 'multiply';
+            const color = withAlpha(a.strokeColor || '#000000', opacity);
+            const strokes = segments
+                .map(toPoints)
+                .filter((pts) => pts.length > 0)
+                .map((pts, i) => ({
+                id: `${id}-${i}`,
+                layerId: DEFAULT_LAYER_ID,
+                // The Skia highlighter draws at 0.3 alpha, the closest match to
+                // Nutrient's multiply-blended highlighter ink.
+                tool: multiply ? 'highlighter' : 'pen',
+                color,
+                width: isNum(a.lineWidth) ? a.lineWidth : 1,
+                cap: 'round',
+                // A single tap is one point; the renderer draws a dot for a
+                // zero-length two-point stroke.
+                points: (pts.length === 1 ? [pts[0], pts[0]] : pts).flat(),
+                createdAt,
+            }));
+            if (strokes.length === 0)
+                return 'Ink annotation has no points';
+            return { strokes };
+        }
+        case 'pspdfkit/shape/line': {
+            const start = toPoint(a.startPoint);
+            const end = toPoint(a.endPoint);
+            if (!start || !end)
+                return 'Line has no end points';
+            const style = strokeStyleOf(a);
+            delete style.fill; // Nutrient fills only closed arrowheads.
+            const endCap = capOf(a.lineCaps?.end);
+            const startCap = capOf(a.lineCaps?.start);
+            if (endCap)
+                style.cap = endCap;
+            if (startCap)
+                style.startCap = startCap;
+            return {
+                shapes: [shape(id, 'line', [vec(start), vec(end)], style, createdAt)],
+            };
+        }
+        case 'pspdfkit/shape/rectangle':
+        case 'pspdfkit/shape/ellipse': {
+            const bbox = toBbox(a.bbox);
+            if (!bbox)
+                return 'Shape has no bounding box';
+            const style = strokeStyleOf(a);
+            const inset = (style.strokeWidth ?? 0) / 2;
+            if (a.type === 'pspdfkit/shape/rectangle') {
+                return {
+                    shapes: [shape(id, 'rect', insetRect(bbox, inset), style, createdAt)],
+                };
+            }
+            const points = ellipsePolygon(bbox, inset);
+            return {
+                shapes: [
+                    shape(id, 'polygon', points, style, createdAt, {
+                        geometry: { points, closed: true },
+                    }),
+                ],
+            };
+        }
+        case 'pspdfkit/shape/polygon':
+        case 'pspdfkit/shape/polyline': {
+            const pts = toPoints(a.points).map(vec);
+            if (pts.length < 2)
+                return 'Shape has fewer than two points';
+            const closed = a.type === 'pspdfkit/shape/polygon';
+            const style = strokeStyleOf(a);
+            if (!closed) {
+                delete style.fill;
+                const endCap = capOf(a.lineCaps?.end);
+                const startCap = capOf(a.lineCaps?.start);
+                if (endCap)
+                    style.cap = endCap;
+                if (startCap)
+                    style.startCap = startCap;
+            }
+            return {
+                shapes: [
+                    shape(id, 'polygon', pts, style, createdAt, {
+                        geometry: { points: pts, closed },
+                    }),
+                ],
+            };
+        }
+        case 'pspdfkit/text': {
+            const bbox = toBbox(a.bbox);
+            const text = textOf(a.text);
+            if (!bbox)
+                return 'Text has no bounding box';
+            if (!text.trim())
+                return 'Text annotation is empty';
+            const [left, top, w, h] = bbox;
+            const fontSize = isNum(a.fontSize) && a.fontSize > 0 ? a.fontSize : 12;
+            const shapes = [];
+            if (a.backgroundColor) {
+                shapes.push(shape(`${id}-bg`, 'rect', [
+                    { x: left, y: top },
+                    { x: left + w, y: top + h },
+                ], fillOnlyStyle(withAlpha(a.backgroundColor, opacity)), createdAt));
+            }
+            // Nutrient `rotation` is counter-clockwise in quarter turns and `bbox`
+            // is the ROTATED box. The text shape rotates clockwise about its
+            // origin, so the origin is the unrotated box's top-left corner as it
+            // lands after the turn (see textRotationMatrix in export/pdf/marks.ts).
+            const ccw = isNum(a.rotation)
+                ? (((Math.round(a.rotation / 90) * 90) % 360) + 360) % 360
+                : 0;
+            const origin = ccw === 90
+                ? { x: left, y: top + h }
+                : ccw === 180
+                    ? { x: left + w, y: top + h }
+                    : ccw === 270
+                        ? { x: left + w, y: top }
+                        : { x: left, y: top };
+            // Unrotated, the text runs along the box's long side at 90/270.
+            const runLength = ccw === 90 || ccw === 270 ? h : w;
+            shapes.push(shape(id, 'text', [origin], {
+                stroke: withAlpha(a.fontColor || '#000000', opacity),
+                fontSize,
+            }, createdAt, {
+                text,
+                ...(ccw
+                    ? { geometry: { points: [origin], rotation: 360 - ccw } }
+                    : {}),
+            }));
+            const wraps = text
+                .split('\n')
+                .some((line) => estimatedTextWidth(line, fontSize) > runLength * 1.05);
+            const warning = ccw
+                ? 'Rotated text is exported rotated but shows upright in the Skia editor'
+                : wraps
+                    ? 'Text relied on word wrap; lines only break at explicit newlines'
+                    : undefined;
+            return { shapes, warning };
+        }
+        case 'pspdfkit/markup/highlight':
+        case 'pspdfkit/markup/underline':
+        case 'pspdfkit/markup/strikeout':
+        case 'pspdfkit/markup/squiggly': {
+            const rects = Array.isArray(a.rects)
+                ? a.rects.map(toBbox).filter((r) => r !== null)
+                : [];
+            if (rects.length === 0)
+                return 'Markup has no rects';
+            const color = a.color || a.strokeColor || '#FFFF00';
+            const shapes = rects.map(([left, top, w, h], i) => {
+                const sid = `${id}-${i}`;
+                if (a.type === 'pspdfkit/markup/highlight') {
+                    return shape(sid, 'rect', [
+                        { x: left, y: top },
+                        { x: left + w, y: top + h },
+                    ], fillOnlyStyle(withAlpha(color, opacity * MULTIPLY_ALPHA)), createdAt);
+                }
+                const y = a.type === 'pspdfkit/markup/strikeout' ? top + h / 2 : top + h * 0.92;
+                return shape(sid, 'line', [
+                    { x: left, y },
+                    { x: left + w, y },
+                ], {
+                    stroke: withAlpha(color, opacity),
+                    strokeWidth: Math.max(0.75, h * 0.07),
+                    cap: 'butt',
+                }, createdAt);
+            });
+            return {
+                shapes,
+                warning: a.type === 'pspdfkit/markup/squiggly'
+                    ? 'Squiggly underline is drawn straight'
+                    : undefined,
+            };
+        }
+        case 'pspdfkit/stamp': {
+            const bbox = toBbox(a.bbox);
+            if (!bbox)
+                return 'Stamp has no bounding box';
+            const [left, top, w, h] = bbox;
+            const label = [a.title || a.stampType, a.subtitle]
+                .filter((s) => typeof s === 'string' && s.length > 0)
+                .join('\n');
+            const color = withAlpha(a.color || '#2492FB', opacity);
+            const fontSize = Math.max(6, Math.min(h / (label.includes('\n') ? 2.6 : 1.6), 36));
+            return {
+                shapes: [
+                    shape(`${id}-border`, 'rect', insetRect(bbox, 1), { stroke: color, strokeWidth: 2 }, createdAt),
+                    ...(label
+                        ? [
+                            shape(id, 'text', [
+                                {
+                                    x: left + 4,
+                                    y: top + Math.max(0, (h - fontSize * 1.2) / 2),
+                                },
+                            ], { stroke: color, fontSize }, createdAt, { text: label }),
+                        ]
+                        : []),
+                ],
+                warning: `Stamp drawn as a labelled box (${w.toFixed(0)}×${h.toFixed(0)} pt)`,
+            };
+        }
+        default:
+            return `Unsupported annotation type`;
+    }
+};
+/* ------------------------------------------------------------------ *
+ * Entry point
+ * ------------------------------------------------------------------ */
+const SKIP_REASONS = {
+    'pspdfkit/image': 'Image annotations are not supported yet',
+    'pspdfkit/note': 'Sticky notes have no canvas equivalent',
+    'pspdfkit/comment-marker': 'Comments have no canvas equivalent',
+    'pspdfkit/link': 'Links have no canvas equivalent',
+    'pspdfkit/widget': 'Form fields live in the PDF itself and are kept as-is',
+    'pspdfkit/markup/redaction': 'Unapplied redactions are not converted',
+    'pspdfkit/media': 'Media annotations are not supported',
+    'pspdfkit/file': 'File attachments are not supported',
+    'pspdfkit/sound': 'Sound annotations are not supported',
+};
+export const instantJsonToPdfCanvas = (input) => {
+    const now = input.now ?? Date.now();
+    const raw = input.instantJson
+        ?.annotations;
+    const annotations = Array.isArray(raw)
+        ? raw.filter((a) => a && typeof a === 'object')
+        : [];
+    const result = {
+        pageStates: {},
+        tileDocSize: NUTRIENT_TILE_DOC_SIZE,
+        converted: {},
+        droppedTileImages: 0,
+        skipped: [],
+        warnings: [],
+    };
+    const usedIds = new Set();
+    const stateFor = (pageIndex) => {
+        let state = result.pageStates[pageIndex];
+        if (!state) {
+            state = { ...emptyPdfCanvasPageState(pageIndex), updatedAt: now };
+            result.pageStates[pageIndex] = state;
+        }
+        return state;
+    };
+    const count = (type) => {
+        result.converted[type] = (result.converted[type] ?? 0) + 1;
+    };
+    // Mobile keys tiles by `customData.id` and keeps one image per id, drawn at
+    // the LAST anchor carrying it (reconcileTile sweeps the others' images). A
+    // copied or rebound anchor can leave duplicates; draw what the app draws.
+    const lastAnchorOfTile = new Map();
+    annotations.forEach((a, index) => {
+        const cd = tileCustomDataOf(a);
+        if (cd &&
+            typeof cd.id === 'string' &&
+            cd.id &&
+            a.type !== 'pspdfkit/image') {
+            lastAnchorOfTile.set(cd.id, index);
+        }
+    });
+    annotations.forEach((a, index) => {
+        const type = typeof a.type === 'string' ? a.type : 'unknown';
+        const sourceId = (typeof a.id === 'string' && a.id) ||
+            (typeof a.name === 'string' && a.name) ||
+            `#${index}`;
+        const note = (reason, extra) => ({ id: sourceId, type, pageIndex: a.pageIndex, reason, ...extra });
+        const skip = (reason, extra) => result.skipped.push(note(reason, extra));
+        const pageIndex = a.pageIndex;
+        if (!isNum(pageIndex) || !Number.isInteger(pageIndex)) {
+            skip('Annotation has no page index');
+            return;
+        }
+        if (!input.pages[pageIndex]) {
+            skip(`Page ${pageIndex + 1} does not exist in the PDF`);
+            return;
+        }
+        // Unique element id per page state (web payloads can repeat a tile's
+        // customData id on its anchor and image).
+        let elementId = `nutrient-${sourceId.replace(/^#/, 'i')}`;
+        for (let n = 2; usedIds.has(elementId); n++) {
+            elementId = `nutrient-${sourceId.replace(/^#/, 'i')}-${n}`;
+        }
+        const tile = tileCustomDataOf(a);
+        if (tile) {
+            if (type === 'pspdfkit/image') {
+                result.droppedTileImages++;
+                return;
+            }
+            if (typeof tile.id === 'string' &&
+                tile.id &&
+                lastAnchorOfTile.get(tile.id) !== index) {
+                skip('Duplicate tile anchor; the app draws only one tile per tile id');
+                return;
+            }
+            const converted = convertTileAnchor(a, tile, elementId);
+            if (!converted) {
+                skip('Measurement tile anchor has no geometry');
+                return;
+            }
+            usedIds.add(elementId);
+            const state = stateFor(pageIndex);
+            state.placedMeasurements.push(converted.placed);
+            if (converted.leader)
+                state.shapes.push(converted.leader);
+            // Polygon / ellipse anchors: keep the drawn outline.
+            if (!isHidden(a) &&
+                tile.measurementMode !== 'none' &&
+                (type === 'pspdfkit/shape/polygon' || type === 'pspdfkit/shape/ellipse')) {
+                const outline = convertDrawn(a, `${elementId}-outline`);
+                if (typeof outline !== 'string') {
+                    state.shapes.push(...(outline.shapes ?? []));
+                }
+            }
+            count(tile.isGroupHeader ? 'tile/header' : 'tile/measurement');
+            return;
+        }
+        if (isHidden(a)) {
+            skip('Hidden annotation');
+            return;
+        }
+        const known = SKIP_REASONS[type];
+        if (known) {
+            const text = type === 'pspdfkit/note' || type === 'pspdfkit/comment-marker'
+                ? textOf(a.text) || undefined
+                : undefined;
+            skip(type === 'pspdfkit/image' && a.isSignature
+                ? 'Image signatures are not supported yet'
+                : known, text ? { text } : undefined);
+            return;
+        }
+        const drawn = convertDrawn(a, elementId);
+        if (typeof drawn === 'string') {
+            skip(drawn);
+            return;
+        }
+        usedIds.add(elementId);
+        const state = stateFor(pageIndex);
+        if (drawn.strokes)
+            state.strokes.push(...drawn.strokes);
+        if (drawn.shapes)
+            state.shapes.push(...drawn.shapes);
+        if (drawn.warning)
+            result.warnings.push(note(drawn.warning));
+        count(type);
+    });
+    return result;
+};

package/dist/export/pdf/index.d.ts

@@ -1,4 +1,4 @@
-export { renderCanvasToPdf, renderPdfCanvasToPdf, } from './renderCanvasToPdf.js';
+export { renderCanvasToPdf, renderPdfCanvasToPdf, describePdfPages, } from './renderCanvasToPdf.js';
 export { stripPdfEncryption, type StripPdfEncryptionOptions, type StripPdfEncryptionResult, } from './decrypt.js';
 export { docToPageMatrix, pageRectsOf, normalizeRotation, rotatedBoxSize, applyMatrix, type AffineMatrix, type PageRotation, type PdfBox, } from './pageMapping.js';
 export { resolveTileContent, measurementTileFillFor, FORMULA_COLUMN_TILE_FILL, PLANE_COMPUTED_TILE_FILL, type TileFileInfo, type TileResolutionContext, } from './tileContent.js';

package/dist/export/pdf/index.js

@@ -1,4 +1,4 @@
-export { renderCanvasToPdf, renderPdfCanvasToPdf, } from './renderCanvasToPdf.js';
+export { renderCanvasToPdf, renderPdfCanvasToPdf, describePdfPages, } from './renderCanvasToPdf.js';
 export { stripPdfEncryption, } from './decrypt.js';
 export { docToPageMatrix, pageRectsOf, normalizeRotation, rotatedBoxSize, applyMatrix, } from './pageMapping.js';
 export { resolveTileContent, measurementTileFillFor, FORMULA_COLUMN_TILE_FILL, PLANE_COMPUTED_TILE_FILL, } from './tileContent.js';

package/dist/export/pdf/marks.js

@@ -9,8 +9,8 @@ import { DEFAULT_TEXT_FONT_SIZE, TEXT_BASELINE_FACTOR, TEXT_LINE_HEIGHT_FACTOR,
 import { normalizeRect, placementOf, } from '../../annotation/canvas/measurementGeometry.js';
 import { MEASUREMENT_LINE_COLOR, MEASUREMENT_LINE_WIDTH, MEASUREMENT_RECT_WIDTH, } from '../../annotation/canvas/measurementLineStyle.js';
 import { parseHexColor } from './color.js';
-import { circlePathOps, fillStateOps, flatPolylinePathOps, polylinePathOps, rectPathOps, strokeStateOps, } from './emit.js';
-import { boundsToRect } from './pageMapping.js';
+import { circlePathOps, fillStateOps, flatPolylinePathOps, polylinePathOps, rectPathOps, strokeStateOps, withMatrix, } from './emit.js';
+import { boundsToRect, } from './pageMapping.js';
 // Readable glyph colour over a highlight band — mirror of
 // ShapeElement.highlightTextColor (which lives behind a Skia import).
 const highlightTextColor = (hex) => {
@@ -118,10 +118,51 @@ export const strokeOps = (s, ctx) => {
 /* ------------------------------------------------------------------ *
  * Shapes
  * ------------------------------------------------------------------ */
+/**
+ * Doc-space rotation of a text shape: `geometry.rotation` degrees CLOCKWISE
+ * (y-down) about its origin, `points[0]`. Only set by converted Nutrient text
+ * so far — the Skia canvas still draws every text shape upright.
+ */
+const textRotationMatrix = (shape) => {
+    const deg = shape.geometry.rotation;
+    const origin = shape.geometry.points[0];
+    if (!deg || !origin || !Number.isFinite(deg) || deg % 360 === 0)
+        return null;
+    const t = (deg * Math.PI) / 180;
+    const c = Math.cos(t);
+    const s = Math.sin(t);
+    return [
+        c,
+        s,
+        -s,
+        c,
+        origin.x - c * origin.x + s * origin.y,
+        origin.y - s * origin.x - c * origin.y,
+    ];
+};
 export const shapeBounds = (shape) => {
     if (shape.kind === 'text') {
         const b = textShapeBounds(shape);
-        return b ? boundsToRect(b, 4) : null;
+        if (!b)
+            return null;
+        const m = textRotationMatrix(shape);
+        if (!m)
+            return boundsToRect(b, 4);
+        const corners = [
+            [b.minX, b.minY],
+            [b.maxX, b.minY],
+            [b.minX, b.maxY],
+            [b.maxX, b.maxY],
+        ].map(([x, y]) => ({
+            x: m[0] * x + m[2] * y + m[4],
+            y: m[1] * x + m[3] * y + m[5],
+        }));
+        return boundsToRect({
+            minX: Math.min(...corners.map((p) => p.x)),
+            minY: Math.min(...corners.map((p) => p.y)),
+            maxX: Math.max(...corners.map((p) => p.x)),
+            maxY: Math.max(...corners.map((p) => p.y)),
+        }, 4);
     }
     const b = visualShapeBounds(shape);
     if (!b)
@@ -169,7 +210,8 @@ const textShapeOps = (shape, ctx) => {
             reason: 'Some characters have no glyph in the export fonts and were dropped',
         });
     }
-    return ops;
+    const rotation = textRotationMatrix(shape);
+    return rotation ? withMatrix(rotation, ops) : ops;
 };
 export const shapeOps = (shape, ctx) => {
     const { kind, geometry, style } = shape;

package/dist/export/pdf/renderCanvasToPdf.d.ts

@@ -1,5 +1,14 @@
+import type { PdfCanvasPage } from '../../types/pdfCanvas.js';
 import { type RenderCanvasToPdfInput, type RenderCanvasToPdfResult, type RenderPdfCanvasToPdfInput } from './types.js';
 export declare const renderCanvasToPdf: (input: RenderCanvasToPdfInput) => Promise<RenderCanvasToPdfResult>;
+/**
+ * The `PdfCanvasDocument.pages` record for a PDF: each page's extents after
+ * its own /Rotate, measured exactly as renderPdfCanvasToPdf validates them,
+ * at user rotation 0. For building a PdfCanvas record server-side (e.g. when
+ * converting a legacy Nutrient file) without rasterizing. The PDF must be
+ * unencrypted (stripPdfEncryption).
+ */
+export declare const describePdfPages: (sourcePdf: Uint8Array) => Promise<PdfCanvasPage[]>;
 /**
  * Export a PdfCanvas file. Each page's state is drawn in that page's own doc
  * space (the DISPLAYED page: rotated extents, origin top-left). A user

package/dist/export/pdf/renderCanvasToPdf.js

@@ -334,6 +334,20 @@ export const renderCanvasToPdf = async (input) => {
     const pdf = await doc.save({ useObjectStreams: false });
     return { pdf, pageCount: pages.length, annotationCount, skipped };
 };
+/**
+ * The `PdfCanvasDocument.pages` record for a PDF: each page's extents after
+ * its own /Rotate, measured exactly as renderPdfCanvasToPdf validates them,
+ * at user rotation 0. For building a PdfCanvas record server-side (e.g. when
+ * converting a legacy Nutrient file) without rasterizing. The PDF must be
+ * unencrypted (stripPdfEncryption).
+ */
+export const describePdfPages = async (sourcePdf) => {
+    const doc = await loadSource(sourcePdf);
+    return doc.getPages().map((page) => {
+        const size = rotatedBoxSize(pageBox(page), normalizeRotation(page.getRotation().angle));
+        return { width: size.width, height: size.height, rotation: 0 };
+    });
+};
 /**
  * Export a PdfCanvas file. Each page's state is drawn in that page's own doc
  * space (the DISPLAYED page: rotated extents, origin top-left). A user

package/dist/server.d.ts

@@ -19,5 +19,6 @@ export { numberToLetterIndex, formGroupInputLabel, listGroupMeasurementLabel, }
 export { toSelectedValues, formatSelectedValues, toStoredValue, } from './utils/selectValues.js';
 export * from './calculator/index.js';
 export * from './export/pdf/index.js';
+export { instantJsonToPdfCanvas, NUTRIENT_TILE_DOC_SIZE, type InstantJsonConversion, type InstantJsonToPdfCanvasInput, type NutrientSkippedAnnotation, } from './export/nutrient/instantJsonToPdfCanvas.js';
 export { applyGroupFormulaUm, groupFormulaExpression, unitNumberToMicrometers, type GroupFormulaFrame, } from './formulas/groupFormula.js';
 export { MEASUREMENT_LINE_COLOR, MEASUREMENT_LINE_WIDTH, MEASUREMENT_RECT_WIDTH, } from './annotation/canvas/measurementLineStyle.js';

package/dist/server.js

@@ -26,6 +26,7 @@ export * from './calculator/index.js';
 // Canvas → annotated PDF export (Cloud Function renderer). Pure pdf-lib; no
 // React or Skia anywhere in its import graph.
 export * from './export/pdf/index.js';
+export { instantJsonToPdfCanvas, NUTRIENT_TILE_DOC_SIZE, } from './export/nutrient/instantJsonToPdfCanvas.js';
 // groupFormula's own micrometersToUnitNumber (integer constants, NaN on
 // unknown units) stays module-local: the canonical export of that name is the
 // mathjs-exact one from evaluateFormula.js above, and no consumer imported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.26.2",
+  "version": "1.28.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",