@reekon-tools/boldr-utils 1.26.2 → 1.27.0

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.27.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",