@build-qube/papyra 0.2.0 → 0.3.0

package/README.md

@@ -104,6 +104,24 @@ Encrypted files throw `PasswordRequiredError` or `IncorrectPasswordError`, both
 extending `PasswordError` with a `retry` flag, so one dialog handles the cold ask and
 the wrong answer.
 
+## Rotate the view
+
+```ts
+const vp = viewport(doc.pageSize(index), { fitWidth: 1600, rotation: 90 });
+
+paintToCanvas(await doc.renderPage(index, { dpi: vp.dpi }), canvas, {
+  rotation: vp.rotation,
+});
+const box = viewportRect(link.rect, vp);   // the link layer, turned to match
+```
+
+Pages render unrotated and the canvas does the turning, so a rotate button costs no
+render. Size through the viewport rather than with `fitWidth` directly: turned, the
+width on screen is the page's height, and `vp.dpi` carries the answer back.
+
+Renders draw annotations by default. Pass `{ annotations: false }` when you are drawing
+your own link or highlight layer, or they appear twice.
+
 ## Two things that will bite you
 
 **Size with `fitWidth`, not `dpi`.** Page areas vary by two orders of magnitude. At a

package/dist/attachments.d.ts

@@ -0,0 +1,76 @@
+import type { Attachment as NativeAttachment } from '@build-qube/papyra-native';
+/**
+ * A file embedded in the document.
+ *
+ * Metadata only. The bytes come from {@link Document.attachmentData}, because listing
+ * what a document carries is a different question from opening one of the things it
+ * carries, and an embedded file is as large as it is.
+ */
+export interface Attachment {
+    /** Position in {@link Document.attachments}, and what identifies it for a fetch. */
+    readonly index: number;
+    /**
+     * The name to save the file under.
+     *
+     * `/UF` where the document provides it — the Unicode spelling, and the one the spec
+     * tells a reader to prefer — falling back to `/F`, then to the name the file was
+     * filed under. Never empty.
+     */
+    readonly name: string;
+    /** The document's own description of what the file is for. */
+    readonly description: string | null;
+    /**
+     * The declared media type, e.g. `'application/xml'`.
+     *
+     * Absent more often than not, so fall back to the extension on {@link name} rather
+     * than treating this as the answer. {@link attachmentMediaType} does exactly that.
+     */
+    readonly mediaType: string | null;
+    /**
+     * Length in bytes, uncompressed, **as the document claims it**.
+     *
+     * Not a measurement: reading the true length means decompressing the stream, which
+     * is the work this type exists to defer. Fine for a size column; not something to
+     * allocate against.
+     */
+    readonly size: number | null;
+    /** Creation date, ISO 8601. */
+    readonly created: string | null;
+    /** Modification date, ISO 8601. */
+    readonly modified: string | null;
+    /**
+     * What the file is to the document: `'Source'`, `'Data'`, `'Alternative'`,
+     * `'Supplement'`, `'EncryptedPayload'` or `'Unspecified'`.
+     *
+     * This is what identifies a hybrid invoice. A ZUGFeRD or Factur-X PDF carries its
+     * XML with a relationship of `Alternative` or `Data`, and that is the difference
+     * between a machine-readable invoice and a PDF with a file stapled to it — see
+     * {@link isInvoiceAttachment}.
+     */
+    readonly relationship: string | null;
+}
+/** @internal */
+export declare function toAttachment(native: NativeAttachment, index: number): Attachment;
+/**
+ * The attachment's media type, falling back to its extension.
+ *
+ * `'application/octet-stream'` when neither answers, which is the honest default for
+ * bytes nothing describes — and the one a download will not misrender.
+ */
+export declare function attachmentMediaType(file: Attachment): string;
+/**
+ * Whether this attachment is the machine-readable half of a hybrid invoice.
+ *
+ * ZUGFeRD, Factur-X, Order-X and XRechnung all work the same way: the PDF is what a
+ * person reads, and an embedded XML file is what an accounting system reads. Both
+ * halves are the same invoice, and a consumer that ignores the XML is retyping data
+ * the document already carries.
+ *
+ * Matched on the standardised filename rather than on
+ * {@link Attachment.relationship} alone. The relationship narrows it — the standards
+ * require `Alternative` or `Data` — but producers get it wrong often enough that
+ * requiring it would miss real invoices, while the filenames are fixed by the
+ * specifications and are what every other implementation keys on.
+ */
+export declare function isInvoiceAttachment(file: Attachment): boolean;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,gBAAgB;AAChB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,GACZ,UAAU,CAWZ;AAiBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAK5D;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE7D"}

