@reekon-tools/boldr-utils 1.22.0 → 1.23.0

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

@@ -0,0 +1,23 @@
+import { PDFDocument, PDFPage, PDFRef } from 'pdf-lib';
+import type { Mark } from './marks.js';
+import { type AffineMatrix, type DocRect } from './pageMapping.js';
+import type { FormScope } from './resources.js';
+export interface AddAnnotationInput {
+    doc: PDFDocument;
+    page: PDFPage;
+    mark: Mark;
+    /** The page's doc-space rect; the appearance is clipped to it. */
+    pageRect: DocRect;
+    matrix: AffineMatrix;
+    /** The scope the mark's operators registered their resources in. */
+    scope: FormScope;
+    /** A sibling annotation this one belongs with (Acrobat groups them). */
+    groupWith?: PDFRef;
+}
+/**
+ * Wrap a mark as an annotation on `page`. Returns the annotation's ref, or
+ * null when the mark lies entirely outside the page.
+ */
+export declare const addMarkAnnotation: ({ doc, page, mark, pageRect, matrix, scope, groupWith, }: AddAnnotationInput) => PDFRef | null;
+/** How many annotations a page carries (for tests and the result). */
+export declare const annotationCount: (page: PDFPage) => number;

package/dist/export/pdf/annots.js

@@ -0,0 +1,135 @@
+// Annotation mode: every element becomes a PDF annotation object — what
+// Preview, Acrobat and friends show as selectable, movable, deletable
+// markup — carrying the element's exact drawing as its appearance stream
+// plus the standard fields a viewer reads back (colour, width, points).
+//
+// The appearance stream is a Form XObject whose space IS doc space: its
+// /Matrix is the page's doc→user matrix and its /BBox the element's doc
+// bounds clipped to the page, so the operators the flatten path emits are
+// reused byte for byte. /Rect is set to exactly the transformed /BBox, which
+// makes the spec's rect-fitting step (§12.5.5) the identity.
+import { PDFHexString, PDFString, } from 'pdf-lib';
+import { dashIntervals } from '../../annotation/canvas/strokeGeometry.js';
+import { parseHexColor } from './color.js';
+import { applyMatrix, intersectRects, } from './pageMapping.js';
+/** /F flags: Print (bit 3). Not Hidden, not NoView, not Locked. */
+const ANNOT_FLAG_PRINT = 4;
+const rgbArray = (hex) => {
+    const { rgb } = parseHexColor(hex);
+    return [rgb.red, rgb.green, rgb.blue];
+};
+const round = (n) => Math.round(n * 1000) / 1000;
+const mapPoint = (m, p) => {
+    const q = applyMatrix(m, p.x, p.y);
+    return [round(q.x), round(q.y)];
+};
+const flatPoints = (m, pts) => pts.flatMap((p) => mapPoint(m, p));
+/** Axis-aligned user-space rect [llx lly urx ury] of a doc rect under `m`. */
+const userRect = (m, r) => {
+    const corners = [
+        applyMatrix(m, r.x, r.y),
+        applyMatrix(m, r.x + r.width, r.y),
+        applyMatrix(m, r.x, r.y + r.height),
+        applyMatrix(m, r.x + r.width, r.y + r.height),
+    ];
+    const xs = corners.map((c) => c.x);
+    const ys = corners.map((c) => c.y);
+    return [
+        round(Math.min(...xs)),
+        round(Math.min(...ys)),
+        round(Math.max(...xs)),
+        round(Math.max(...ys)),
+    ];
+};
+const lineEnding = (arrow) => (arrow ? 'ClosedArrow' : 'None');
+/** Subtype-specific dictionary entries, in page user space. */
+const metaEntries = (meta, m) => {
+    switch (meta.subtype) {
+        case 'Ink':
+            return {
+                C: rgbArray(meta.color),
+                BS: { W: meta.width, S: 'S' },
+                InkList: meta.paths.map((path) => flatPoints(m, path)),
+            };
+        case 'Line':
+            return {
+                C: rgbArray(meta.color),
+                IC: rgbArray(meta.color), // arrowhead fill
+                BS: borderStyle(meta.width, meta.dash),
+                L: [...mapPoint(m, meta.a), ...mapPoint(m, meta.b)],
+                LE: [lineEnding(meta.startArrow), lineEnding(meta.endArrow)],
+            };
+        case 'Square':
+        case 'Circle':
+            return {
+                C: rgbArray(meta.color),
+                ...(meta.fill ? { IC: rgbArray(meta.fill) } : {}),
+                BS: borderStyle(meta.width, meta.dash),
+            };
+        case 'Polygon':
+        case 'PolyLine':
+            return {
+                C: rgbArray(meta.color),
+                ...(meta.fill ? { IC: rgbArray(meta.fill) } : {}),
+                BS: borderStyle(meta.width, meta.dash),
+                Vertices: flatPoints(m, meta.vertices),
+                ...(meta.subtype === 'PolyLine'
+                    ? { LE: [lineEnding(meta.startArrow), lineEnding(meta.endArrow)] }
+                    : {}),
+            };
+        case 'FreeText': {
+            const [r, g, b] = rgbArray(meta.color);
+            return {
+                DA: PDFString.of(`/Helv ${round(meta.fontSize)} Tf ${r} ${g} ${b} rg`),
+                Contents: PDFHexString.fromText(meta.text),
+            };
+        }
+        case 'Stamp':
+            return meta.contents
+                ? { Contents: PDFHexString.fromText(meta.contents) }
+                : {};
+    }
+};
+const borderStyle = (width, dash) => dash ? { W: width, S: 'D', D: dashIntervals(width) } : { W: width, S: 'S' };
+const alphaOf = (meta) => ('alpha' in meta ? meta.alpha : 1);
+/**
+ * Wrap a mark as an annotation on `page`. Returns the annotation's ref, or
+ * null when the mark lies entirely outside the page.
+ */
+export const addMarkAnnotation = ({ doc, page, mark, pageRect, matrix, scope, groupWith, }) => {
+    const bbox = intersectRects(mark.bounds, pageRect);
+    if (!bbox || mark.ops.length === 0)
+        return null;
+    const { context } = doc;
+    const form = context.formXObject(mark.ops, {
+        BBox: [
+            round(bbox.x),
+            round(bbox.y),
+            round(bbox.x + bbox.width),
+            round(bbox.y + bbox.height),
+        ],
+        Matrix: matrix.map(round),
+        Resources: scope.resources(),
+    });
+    const formRef = context.register(form);
+    const alpha = alphaOf(mark.annot);
+    const dict = {
+        Type: 'Annot',
+        Subtype: mark.annot.subtype,
+        Rect: userRect(matrix, bbox),
+        F: ANNOT_FLAG_PRINT,
+        P: page.ref,
+        NM: PDFString.of(mark.id),
+        AP: { N: formRef },
+        ...(alpha < 1 ? { CA: round(alpha) } : {}),
+        ...metaEntries(mark.annot, matrix),
+        ...(groupWith ? { IRT: groupWith, RT: 'Group' } : {}),
+    };
+    // `LiteralObject` is not re-exported by pdf-lib, so the shape is asserted
+    // from `obj`'s own parameter type.
+    const ref = context.register(context.obj(dict));
+    page.node.addAnnot(ref);
+    return ref;
+};
+/** How many annotations a page carries (for tests and the result). */
+export const annotationCount = (page) => page.node.Annots()?.size() ?? 0;

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

