@build-qube/papyra 0.1.0 → 0.3.0

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A document that could not be opened because of its password.
+ *
+ * The base of both password failures, because a viewer handles them in one place: a
+ * dialog that either asks for the first time or says the last answer was wrong.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   doc = await open(file, { password });
+ * } catch (e) {
+ *   if (e instanceof PasswordError) showPasswordDialog({ retry: e.retry });
+ *   else throw e;
+ * }
+ * ```
+ */
+export declare class PasswordError extends Error {
+    /**
+     * A password was already tried and rejected.
+     *
+     * `false` the first time, so a dialog can open without an error on it.
+     */
+    readonly retry: boolean;
+}
+/** The document is encrypted and {@link OpenOptions.password} was not supplied. */
+export declare class PasswordRequiredError extends PasswordError {
+    /** Always `'PasswordRequiredError'`. */
+    readonly name = "PasswordRequiredError";
+    readonly retry = false;
+    constructor(message?: string);
+}
+/** A password was supplied and it did not open the document. */
+export declare class IncorrectPasswordError extends PasswordError {
+    /** Always `'IncorrectPasswordError'`. */
+    readonly name = "IncorrectPasswordError";
+    readonly retry = true;
+    constructor(message?: string);
+}
+/**
+ * Rethrow a load failure as itself, or as the typed error it was tagged as.
+ *
+ * @internal
+ */
+export declare function rethrowLoadError(error: unknown): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAS;CACjC;AAED,mFAAmF;AACnF,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,wCAAwC;IACxC,SAAkB,IAAI,2BAA2B;IACjD,SAAkB,KAAK,SAAS;IAChC,YAAY,OAAO,SAAmC,EAErD;CACF;AAED,gEAAgE;AAChE,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,yCAAyC;IACzC,SAAkB,IAAI,4BAA4B;IAClD,SAAkB,KAAK,QAAQ;IAC/B,YAAY,OAAO,SAAuC,EAEzD;CACF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAQtD"}

package/dist/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Tags the bindings put in front of a load failure's message.
+ *
+ * napi-rs gives every error it throws the same `code`, so the message is the only
+ * channel a typed failure can travel through. These are stripped before the error
+ * reaches a caller — keep them in step with `TAG_PASSWORD_REQUIRED` and
+ * `TAG_INCORRECT_PASSWORD` in `packages/bindings/src/lib.rs`.
+ */
+const TAGS = {
+    'papyra/password-required': (message) => new PasswordRequiredError(message),
+    'papyra/incorrect-password': (message) => new IncorrectPasswordError(message),
+};
+/**
+ * A document that could not be opened because of its password.
+ *
+ * The base of both password failures, because a viewer handles them in one place: a
+ * dialog that either asks for the first time or says the last answer was wrong.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   doc = await open(file, { password });
+ * } catch (e) {
+ *   if (e instanceof PasswordError) showPasswordDialog({ retry: e.retry });
+ *   else throw e;
+ * }
+ * ```
+ */
+export class PasswordError extends Error {
+    /**
+     * A password was already tried and rejected.
+     *
+     * `false` the first time, so a dialog can open without an error on it.
+     */
+    retry = false;
+}
+/** The document is encrypted and {@link OpenOptions.password} was not supplied. */
+export class PasswordRequiredError extends PasswordError {
+    /** Always `'PasswordRequiredError'`. */
+    name = 'PasswordRequiredError';
+    retry = false;
+    constructor(message = 'this PDF is password-protected') {
+        super(message);
+    }
+}
+/** A password was supplied and it did not open the document. */
+export class IncorrectPasswordError extends PasswordError {
+    /** Always `'IncorrectPasswordError'`. */
+    name = 'IncorrectPasswordError';
+    retry = true;
+    constructor(message = 'the supplied password is incorrect') {
+        super(message);
+    }
+}
+/**
+ * Rethrow a load failure as itself, or as the typed error it was tagged as.
+ *
+ * @internal
+ */
+export function rethrowLoadError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    for (const [tag, build] of Object.entries(TAGS)) {
+        if (message.startsWith(tag)) {
+            throw build(message.slice(tag.length).trim());
+        }
+    }
+    throw error;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,IAAI,GAAG;IACX,0BAA0B,EAAE,CAAC,OAAe,EAAE,EAAE,CAC9C,IAAI,qBAAqB,CAAC,OAAO,CAAC;IACpC,2BAA2B,EAAE,CAAC,OAAe,EAAE,EAAE,CAC/C,IAAI,sBAAsB,CAAC,OAAO,CAAC;CAC7B,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC;;;;OAIG;IACM,KAAK,GAAY,KAAK,CAAC;CACjC;AAED,mFAAmF;AACnF,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACtD,wCAAwC;IACtB,IAAI,GAAG,uBAAuB,CAAC;IAC/B,KAAK,GAAG,KAAK,CAAC;IAChC,YAAY,OAAO,GAAG,gCAAgC;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IACvD,yCAAyC;IACvB,IAAI,GAAG,wBAAwB,CAAC;IAChC,KAAK,GAAG,IAAI,CAAC;IAC/B,YAAY,OAAO,GAAG,oCAAoC;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC"}