package/dist/attachments.js

@@ -0,0 +1,65 @@
+/** @internal */
+export function toAttachment(native, index) {
+    return {
+        index,
+        name: native.name,
+        description: native.description ?? null,
+        mediaType: native.mediaType ?? null,
+        size: native.size ?? null,
+        created: native.created ?? null,
+        modified: native.modified ?? null,
+        relationship: native.relationship ?? null,
+    };
+}
+/** Extension to media type, for the majority of files that declare none. */
+const BY_EXTENSION = {
+    csv: 'text/csv',
+    html: 'text/html',
+    json: 'application/json',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    svg: 'image/svg+xml',
+    txt: 'text/plain',
+    xml: 'application/xml',
+    zip: 'application/zip',
+};
+/**
+ * The attachment's media type, falling back to its extension.
+ *
+ * `'application/octet-stream'` when neither answers, which is the honest default for
+ * bytes nothing describes — and the one a download will not misrender.
+ */
+export function attachmentMediaType(file) {
+    if (file.mediaType)
+        return file.mediaType;
+    const dot = file.name.lastIndexOf('.');
+    const extension = dot < 0 ? '' : file.name.slice(dot + 1).toLowerCase();
+    return BY_EXTENSION[extension] ?? 'application/octet-stream';
+}
+/** The filenames the hybrid-invoice standards define, lowercased. */
+const INVOICE_NAMES = new Set([
+    'factur-x.xml',
+    'zugferd-invoice.xml',
+    'xrechnung.xml',
+    'order-x.xml',
+]);
+/**
+ * Whether this attachment is the machine-readable half of a hybrid invoice.
+ *
+ * ZUGFeRD, Factur-X, Order-X and XRechnung all work the same way: the PDF is what a
+ * person reads, and an embedded XML file is what an accounting system reads. Both
+ * halves are the same invoice, and a consumer that ignores the XML is retyping data
+ * the document already carries.
+ *
+ * Matched on the standardised filename rather than on
+ * {@link Attachment.relationship} alone. The relationship narrows it — the standards
+ * require `Alternative` or `Data` — but producers get it wrong often enough that
+ * requiring it would miss real invoices, while the filenames are fixed by the
+ * specifications and are what every other implementation keys on.
+ */
+export function isInvoiceAttachment(file) {
+    return INVOICE_NAMES.has(file.name.toLowerCase());
+}
+//# sourceMappingURL=attachments.js.map

package/dist/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAqDA,gBAAgB;AAChB,MAAM,UAAU,YAAY,CAC1B,MAAwB,EACxB,KAAa;IAEb,OAAO;QACL,KAAK;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;QACvC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;QACnC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;QACzB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;KAC1C,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,YAAY,GAA2B;IAC3C,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,kBAAkB;IACxB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,eAAe;IACpB,GAAG,EAAE,YAAY;IACjB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;CACvB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAClD,IAAI,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxE,OAAO,YAAY,CAAC,SAAS,CAAC,IAAI,0BAA0B,CAAC;AAC/D,CAAC;AAED,qEAAqE;AACrE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,cAAc;IACd,qBAAqB;IACrB,eAAe;IACf,aAAa;CACd,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAClD,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/canvas.d.ts

@@ -1,4 +1,5 @@
 import type { RenderedPage } from './types.js';