@@ -0,0 +1,21 @@
+export interface StripPdfEncryptionOptions {
+    /** User password, when the document needs one. Never stored. */
+    password?: string;
+    /** The PDFium wasm bytes; resolved from `@embedpdf/pdfium` when absent. */
+    wasmBinary?: ArrayBuffer;
+}
+export interface StripPdfEncryptionResult {
+    bytes: Uint8Array;
+    /** False when the input had no /Encrypt and was returned untouched. */
+    wasEncrypted: boolean;
+}
+/**
+ * Open `bytes` with PDFium and return a plaintext copy when the document is
+ * encrypted, or the input untouched when it is not.
+ *
+ * @throws PdfExportError `password-required` when the document needs a user
+ * password and none was given; `password-incorrect` when the given one was
+ * refused; `unsupported` for a security handler PDFium cannot open;
+ * `corrupt` when the bytes are not a PDF or the copy could not be written.
+ */
+export declare const stripPdfEncryption: (bytes: Uint8Array, options?: StripPdfEncryptionOptions) => Promise<StripPdfEncryptionResult>;

package/dist/export/pdf/decrypt.js

@@ -0,0 +1,121 @@
+// Strip a PDF's encryption so pdf-lib can append to it.
+//
+// Files saved by annotation tools (Nutrient included) and by many CAD /
+// Bluebeam exports carry an /Encrypt dictionary with an EMPTY user password:
+// every viewer opens them without a prompt, but every stream inside is still
+// RC4 / AES ciphertext keyed off that empty password. PDFium decrypts on the
+// fly, which is why the canvas renders such a file; pdf-lib cannot decrypt at
+// all and refuses to load it. Appending plaintext marks to a document whose
+// trailer says "encrypted" is not an option either — a viewer would run the
+// document key over our plaintext and paint garbage.
+//
+// So the fix is to open with PDFium (the same wasm build the web canvas
+// renders with), drop the encryption, and save a plaintext copy. A document
+// that genuinely needs a user password is reported as such so a host can
+// prompt for it and call again with `password`; nothing here persists it.
+//
+// NODE ONLY. Reached from the `./server` entry, never from the app barrel:
+// it resolves the wasm off disk and loads `@embedpdf/pdfium` lazily (an
+// optional peer), so a consumer that never calls it never pays for it.
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { PdfExportError } from './types.js';
+/** PDFium's FPDF_GetLastError codes. */
+const FPDF_ERR_PASSWORD = 4;
+const FPDF_ERR_SECURITY = 5;
+let modulePromise = null;
+// `HEAPU8` is an Emscripten runtime field the wrapper's typings omit. Read it
+// through a call every time: Emscripten REPLACES the view when memory grows.
+const heapU8 = (m) => m.pdfium.HEAPU8;
+const loadPdfium = (wasmBinary) => {
+    if (wasmBinary)
+        return initPdfium(wasmBinary);
+    if (modulePromise === null) {
+        modulePromise = (async () => {
+            const require_ = createRequire(import.meta.url);
+            const bytes = await readFile(require_.resolve('@embedpdf/pdfium/pdfium.wasm'));
+            return initPdfium(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        })();
+    }
+    return modulePromise;
+};
+const initPdfium = async (wasmBinary) => {
+    const { init } = await import('@embedpdf/pdfium');
+    const m = await init({ wasmBinary });
+    m.PDFiumExt_Init();
+    return m;
+};
+/**
+ * Open `bytes` with PDFium and return a plaintext copy when the document is
+ * encrypted, or the input untouched when it is not.
+ *
+ * @throws PdfExportError `password-required` when the document needs a user
+ * password and none was given; `password-incorrect` when the given one was
+ * refused; `unsupported` for a security handler PDFium cannot open;
+ * `corrupt` when the bytes are not a PDF or the copy could not be written.
+ */
+export const stripPdfEncryption = async (bytes, options = {}) => {
+    const m = await loadPdfium(options.wasmBinary);
+    const { malloc, free } = m.pdfium.wasmExports;
+    const ptr = malloc(bytes.byteLength);
+    heapU8(m).set(bytes, ptr);
+    const doc = m.FPDF_LoadMemDocument(ptr, bytes.byteLength, options.password ?? '');
+    if (!doc) {
+        const err = m.FPDF_GetLastError();
+        free(ptr);
+        if (err === FPDF_ERR_PASSWORD) {
+            throw options.password !== undefined
+                ? new PdfExportError('password-incorrect', 'The PDF password is incorrect')
+                : new PdfExportError('password-required', 'This PDF is protected by a password');
+        }
+        if (err === FPDF_ERR_SECURITY) {
+            throw new PdfExportError('unsupported', 'This PDF uses a security handler that cannot be opened');
+        }
+        throw new PdfExportError('corrupt', `PDFium could not open the PDF (error ${err})`);
+    }
+    try {
+        if (!m.EPDF_IsEncrypted(doc))
+            return { bytes, wasEncrypted: false };
+        if (!m.EPDF_RemoveEncryption(doc)) {
+            throw new PdfExportError('corrupt', 'The PDF encryption could not be removed');
+        }
+        return { bytes: saveCopy(m, doc), wasEncrypted: true };
+    }
+    finally {
+        m.FPDF_CloseDocument(doc);
+        free(ptr);
+    }
+};
+/**
+ * FPDF_SaveAsCopy through an FPDF_FILEWRITE: `{ int version; int (*WriteBlock)
+ * (FPDF_FILEWRITE*, const void*, unsigned long); }` — two 32-bit words in
+ * wasm32, the callback registered into the function table for the duration.
+ */
+const saveCopy = (m, doc) => {
+    const { malloc, free } = m.pdfium.wasmExports;
+    const chunks = [];
+    const writeBlock = m.pdfium.addFunction((_self, data, size) => {
+        // Re-read the heap each call: it is replaced when memory grows.
+        chunks.push(heapU8(m).slice(data, data + size));
+        return 1;
+    }, 'iiii');
+    const fileWrite = malloc(8);
+    try {
+        m.pdfium.setValue(fileWrite, 1, 'i32');
+        m.pdfium.setValue(fileWrite + 4, writeBlock, 'i32');
+        if (!m.FPDF_SaveAsCopy(doc, fileWrite, 0)) {
+            throw new PdfExportError('corrupt', 'PDFium could not write the decrypted copy');
+        }
+    }
+    finally {
+        free(fileWrite);
+        m.pdfium.removeFunction(writeBlock);
+    }
+    const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let o = 0;
+    for (const c of chunks) {
+        out.set(c, o);
+        o += c.length;
+    }
+    return out;
+};

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

@@ -1,4 +1,5 @@
-import { PDFDocument, PDFFont, PDFName, PDFPage, type PDFOperator } from 'pdf-lib';
+import { PDFDocument, PDFFont, PDFName, type PDFOperator } from 'pdf-lib';
+import type { ResourceScope } from './resources.js';
 export type TextAlign = 'left' | 'center' | 'right';
 export interface TextOptions {
     align?: TextAlign;
@@ -8,7 +9,6 @@ export interface TextOptions {
 export declare class PdfFonts {
     private readonly primary;
     private readonly fallback;
-    private readonly keys;
     private constructor();
     static create(doc: PDFDocument, primaryBytes: Uint8Array): Promise<PdfFonts>;
     /** Whether the primary face has a glyph for every code point of `text`. */
@@ -26,13 +26,12 @@ export declare class PdfFonts {
         dropped: boolean;
     };
     width(text: string, size: number): number;
-    private keyFor;
     /**
      * Operators drawing one line of text in a y-DOWN space, with its baseline at
      * `yBaseline` and its left / centre / right edge at `x`. Returns [] when
      * nothing of the text is drawable.
      */
-    textOps(page: PDFPage, text: string, size: number, color: string, x: number, yBaseline: number, options?: TextOptions): PDFOperator[];
+    textOps(scope: ResourceScope, text: string, size: number, color: string, x: number, yBaseline: number, options?: TextOptions): PDFOperator[];
     /** Largest size ≤ `max` at which `text` fits in `maxWidth`. */
     fitSize(text: string, maxWidth: number, max: number, min?: number): number;
 }

package/dist/export/pdf/fonts.js

@@ -10,7 +10,6 @@ export class PdfFonts {
     constructor(primary, fallback) {
         this.primary = primary;
         this.fallback = fallback;
-        this.keys = new Map();
     }
     static async create(doc, primaryBytes) {
         doc.registerFontkit(fontkit);
@@ -52,23 +51,12 @@ export class PdfFonts {
         const p = this.pick(text);
         return p.text ? p.font.widthOfTextAtSize(p.text, size) : 0;
     }
-    keyFor(page, font) {
-        let keys = this.keys.get(page);
-        if (!keys) {
-            keys = {
-                primary: page.node.newFontDictionary(this.primary.name, this.primary.ref),
-                fallback: page.node.newFontDictionary(this.fallback.name, this.fallback.ref),
-            };
-            this.keys.set(page, keys);
-        }
-        return font === this.primary ? keys.primary : keys.fallback;
-    }
     /**
      * Operators drawing one line of text in a y-DOWN space, with its baseline at
      * `yBaseline` and its left / centre / right edge at `x`. Returns [] when
      * nothing of the text is drawable.
      */
-    textOps(page, text, size, color, x, yBaseline, options = {}) {
+    textOps(scope, text, size, color, x, yBaseline, options = {}) {
         const picked = this.pick(text);
         if (!picked.text || size <= 0)
             return [];
@@ -77,7 +65,7 @@ export class PdfFonts {
         const left = align === 'center' ? x - w / 2 : align === 'right' ? x - w : x;
         return withMatrix(uprightAt(left, yBaseline), drawText(picked.font.encodeText(picked.text), {
             color: parseHexColor(color).rgb,
-            font: this.keyFor(page, picked.font),
+            font: scope.fontKey(picked.font),
             size,
             rotate: degrees(0),
             xSkew: degrees(0),

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

@@ -1,5 +1,7 @@
 export { renderCanvasToPdf } 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';
 export { tileFootprint, type TileFootprint } from './tiles.js';
+export { annotationCount } from './annots.js';
 export { PdfExportError, type EmbeddedImage, type PdfExportCalibration, type RenderCanvasToPdfInput, type RenderCanvasToPdfResult, type ResolvedTileContent, type MeasurementTileContent, type LiteralTileContent, type EmptyTileContent, type HeaderTileContent, type ObjectTileContent, type PlaneDimensionTileContent, type InstructionsTileContent, type SkippedItem, } from './types.js';

package/dist/export/pdf/index.js

@@ -1,5 +1,7 @@
 export { renderCanvasToPdf } 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';
 export { tileFootprint } from './tiles.js';
+export { annotationCount } from './annots.js';
 export { PdfExportError, } from './types.js';

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

@@ -1,16 +1,73 @@
-import { type PDFName, type PDFOperator, type PDFPage } from 'pdf-lib';
-import type { AnnotationShape, AnnotationStroke, PlacedMeasurementRef } from '../../types/annotation.js';
+import { type PDFOperator } from 'pdf-lib';
+import type { AnnotationShape, AnnotationStroke, PlacedMeasurementRef, Vec2 } from '../../types/annotation.js';
 import { dashIntervals } from '../../annotation/canvas/strokeGeometry.js';
 import type { PdfFonts } from './fonts.js';
 import { type DocRect } from './pageMapping.js';
+import type { ResourceScope } from './resources.js';
 import type { SkippedItem } from './types.js';
 export interface MarkContext {
-    page: PDFPage;
+    /** Where fonts, images and opacity states get registered. */
+    scope: ResourceScope;
     fonts: PdfFonts;
-    /** An ExtGState carrying `alpha` (CA/ca) for this page; undefined at 1. */
-    alphaState: (alpha: number) => PDFName | undefined;
     skipped: SkippedItem[];
 }
+/**
+ * What an element IS, for the annotation dictionary that wraps its
+ * appearance stream in annotation mode: the standard fields a viewer reads
+ * back (and regenerates from after an edit). Points and rects are in DOC
+ * space; the annotation builder maps them onto the page.
+ */
+export type AnnotMeta = {
+    subtype: 'Ink';
+    color: string;
+    width: number;
+    alpha: number;
+    paths: Vec2[][];
+} | {
+    subtype: 'Line';
+    color: string;
+    width: number;
+    alpha: number;
+    dash: boolean;
+    a: Vec2;
+    b: Vec2;
+    startArrow: boolean;
+    endArrow: boolean;
+} | {
+    subtype: 'Square' | 'Circle';
+    color: string;
+    fill?: string;
+    width: number;
+    alpha: number;
+    dash: boolean;
+    rect: DocRect;
+} | {
+    subtype: 'Polygon' | 'PolyLine';
+    color: string;
+    fill?: string;
+    width: number;
+    alpha: number;
+    dash: boolean;
+    vertices: Vec2[];
+    startArrow: boolean;
+    endArrow: boolean;
+} | {
+    subtype: 'FreeText';
+    color: string;
+    fontSize: number;
+    text: string;
+    alpha: number;
+} | {
+    subtype: 'Stamp';
+    contents?: string;
+};
+/** One drawable element: its operators, its doc-space bounds, its identity. */
+export interface Mark {
+    id: string;
+    ops: PDFOperator[];
+    bounds: DocRect;
+    annot: AnnotMeta;
+}
 export declare const strokeBounds: (s: AnnotationStroke) => DocRect | null;
 export declare const strokeOps: (s: AnnotationStroke, ctx: MarkContext) => PDFOperator[];
 export declare const shapeBounds: (shape: AnnotationShape) => DocRect | null;
@@ -18,3 +75,7 @@ export declare const shapeOps: (shape: AnnotationShape, ctx: MarkContext) => PDF
 export declare const measurementMarkBounds: (placed: PlacedMeasurementRef) => DocRect | null;
 export declare const measurementMarkOps: (placed: PlacedMeasurementRef, ctx: MarkContext) => PDFOperator[];
 export { dashIntervals };
+export declare const strokeMark: (s: AnnotationStroke, ctx: MarkContext) => Mark | null;
+export declare const shapeMark: (shape: AnnotationShape, ctx: MarkContext) => Mark | null;
+/** The measurement annotation's line / rectangle (not its tile). */
+export declare const measurementMark: (placed: PlacedMeasurementRef, ctx: MarkContext) => Mark | null;

package/dist/export/pdf/marks.js

@@ -66,7 +66,7 @@ export const strokeOps = (s, ctx) => {
         return [];
     const opacity = s.tool === 'highlighter' ? 0.3 : 1;
     const alpha = opacity * parseHexColor(s.color).alpha;
-    const gs = ctx.alphaState(alpha);
+    const gs = ctx.scope.alphaState(alpha);
     const isDot = n === 4 && s.points[0] === s.points[2] && s.points[1] === s.points[3];
     if (isDot) {
         // Skia paints a zero-length round-capped contour as a dot; PDF only does
@@ -137,7 +137,7 @@ const textShapeOps = (shape, ctx) => {
     const colorStr = shape.style.stroke ?? '#000000';
     const decoration = shape.style.textDecoration;
     const glyphColor = decoration === 'highlight' ? highlightTextColor(colorStr) : colorStr;
-    const gs = ctx.alphaState(parseHexColor(colorStr).alpha);
+    const gs = ctx.scope.alphaState(parseHexColor(colorStr).alpha);
     const lineHeight = TEXT_LINE_HEIGHT_FACTOR * fontSize;
     const ops = [];
     let lost = false;
@@ -151,7 +151,7 @@ const textShapeOps = (shape, ctx) => {
         if (decoration === 'highlight' && width > 0) {
             ops.push(pushGraphicsState(), ...fillStateOps(colorStr, gs), rectangle(origin.x, top, width, lineHeight), fill(), popGraphicsState());
         }
-        ops.push(...ctx.fonts.textOps(ctx.page, line, fontSize, glyphColor, origin.x, baseline, {
+        ops.push(...ctx.fonts.textOps(ctx.scope, line, fontSize, glyphColor, origin.x, baseline, {
             graphicsState: gs,
         }));
         if ((decoration === 'underline' || decoration === 'squiggle') &&
@@ -177,7 +177,7 @@ export const shapeOps = (shape, ctx) => {
         return textShapeOps(shape, ctx);
     const strokeColor = style.stroke ?? '#000000';
     const strokeWidth = style.strokeWidth ?? 2;
-    const gs = ctx.alphaState(parseHexColor(strokeColor).alpha);
+    const gs = ctx.scope.alphaState(parseHexColor(strokeColor).alpha);
     const closed = geometry.closed !== false;
     const pts = geometry.points;
     const strokeWith = (pathOps, join, cap) => [
@@ -197,7 +197,7 @@ export const shapeOps = (shape, ctx) => {
     const fillWith = (pathOps) => style.fill
         ? [
             pushGraphicsState(),
-            ...fillStateOps(style.fill, ctx.alphaState(parseHexColor(style.fill).alpha)),
+            ...fillStateOps(style.fill, ctx.scope.alphaState(parseHexColor(style.fill).alpha)),
             ...pathOps,
             fill(),
             popGraphicsState(),
@@ -298,7 +298,7 @@ export const measurementMarkOps = (placed, ctx) => {
                 width,
                 join: 'miter',
                 dash: !!placed.lineDash,
-                graphicsState: ctx.alphaState(parseHexColor(color).alpha),
+                graphicsState: ctx.scope.alphaState(parseHexColor(color).alpha),
             }),
             ...rectPathOps(n.minX, n.minY, n.maxX - n.minX, n.maxY - n.minY),
             stroke(),
@@ -309,7 +309,7 @@ export const measurementMarkOps = (placed, ctx) => {
         const { a, b } = placed.line;
         const color = placed.lineColor ?? MEASUREMENT_LINE_COLOR;
         const width = placed.lineWidth ?? MEASUREMENT_LINE_WIDTH;
-        const gs = ctx.alphaState(parseHexColor(color).alpha);
+        const gs = ctx.scope.alphaState(parseHexColor(color).alpha);
         const ops = [
             pushGraphicsState(),
             ...strokeStateOps({
@@ -334,3 +334,146 @@ export const measurementMarkOps = (placed, ctx) => {
 };
 // Re-exported so the renderer can size dash tests without a second import.
 export { dashIntervals };
+/* ------------------------------------------------------------------ *
+ * Marks: ops + bounds + annotation metadata, per element
+ * ------------------------------------------------------------------ */
+const strokePaths = (s) => {
+    const pts = [];
+    for (let i = 0; i + 1 < s.points.length; i += 2) {
+        pts.push({ x: s.points[i], y: s.points[i + 1] });
+    }
+    return pts;
+};
+export const strokeMark = (s, ctx) => {
+    const bounds = strokeBounds(s);
+    if (!bounds)
+        return null;
+    const opacity = s.tool === 'highlighter' ? 0.3 : 1;
+    return {
+        id: s.id,
+        ops: strokeOps(s, ctx),
+        bounds,
+        annot: {
+            subtype: 'Ink',
+            color: s.color,
+            width: s.width,
+            alpha: opacity * parseHexColor(s.color).alpha,
+            paths: [strokePaths(s)],
+        },
+    };
+};
+export const shapeMark = (shape, ctx) => {
+    const bounds = shapeBounds(shape);
+    if (!bounds)
+        return null;
+    const ops = shapeOps(shape, ctx);
+    const { kind, geometry, style } = shape;
+    const color = style.stroke ?? '#000000';
+    const width = style.strokeWidth ?? 2;
+    const alpha = parseHexColor(color).alpha;
+    const dash = !!style.dash;
+    const pts = geometry.points;
+    let annot;
+    switch (kind) {
+        case 'rect':
+        case 'ellipse': {
+            const b = visualShapeBounds(shape);
+            annot = {
+                subtype: kind === 'rect' ? 'Square' : 'Circle',
+                color,
+                fill: style.fill,
+                width,
+                alpha,
+                dash,
+                rect: boundsToRect(b),
+            };
+            break;
+        }
+        case 'line':
+        case 'arrow':
+            annot = {
+                subtype: 'Line',
+                color,
+                width,
+                alpha,
+                dash,
+                a: pts[0],
+                b: pts[1],
+                startArrow: style.startCap === 'arrow',
+                endArrow: kind === 'arrow' || style.cap === 'arrow',
+            };
+            break;
+        case 'polygon': {
+            const closed = geometry.closed !== false;
+            annot = {
+                subtype: closed ? 'Polygon' : 'PolyLine',
+                color,
+                fill: closed ? style.fill : undefined,
+                width,
+                alpha,
+                dash,
+                vertices: pts,
+                startArrow: !closed && style.startCap === 'arrow',
+                endArrow: !closed && style.cap === 'arrow',
+            };
+            break;
+        }
+        case 'text':
+            annot = {
+                subtype: 'FreeText',
+                color,
+                fontSize: style.fontSize ?? DEFAULT_TEXT_FONT_SIZE,
+                text: shape.text ?? '',
+                alpha,
+            };
+            break;
+        default:
+            return null;
+    }
+    return { id: shape.id, ops, bounds, annot };
+};
+/** The measurement annotation's line / rectangle (not its tile). */
+export const measurementMark = (placed, ctx) => {
+    const bounds = measurementMarkBounds(placed);
+    if (!bounds)
+        return null;
+    const ops = measurementMarkOps(placed, ctx);
+    const color = placed.lineColor ?? MEASUREMENT_LINE_COLOR;
+    const alpha = parseHexColor(color).alpha;
+    const dash = !!placed.lineDash;
+    if (placementOf(placed) === 'rectangle' && placed.rect) {
+        const n = normalizeRect(placed.rect);
+        return {
+            id: `${placed.id}:rect`,
+            ops,
+            bounds,
+            annot: {
+                subtype: 'Square',
+                color,
+                width: placed.lineWidth ?? MEASUREMENT_RECT_WIDTH,
+                alpha,
+                dash,
+                rect: boundsToRect(n),
+            },
+        };
+    }
+    if (placementOf(placed) === 'line' && placed.line) {
+        return {
+            id: `${placed.id}:line`,
+            ops,
+            bounds,
+            annot: {
+                subtype: 'Line',
+                color,
+                width: placed.lineWidth ?? MEASUREMENT_LINE_WIDTH,
+                alpha,
+                dash,
+                a: placed.line.a,
+                b: placed.line.b,
+                startArrow: placed.lineStartCap === 'arrow',
+                endArrow: placed.lineCap === 'arrow',
+            },
+        };
+    }
+    return null;
+};

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

@@ -39,6 +39,8 @@ export declare const applyMatrix: (m: AffineMatrix, x: number, y: number) => {
     x: number;
     y: number;
 };
+/** The overlap of two rects, or null when they do not overlap. */
+export declare const intersectRects: (a: DocRect, b: DocRect) => DocRect | null;
 export declare const rectsIntersect: (a: DocRect, b: DocRect) => boolean;
 /** Axis-aligned bounds → DocRect, inflated by `pad` on every side. */
 export declare const boundsToRect: (b: {

package/dist/export/pdf/pageMapping.js

@@ -54,6 +54,16 @@ export const applyMatrix = (m, x, y) => ({
     x: m[0] * x + m[2] * y + m[4],
     y: m[1] * x + m[3] * y + m[5],
 });
+/** The overlap of two rects, or null when they do not overlap. */
+export const intersectRects = (a, b) => {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    if (right <= x || bottom <= y)
+        return null;
+    return { x, y, width: right - x, height: bottom - y };
+};
 export const rectsIntersect = (a, b) => a.x < b.x + b.width &&
     a.x + a.width > b.x &&
     a.y < b.y + b.height &&

package/dist/export/pdf/renderCanvasToPdf.js

@@ -9,9 +9,11 @@ import { STAMP_TILE_SIZE } from '../../annotation/canvas/stampLayout.js';
 import { clipRectOps, withMatrix } from './emit.js';
 import { PdfFonts } from './fonts.js';
 import { layerOps, layerVisibleRect } from './layers.js';
-import { measurementMarkBounds, measurementMarkOps, shapeBounds, shapeOps, strokeBounds, strokeOps, } from './marks.js';
+import { addMarkAnnotation } from './annots.js';
+import { measurementMark, measurementMarkBounds, measurementMarkOps, shapeBounds, shapeMark, shapeOps, strokeBounds, strokeMark, strokeOps, } from './marks.js';
+import { FormScope, PageScope } from './resources.js';
 import { docToPageMatrix, normalizeRotation, pageRectsOf, rectsIntersect, rotatedBoxSize, } from './pageMapping.js';
-import { designBoxFor, tileFootprint, tileOps, } from './tiles.js';
+import { designBoxFor, tileFootprint, tileOps } from './tiles.js';
 import { PdfExportError, } from './types.js';
 /** Stored page sizes may differ from the file's boxes by rounding only. */
 const PAGE_SIZE_TOLERANCE_PT = 1.5;
@@ -41,8 +43,11 @@ const loadSource = async (bytes) => {
         return await PDFDocument.load(bytes, { updateMetadata: false });
     }
     catch (e) {
-        if (e instanceof EncryptedPDFError) {
-            throw new PdfExportError('encrypted', 'The source PDF is encrypted and cannot be exported');
+        // Both checks: pdf-lib's dual CJS/ESM build can hand back an
+        // EncryptedPDFError whose class identity differs from the one imported.
+        if (e instanceof EncryptedPDFError ||
+            (e instanceof Error && /is encrypted/i.test(e.message))) {
+            throw new PdfExportError('encrypted', 'The source PDF is encrypted; strip it with stripPdfEncryption before rendering');
         }
         throw new PdfExportError('corrupt', `The source PDF could not be parsed: ${e instanceof Error ? e.message : String(e)}`);
     }
@@ -134,68 +139,150 @@ export const renderCanvasToPdf = async (input) => {
             .zoom, 1e-6);
     const hiddenLayerIds = new Set(canvas.layers.filter((l) => l.visible === false).map((l) => l.id));
     const visible = (layerId) => !hiddenLayerIds.has(layerId);
-    for (const { page, box, rotation, rect } of geometry) {
-        // Per-page resource registries.
-        const alphaStates = new Map();
-        const alphaState = (alpha) => {
-            const a = Math.round(Math.min(1, Math.max(0, alpha)) * 1000) / 1000;
-            if (a >= 1)
+    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;
-            let name = alphaStates.get(a);
-            if (!name) {
-                name = page.node.newExtGState('GSa', doc.context.obj({ Type: 'ExtGState', CA: a, ca: a }));
-                alphaStates.set(a, name);
+        }
+    };
+    for (const { page, box, rotation, rect } of geometry) {
+        const matrix = docToPageMatrix(rect, box, rotation);
+        const onPage = (b) => b !== null && rectsIntersect(b, rect);
+        if (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) {
+                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) {
+                if (!visible(s.layerId) || !onPage(strokeBounds(s)))
+                    continue;
+                ops.push(...strokeOps(s, ctx));
+            }
+            for (const sh of canvas.shapes) {
+                if (!visible(sh.layerId) || !onPage(shapeBounds(sh)))
+                    continue;
+                ops.push(...shapeOps(sh, ctx));
+            }
+            for (const { placed } of tiles) {
+                if (!visible(placed.layerId) || !onPage(measurementMarkBounds(placed)))
+                    continue;
+                ops.push(...measurementMarkOps(placed, ctx));
+            }
+            for (const { placed, content } of tiles) {
+                if (!visible(placed.layerId))
+                    continue;
+                const footprint = tileFootprint(placed, canvas, input.calibration, fallbackDocEdge, designBoxFor(placed, content));
+                if (!onPage(footprint))
+                    continue;
+                ops.push(...tileOps({ scope, fonts, thumbnail: thumbnails.get(placed.id) }, content, footprint));
             }
-            return name;
+            if (ops.length === 0)
+                continue;
+            page.pushOperators(...withMatrix(matrix, [
+                ...clipRectOps(rect.x, rect.y, rect.width, rect.height),
+                ...ops,
+            ]));
+            continue;
+        }
+        // Annotation mode: one annotation per element, each with its own
+        // appearance stream and resources. Same z-order as the screen.
+        const add = (mark, scope, groupWith) => {
+            if (!mark)
+                return null;
+            const ref = addMarkAnnotation({
+                doc,
+                page,
+                mark,
+                pageRect: rect,
+                matrix,
+                scope,
+                groupWith,
+            });
+            if (ref)
+                annotationCount++;
+            return ref;
         };
-        const registerImage = (img) => ({
-            name: page.node.newXObject('Im', img.ref),
-            width: img.width,
-            height: img.height,
-        });
-        const ctx = { page, fonts, alphaState, skipped };
-        const onPage = (b) => b !== null && rectsIntersect(b, rect);
-        const ops = [];
-        // 1. Background image layers, array order.
         for (const layer of layers) {
             const img = layerImages.get(layer.id);
-            if (!img || !onPage(layerVisibleRect(layer)))
+            const bounds = layerVisibleRect(layer);
+            if (!img || !onPage(bounds))
                 continue;
-            ops.push(...layerOps(layer, registerImage(img).name));
+            const scope = new FormScope(doc.context);
+            add({
+                id: layer.id,
+                ops: layerOps(layer, scope.imageKey(img)),
+                bounds,
+                annot: {
+                    subtype: 'Stamp',
+                    contents: layer.fileId ? 'Placed file' : 'Background image',
+                },
+            }, scope);
         }
-        // 2. Strokes, then shapes, then measurement lines / rects — the Skia order.
         for (const s of canvas.strokes) {
             if (!visible(s.layerId) || !onPage(strokeBounds(s)))
                 continue;
-            ops.push(...strokeOps(s, ctx));
+            const scope = new FormScope(doc.context);
+            add(strokeMark(s, { scope, fonts, skipped }), scope);
         }
         for (const sh of canvas.shapes) {
             if (!visible(sh.layerId) || !onPage(shapeBounds(sh)))
                 continue;
-            ops.push(...shapeOps(sh, ctx));
+            const scope = new FormScope(doc.context);
+            add(shapeMark(sh, { scope, fonts, skipped }), scope);
         }
+        // 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) {
             if (!visible(placed.layerId) || !onPage(measurementMarkBounds(placed)))
                 continue;
-            ops.push(...measurementMarkOps(placed, ctx));
+            const scope = new FormScope(doc.context);
+            const ref = add(measurementMark(placed, { scope, fonts, skipped }), scope);
+            if (ref)
+                markRefs.set(placed.id, ref);
         }
-        // 3. Tiles on top, like the overlay.
         for (const { placed, content } of tiles) {
             if (!visible(placed.layerId))
                 continue;
             const footprint = tileFootprint(placed, canvas, input.calibration, fallbackDocEdge, designBoxFor(placed, content));
             if (!onPage(footprint))
                 continue;
-            const thumb = thumbnails.get(placed.id);
-            ops.push(...tileOps({ page, fonts, thumbnail: thumb ? registerImage(thumb) : undefined }, content, footprint));
+            const scope = new FormScope(doc.context);
+            add({
+                id: placed.id,
+                ops: tileOps({ scope, fonts, thumbnail: thumbnails.get(placed.id) }, content, footprint),
+                bounds: footprint,
+                annot: { subtype: 'Stamp', contents: tileContents(content) },
+            }, scope, markRefs.get(placed.id));
         }
-        if (ops.length === 0)
-            continue;
-        page.pushOperators(...withMatrix(docToPageMatrix(rect, box, rotation), [
-            ...clipRectOps(rect.x, rect.y, rect.width, rect.height),
-            ...ops,
-        ]));
     }
     const pdf = await doc.save({ useObjectStreams: false });
-    return { pdf, pageCount: pages.length, skipped };
+    return { pdf, pageCount: pages.length, annotationCount, skipped };
 };

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

@@ -0,0 +1,35 @@
+import { PDFContext, PDFDict, PDFFont, PDFImage, PDFName, PDFPage } from 'pdf-lib';
+export interface ResourceScope {
+    fontKey(font: PDFFont): PDFName;
+    imageKey(image: PDFImage): PDFName;
+    /** An ExtGState carrying `alpha` (CA/ca), or undefined at full opacity. */
+    alphaState(alpha: number): PDFName | undefined;
+}
+/** Resources on the page itself — content-stream (flatten) output. */
+export declare class PageScope implements ResourceScope {
+    private readonly page;
+    private readonly context;
+    private readonly fonts;
+    private readonly images;
+    private readonly alphas;
+    constructor(page: PDFPage, context: PDFContext);
+    fontKey(font: PDFFont): PDFName;
+    imageKey(image: PDFImage): PDFName;
+    alphaState(alpha: number): PDFName | undefined;
+}
+/** Resources collected for ONE appearance stream (annotation mode). */
+export declare class FormScope implements ResourceScope {
+    private readonly context;
+    private readonly fontDict;
+    private readonly xobjectDict;
+    private readonly gsDict;
+    private readonly fonts;
+    private readonly images;
+    private readonly alphas;
+    constructor(context: PDFContext);
+    fontKey(font: PDFFont): PDFName;
+    imageKey(image: PDFImage): PDFName;
+    alphaState(alpha: number): PDFName | undefined;
+    /** The /Resources dictionary for the appearance stream. */
+    resources(): PDFDict;
+}

package/dist/export/pdf/resources.js

@@ -0,0 +1,95 @@
+// Where an element's PDF resources (fonts, images, opacity states) get
+// registered. The emitters only ask a scope for a resource NAME; whether that
+// name lands in the page's resource dictionary (flatten mode) or in one
+// annotation appearance stream's own /Resources (annotation mode) is the
+// scope's business.
+import { PDFName, } from 'pdf-lib';
+const roundAlpha = (alpha) => Math.round(Math.min(1, Math.max(0, alpha)) * 1000) / 1000;
+const extGState = (context, alpha) => context.obj({ Type: 'ExtGState', CA: alpha, ca: alpha });
+/** Resources on the page itself — content-stream (flatten) output. */
+export class PageScope {
+    constructor(page, context) {
+        this.page = page;
+        this.context = context;
+        this.fonts = new Map();
+        this.images = new Map();
+        this.alphas = new Map();
+    }
+    fontKey(font) {
+        let key = this.fonts.get(font);
+        if (!key) {
+            key = this.page.node.newFontDictionary(font.name, font.ref);
+            this.fonts.set(font, key);
+        }
+        return key;
+    }
+    imageKey(image) {
+        let key = this.images.get(image);
+        if (!key) {
+            key = this.page.node.newXObject('Im', image.ref);
+            this.images.set(image, key);
+        }
+        return key;
+    }
+    alphaState(alpha) {
+        const a = roundAlpha(alpha);
+        if (a >= 1)
+            return undefined;
+        let key = this.alphas.get(a);
+        if (!key) {
+            key = this.page.node.newExtGState('GSa', extGState(this.context, a));
+            this.alphas.set(a, key);
+        }
+        return key;
+    }
+}
+/** Resources collected for ONE appearance stream (annotation mode). */
+export class FormScope {
+    constructor(context) {
+        this.context = context;
+        this.fonts = new Map();
+        this.images = new Map();
+        this.alphas = new Map();
+        this.fontDict = context.obj({});
+        this.xobjectDict = context.obj({});
+        this.gsDict = context.obj({});
+    }
+    fontKey(font) {
+        let key = this.fonts.get(font);
+        if (!key) {
+            key = PDFName.of(`F${this.fonts.size + 1}`);
+            this.fontDict.set(key, font.ref);
+            this.fonts.set(font, key);
+        }
+        return key;
+    }
+    imageKey(image) {
+        let key = this.images.get(image);
+        if (!key) {
+            key = PDFName.of(`Im${this.images.size + 1}`);
+            this.xobjectDict.set(key, image.ref);
+            this.images.set(image, key);
+        }
+        return key;
+    }
+    alphaState(alpha) {
+        const a = roundAlpha(alpha);
+        if (a >= 1)
+            return undefined;
+        let key = this.alphas.get(a);
+        if (!key) {
+            key = PDFName.of(`GS${this.alphas.size + 1}`);
+            this.gsDict.set(key, extGState(this.context, a));
+            this.alphas.set(a, key);
+        }
+        return key;
+    }
+    /** The /Resources dictionary for the appearance stream. */
+    resources() {
+        return this.context.obj({
+            Font: this.fontDict,
+            XObject: this.xobjectDict,
+            ExtGState: this.gsDict,
+        });
+    }
+}

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

@@ -1,19 +1,15 @@
-import { type PDFName, type PDFOperator, type PDFPage } from 'pdf-lib';
+import { type PDFImage, type PDFOperator } from 'pdf-lib';
 import type { AnnotationCanvasState, PlacedMeasurementRef } from '../../types/annotation.js';
 import type { PdfFonts } from './fonts.js';
+import type { ResourceScope } from './resources.js';
 import type { AffineMatrix, DocRect } from './pageMapping.js';
 import type { PdfExportCalibration, ResolvedTileContent } from './types.js';
-/** An image XObject already registered on the page, with its pixel size. */
-export interface PageImage {
-    name: PDFName;
-    width: number;
-    height: number;
-}
 export interface TilePaintContext {
-    page: PDFPage;
+    /** Where fonts, images and opacity states get registered. */
+    scope: ResourceScope;
     fonts: PdfFonts;
     /** Object-tile thumbnail, when the content carries one and it embedded. */
-    thumbnail?: PageImage;
+    thumbnail?: PDFImage;
 }
 export interface TileFootprint extends DocRect {
     /** Design-space box the painter lays out in. */

package/dist/export/pdf/tiles.js

@@ -133,15 +133,15 @@ const valueRowOps = (ctx, value, cx, cy, color, availableWidth, tileWidth) => {
     tokens.forEach((t, i) => {
         const w = widths[i];
         if (!t.fraction) {
-            ops.push(...ctx.fonts.textOps(ctx.page, t.text, fs, color, x, baseline));
+            ops.push(...ctx.fonts.textOps(ctx.scope, t.text, fs, color, x, baseline));
         }
         else {
             const stackW = Math.max(ctx.fonts.width(t.fraction.num, fracFs), ctx.fonts.width(t.fraction.den, fracFs));
             const scx = x + stackW / 2;
             // Numerator above the rule, denominator below; rule at the row centre.
-            ops.push(...ctx.fonts.textOps(ctx.page, t.fraction.num, fracFs, color, scx, cy - fracFs * 0.15, { align: 'center' }), pushGraphicsState(), ...fillStateOps(color), rectangle(x, cy - fracFs * 0.05, stackW, Math.max(fracFs * 0.08, 0.8)), fill(), popGraphicsState(), ...ctx.fonts.textOps(ctx.page, t.fraction.den, fracFs, color, scx, cy + fracFs * 0.85, { align: 'center' }));
+            ops.push(...ctx.fonts.textOps(ctx.scope, t.fraction.num, fracFs, color, scx, cy - fracFs * 0.15, { align: 'center' }), pushGraphicsState(), ...fillStateOps(color), rectangle(x, cy - fracFs * 0.05, stackW, Math.max(fracFs * 0.08, 0.8)), fill(), popGraphicsState(), ...ctx.fonts.textOps(ctx.scope, t.fraction.den, fracFs, color, scx, cy + fracFs * 0.85, { align: 'center' }));
             if (t.fraction.suffix) {
-                ops.push(...ctx.fonts.textOps(ctx.page, t.fraction.suffix, fs, color, x + stackW, baseline));
+                ops.push(...ctx.fonts.textOps(ctx.scope, t.fraction.suffix, fs, color, x + stackW, baseline));
             }
         }
         x += w + gap;
@@ -156,7 +156,7 @@ const measurementTileOps = (ctx, c) => {
     const white = GeneralColors.white;
     // Header row: position label, bold, top-left.
     if (c.positionLabel) {
-        ops.push(...ctx.fonts.textOps(ctx.page, c.positionLabel, 12, white, 6, 14));
+        ops.push(...ctx.fonts.textOps(ctx.scope, c.positionLabel, 12, white, 6, 14));
     }
     // Value row, centred on the tile, between the two unit slots.
     const hasUnit = !!c.unit;
@@ -164,7 +164,7 @@ const measurementTileOps = (ctx, c) => {
     const valueText = (c.negative ? '-' : '') + c.value;
     ops.push(...valueRowOps(ctx, valueText, SQUARE / 2, 48, white, available, SQUARE));
     if (hasUnit) {
-        ops.push(...ctx.fonts.textOps(ctx.page, c.unit, UNIT_FONT, white, SQUARE - UNIT_RESERVE / 2, 52, {
+        ops.push(...ctx.fonts.textOps(ctx.scope, c.unit, UNIT_FONT, white, SQUARE - UNIT_RESERVE / 2, 52, {
             align: 'center',
         }));
     }
@@ -175,7 +175,7 @@ const measurementTileOps = (ctx, c) => {
             ops.push(...filledRoundedRect(4, SQUARE - 20, SQUARE - 8, 16, 3, FormulaColors.darkPurple), ...strokedRoundedRect(4, SQUARE - 20, SQUARE - 8, 16, 3, FormulaColors.purple, 1));
         }
         const text = truncate(ctx.fonts, c.label, labelSize, SQUARE - 12);
-        ops.push(...ctx.fonts.textOps(ctx.page, text, labelSize, white, SQUARE / 2, SQUARE - 8, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, text, labelSize, white, SQUARE / 2, SQUARE - 8, { align: 'center' }));
     }
     return ops;
 };
@@ -186,9 +186,9 @@ const emptyTileOps = (ctx, c) => {
         ...strokedRoundedRect(0, 0, SQUARE, SQUARE, CARD_RADIUS, GeneralColors.grey3, 1),
     ];
     if (c.topLeftLabel)
-        ops.push(...ctx.fonts.textOps(ctx.page, c.topLeftLabel, 10, ink, 8, 18));
+        ops.push(...ctx.fonts.textOps(ctx.scope, c.topLeftLabel, 10, ink, 8, 18));
     if (c.topRightLabel) {
-        ops.push(...ctx.fonts.textOps(ctx.page, c.topRightLabel, 10, ink, SQUARE - 8, 18, {
+        ops.push(...ctx.fonts.textOps(ctx.scope, c.topRightLabel, 10, ink, SQUARE - 8, 18, {
             align: 'right',
         }));
     }
@@ -205,7 +205,7 @@ const emptyTileOps = (ctx, c) => {
     ]), stroke(), popGraphicsState());
     if (c.bottomLabel) {
         const text = truncate(ctx.fonts, c.bottomLabel, 10, SQUARE - 16);
-        ops.push(...ctx.fonts.textOps(ctx.page, text, 10, ink, cx, SQUARE - 10, {
+        ops.push(...ctx.fonts.textOps(ctx.scope, text, 10, ink, cx, SQUARE - 10, {
             align: 'center',
         }));
     }
@@ -216,17 +216,17 @@ const literalTileOps = (ctx, c) => {
     const fillColor = filled ? TileColors.activeBlue : GeneralColors.grey2;
     const ink = filled ? GeneralColors.white : GeneralColors.grey4;
     const ops = filledRoundedRect(0, 0, SQUARE, SQUARE, CARD_RADIUS, fillColor);
-    ops.push(...ctx.fonts.textOps(ctx.page, c.topLeftLabel, 10, ink, 8, 18));
-    ops.push(...ctx.fonts.textOps(ctx.page, c.topRightLabel, 10, ink, SQUARE - 8, 18, {
+    ops.push(...ctx.fonts.textOps(ctx.scope, c.topLeftLabel, 10, ink, 8, 18));
+    ops.push(...ctx.fonts.textOps(ctx.scope, c.topRightLabel, 10, ink, SQUARE - 8, 18, {
         align: 'right',
     }));
     ops.push(...filledRoundedRect(8, 28, SQUARE - 16, 40, 4, filled ? TileColors.activeBlue : GeneralColors.grey3));
     if (filled) {
         const size = ctx.fonts.fitSize(c.value, SQUARE - 24, 16, 6);
-        ops.push(...ctx.fonts.textOps(ctx.page, c.value, size, ink, SQUARE / 2, 48 + size * 0.35, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, c.value, size, ink, SQUARE / 2, 48 + size * 0.35, { align: 'center' }));
     }
     const bottom = truncate(ctx.fonts, c.bottomLabel, 10, SQUARE - 16);
-    ops.push(...ctx.fonts.textOps(ctx.page, bottom, 10, ink, SQUARE / 2, SQUARE - 10, {
+    ops.push(...ctx.fonts.textOps(ctx.scope, bottom, 10, ink, SQUARE / 2, SQUARE - 10, {
         align: 'center',
     }));
     return ops;
@@ -273,7 +273,7 @@ const headerTileOps = (ctx, c) => {
                     ops.push(...globeOps(W / 2, by + S.badgeHeight / 2, S.globeSize, S.globeColor));
                 else {
                     const text = truncate(ctx.fonts, b.text, S.badgeFontSize, inner - 10);
-                    ops.push(...ctx.fonts.textOps(ctx.page, text, S.badgeFontSize, S.badgeTextColor, W / 2, by + S.badgeHeight / 2 + S.badgeFontSize * 0.35, { align: 'center' }));
+                    ops.push(...ctx.fonts.textOps(ctx.scope, text, S.badgeFontSize, S.badgeTextColor, W / 2, by + S.badgeHeight / 2 + S.badgeFontSize * 0.35, { align: 'center' }));
                 }
             });
         }
@@ -287,7 +287,7 @@ const headerTileOps = (ctx, c) => {
                     ops.push(...globeOps(bx + bw / 2, y + S.badgeHeight / 2, S.globeSize, S.globeColor));
                 else {
                     const text = truncate(ctx.fonts, b.text, S.badgeFontSize, bw - 10);
-                    ops.push(...ctx.fonts.textOps(ctx.page, text, S.badgeFontSize, S.badgeTextColor, bx + bw / 2, y + S.badgeHeight / 2 + S.badgeFontSize * 0.35, { align: 'center' }));
+                    ops.push(...ctx.fonts.textOps(ctx.scope, text, S.badgeFontSize, S.badgeTextColor, bx + bw / 2, y + S.badgeHeight / 2 + S.badgeFontSize * 0.35, { align: 'center' }));
                 }
             });
         }
@@ -295,7 +295,7 @@ const headerTileOps = (ctx, c) => {
     }
     if (d.name !== null) {
         const text = truncate(ctx.fonts, d.name, S.nameFontSize, inner);
-        ops.push(...ctx.fonts.textOps(ctx.page, text, S.nameFontSize, S.nameColor, W / 2, y + S.nameGap + S.nameFontSize * 0.95, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, text, S.nameFontSize, S.nameColor, W / 2, y + S.nameGap + S.nameFontSize * 0.95, { align: 'center' }));
     }
     return ops;
 };
@@ -311,14 +311,14 @@ const objectTileOps = (ctx, c) => {
     if (!thumb) {
         ops.push(...filledRoundedRect(x, y, w, h, CARD_RADIUS, GeneralColors.grey2));
         const name = truncate(ctx.fonts, c.name || 'Object removed', 9, w - 8);
-        ops.push(...ctx.fonts.textOps(ctx.page, name, 9, GeneralColors.grey4, SQUARE / 2, SQUARE / 2 + 3, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, name, 9, GeneralColors.grey4, SQUARE / 2, SQUARE / 2 + 3, { align: 'center' }));
         return ops;
     }
     // Thumbnail, cover-fit and clipped to the rounded card.
     const scale = Math.max(w / thumb.width, h / thumb.height);
     const iw = thumb.width * scale;
     const ih = thumb.height * scale;
-    ops.push(pushGraphicsState(), ...roundedRectPathOps(x, y, w, h, CARD_RADIUS), clip(), endPath(), ...imageOps(thumb.name, x + (w - iw) / 2, y + (h - ih) / 2, iw, ih), popGraphicsState());
+    ops.push(pushGraphicsState(), ...roundedRectPathOps(x, y, w, h, CARD_RADIUS), clip(), endPath(), ...imageOps(ctx.scope.imageKey(thumb), x + (w - iw) / 2, y + (h - ih) / 2, iw, ih), popGraphicsState());
     // Footer bar by object type: a layout group gets the magenta bar with white
     // ink, a plain photo/background none, every document a white bar with dark ink.
     const type = c.fileType;
@@ -330,7 +330,7 @@ const objectTileOps = (ctx, c) => {
     if (bar) {
         ops.push(pushGraphicsState(), ...roundedRectPathOps(x, y, w, h, CARD_RADIUS), clip(), endPath(), ...fillStateOps(bar.fill), rectangle(x, y + h - OBJECT_BAR_HEIGHT, w, OBJECT_BAR_HEIGHT), fill(), popGraphicsState());
         const name = truncate(ctx.fonts, c.name, 9, w - 8);
-        ops.push(...ctx.fonts.textOps(ctx.page, name, 9, bar.ink, SQUARE / 2, y + h - OBJECT_BAR_HEIGHT / 2 + 3, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, name, 9, bar.ink, SQUARE / 2, y + h - OBJECT_BAR_HEIGHT / 2 + 3, { align: 'center' }));
     }
     return ops;
 };
@@ -365,7 +365,7 @@ const instructionsTileOps = (ctx, c) => {
     const lh = size * 1.25;
     const top = SQUARE / 2 - (lines.length * lh) / 2;
     lines.forEach((line, i) => {
-        ops.push(...ctx.fonts.textOps(ctx.page, truncate(ctx.fonts, line, size, maxW), size, color, SQUARE / 2, top + i * lh + size * 0.9, { align: 'center' }));
+        ops.push(...ctx.fonts.textOps(ctx.scope, truncate(ctx.fonts, line, size, maxW), size, color, SQUARE / 2, top + i * lh + size * 0.9, { align: 'center' }));
     });
     return ops;
 };

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

@@ -89,13 +89,24 @@ export interface RenderCanvasToPdfInput {
     calibration?: PdfExportCalibration;
     /** TTF/OTF bytes of the primary font (Metropolis Bold in the apps). */
     primaryFont: Uint8Array;
+    /**
+     * 'annotations' (default): every layer, mark and tile becomes a PDF
+     * annotation object — selectable, movable and deletable in Preview /
+     * Acrobat, with the element's exact drawing as its appearance. 'flatten':
+     * everything is appended to the page content stream and cannot be edited.
+     */
+    mode?: 'annotations' | 'flatten';
 }
 export interface RenderCanvasToPdfResult {
     pdf: Uint8Array;
     pageCount: number;
+    /** Annotations written across all pages (0 in flatten mode). */
+    annotationCount: number;
     skipped: SkippedItem[];
 }
 export declare class PdfExportError extends Error {
-    readonly code: 'no-pdf-document' | 'page-count-mismatch' | 'page-geometry-mismatch' | 'encrypted' | 'corrupt';
+    readonly code: 'no-pdf-document' | 'page-count-mismatch' | 'page-geometry-mismatch'
+    /** The renderer was handed an encrypted PDF — run stripPdfEncryption first. */
+     | 'encrypted' | 'password-required' | 'password-incorrect' | 'unsupported' | 'corrupt';
     constructor(code: PdfExportError['code'], message: string);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",
@@ -52,7 +52,9 @@
     "pdf-lib": "1.17.1",
     "zod": "^4.4.3"
   },
+  "//peerDependencies-embedpdf": "OPTIONAL, server only: `@embedpdf/pdfium` is imported lazily by exactly one module (export/pdf/decrypt.ts, reached through the ./server entry) to strip PDF encryption before pdf-lib appends to a page. The apps never resolve it.",
   "peerDependencies": {
+    "@embedpdf/pdfium": ">=2.15.0",
     "@shopify/react-native-skia": ">=2.5.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.74.0",
@@ -60,6 +62,9 @@
     "react-native-reanimated": ">=3.0.0"
   },
   "peerDependenciesMeta": {
+    "@embedpdf/pdfium": {
+      "optional": true
+    },
     "react-native": {
       "optional": true
     },