package/dist/fingerprint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A stable identifier for a document's bytes.
+ *
+ * Sixteen hex characters, derived from the head, the tail and the length of the file.
+ * Meant as a key for whatever a viewer remembers per document — the page it was left
+ * on, the zoom, a set of highlights.
+ *
+ * **This is a content hash, not the PDF's `/ID`.** hayro exposes no trailer accessor,
+ * so the identifier the spec defines is out of reach; the practical difference is
+ * that a document saved with an incremental update keeps its `/ID` and gets a new
+ * fingerprint here. For "is this the same file I had open", which is what the value
+ * is for, hashing the bytes is the stronger answer anyway — it also distinguishes two
+ * documents that were copied from one another and kept the same `/ID`.
+ *
+ * @internal
+ */
+export declare function fingerprint(bytes: Uint8Array): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAarD"}

package/dist/fingerprint.js

@@ -0,0 +1,48 @@
+/**
+ * How many bytes to read from each end of the file.
+ *
+ * The tail is the load-bearing half: it holds the cross-reference table and the
+ * trailer, and the trailer is where `/ID` lives. So although this never parses the
+ * document, a file that carries an `/ID` still contributes it to the hash.
+ */
+const SAMPLE = 4096;
+/** FNV-1a, 32-bit. Two runs at different offsets give the 64 bits below. */
+function fnv1a(bytes, seed) {
+    let hash = seed;
+    for (const byte of bytes) {
+        hash ^= byte;
+        // The FNV prime, 16777619, as shifts — `Math.imul` keeps this in 32 bits where
+        // `*` would silently go through a double and lose the low bits.
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/**
+ * A stable identifier for a document's bytes.
+ *
+ * Sixteen hex characters, derived from the head, the tail and the length of the file.
+ * Meant as a key for whatever a viewer remembers per document — the page it was left
+ * on, the zoom, a set of highlights.
+ *
+ * **This is a content hash, not the PDF's `/ID`.** hayro exposes no trailer accessor,
+ * so the identifier the spec defines is out of reach; the practical difference is
+ * that a document saved with an incremental update keeps its `/ID` and gets a new
+ * fingerprint here. For "is this the same file I had open", which is what the value
+ * is for, hashing the bytes is the stronger answer anyway — it also distinguishes two
+ * documents that were copied from one another and kept the same `/ID`.
+ *
+ * @internal
+ */
+export function fingerprint(bytes) {
+    const head = bytes.subarray(0, SAMPLE);
+    // `subarray` clamps, so a file shorter than one sample simply hashes twice rather
+    // than needing a branch.
+    const tail = bytes.subarray(Math.max(0, bytes.length - SAMPLE));
+    const low = fnv1a(tail, fnv1a(head, 0x811c9dc5));
+    // A second pass from a different seed, so the two halves of the output are not the
+    // same 32 bits twice. Length goes in as well: it separates a file from its own
+    // prefix, which the samples alone would not.
+    const high = fnv1a(tail, fnv1a(head, bytes.length >>> 0));
+    return high.toString(16).padStart(8, '0') + low.toString(16).padStart(8, '0');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,IAAI,CAAC;AAEpB,4EAA4E;AAC5E,SAAS,KAAK,CAAC,KAAiB,EAAE,IAAY;IAC5C,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,IAAI,CAAC;QACb,+EAA+E;QAC/E,gEAAgE;QAChE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACvC,kFAAkF;IAClF,yBAAyB;IACzB,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAEhE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IACjD,mFAAmF;IACnF,+EAA+E;IAC/E,6CAA6C;IAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;IAE1D,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAChF,CAAC"}

package/dist/index.d.ts

@@ -13,12 +13,17 @@
  * onScroll(() => job.setPriority(0));
  * ```
  */
+export type { Attachment } from './attachments.js';
+export { attachmentMediaType, isInvoiceAttachment, } from './attachments.js';
 export type { CacheStats } from './cache.js';
+export type { PaintOptions } from './canvas.js';
 export { paintToCanvas, toImageData } from './canvas.js';
-export type { ImageHandle, RenderHandle } from './document.js';
+export type { ImageHandle, RenderHandle, SvgHandle } from './document.js';
 export { Document, open } from './document.js';
-export type { EncodedFormat, EncodedImage, EncodeOptions, } from './encode.js';
-export { encode, encodedImage, mimeType, PageImage } from './encode.js';
+export type { EncodedFormat, EncodedImage, EncodeOptions, RasterFormat, SvgPage, } from './encode.js';
+export { encode, encodedImage, mimeType, PageImage, svgPage, } from './encode.js';
+export { IncorrectPasswordError, PasswordError, PasswordRequiredError, } from './errors.js';
+export type { LinkTarget, PageLink } from './links.js';
 export type { DestinationKind, OutlineDestination, OutlineNode, } from './outline.js';
 export { buildOutlineTree, walkOutline } from './outline.js';
 export type { Runtime } from './runtime.js';
@@ -27,7 +32,11 @@ export type { JobHandle, JobTiming } from './scheduler.js';
 export { AbortError, DEFAULT_PRIORITY } from './scheduler.js';
 export type { MatchOptions, SearchMatch } from './search.js';
 export { findRanges, searchPageText } from './search.js';
+export type { MarkedContent, OrderedLine, StructNode, } from './structure.js';
+export { buildStructTree, readingOrder, structuredPageString, walkStructTree, } from './structure.js';
 export type { PageText, Quad, Rect, TextLine } from './text.js';
-export { lineQuad, pageString, quadBounds, scaleQuad, } from './text.js';
-export type { OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, SearchOptions, StreamedPage, StreamOptions, } from './types.js';
+export { lineQuad, pageString, quadBounds, scaleQuad, scaleRect, } from './text.js';
+export type { DocumentMetadata, OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, SearchOptions, StreamedPage, StreamOptions, SvgOptions, } from './types.js';
+export type { Rotation, Viewport, ViewportOptions } from './viewport.js';
+export { rotatePage, rotateSize, viewport, viewportQuad, viewportRect, } from './viewport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,WAAW,EACX,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,aAAa,EACb,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -13,12 +13,16 @@
  * onScroll(() => job.setPriority(0));
  * ```
  */
+export { attachmentMediaType, isInvoiceAttachment, } from './attachments.js';
 export { paintToCanvas, toImageData } from './canvas.js';
 export { Document, open } from './document.js';
-export { encode, encodedImage, mimeType, PageImage } from './encode.js';
+export { encode, encodedImage, mimeType, PageImage, svgPage, } from './encode.js';
+export { IncorrectPasswordError, PasswordError, PasswordRequiredError, } from './errors.js';
 export { buildOutlineTree, walkOutline } from './outline.js';
 export { backend, currentRuntime, hardwareConcurrency, init, } from './runtime.js';
 export { AbortError, DEFAULT_PRIORITY } from './scheduler.js';
 export { findRanges, searchPageText } from './search.js';
-export { lineQuad, pageString, quadBounds, scaleQuad, } from './text.js';
+export { buildStructTree, readingOrder, structuredPageString, walkStructTree, } from './structure.js';
+export { lineQuad, pageString, quadBounds, scaleQuad, scaleRect, } from './text.js';
+export { rotatePage, rotateSize, viewport, viewportQuad, viewportRect, } from './viewport.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAM/C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMxE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,GACV,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAQ/C,OAAO,EACL,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMzD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,GACV,MAAM,WAAW,CAAC;AAcnB,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/links.d.ts

@@ -0,0 +1,53 @@
+import type { PageLink as NativePageLink } from '@build-qube/papyra-native';
+import { type OutlineDestination } from './outline.js';
+import type { Rect } from './text.js';
+/**
+ * Where a link goes.
+ *
+ * A discriminated union rather than two nullable fields, so narrowing on `kind` gives
+ * you the payload without a non-null assertion:
+ *
+ * ```ts
+ * if (link.target.kind === 'uri') window.open(link.target.uri);
+ * else void doc.render(link.target.dest.page, { fitWidth: 1600 });
+ * ```
+ */
+export type LinkTarget = {
+    /** The link points somewhere in this document. */
+    readonly kind: 'internal';
+    /** The page and the view, in the same shape an outline entry uses. */
+    readonly dest: OutlineDestination;
+} | {
+    /**
+     * The link points out of this document.
+     *
+     * Not necessarily `http`: `mailto:` and `file:` are both common, and papyra
+     * does not validate the string. Decide for yourself what you are willing to
+     * follow before handing it to a browser.
+     */
+    readonly kind: 'uri';
+    /** The URI, exactly as the document wrote it. */
+    readonly uri: string;
+};
+/**
+ * One link on a page: a clickable region, and what it does.
+ *
+ * Only links that resolve to something actionable are reported — a `/Link` pointing
+ * at a page the document does not contain, or carrying an action papyra does not act
+ * on, is dropped rather than handed over as a region that would swallow clicks.
+ */
+export interface PageLink {
+    /**
+     * The clickable region, in the same 72-DPI top-left space as {@link PageText} and
+     * {@link PageSize}. Multiply by `rendered.width / pageSize.width` to place it over
+     * a render — {@link scaleRect} does exactly that.
+     */
+    readonly rect: Rect;
+    /** Where activating the link goes. Narrow on `target.kind`. */
+    readonly target: LinkTarget;
+    /** The annotation's tooltip, when it has one. */
+    readonly alt: string | null;
+}
+/** @internal */
+export declare function toPageLink(native: NativePageLink): PageLink | null;
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAE,KAAK,kBAAkB,EAAiB,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAClB;IACE,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;CACnC,GACD;IACE;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,gBAAgB;AAChB,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,IAAI,CAelE"}

package/dist/links.js

@@ -0,0 +1,26 @@
+import { toDestination } from './outline.js';
+/** @internal */
+export function toPageLink(native) {
+    const target = linkTarget(native);
+    // The bindings only emit a link with one target or the other, so this is
+    // unreachable in practice; dropping it beats widening the type with a null target.
+    if (!target)
+        return null;
+    return {
+        rect: {
+            x: native.x0,
+            y: native.y0,
+            width: native.x1 - native.x0,
+            height: native.y1 - native.y0,
+        },
+        target,
+        alt: native.alt ?? null,
+    };
+}
+function linkTarget(native) {
+    if (native.uri !== undefined)
+        return { kind: 'uri', uri: native.uri };
+    const dest = toDestination(native.dest);
+    return dest ? { kind: 'internal', dest } : null;
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,aAAa,EAAE,MAAM,cAAc,CAAC;AAsDtE,gBAAgB;AAChB,MAAM,UAAU,UAAU,CAAC,MAAsB;IAC/C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAClC,yEAAyE;IACzE,mFAAmF;IACnF,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO;QACL,IAAI,EAAE;YACJ,CAAC,EAAE,MAAM,CAAC,EAAE;YACZ,CAAC,EAAE,MAAM,CAAC,EAAE;YACZ,KAAK,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE;YAC5B,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE;SAC9B;QACD,MAAM;QACN,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,MAAsB;IACxC,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC"}

package/dist/outline.d.ts

@@ -1,4 +1,4 @@
-import type { OutlineEntry as NativeEntry } from '@build-qube/papyra-native';
+import type { OutlineDestination as NativeDestination, OutlineEntry as NativeEntry } from '@build-qube/papyra-native';
 /** How a destination positions the page in the window (PDF 32000-1, 12.3.2.2). */
 export type DestinationKind = 'XYZ' | 'Fit' | 'FitH' | 'FitV' | 'FitR' | 'FitB' | 'FitBH' | 'FitBV';
 /**
@@ -45,6 +45,14 @@ export interface OutlineNode {
     /** Nested entries, empty for a leaf. */
     readonly children: OutlineNode[];
 }
+/**
+ * napi omits absent numbers rather than nulling them; normalise to one shape.
+ *
+ * Shared with the link reader, whose targets resolve to the same destinations.
+ *
+ * @internal
+ */
+export declare function toDestination(dest: NativeDestination | undefined): OutlineDestination | null;
 /**
  * Rebuild the tree from the flat pre-order list the bindings return.
  *

package/dist/outline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../src/outline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,IAAI,WAAW,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,kFAAkF;AAClF,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;CAClC;AA+BD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,WAAW,EAAE,GAC9B,WAAW,EAAE,CAyBf;AAED,sEAAsE;AACtE,wBAAiB,WAAW,CAC1B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,KAAK,SAAI,GACR,SAAS,CAAC;IACX,iBAAiB;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAKD"}
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../src/outline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,IAAI,iBAAiB,EACvC,YAAY,IAAI,WAAW,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,kFAAkF;AAClF,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;CAClC;AAaD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,GAAG,SAAS,GAClC,kBAAkB,GAAG,IAAI,CAa3B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,WAAW,EAAE,GAC9B,WAAW,EAAE,CAyBf;AAED,sEAAsE;AACtE,wBAAiB,WAAW,CAC1B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,KAAK,SAAI,GACR,SAAS,CAAC;IACX,iBAAiB;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAKD"}

package/dist/outline.js

@@ -8,8 +8,14 @@ const KINDS = new Set([
     'FitBH',
     'FitBV',
 ]);
-/** napi omits absent numbers rather than nulling them; normalise to one shape. */
-function destination(dest) {
+/**
+ * napi omits absent numbers rather than nulling them; normalise to one shape.
+ *
+ * Shared with the link reader, whose targets resolve to the same destinations.
+ *
+ * @internal
+ */
+export function toDestination(dest) {
     if (!dest)
         return null;
     return {
@@ -36,7 +42,7 @@ export function buildOutlineTree(entries) {
     const roots = [];
     const stack = [];
     for (const entry of entries) {
-        const dest = destination(entry.dest);
+        const dest = toDestination(entry.dest);
         const node = {
             title: entry.title,
             dest,

package/dist/outline.js.map

@@ -1 +1 @@
-{"version":3,"file":"outline.js","sourceRoot":"","sources":["../src/outline.ts"],"names":[],"mappings":"AA8DA,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS;IAC5B,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;CACR,CAAC,CAAC;AAEH,kFAAkF;AAClF,SAAS,WAAW,CAClB,IAAmC;IAEnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,8EAA8E;QAC9E,iDAAiD;QACjD,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAoB;QACnE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;KACxB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA+B;IAE/B,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAkB,EAAE,CAAC;IAEhC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,IAAI,GAAgB;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI;YACJ,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,IAAI;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,EAAE;SACb,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;QACrB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAChC,IAAI,MAAM;YAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAClC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sEAAsE;AACtE,MAAM,SAAS,CAAC,CAAC,WAAW,CAC1B,KAA6B,EAC7B,KAAK,GAAG,CAAC;IAOT,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}
+{"version":3,"file":"outline.js","sourceRoot":"","sources":["../src/outline.ts"],"names":[],"mappings":"AA8DA,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS;IAC5B,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAmC;IAEnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,8EAA8E;QAC9E,iDAAiD;QACjD,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAoB;QACnE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;KACxB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA+B;IAE/B,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAkB,EAAE,CAAC;IAEhC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,IAAI,GAAgB;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI;YACJ,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,IAAI;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,EAAE;SACb,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;QACrB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAChC,IAAI,MAAM;YAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAClC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sEAAsE;AACtE,MAAM,SAAS,CAAC,CAAC,WAAW,CAC1B,KAA6B,EAC7B,KAAK,GAAG,CAAC;IAOT,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/structure.d.ts

@@ -0,0 +1,119 @@
+import type { StructEntry as NativeEntry } from '@build-qube/papyra-native';
+import type { PageText, TextLine } from './text.js';
+/**
+ * One run of page content owned by a {@link StructNode}.
+ *
+ * The pair is what makes the join work: a marked-content id is only unique within a
+ * single page's content stream, so an id on its own addresses nothing.
+ */
+export interface MarkedContent {
+    /** 0-based page index. */
+    readonly page: number;
+    /** Matches {@link TextLine.mcid} on that page. */
+    readonly mcid: number;
+}
+/**
+ * A node in the document structure tree.
+ *
+ * A tagged PDF states what its content *means* — which runs are a heading, which are
+ * a table cell — and, more usefully than either, what order it is meant to be read
+ * in. Nothing else in a PDF carries that: {@link PageText.lines} is content-stream
+ * order, which interleaves the columns of a two-column page.
+ */
+export interface StructNode {
+    /**
+     * Standard structure type: `'Document'`, `'H1'`, `'P'`, `'Table'`, `'TD'`,
+     * `'Figure'`, and the rest of ISO 32000-1's set.
+     *
+     * Already resolved through the document's `/RoleMap`, so a file that tags its
+     * headings `Heading1` and maps that onto `H1` reports `'H1'` here. Word and
+     * InDesign both emit such files, so matching on {@link StructNode.rawRole} instead
+     * misses a large share of real tagged documents.
+     */
+    readonly role: string;
+    /**
+     * The document's own tag, before `/RoleMap`. Equal to {@link StructNode.role}
+     * unless the document remapped it.
+     */
+    readonly rawRole: string;
+    /**
+     * Content this element owns directly, in the order the tree declares it.
+     *
+     * Empty for a pure container — a `Sect` whose text all belongs to the `P`s beneath
+     * it — which is most interior nodes.
+     */
+    readonly content: readonly MarkedContent[];
+    /** `/Alt`: replacement text for a figure, and the only text an image has. */
+    readonly alt: string | null;
+    /**
+     * `/ActualText`: text that replaces the content rather than describing it, which is
+     * how a document spells out a ligature or a decorative glyph.
+     */
+    readonly actualText: string | null;
+    /** `/Lang`: a BCP 47 tag overriding the document language for this subtree. */
+    readonly lang: string | null;
+    /** `/T`: a human-readable title for the element, such as a table's caption. */
+    readonly title: string | null;
+    /** Nested elements, empty for a leaf. */
+    readonly children: StructNode[];
+}
+/**
+ * Rebuild the tree from the flat pre-order list the bindings return.
+ *
+ * The same stack-by-level pass {@link buildOutlineTree} uses, and correct for the same
+ * reason: pre-order guarantees a node's parent is the most recent node one level
+ * shallower. A level that skips a step cannot come from our own walker, and is clamped
+ * rather than trusted — a malformed document should flatten, not crash.
+ */
+export declare function buildStructTree(entries: readonly NativeEntry[]): StructNode[];
+/** Walk a structure tree depth-first, yielding each node with its depth. */
+export declare function walkStructTree(nodes: readonly StructNode[], depth?: number): Generator<{
+    /** The element. */
+    node: StructNode;
+    /** How deep it sits, 0 for a root. */
+    depth: number;
+}>;
+/** One line of a page, with the structure element that claims it. */
+export interface OrderedLine {
+    /** The line, exactly as {@link PageText} reported it. */
+    readonly line: TextLine;
+    /**
+     * The element whose content the line's first glyph sits in, or `null` for a line
+     * the structure tree does not account for.
+     */
+    readonly node: StructNode | null;
+}
+/**
+ * Put a page's lines into the reading order the document declares.
+ *
+ * This is the payoff of a tagged PDF and the one thing geometry cannot recover: on a
+ * two-column page the content stream may draw both columns interleaved, and no line
+ * grouping fixes that, because the drawing order genuinely is what it is. The
+ * structure tree states the intended order outright.
+ *
+ * Lines are keyed by their first glyph's {@link TextLine.mcid}, so a line is placed by
+ * the element that *starts* it. Ties — several lines inside one `P`, which is the
+ * normal case for a wrapped paragraph — keep their original relative order, so within
+ * an element the result is still the content stream's sequence. That is what makes
+ * this safe on a document whose tagging is partial.
+ *
+ * Lines with no structure element go **last**, rather than being dropped: untagged
+ * content is usually a running head or a page number, and losing it silently would be
+ * worse than putting it at the end. Pass `includeUntagged: false` to drop them.
+ *
+ * Returns the lines in content-stream order, unchanged, when the page has no tagged
+ * content at all — an untagged document is the common case and should not come back
+ * empty or reshuffled.
+ */
+export declare function readingOrder(text: PageText, tree: readonly StructNode[], options?: {
+    /** Keep lines no element claims, at the end. Defaults to `true`. */
+    readonly includeUntagged?: boolean;
+}): OrderedLine[];
+/**
+ * Every character of a page in declared reading order, one line per entry.
+ *
+ * The structure-aware counterpart to {@link pageString}; identical to it on an
+ * untagged page.
+ */
+export declare function structuredPageString(text: PageText, tree: readonly StructNode[]): string;
+//# sourceMappingURL=structure.d.ts.map

package/dist/structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,IAAI,WAAW,EAE3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAyB7E;AAED,4EAA4E;AAC5E,wBAAiB,cAAc,CAC7B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,KAAK,SAAI,GACR,SAAS,CAAC;IACX,mBAAmB;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAKD;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,OAAO,GAAE;IACP,oEAAoE;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC/B,GACL,WAAW,EAAE,CA4Cf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,SAAS,UAAU,EAAE,GAC1B,MAAM,CAIR"}