+import type { Rotation } from './viewport.js';
 /**
  * Wrap a rendered page as `ImageData`, ready for `putImageData`.
  *
@@ -7,6 +8,30 @@ import type { RenderedPage } from './types.js';
  * unconditionally keeps both runtimes on the same path.
  */
 export declare function toImageData(page: RenderedPage): ImageData;
-/** Paint a rendered page onto a canvas, resizing the canvas to match. */
-export declare function paintToCanvas(page: RenderedPage, canvas: HTMLCanvasElement | OffscreenCanvas): void;
+/** How to paint. */
+export interface PaintOptions {
+    /**
+     * Quarter turns clockwise to apply while drawing. Defaults to none.
+     *
+     * Free in the sense that matters: the pixels are not copied twice and no rotated
+     * bitmap is retained. Pair it with a {@link Viewport} of the same rotation so that
+     * link regions and text highlights land on the same page the pixels do.
+     */
+    rotation?: Rotation;
+}
+/**
+ * Paint a rendered page onto a canvas, resizing the canvas to match.
+ *
+ * With a `rotation` the canvas takes the turned dimensions — a 90° view of a portrait
+ * page is a landscape canvas.
+ *
+ * @example
+ * ```ts
+ * const vp = viewport(doc.pageSize(0), { fitWidth: 1600, rotation: 90 });
+ * paintToCanvas(await doc.renderPage(0, { dpi: vp.dpi }), canvas, {
+ *   rotation: vp.rotation,
+ * });
+ * ```
+ */
+export declare function paintToCanvas(page: RenderedPage, canvas: HTMLCanvasElement | OffscreenCanvas, options?: PaintOptions): void;
 //# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAMzD;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAC1C,IAAI,CASN"}
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAMzD;AAED,oBAAoB;AACpB,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,iBAAiB,GAAG,eAAe,EAC3C,OAAO,GAAE,YAAiB,GACzB,IAAI,CA+BN"}

package/dist/canvas.js

@@ -8,13 +8,66 @@
 export function toImageData(page) {
     return new ImageData(Uint8ClampedArray.from(page.data), page.width, page.height);
 }
