@reekon-tools/boldr-utils 1.23.0 → 1.25.0

package/dist/export/pdf/renderCanvasToPdf.js

@@ -2,8 +2,17 @@
 // canvas's layers, marks and tiles to each page's content stream under one
 // matrix per page. The original page content and its own /Annots are never
 // touched, so the source stays vector, searchable and selectable.
-import { EncryptedPDFError, PDFDocument, } from 'pdf-lib';
+//
+// Two entry points share one page renderer:
+//  - renderCanvasToPdf: a Canvas file carrying a `viewport.pdfDocument`
+//    filmstrip — every element lives in one stacked doc space and is drawn on
+//    each page its bounds intersect.
+//  - renderPdfCanvasToPdf: a PdfCanvas file — one page state per page, each in
+//    that page's own doc space, with the user's per-page rotation folded into
+//    /Rotate and the page matrix.
+import { EncryptedPDFError, PDFDocument, degrees, } from 'pdf-lib';
 import { backgroundLayersOf } from '../../annotation/canvas/backgroundLayers.js';
+import { effectivePageRotation, pdfPageDisplaySize, } from '../../annotation/canvas/pdfCanvasPages.js';
 import { fitRectToScreen } from '../../annotation/canvas/viewport.js';
 import { STAMP_TILE_SIZE } from '../../annotation/canvas/stampLayout.js';
 import { clipRectOps, withMatrix } from './emit.js';
@@ -52,153 +61,152 @@ const loadSource = async (bytes) => {
         throw new PdfExportError('corrupt', `The source PDF could not be parsed: ${e instanceof Error ? e.message : String(e)}`);
     }
 };
