@reekon-tools/boldr-utils 1.21.1 → 1.23.0

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -10,17 +10,9 @@ import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
 import { PlaneElement, PLANE_CHROME_COLOR, PLANE_GRID_COLOR, PLANE_GRID_OPACITY, PLANE_GRID_WIDTH, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
 import { StrokeElement } from './elements/StrokeElement.js';
-// Default visual constants for the measurement-annotation line (the tile itself
-// is a fixed-size overlay; only the line lives in Skia). Width is in doc units,
-// so it scales with zoom like the drawn line/arrow shapes. These are fallbacks:
-// a placed annotation may override them via `lineColor`/`lineWidth`/`lineCap`.
-// The leader line defaults to the medium width preset so it reads clearly
-// against the document; the rectangle border stays thinner (it outlines a
-// region rather than pointing at one).
-const MEASUREMENT_LINE_COLOR = '#0066FF';
-const MEASUREMENT_LINE_WIDTH = 16;
-const MEASUREMENT_RECT_WIDTH = 2;
-// Endpoint handle color — constant selection chrome, independent of the (now
+import { MEASUREMENT_LINE_COLOR, MEASUREMENT_LINE_WIDTH, MEASUREMENT_RECT_WIDTH, } from './measurementLineStyle.js';
+// The measurement-line defaults live in measurementLineStyle.ts (shared with
+// the PDF exporter). Endpoint handle color — constant selection chrome, independent of the (now
 // editable) line color so the handles stay legible on any line color.
 const MEASUREMENT_HANDLE_COLOR = '#0066FF';
 // Selection bounding box for strokes/shapes (measurements get handles instead).

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

@@ -0,0 +1,3 @@
+export declare const MEASUREMENT_LINE_COLOR = "#0066FF";
+export declare const MEASUREMENT_LINE_WIDTH = 16;
+export declare const MEASUREMENT_RECT_WIDTH = 2;

package/dist/annotation/canvas/measurementLineStyle.js

@@ -0,0 +1,14 @@
+// Default visual constants for the measurement-annotation line and rectangle
+// (the `placement: 'line'` / `'rectangle'` variants of PlacedMeasurementRef).
+// Widths are in doc units, so they scale with zoom like the drawn shapes. A
+// placed annotation may override them via `lineColor` / `lineWidth` /
+// `lineCap`. Skia-free so the PDF exporter (export/pdf) and the Skia scene
+// (AnnotationCanvasSkia) read ONE source — a change here re-styles both the
+// screen and the exported page.
+//
+// The leader line defaults to the medium width preset so it reads clearly
+// against the document; the rectangle border stays thinner (it outlines a
+// region rather than pointing at one).
+export const MEASUREMENT_LINE_COLOR = '#0066FF';
+export const MEASUREMENT_LINE_WIDTH = 16;
+export const MEASUREMENT_RECT_WIDTH = 2;

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/color.d.ts

@@ -0,0 +1,7 @@
+import { type RGB } from 'pdf-lib';
+export interface ParsedColor {
+    rgb: RGB;
+    /** 0..1. Absent alpha parses as 1. */
+    alpha: number;
+}
+export declare const parseHexColor: (input: string | undefined) => ParsedColor;

package/dist/export/pdf/color.js

@@ -0,0 +1,39 @@
+// Hex colour parsing for the PDF emitter. The canvas stores colours as CSS hex
+// strings (`#RGB`, `#RRGGBB`, `#RRGGBBAA`); pdf-lib wants 0..1 components and
+// PDF carries alpha separately (an ExtGState), so the two are split here.
+import { rgb } from 'pdf-lib';
+const BLACK = { rgb: rgb(0, 0, 0), alpha: 1 };
+const channel = (hex, i, width) => {
+    const raw = hex.slice(i, i + width);
+    const v = parseInt(width === 1 ? raw + raw : raw, 16);
+    return Number.isNaN(v) ? 0 : v / 255;
+};
+export const parseHexColor = (input) => {
+    if (!input)
+        return BLACK;
+    const hex = input.trim().replace(/^#/, '');
+    switch (hex.length) {
+        case 3:
+            return {
+                rgb: rgb(channel(hex, 0, 1), channel(hex, 1, 1), channel(hex, 2, 1)),
+                alpha: 1,
+            };
+        case 4:
+            return {
+                rgb: rgb(channel(hex, 0, 1), channel(hex, 1, 1), channel(hex, 2, 1)),
+                alpha: channel(hex, 3, 1),
+            };
+        case 6:
+            return {
+                rgb: rgb(channel(hex, 0, 2), channel(hex, 2, 2), channel(hex, 4, 2)),
+                alpha: 1,
+            };
+        case 8:
+            return {
+                rgb: rgb(channel(hex, 0, 2), channel(hex, 2, 2), channel(hex, 4, 2)),
+                alpha: channel(hex, 6, 2),
+            };
+        default:
+            return BLACK;
+    }
+};

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/emit.d.ts

@@ -0,0 +1,37 @@
+import { LineCapStyle, type PDFName, type PDFOperator } from 'pdf-lib';
+import type { StrokeCap, Vec2 } from '../../types/annotation.js';
+import type { AffineMatrix } from './pageMapping.js';
+export declare const withMatrix: (m: AffineMatrix, ops: PDFOperator[]) => PDFOperator[];
+/** Flip back to y-up at (x, y): text and images are drawn upright inside it. */
+export declare const uprightAt: (x: number, y: number) => AffineMatrix;
+export declare const lineCapOf: (cap: StrokeCap | undefined) => LineCapStyle;
+export interface StrokeStyle {
+    color: string;
+    width: number;
+    cap?: StrokeCap;
+    join?: 'round' | 'miter';
+    dash?: boolean;
+    /** ExtGState resource name carrying the element's opacity, if any. */
+    graphicsState?: PDFName;
+}
+/** Operators that set the stroking state for a Skia-style stroked paint. */
+export declare const strokeStateOps: (s: StrokeStyle) => PDFOperator[];
+export declare const fillStateOps: (color: string, graphicsState?: PDFName) => PDFOperator[];
+/** Path construction for a polyline over `points`; no painting operator. */
+export declare const polylinePathOps: (points: readonly Vec2[], close?: boolean) => PDFOperator[];
+/** Same, over the flat [x, y, x, y, …] array strokes store. */
+export declare const flatPolylinePathOps: (points: readonly number[]) => PDFOperator[];
+export declare const circlePathOps: (cx: number, cy: number, r: number) => PDFOperator[];
+export declare const rectPathOps: (x: number, y: number, w: number, h: number) => PDFOperator[];
+/** Rounded rectangle path in a y-down space (radius clamped to half a side). */
+export declare const roundedRectPathOps: (x: number, y: number, w: number, h: number, radius: number) => PDFOperator[];
+/** Intersect the clip with an axis-aligned rect (no painting). */
+export declare const clipRectOps: (x: number, y: number, w: number, h: number) => PDFOperator[];
+export declare const strokeOp: () => PDFOperator;
+export declare const fillOp: () => PDFOperator;
+/**
+ * Draw an image XObject so it occupies the y-down rect (x, y, w, h) with its
+ * top row at `y`. PDF maps the unit square's TOP edge to the image's first
+ * row, so under a y-down CTM the image must be un-flipped locally.
+ */
+export declare const imageOps: (name: PDFName, x: number, y: number, w: number, h: number, graphicsState?: PDFName) => PDFOperator[];

package/dist/export/pdf/emit.js

@@ -0,0 +1,129 @@
+// Low-level PDF operator helpers for the exporter. Everything here works in
+// the CURRENT coordinate system (whatever `cm` is in force), so the same
+// helpers draw marks in doc space and tile chrome in a tile's design space.
+import { LineCapStyle, LineJoinStyle, appendBezierCurve, clip, closePath, concatTransformationMatrix, degrees, drawImage, endPath, fill, lineTo, moveTo, popGraphicsState, pushGraphicsState, rectangle, setDashPattern, setFillingColor, setGraphicsState, setLineCap, setLineJoin, setLineWidth, setStrokingColor, stroke, } from 'pdf-lib';
+import { dashIntervals, toSkiaStrokeCap, } from '../../annotation/canvas/strokeGeometry.js';
+import { parseHexColor } from './color.js';
+/** Bézier circle constant. */
+const KAPPA = 0.5522847498307936;
+export const withMatrix = (m, ops) => [
+    pushGraphicsState(),
+    concatTransformationMatrix(m[0], m[1], m[2], m[3], m[4], m[5]),
+    ...ops,
+    popGraphicsState(),
+];
+/** Flip back to y-up at (x, y): text and images are drawn upright inside it. */
+export const uprightAt = (x, y) => [
+    1,
+    0,
+    0,
+    -1,
+    x,
+    y,
+];
+export const lineCapOf = (cap) => {
+    switch (toSkiaStrokeCap(cap)) {
+        case 'butt':
+            return LineCapStyle.Butt;
+        case 'square':
+            return LineCapStyle.Projecting;
+        default:
+            return LineCapStyle.Round;
+    }
+};
+/** Operators that set the stroking state for a Skia-style stroked paint. */
+export const strokeStateOps = (s) => {
+    const ops = [];
+    if (s.graphicsState)
+        ops.push(setGraphicsState(s.graphicsState));
+    ops.push(setStrokingColor(parseHexColor(s.color).rgb), setLineWidth(s.width), setLineCap(lineCapOf(s.cap)), setLineJoin(s.join === 'round' ? LineJoinStyle.Round : LineJoinStyle.Miter));
+    if (s.dash) {
+        const [on, off] = dashIntervals(s.width);
+        ops.push(setDashPattern([on, off], 0));
+    }
+    return ops;
+};
+export const fillStateOps = (color, graphicsState) => {
+    const ops = [];
+    if (graphicsState)
+        ops.push(setGraphicsState(graphicsState));
+    ops.push(setFillingColor(parseHexColor(color).rgb));
+    return ops;
+};
+/** Path construction for a polyline over `points`; no painting operator. */
+export const polylinePathOps = (points, close = false) => {
+    if (points.length === 0)
+        return [];
+    const ops = [moveTo(points[0].x, points[0].y)];
+    for (let i = 1; i < points.length; i++) {
+        ops.push(lineTo(points[i].x, points[i].y));
+    }
+    if (close)
+        ops.push(closePath());
+    return ops;
+};
+/** Same, over the flat [x, y, x, y, …] array strokes store. */
+export const flatPolylinePathOps = (points) => {
+    if (points.length < 2)
+        return [];
+    const ops = [moveTo(points[0], points[1])];
+    for (let i = 2; i + 1 < points.length; i += 2) {
+        ops.push(lineTo(points[i], points[i + 1]));
+    }
+    return ops;
+};
+export const circlePathOps = (cx, cy, r) => {
+    const k = KAPPA * r;
+    return [
+        moveTo(cx + r, cy),
+        appendBezierCurve(cx + r, cy + k, cx + k, cy + r, cx, cy + r),
+        appendBezierCurve(cx - k, cy + r, cx - r, cy + k, cx - r, cy),
+        appendBezierCurve(cx - r, cy - k, cx - k, cy - r, cx, cy - r),
+        appendBezierCurve(cx + k, cy - r, cx + r, cy - k, cx + r, cy),
+        closePath(),
+    ];
+};
+export const rectPathOps = (x, y, w, h) => [rectangle(x, y, w, h)];
+/** Rounded rectangle path in a y-down space (radius clamped to half a side). */
+export const roundedRectPathOps = (x, y, w, h, radius) => {
+    const r = Math.max(0, Math.min(radius, w / 2, h / 2));
+    if (r === 0)
+        return rectPathOps(x, y, w, h);
+    const k = KAPPA * r;
+    return [
+        moveTo(x + r, y),
+        lineTo(x + w - r, y),
+        appendBezierCurve(x + w - r + k, y, x + w, y + r - k, x + w, y + r),
+        lineTo(x + w, y + h - r),
+        appendBezierCurve(x + w, y + h - r + k, x + w - r + k, y + h, x + w - r, y + h),
+        lineTo(x + r, y + h),
+        appendBezierCurve(x + r - k, y + h, x, y + h - r + k, x, y + h - r),
+        lineTo(x, y + r),
+        appendBezierCurve(x, y + r - k, x + r - k, y, x + r, y),
+        closePath(),
+    ];
+};
+/** Intersect the clip with an axis-aligned rect (no painting). */
+export const clipRectOps = (x, y, w, h) => [rectangle(x, y, w, h), clip(), endPath()];
+export const strokeOp = () => stroke();
+export const fillOp = () => fill();
+/**
+ * Draw an image XObject so it occupies the y-down rect (x, y, w, h) with its
+ * top row at `y`. PDF maps the unit square's TOP edge to the image's first
+ * row, so under a y-down CTM the image must be un-flipped locally.
+ */
+export const imageOps = (name, x, y, w, h, graphicsState) => {
+    const ops = [pushGraphicsState()];
+    if (graphicsState)
+        ops.push(setGraphicsState(graphicsState));
+    ops.push(concatTransformationMatrix(w, 0, 0, -h, x, y + h), ...drawImage(name, {
+        x: 0,
+        y: 0,
+        width: 1,
+        height: 1,
+        rotate: degrees(0),
+        xSkew: degrees(0),
+        ySkew: degrees(0),
+    }), popGraphicsState());
+    return ops;
+};

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

@@ -0,0 +1,37 @@
+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;
+    /** ExtGState name carrying an opacity, if any. */
+    graphicsState?: PDFName;
+}
+export declare class PdfFonts {
+    private readonly primary;
+    private readonly fallback;
+    private constructor();
+    static create(doc: PDFDocument, primaryBytes: Uint8Array): Promise<PdfFonts>;
+    /** Whether the primary face has a glyph for every code point of `text`. */
+    private primaryCovers;
+    /** Drop the code points the standard fallback cannot encode. */
+    private fallbackUsable;
+    /**
+     * The face to draw `text` with and the text it can actually show. The
+     * primary wins when it covers every glyph; otherwise the fallback, minus
+     * anything even it cannot encode. `dropped` is true when glyphs were lost.
+     */
+    pick(text: string): {
+        font: PDFFont;
+        text: string;
+        dropped: boolean;
+    };
+    width(text: string, size: number): number;
+    /**
+     * 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(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;
+}