-/** Paint a rendered page onto a canvas, resizing the canvas to match. */
-export function paintToCanvas(page, canvas) {
-    canvas.width = page.width;
-    canvas.height = page.height;
+/**
+ * Paint a rendered page onto a canvas, resizing the canvas to match.
+ *
+ * With a `rotation` the canvas takes the turned dimensions — a 90° view of a portrait
+ * page is a landscape canvas.
+ *
+ * @example
+ * ```ts
+ * const vp = viewport(doc.pageSize(0), { fitWidth: 1600, rotation: 90 });
+ * paintToCanvas(await doc.renderPage(0, { dpi: vp.dpi }), canvas, {
+ *   rotation: vp.rotation,
+ * });
+ * ```
+ */
+export function paintToCanvas(page, canvas, options = {}) {
+    const rotation = options.rotation ?? 0;
+    const turned = rotation === 90 || rotation === 270;
+    canvas.width = turned ? page.height : page.width;
+    canvas.height = turned ? page.width : page.height;
     const ctx = canvas.getContext('2d');
     if (!ctx)
         throw new Error('papyra: could not get a 2d canvas context');
-    ctx.putImageData(toImageData(page), 0, 0);
+    if (rotation === 0) {
+        ctx.putImageData(toImageData(page), 0, 0);
+        return;
+    }
+    // `putImageData` writes straight to the backing store and ignores the transform, so
+    // a rotation cannot go through it. The pixels land on a scratch surface first and
+    // are then blitted under a transform, which is one extra copy — against rotating
+    // the buffer ourselves, which is a copy plus a per-pixel loop in JS.
+    const scratch = scratchCanvas(page.width, page.height);
+    const scratchCtx = scratch.getContext('2d');
+    if (!scratchCtx)
+        throw new Error('papyra: could not get a 2d canvas context');
+    scratchCtx.putImageData(toImageData(page), 0, 0);
+    // Each pair puts the rotated page's origin back at the canvas corner: at 90° the
+    // page's top-left corner ends up top-right, so the axes move there first.
+    if (rotation === 90)
+        ctx.translate(canvas.width, 0);
+    else if (rotation === 180)
+        ctx.translate(canvas.width, canvas.height);
+    else
+        ctx.translate(0, canvas.height);
+    ctx.rotate((rotation * Math.PI) / 180);
+    ctx.drawImage(scratch, 0, 0);
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+}
+/**
+ * A surface to hold the unrotated pixels.
+ *
+ * `OffscreenCanvas` when there is one — it is the only option inside a worker, where
+ * there is no `document` to create an element from.
+ */
+function scratchCanvas(width, height) {
+    if (typeof OffscreenCanvas !== 'undefined') {
+        return new OffscreenCanvas(width, height);
+    }
+    const el = document.createElement('canvas');
+    el.width = width;
+    el.height = height;
+    return el;
 }
 //# sourceMappingURL=canvas.js.map

package/dist/canvas.js.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,OAAO,IAAI,SAAS,CAClB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EACjC,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,MAAM,CACZ,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAC3B,IAAkB,EAClB,MAA2C;IAE3C,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAG1B,CAAC;IACT,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACvE,GAAG,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,OAAO,IAAI,SAAS,CAClB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EACjC,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,MAAM,CACZ,CAAC;AACJ,CAAC;AAcD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAkB,EAClB,MAA2C,EAC3C,OAAO,GAAiB,EAAE;IAE1B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,KAAK,EAAE,IAAI,QAAQ,KAAK,GAAG,CAAC;IACnD,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IACjD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAElD,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAsB,CAAC;IACzD,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAEvE,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,GAAG,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IAED,oFAAoF;IACpF,kFAAkF;IAClF,iFAAiF;IACjF,qEAAqE;IACrE,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAsB,CAAC;IACjE,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC9E,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEjD,iFAAiF;IACjF,0EAA0E;IAC1E,IAAI,QAAQ,KAAK,EAAE;QAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;SAC/C,IAAI,QAAQ,KAAK,GAAG;QAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;;QACjE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC;IACvC,GAAG,CAAC,SAAS,CAAC,OAA4B,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAa,EAAE,MAAc;IAClD,IAAI,OAAO,eAAe,KAAK,WAAW,EAAE,CAAC;QAC3C,OAAO,IAAI,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC5C,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC;IACjB,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/document.d.ts

@@ -1,10 +1,12 @@
 import { PdfDocument as NativeDocument } from '@build-qube/papyra-native';
+import { type Attachment } from './attachments.js';
 import { type CacheStats } from './cache.js';
 import { PageImage, type SvgPage } from './encode.js';
 import { type PageLink } from './links.js';
 import { type OutlineNode } from './outline.js';
 import { type JobHandle } from './scheduler.js';
 import { type SearchMatch } from './search.js';
+import { type StructNode } from './structure.js';
 import { type PageText } from './text.js';
 import type { DocumentMetadata, OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, SearchOptions, StreamedPage, StreamOptions, SvgOptions } from './types.js';
 /** A queued render, plus whether it was served from cache without rendering at all. */
@@ -139,6 +141,65 @@ export declare class Document {
      * ```
      */
     pageLabels(): Promise<readonly string[]>;
+    /**
+     * The document structure tree, if the document is tagged.
+     *
+     * Resolves to an **empty array** for an untagged document, which is the common
+     * case — most PDFs carry no `/StructTreeRoot` at all. That emptiness is the signal
+     * to fall back to {@link Document.pageText} on its own.
+     *
+     * What it buys, when it is there, is the thing extraction otherwise cannot get:
+     * the reading order the author declared. {@link Document.pageText} reports lines in
+     * content-stream order, and a two-column page is free to draw its columns
+     * interleaved. Pass both to {@link readingOrder} to resolve it.
+     *
+     * The walk runs off the event loop and the result is memoised — it is one walk for
+     * the whole document, not one per page.
+     *
+     * @example
+     * ```ts
+     * const [text, tree] = await Promise.all([
+     *   doc.pageText(0),
+     *   doc.structTree(),
+     * ]);
+     * for (const { line, node } of readingOrder(text, tree)) {
+     *   console.log(node?.role ?? '-', line.text);
+     * }
+     * ```
+     */
+    structTree(): Promise<StructNode[]>;
+    /**
+     * The files embedded in the document, in the order it files them.
+     *
+     * Resolves to an **empty array** when there are none, which is the common case.
+     * Metadata only — {@link Document.attachmentData} fetches the bytes, so listing a
+     * document's attachments never decompresses one.
+     *
+     * Worth honouring even in a viewer that has no use for the files themselves: a
+     * ZUGFeRD or Factur-X invoice keeps its machine-readable half here, and a reader
+     * that never mentions it leaves the user retyping data the document is carrying.
+     * See {@link isInvoiceAttachment}.
+     *
+     * The walk runs off the event loop and the result is memoised.
+     *
+     * @example
+     * ```ts
+     * for (const file of await doc.attachments()) {
+     *   const bytes = await doc.attachmentData(file.index);
+     *   await write(file.name, bytes);
+     * }
+     * ```
+     */
+    attachments(): Promise<readonly Attachment[]>;
+    /**
+     * Decompress one embedded file, by its {@link Attachment.index}.
+     *
+     * Not cached: the bytes are the caller's to keep or drop, and holding every
+     * attachment a document was ever asked for is the cost {@link Document.attachments}
+     * is shaped to avoid. Rejects if the index names no attachment, or if the stream
+     * cannot be decoded.
+     */
+    attachmentData(index: number): Promise<Uint8Array>;
     /**
      * The links on one page — where they are, and where they go.
      *

package/dist/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,IAAI,cAAc,EAG9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAW,MAAM,aAAa,CAAC;AAG/D,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,YAAY,CAAC;AACvD,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAOlE,OAAO,EAAoB,KAAK,SAAS,EAAa,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,WAAW,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACX,MAAM,YAAY,CAAC;AA2CpB,uFAAuF;AACvF,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,YAAY,CAAC;IAC3D;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AA+B3C;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED;;;;;;GAMG;AACH,qBAAa,QAAQ;;IAoBnB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,8CAA8C;IAC9C,YACE,KAAK,EAAE,cAAc,EACrB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,GAAE,WAAgB,EAoB1B;IAED,sEAAsE;IACtE,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,8BAA8B;IAC9B,UAAU,IAAI,IAAI,CAEjB;IAED,sFAAsF;IACtF,IAAI,MAAM,IAAI;QACZ,gFAAgF;QAChF,OAAO,EAAE,MAAM,CAAC;QAChB,4EAA4E;QAC5E,OAAO,EAAE,MAAM,CAAC;QAChB;;;;;WAKG;QACH,YAAY,EAAE,MAAM,CAAC;KACtB,CAMA;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;OAUG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAUtC;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,gBAAgB,CAG/B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAO7C;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CA0BvD;IAED,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAEhC;IAED,yDAAyD;IACnD,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAEvB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,SAAS,CAAC,CAEpB;IAED;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,WAAW,CAoBnE;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzE;IAED;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,SAAS,CA0B5D;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAqB/D;IA4BD;;;;;;;;;;;OAWG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CAoBzB;IAED;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,cAAc,CAAC,YAAY,CAAC,CA2CvE;IAED;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACxD,OAAO,CAAC,QAAQ,CAAC,CAgCnB;IAED;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;IAiBD;;;;;;;;;;;;;;;;;OAiBG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAAC,WAAW,CAAC,CAmB7B;IAED,2EAA2E;IAC3E,IAAI,SAAS,IAAI,UAAU,CAE1B;IAED,wDAAwD;IACxD,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/document.js

@@ -1,4 +1,5 @@
 import { PdfDocument as NativeDocument, } from '@build-qube/papyra-native';
+import { toAttachment } from './attachments.js';
 import { RenderCache } from './cache.js';
 import { PageImage, svgPage } from './encode.js';
 import { rethrowLoadError } from './errors.js';
@@ -9,6 +10,7 @@ import { currentRuntime, hardwareConcurrency, init, MAX_WASM_CONCURRENCY, } from
 import { DEFAULT_PRIORITY, Scheduler } from './scheduler.js';
 import { searchPageText } from './search.js';
 import { toBytes } from './source.js';
+import { buildStructTree } from './structure.js';
 import { pageTextBytes, toPageText } from './text.js';
 const DEFAULT_DPI = 72;
 /**
@@ -44,6 +46,17 @@ const LINK_BYTES = 96;
  * than one that takes another beat to fill in.
  */
 const DEFAULT_TEXT_PRIORITY = 3;
+/**
+ * Cache- and coalescing-key suffix for the annotation switch.
+ *
+ * Empty in the default case, so the ordinary key keeps the shape it has always had.
+ * The suffix has to exist at all because the scheduler coalesces on this string and
+ * the cache is looked up by it: without it, asking for a page with annotations off
+ * would be served the bitmap that still has them drawn on.
+ */
+function annotationKey(options) {
+    return options.annotations === false ? ':noannots' : '';
+}
 /** napi omits absent strings rather than nulling them; normalise to one shape. */
 function toMetadata(info) {
     return {
@@ -110,6 +123,10 @@ export class Document {
     #linksPending = new Map();
     /** Memoised by {@link outline}; the outline cannot change under us. */
     #outline;
+    /** Memoised by {@link attachments}. */
+    #attachments;
+    /** Memoised by {@link structTree}. */
+    #structure;
     /** Memoised by {@link pageLabels}. */
     #labels;
     /** Memoised by {@link metadata}. */
@@ -242,6 +259,87 @@ export class Document {
         });
         return this.#labels;
     }
+    /**
+     * The document structure tree, if the document is tagged.
+     *
+     * Resolves to an **empty array** for an untagged document, which is the common
+     * case — most PDFs carry no `/StructTreeRoot` at all. That emptiness is the signal
+     * to fall back to {@link Document.pageText} on its own.
+     *
+     * What it buys, when it is there, is the thing extraction otherwise cannot get:
+     * the reading order the author declared. {@link Document.pageText} reports lines in
+     * content-stream order, and a two-column page is free to draw its columns
+     * interleaved. Pass both to {@link readingOrder} to resolve it.
+     *
+     * The walk runs off the event loop and the result is memoised — it is one walk for
+     * the whole document, not one per page.
+     *
+     * @example
+     * ```ts
+     * const [text, tree] = await Promise.all([
+     *   doc.pageText(0),
+     *   doc.structTree(),
+     * ]);
+     * for (const { line, node } of readingOrder(text, tree)) {
+     *   console.log(node?.role ?? '-', line.text);
+     * }
+     * ```
+     */
+    async structTree() {
+        this.#structure ??= this.#inner
+            .structTree()
+            .then(buildStructTree)
+            // A failed walk must not be cached as a permanent absence of structure.
+            .catch((e) => {
+            this.#structure = undefined;
+            throw e;
+        });
+        return this.#structure;
+    }
+    /**
+     * The files embedded in the document, in the order it files them.
+     *
+     * Resolves to an **empty array** when there are none, which is the common case.
+     * Metadata only — {@link Document.attachmentData} fetches the bytes, so listing a
+     * document's attachments never decompresses one.
+     *
+     * Worth honouring even in a viewer that has no use for the files themselves: a
+     * ZUGFeRD or Factur-X invoice keeps its machine-readable half here, and a reader
+     * that never mentions it leaves the user retyping data the document is carrying.
+     * See {@link isInvoiceAttachment}.
+     *
+     * The walk runs off the event loop and the result is memoised.
+     *
+     * @example
+     * ```ts
+     * for (const file of await doc.attachments()) {
+     *   const bytes = await doc.attachmentData(file.index);
+     *   await write(file.name, bytes);
+     * }
+     * ```
+     */
+    async attachments() {
+        this.#attachments ??= this.#inner
+            .attachments()
+            .then((files) => files.map(toAttachment))
+            // A failed walk must not be cached as a permanent absence of attachments.
+            .catch((e) => {
+            this.#attachments = undefined;
+            throw e;
+        });
+        return this.#attachments;
+    }
+    /**
+     * Decompress one embedded file, by its {@link Attachment.index}.
+     *
+     * Not cached: the bytes are the caller's to keep or drop, and holding every
+     * attachment a document was ever asked for is the cost {@link Document.attachments}
+     * is shaped to avoid. Rejects if the index names no attachment, or if the stream
+     * cannot be decoded.
+     */
+    async attachmentData(index) {
+        return this.#inner.attachmentData(index);
+    }
     /**
      * The links on one page — where they are, and where they go.
      *
@@ -334,9 +432,9 @@ export class Document {
         // A distinct key space from `render`, so an image request never coalesces onto a
         // pending raw render (different return type) or vice versa.
         const handle = this.#scheduler.submit({
-            key: `image:${index}@${dpi.toFixed(4)}`,
+            key: `image:${index}@${dpi.toFixed(4)}${annotationKey(options)}`,
             priority: options.priority ?? DEFAULT_PRIORITY,
-            run: () => this.#inner.renderPageImageAsync(index, dpi, options.signal).then((img) => new PageImage(img)),
+            run: () => this.#inner.renderPageImageAsync(index, dpi, options.annotations, options.signal).then((img) => new PageImage(img)),
         });
         attachSignal(handle, options.signal);
         return handle;
@@ -375,9 +473,9 @@ export class Document {
         const handle = this.#scheduler.submit({
             // The background is part of the key: the scheduler coalesces same-key requests,
             // and an opaque and a transparent conversion of one page are different output.
-            key: `svg:${index}${opaque ? '' : ':transparent'}`,
+            key: `svg:${index}${opaque ? '' : ':transparent'}${annotationKey(options)}`,
             priority: options.priority ?? DEFAULT_PRIORITY,
-            run: () => this.#inner.renderPageSvgAsync(index, opaque, options.signal).then(svgPage),
+            run: () => this.#inner.renderPageSvgAsync(index, opaque, options.annotations, options.signal).then(svgPage),
         });
         attachSignal(handle, options.signal);
         return handle;
@@ -400,14 +498,14 @@ export class Document {
      */
     render(index, options = {}) {
         const dpi = this.#resolveDpi(index, options);
-        const key = `${index}@${dpi.toFixed(4)}`;
+        const key = `${index}@${dpi.toFixed(4)}${annotationKey(options)}`;
         const hit = this.#cache.get(key);
         if (hit)
             return cachedHandle(key, hit);
         const handle = this.#scheduler.submit({
             key,
             priority: options.priority ?? DEFAULT_PRIORITY,
-            run: () => this.#inner.renderPageAsync(index, dpi).then((page) => {
+            run: () => this.#inner.renderPageAsync(index, dpi, options.annotations).then((page) => {
                 this.#cache.set(key, page);
                 return page;
             }),
@@ -455,7 +553,7 @@ export class Document {
             let dpi = DEFAULT_DPI;
             for (let i = start; i < end; i++)
                 dpi = this.#resolveDpi(i, options);
-            return (await this.#inner.renderPagesAsync(start, end, dpi));
+            return (await this.#inner.renderPagesAsync(start, end, dpi, options.annotations));
         }
         const out = [];
         for await (const { page, bitmap } of this.stream({