-export const renderCanvasToPdf = async (input) => {
-    const { canvas } = input;
-    const pdfDoc = canvas.viewport.pdfDocument;
-    if (!pdfDoc) {
-        throw new PdfExportError('no-pdf-document', 'This canvas has no PDF document to export');
+const assertPageCount = (pages, recorded, stored) => {
+    if (pages.length !== recorded || stored !== pages.length) {
+        throw new PdfExportError('page-count-mismatch', `The canvas records ${stored} pages but the PDF has ${pages.length}`);
     }
-    const doc = await loadSource(input.sourcePdf);
-    const pages = doc.getPages();
-    if (pages.length !== pdfDoc.pageCount ||
-        pdfDoc.pages.length !== pages.length) {
-        throw new PdfExportError('page-count-mismatch', `The canvas records ${pdfDoc.pages.length} pages but the PDF has ${pages.length}`);
+};
+const assertPageSize = (index, actual, stored) => {
+    if (Math.abs(actual.width - stored.width) > PAGE_SIZE_TOLERANCE_PT ||
+        Math.abs(actual.height - stored.height) > PAGE_SIZE_TOLERANCE_PT) {
+        throw new PdfExportError('page-geometry-mismatch', `Page ${index + 1} is ${actual.width}×${actual.height} pt in the PDF but ${stored.width}×${stored.height} pt on the canvas`);
     }
-    const pageRects = pageRectsOf(pdfDoc);
-    const skipped = [];
-    // Per-page geometry, validated against what the canvas was laid out from.
-    const geometry = pages.map((page, i) => {
-        const box = pageBox(page);
-        const rotation = normalizeRotation(page.getRotation().angle);
-        const size = rotatedBoxSize(box, rotation);
-        const stored = pdfDoc.pages[i];
-        if (Math.abs(size.width - stored.width) > PAGE_SIZE_TOLERANCE_PT ||
-            Math.abs(size.height - stored.height) > PAGE_SIZE_TOLERANCE_PT) {
-            throw new PdfExportError('page-geometry-mismatch', `Page ${i + 1} is ${size.width}×${size.height} pt in the PDF but ${stored.width}×${stored.height} pt on the canvas`);
-        }
-        return { page, box, rotation, rect: pageRects[i] };
-    });
-    const fonts = await PdfFonts.create(doc, input.primaryFont);
+};
+/** Content string for a tile's annotation (what Acrobat's comment shows). */
+const tileContents = (content) => {
+    switch (content.kind) {
+        case 'measurement':
+            return [
+                content.label,
+                `${content.negative ? '-' : ''}${content.value} ${content.unit}`.trim(),
+            ]
+                .filter(Boolean)
+                .join(': ');
+        case 'planeDimension':
+            return `${content.value} ${content.unit}`.trim();
+        case 'header':
+            return (content.descriptor.name ??
+                content.descriptor.badges.map((b) => b.text).join(' '));
+        case 'object':
+            return content.name;
+        case 'literal':
+            return content.value || undefined;
+        case 'instructions':
+            return content.text || undefined;
+        default:
+            return undefined;
+    }
+};
+const renderJobs = async (doc, jobs, options, skipped) => {
+    const fonts = await PdfFonts.create(doc, options.primaryFont);
     // Background layers: embed once, draw on every page they overlap.
-    const layers = backgroundLayersOf(canvas.viewport);
     const layerImages = new Map();
-    for (const layer of layers) {
-        if (layer.format === 'svg') {
-            skipped.push({
-                id: layer.id,
-                kind: 'layer',
-                reason: 'SVG background layers are not exported yet',
-            });
-            continue;
-        }
-        const bytes = input.layerImages[layer.id];
-        if (!bytes) {
-            skipped.push({
-                id: layer.id,
-                kind: 'layer',
-                reason: 'Layer image bytes were not provided',
-            });
-            continue;
-        }
-        try {
-            layerImages.set(layer.id, await embedImage(doc, bytes));
-        }
-        catch (e) {
-            skipped.push({
-                id: layer.id,
-                kind: 'layer',
-                reason: `Layer image could not be embedded: ${e instanceof Error ? e.message : String(e)}`,
-            });
-        }
-    }
-    // Tiles: resolve content once; embed object thumbnails once.
-    const tiles = canvas.placedMeasurements.map((placed) => {
-        const content = input.resolveTile(placed) ?? {
-            kind: 'empty',
-        };
-        return { placed, content };
-    });
-    const thumbnails = new Map();
-    for (const { placed, content } of tiles) {
-        if (content.kind === 'object' && content.thumbnail) {
+    const seenLayers = new Set();
+    for (const job of jobs) {
+        for (const layer of job.layers) {
+            if (seenLayers.has(layer.id))
+                continue;
+            seenLayers.add(layer.id);
+            if (layer.format === 'svg') {
+                skipped.push({
+                    id: layer.id,
+                    kind: 'layer',
+                    reason: 'SVG background layers are not exported yet',
+                });
+                continue;
+            }
+            const bytes = options.layerImages[layer.id];
+            if (!bytes) {
+                skipped.push({
+                    id: layer.id,
+                    kind: 'layer',
+                    reason: 'Layer image bytes were not provided',
+                });
+                continue;
+            }
             try {
-                thumbnails.set(placed.id, await embedImage(doc, content.thumbnail));
+                layerImages.set(layer.id, await embedImage(doc, bytes));
             }
             catch (e) {
                 skipped.push({
-                    id: placed.id,
-                    kind: 'tile',
-                    reason: `Object thumbnail could not be embedded: ${e instanceof Error ? e.message : String(e)}`,
+                    id: layer.id,
+                    kind: 'layer',
+                    reason: `Layer image could not be embedded: ${e instanceof Error ? e.message : String(e)}`,
                 });
             }
         }
     }
-    const firstRect = pageRects[0];
+    // Tiles: resolve content once per placed ref; embed object thumbnails once.
+    const tileContent = new Map();
+    const thumbnails = new Map();
+    for (const job of jobs) {
+        for (const placed of job.placed) {
+            if (tileContent.has(placed.id))
+                continue;
+            const content = options.resolveTile(placed) ?? {
+                kind: 'empty',
+            };
+            tileContent.set(placed.id, content);
+            if (content.kind === 'object' && content.thumbnail) {
+                try {
+                    thumbnails.set(placed.id, await embedImage(doc, content.thumbnail));
+                }
+                catch (e) {
+                    skipped.push({
+                        id: placed.id,
+                        kind: 'tile',
+                        reason: `Object thumbnail could not be embedded: ${e instanceof Error ? e.message : String(e)}`,
+                    });
+                }
+            }
+        }
+    }
+    // Calibration fallback from the first page's rect (the tile-scale reference
+    // on screen is the first page too).
+    const firstRect = jobs[0]?.rect ?? { x: 0, y: 0, width: 612, height: 792 };
     const fallbackDocEdge = STAMP_TILE_SIZE /
         Math.max(fitRectToScreen(firstRect, FALLBACK_VIEW.width, FALLBACK_VIEW.height)
             .zoom, 1e-6);
-    const hiddenLayerIds = new Set(canvas.layers.filter((l) => l.visible === false).map((l) => l.id));
-    const visible = (layerId) => !hiddenLayerIds.has(layerId);
-    const mode = input.mode ?? 'annotations';
     let annotationCount = 0;
-    /** Content string for a tile's annotation (what Acrobat's comment shows). */
-    const tileContents = (content) => {
-        switch (content.kind) {
-            case 'measurement':
-                return [
-                    content.label,
-                    `${content.negative ? '-' : ''}${content.value} ${content.unit}`.trim(),
-                ]
-                    .filter(Boolean)
-                    .join(': ');
-            case 'planeDimension':
-                return `${content.value} ${content.unit}`.trim();
-            case 'header':
-                return (content.descriptor.name ??
-                    content.descriptor.badges.map((b) => b.text).join(' '));
-            case 'object':
-                return content.name;
-            case 'literal':
-                return content.value || undefined;
-            case 'instructions':
-                return content.text || undefined;
-            default:
-                return undefined;
-        }
-    };
-    for (const { page, box, rotation, rect } of geometry) {
+    for (const job of jobs) {
+        const { page, box, rotation, rect } = job;
         const matrix = docToPageMatrix(rect, box, rotation);
         const onPage = (b) => b !== null && rectsIntersect(b, rect);
-        if (mode === 'flatten') {
+        const hiddenLayerIds = new Set(job.layerDefs.filter((l) => l.visible === false).map((l) => l.id));
+        const visible = (layerId) => !hiddenLayerIds.has(layerId);
+        const footprintFor = (placed, content) => tileFootprint(placed, { tileDocSize: job.tileDocSize }, options.calibration, fallbackDocEdge, designBoxFor(placed, content));
+        const contentOf = (placed) => tileContent.get(placed.id) ?? { kind: 'empty' };
+        if (options.mode === 'flatten') {
             // Everything into the page's content stream, under one matrix + clip.
             const scope = new PageScope(page, doc.context);
             const ctx = { scope, fonts, skipped };
             const ops = [];
-            for (const layer of layers) {
+            for (const layer of job.layers) {
                 const img = layerImages.get(layer.id);
                 if (!img || !onPage(layerVisibleRect(layer)))
                     continue;
                 ops.push(...layerOps(layer, scope.imageKey(img)));
             }
-            for (const s of canvas.strokes) {
+            for (const s of job.strokes) {
                 if (!visible(s.layerId) || !onPage(strokeBounds(s)))
                     continue;
                 ops.push(...strokeOps(s, ctx));
             }
-            for (const sh of canvas.shapes) {
+            for (const sh of job.shapes) {
                 if (!visible(sh.layerId) || !onPage(shapeBounds(sh)))
                     continue;
                 ops.push(...shapeOps(sh, ctx));
             }
-            for (const { placed } of tiles) {
+            for (const placed of job.placed) {
                 if (!visible(placed.layerId) || !onPage(measurementMarkBounds(placed)))
                     continue;
                 ops.push(...measurementMarkOps(placed, ctx));
             }
-            for (const { placed, content } of tiles) {
+            for (const placed of job.placed) {
                 if (!visible(placed.layerId))
                     continue;
-                const footprint = tileFootprint(placed, canvas, input.calibration, fallbackDocEdge, designBoxFor(placed, content));
+                const content = contentOf(placed);
+                const footprint = footprintFor(placed, content);
                 if (!onPage(footprint))
                     continue;
                 ops.push(...tileOps({ scope, fonts, thumbnail: thumbnails.get(placed.id) }, content, footprint));
@@ -229,7 +237,7 @@ export const renderCanvasToPdf = async (input) => {
                 annotationCount++;
             return ref;
         };
-        for (const layer of layers) {
+        for (const layer of job.layers) {
             const img = layerImages.get(layer.id);
             const bounds = layerVisibleRect(layer);
             if (!img || !onPage(bounds))
@@ -245,13 +253,13 @@ export const renderCanvasToPdf = async (input) => {
                 },
             }, scope);
         }
-        for (const s of canvas.strokes) {
+        for (const s of job.strokes) {
             if (!visible(s.layerId) || !onPage(strokeBounds(s)))
                 continue;
             const scope = new FormScope(doc.context);
             add(strokeMark(s, { scope, fonts, skipped }), scope);
         }
-        for (const sh of canvas.shapes) {
+        for (const sh of job.shapes) {
             if (!visible(sh.layerId) || !onPage(shapeBounds(sh)))
                 continue;
             const scope = new FormScope(doc.context);
@@ -260,7 +268,7 @@ export const renderCanvasToPdf = async (input) => {
         // A measurement's line/rect and its tile are grouped (Acrobat honours
         // /IRT + /RT /Group; other viewers treat them independently).
         const markRefs = new Map();
-        for (const { placed } of tiles) {
+        for (const placed of job.placed) {
             if (!visible(placed.layerId) || !onPage(measurementMarkBounds(placed)))
                 continue;
             const scope = new FormScope(doc.context);
@@ -268,10 +276,11 @@ export const renderCanvasToPdf = async (input) => {
             if (ref)
                 markRefs.set(placed.id, ref);
         }
-        for (const { placed, content } of tiles) {
+        for (const placed of job.placed) {
             if (!visible(placed.layerId))
                 continue;
-            const footprint = tileFootprint(placed, canvas, input.calibration, fallbackDocEdge, designBoxFor(placed, content));
+            const content = contentOf(placed);
+            const footprint = footprintFor(placed, content);
             if (!onPage(footprint))
                 continue;
             const scope = new FormScope(doc.context);
@@ -283,6 +292,93 @@ export const renderCanvasToPdf = async (input) => {
             }, scope, markRefs.get(placed.id));
         }
     }
+    return annotationCount;
+};
+export const renderCanvasToPdf = async (input) => {
+    const { canvas } = input;
+    const pdfDoc = canvas.viewport.pdfDocument;
+    if (!pdfDoc) {
+        throw new PdfExportError('no-pdf-document', 'This canvas has no PDF document to export');
+    }
+    const doc = await loadSource(input.sourcePdf);
+    const pages = doc.getPages();
+    assertPageCount(pages, pdfDoc.pageCount, pdfDoc.pages.length);
+    const pageRects = pageRectsOf(pdfDoc);
+    const layers = backgroundLayersOf(canvas.viewport);
+    // Per-page geometry, validated against what the canvas was laid out from.
+    const jobs = pages.map((page, i) => {
+        const box = pageBox(page);
+        const rotation = normalizeRotation(page.getRotation().angle);
+        assertPageSize(i, rotatedBoxSize(box, rotation), pdfDoc.pages[i]);
+        return {
+            page,
+            box,
+            rotation,
+            rect: pageRects[i],
+            layers,
+            layerDefs: canvas.layers,
+            strokes: canvas.strokes,
+            shapes: canvas.shapes,
+            placed: canvas.placedMeasurements,
+            tileDocSize: canvas.tileDocSize,
+        };
+    });
+    const skipped = [];
+    const annotationCount = await renderJobs(doc, jobs, {
+        resolveTile: input.resolveTile,
+        layerImages: input.layerImages,
+        calibration: input.calibration,
+        primaryFont: input.primaryFont,
+        mode: input.mode ?? 'annotations',
+    }, skipped);
+    const pdf = await doc.save({ useObjectStreams: false });
+    return { pdf, pageCount: pages.length, annotationCount, skipped };
+};
+/**
+ * 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
+ * rotation is written into the page's /Rotate — so the recipient sees the
+ * page as the user did — and the page matrix undoes the combined rotation.
+ * Pages without a state are still rotated.
+ */
+export const renderPdfCanvasToPdf = async (input) => {
+    const { pdfCanvas } = input;
+    const doc = await loadSource(input.sourcePdf);
+    const pages = doc.getPages();
+    assertPageCount(pages, pdfCanvas.document.pageCount, pdfCanvas.document.pages.length);
+    const jobs = [];
+    pages.forEach((page, i) => {
+        const stored = pdfCanvas.document.pages[i];
+        const box = pageBox(page);
+        const intrinsic = normalizeRotation(page.getRotation().angle);
+        // The stored size is the page after its own /Rotate, before the user's.
+        assertPageSize(i, rotatedBoxSize(box, intrinsic), stored);
+        const effective = effectivePageRotation(intrinsic, stored.rotation);
+        if (effective !== intrinsic)
+            page.setRotation(degrees(effective));
+        const display = pdfPageDisplaySize(stored);
+        const state = input.pageStates[i] ?? undefined;
+        jobs.push({
+            page,
+            box,
+            rotation: effective,
+            rect: { x: 0, y: 0, width: display.width, height: display.height },
+            layers: [],
+            layerDefs: state?.layers ?? [],
+            strokes: state?.strokes ?? [],
+            shapes: state?.shapes ?? [],
+            placed: state?.placedMeasurements ?? [],
+            tileDocSize: pdfCanvas.tileDocSize,
+        });
+    });
+    const skipped = [];
+    const annotationCount = await renderJobs(doc, jobs, {
+        resolveTile: input.resolveTile,
+        layerImages: {},
+        calibration: input.calibration,
+        primaryFont: input.primaryFont,
+        mode: input.mode ?? 'annotations',
+    }, skipped);
     const pdf = await doc.save({ useObjectStreams: false });
     return { pdf, pageCount: pages.length, annotationCount, skipped };
 };

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

@@ -1,5 +1,6 @@
 import type { GroupHeaderDescriptor } from '../../annotation/canvas/groupHeaderLayout.js';
 import type { AnnotationCanvasState, PlacedMeasurementRef } from '../../types/annotation.js';
+import type { PdfCanvasData, PdfCanvasPageState } from '../../types/pdfCanvas.js';
 export interface EmbeddedImage {
     bytes: Uint8Array;
     mime: 'image/png' | 'image/jpeg';
@@ -97,6 +98,18 @@ export interface RenderCanvasToPdfInput {
      */
     mode?: 'annotations' | 'flatten';
 }
+export interface RenderPdfCanvasToPdfInput {
+    /** The PDF the file was uploaded from (`pdfCanvas.document.storagePath`). */
+    sourcePdf: Uint8Array;
+    /** The file-level record (`fileData.pdfCanvas`). */
+    pdfCanvas: PdfCanvasData;
+    /** Page docs by page index; a page without one is exported un-annotated. */
+    pageStates: Partial<Record<number, PdfCanvasPageState>>;
+    resolveTile: (ref: PlacedMeasurementRef) => ResolvedTileContent | undefined;
+    calibration?: PdfExportCalibration;
+    primaryFont: Uint8Array;
+    mode?: 'annotations' | 'flatten';
+}
 export interface RenderCanvasToPdfResult {
     pdf: Uint8Array;
     pageCount: number;

package/dist/exports.d.ts

@@ -6,6 +6,7 @@ export { useParseMeasurement } from './utils/useParseMeasurement.js';
 export * from './types/firestore.js';
 export * from './types/layout.js';
 export * from './types/annotation.js';
+export * from './types/pdfCanvas.js';
 export { getToleranceColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, type ToleranceThreshold, type ToleranceConfig, } from './utils/tolerance.js';
 export { GeneralColors, SecondaryColors, FormColors, TileColors, FormulaColors, YellowColors, RedColors, GreenColors, tailwindColors, } from './theme/colors.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
@@ -25,6 +26,7 @@ export { useAnnotationDoc, type UseAnnotationDocResult, } from './annotation/dat
 export { useAnnotationList, type UseAnnotationListResult, } from './annotation/data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, type AnnotationMutations, } from './annotation/data/hooks/useAnnotationMutations.js';
 export { useAnnotationCanvasDoc, type SaveStatus, type UseAnnotationCanvasDocOptions, type UseAnnotationCanvasDocResult, } from './annotation/data/hooks/useAnnotationCanvasDoc.js';
+export { usePdfCanvasDoc, type UsePdfCanvasDocOptions, type UsePdfCanvasDocResult, } from './annotation/data/hooks/usePdfCanvasDoc.js';
 export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
 export type { AnnotationCanvasHandle } from './annotation/canvas/useAnnotationCanvasState.js';
@@ -35,8 +37,9 @@ export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './anno
 export type { CanvasBackgroundSlotArgs, RenderCanvasBackground, } from './annotation/canvas/backgroundSlot.js';
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, type StampTileDims, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, type GroupHeaderBadge, type GroupHeaderDescriptor, } from './annotation/canvas/groupHeaderLayout.js';
-export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, type ViewportApi, type ViewportState, type ZoomLimits, } from './annotation/canvas/viewport.js';
+export { createViewportApi, fitToScreen, fitRectToScreen, fitDocRectViewport, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, type ViewportApi, type ViewportState, type ZoomLimits, } from './annotation/canvas/viewport.js';
 export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, type PdfDocRect, } from './annotation/canvas/pdfDocument.js';
+export { normalizePdfRotation, effectivePageRotation, pdfPageDisplaySize, pdfCanvasPageDocId, emptyPdfCanvasPageState, pdfCanvasPageDocument, pdfCanvasKnobsOf, pdfCanvasKnobsEqual, pageStateToCanvasState, canvasStateToPageState, rotatePointInPage, rotatePageState, rotatePdfCanvasPage, type PdfPageDisplaySize, type PdfRotationDelta, } from './annotation/canvas/pdfCanvasPages.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { fileTileImageSource, expandFileTileToBackground, collapseBackgroundToFileTile, type FileTileImageSource, } from './annotation/canvas/fileTileSwap.js';
 export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';

package/dist/exports.js

@@ -10,6 +10,7 @@ export { useParseMeasurement } from './utils/useParseMeasurement.js';
 export * from './types/firestore.js';
 export * from './types/layout.js';
 export * from './types/annotation.js';
+export * from './types/pdfCanvas.js';
 export { getToleranceColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, } from './utils/tolerance.js';
 // Shared color palette (canonical source for both apps' brand colors).
 export { GeneralColors, SecondaryColors, FormColors, TileColors, FormulaColors, YellowColors, RedColors, GreenColors, tailwindColors, } from './theme/colors.js';
@@ -37,12 +38,14 @@ export { useAnnotationDoc, } from './annotation/data/hooks/useAnnotationDoc.js';
 export { useAnnotationList, } from './annotation/data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, } from './annotation/data/hooks/useAnnotationMutations.js';
 export { useAnnotationCanvasDoc, } from './annotation/data/hooks/useAnnotationCanvasDoc.js';
+export { usePdfCanvasDoc, } from './annotation/data/hooks/usePdfCanvasDoc.js';
 export { hydrateCanvasState } from './annotation/data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotationProvider.js';
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, } from './annotation/canvas/groupHeaderLayout.js';
-export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './annotation/canvas/viewport.js';
+export { createViewportApi, fitToScreen, fitRectToScreen, fitDocRectViewport, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, DEFAULT_ZOOM_LIMITS, } from './annotation/canvas/viewport.js';
 export { DEFAULT_PDF_PAGE_GAP, DEFAULT_MIN_ZOOM, DEFAULT_MAX_ZOOM, makePdfDocumentId, createPdfDocument, pdfPageDocRects, pdfDocumentExtent, pdfFirstPageDocRect, computeZoomFloor, } from './annotation/canvas/pdfDocument.js';
+export { normalizePdfRotation, effectivePageRotation, pdfPageDisplaySize, pdfCanvasPageDocId, emptyPdfCanvasPageState, pdfCanvasPageDocument, pdfCanvasKnobsOf, pdfCanvasKnobsEqual, pageStateToCanvasState, canvasStateToPageState, rotatePointInPage, rotatePageState, rotatePdfCanvasPage, } from './annotation/canvas/pdfCanvasPages.js';
 export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerIsLocked, isBackgroundLayerLocked, defaultBackgroundLayerLocked, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { fileTileImageSource, expandFileTileToBackground, collapseBackgroundToFileTile, } from './annotation/canvas/fileTileSwap.js';
 export { createPenTool, } from './annotation/canvas/tools/penTool.js';

package/dist/server.d.ts

@@ -5,6 +5,8 @@ export { parseMeasurement } from './utils/parseMeasurement.js';
 export * from './types/firestore.js';
 export * from './types/layout.js';
 export * from './types/annotation.js';
+export * from './types/pdfCanvas.js';
+export { normalizePdfRotation, effectivePageRotation, pdfPageDisplaySize, pdfCanvasPageDocId, pageStateToCanvasState, rotatePageState, type PdfPageDisplaySize, type PdfRotationDelta, } from './annotation/canvas/pdfCanvasPages.js';
 export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, type ToleranceThreshold, type ToleranceConfig, } from './utils/tolerance.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
 export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, type MaybeRole, type GroupedGrants, type ResolvedAccess, } from './utils/permissions.js';

package/dist/server.js

@@ -10,6 +10,8 @@ export { parseMeasurement } from './utils/parseMeasurement.js';
 export * from './types/firestore.js';
 export * from './types/layout.js';
 export * from './types/annotation.js';
+export * from './types/pdfCanvas.js';
+export { normalizePdfRotation, effectivePageRotation, pdfPageDisplaySize, pdfCanvasPageDocId, pageStateToCanvasState, rotatePageState, } from './annotation/canvas/pdfCanvasPages.js';
 export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, } from './utils/tolerance.js';
 export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
 export { ROLE_RANK, EMPTY_GRANTS, normalizeRole, roleAtLeast, effectiveRole, canView, canEdit, canManage, canManageOrg, isGuest, groupGrants, resolveAccess, } from './utils/permissions.js';

package/dist/types/firestore.d.ts

@@ -1,4 +1,5 @@
 import type { AnnotationCanvasState } from './annotation.js';
+import type { PdfCanvasData } from './pdfCanvas.js';
 import type { CalculatorUnit } from '../calculator/units.js';
 interface FirestoreDoc {
     id: string;
@@ -170,6 +171,7 @@ export interface SelectedTemplate extends FirestoreDoc {
 export declare enum FileUploadType {
     Annotation = "annotation",
     Canvas = "canvas",
+    PdfCanvas = "pdfCanvas",
     Template = "template",
     Background = "background",
     LayoutGroup = "layoutGroup",
@@ -186,6 +188,7 @@ export interface AnnotationFileData {
         clientId: string;
         seq: number;
     };
+    pdfCanvas?: PdfCanvasData;
 }
 export interface CalculatorFileData {
     templateId: string;
@@ -242,6 +245,9 @@ export type FileUpload = FileUploadBase & ({
 } | {
     type: FileUploadType.Canvas;
     fileData: AnnotationFileData;
+} | {
+    type: FileUploadType.PdfCanvas;
+    fileData: AnnotationFileData;
 } | {
     type: FileUploadType.Calculator;
     fileData: CalculatorFileData;

package/dist/types/firestore.js

@@ -52,6 +52,11 @@ export var FileUploadType;
     // v2 Skia photo-annotation canvas. Distinct from the legacy PSPDFKit
     // `Annotation` docs so file-open routing sends it to the canvas editor.
     FileUploadType["Canvas"] = "canvas";
+    // A PDF annotated one page at a time with the Skia canvas (see
+    // types/pdfCanvas.ts). Its PDF sits at `${folderPath}/file` like a legacy
+    // `Annotation` upload, so a client that predates the type still opens it in
+    // the Nutrient viewer instead of failing.
+    FileUploadType["PdfCanvas"] = "pdfCanvas";
     FileUploadType["Template"] = "template";
     FileUploadType["Background"] = "background";
     FileUploadType["LayoutGroup"] = "layoutGroup";

package/dist/types/pdfCanvas.d.ts

@@ -0,0 +1,38 @@
+import type { AnnotationLayer, AnnotationShape, AnnotationStroke, PlacedMeasurementRef, PlaneCalibration } from './annotation.js';
+export type PdfPageRotation = 0 | 90 | 180 | 270;
+export interface PdfCanvasPage {
+    width: number;
+    height: number;
+    rotation: PdfPageRotation;
+}
+export interface PdfCanvasDocument {
+    storagePath: string;
+    fileName?: string;
+    pageCount: number;
+    pages: PdfCanvasPage[];
+}
+export interface PdfCanvasRev {
+    clientId: string;
+    seq: number;
+}
+export interface PdfCanvasData {
+    schemaVersion: 1;
+    document: PdfCanvasDocument;
+    tileScaleFactor?: number;
+    tileScaleFactorMobile?: number;
+    headerTileScaleFactor?: number;
+    headerTileScaleFactorMobile?: number;
+    tileDocSize?: number;
+    annotatedPages: number[];
+}
+export interface PdfCanvasPageState {
+    schemaVersion: 1;
+    pageIndex: number;
+    layers: AnnotationLayer[];
+    strokes: AnnotationStroke[];
+    shapes: AnnotationShape[];
+    placedMeasurements: PlacedMeasurementRef[];
+    planes?: PlaneCalibration[];
+    updatedAt: number;
+    rev?: PdfCanvasRev;
+}

package/dist/types/pdfCanvas.js

@@ -0,0 +1,16 @@
+// Schema of a PDF CANVAS file (FileUploadType.PdfCanvas): a PDF annotated one
+// page at a time with the Skia canvas. Distinct from a Canvas file carrying a
+// `viewport.pdfDocument` filmstrip — there every page shares one doc space;
+// here EVERY PAGE IS ITS OWN CANVAS whose doc space is that page's displayed
+// extent in PDF points (origin top-left, y down), so the canvas engine needs no
+// page concept at all: the editor mounts the current page's state and swaps it
+// on a page turn.
+//
+// Storage split (see pdfCanvasPages.ts for the mapping helpers):
+//  - `fileData.pdfCanvas` on the file doc: the small file-level record —
+//    which PDF, page geometry + user rotations, shared tile-scale knobs, and
+//    which pages have been annotated.
+//  - `files/{fileId}/pages/{pageIndex}`: one doc per annotated page holding
+//    that page's elements. Sharded so a heavy set never approaches the 1 MiB
+//    doc limit, a save rewrites one page, and a listener watches one page.
+export {};

package/package.json

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