@silurus/ooxml 0.74.6 → 0.75.0

package/dist/transfer-3QEJrsJa.js

@@ -0,0 +1,6 @@
+//#region packages/core/src/worker/transfer.ts
+function e(e) {
+	return e.byteOffset === 0 && e.byteLength === e.buffer.byteLength && e.buffer instanceof ArrayBuffer ? e.buffer : e.slice().buffer;
+}
+//#endregion
+export { e as t };

package/dist/types/docx.d.ts

@@ -1,4 +1,4 @@
-//#region dist/.types-work/mathjax-6BV6bQWa.d.ts
+//#region dist/.types-work/mathjax-BO1uUSCW.d.ts
 //#region packages/core/src/math/mathjax.d.ts
 interface MathSvg {
     /** standalone `<svg>…</svg>` markup. */
@@ -29,7 +29,7 @@ interface MathRenderer {
     mathMLToSvg(mathml: string): Promise<MathSvg>;
 }
 //#endregion
-//#region dist/.types-work/find-highlight-B8ft6Y0g.d.ts
+//#region dist/.types-work/hyperlink-CHHEOeCL.d.ts
 //#region packages/core/src/types/math.d.ts
 type MathStyle = 'roman' | 'italic' | 'bold' | 'boldItalic';
 interface MathRun {
@@ -963,7 +963,157 @@ interface LegendManualLayout {
     h: number;
 }
 //#endregion
+//#region packages/core/src/errors/ooxml-error.d.ts
+/**
+ * Machine-readable code for a typed load-time failure.
+ *
+ * The container-level failures the `load()` factories detect on the main thread
+ * before handing bytes to the parser worker (see `sniffCfb` / `decryptOoxml`).
+ * This is the seed of the broader typed-error surface tracked as PD4 (OoxmlError
+ * typed errors). Add codes here rather than throwing bare `Error(string)`, so
+ * callers can `switch` on `err.code` instead of matching message text.
+ *
+ *   - `'encrypted'`             — password-protected, but no `password` was
+ *     supplied (pass `LoadOptions.password` to decrypt).
+ *   - `'invalid-password'`      — a `password` was supplied but did not match.
+ *   - `'unsupported-encryption'`— encrypted with a scheme other than Agile
+ *     (Standard / Extensible / a legacy binary encryptor), which this library
+ *     cannot decrypt (PD8 implements Agile only).
+ *   - `'legacy-binary-format'`  — a raw .doc / .xls / .ppt (not OOXML).
+ *   - `'not-ooxml'`             — a CFB of an unrecognised kind, or otherwise
+ *     not an OOXML ZIP.
+ */
+type OoxmlErrorCode = 'encrypted' | 'invalid-password' | 'unsupported-encryption' | 'legacy-binary-format' | 'not-ooxml';
+type OoxmlErrorStage = 'container' | 'decompression' | 'parsing' | 'serialization' | 'layout' | 'rendering' | 'worker';
+/**
+ * @deprecated Use {@link OoxmlErrorStage}. Retained as a compatibility alias
+ * for the short-lived resource-governance API that exposed this vocabulary;
+ * scheduled for removal in a future breaking release.
+ */
+type OoxmlErrorSource = 'container' | 'zip-part' | 'parser' | 'serializer' | 'layout' | 'renderer' | 'worker';
+/**
+ * Typed error thrown by the docx / pptx / xlsx `load()` factories for failures
+ * that carry a stable, programmatic {@link OoxmlErrorCode} (e.g. a
+ * password-protected or legacy-binary file detected from its container magic).
+ *
+ * Note on workers: `instanceof OoxmlError` does not survive a structured-clone
+ * across the worker boundary. Detection that needs a typed error is therefore
+ * done on the main thread (before the worker is involved) so a genuine
+ * `OoxmlError` instance is thrown to the caller. Errors that must cross the
+ * worker boundary should carry the `code` string and be reconstructed on the
+ * main side.
+ */
+declare class OoxmlError extends Error {
+    readonly code: OoxmlErrorCode;
+    constructor(code: OoxmlErrorCode, message: string);
+}
+type OoxmlFormat = 'docx' | 'xlsx' | 'pptx';
+interface OoxmlResourceUsageSnapshot {
+    readonly archiveEntryCount: number;
+    readonly declaredInflatedBytes: number;
+    /** Largest actual decompressed size observed for one ZIP entry. */
+    readonly largestInflatedEntryBytes?: number;
+    readonly distinctInflatedBytes: number;
+    readonly operationInflatedBytes: number;
+}
+type ExtensibleLiteral<Known extends string> = Known | (string & Record<never, never>);
+/**
+ * Resource family reported by a policy or hard-quota violation.
+ *
+ * The known literals provide editor completion. The string tail is deliberate:
+ * adding a future format-owned unit must not break exhaustive switches compiled
+ * against an older host while a newer worker is already able to report it.
+ */
+type OoxmlResourceName = ExtensibleLiteral<'archive' | 'archive-entry' | 'xml-event' | 'xml-context' | 'xml-tree' | 'worksheet-row' | 'worksheet-shell'>;
+/** Measurement axis used by an OOXML resource violation. Extensible by design. */
+type OoxmlResourceMetric = ExtensibleLiteral<'declared-inflated-bytes' | 'actual-inflated-bytes' | 'entry-count' | 'central-directory-bytes' | 'distinct-inflated-bytes' | 'bytes' | 'depth' | 'projected-bytes'>;
+/** Stable public violation record. Valid resource/metric pairings are enforced
+ * by the emitting parser and the worker decoder rather than by a closed public
+ * union that would require a breaking expansion for every new hard quota. */
+interface OoxmlResourceViolation {
+    readonly format: OoxmlFormat;
+    readonly operation: string;
+    readonly resource: OoxmlResourceName;
+    readonly metric: OoxmlResourceMetric;
+    readonly part?: string;
+    readonly limit: number;
+    readonly observed: number;
+    readonly configurable: boolean;
+    readonly usage: OoxmlResourceUsageSnapshot;
+}
+interface OoxmlResourceLimitErrorDetails {
+    readonly stage: OoxmlErrorStage;
+    readonly violation: OoxmlResourceViolation;
+}
+/** Deterministic rejection caused by a measured OOXML resource-policy breach. */
+declare class OoxmlResourceLimitError extends Error {
+    readonly code: "ooxml-resource-limit";
+    readonly details: OoxmlResourceLimitErrorDetails;
+    constructor(message: string, details: OoxmlResourceLimitErrorDetails);
+}
+//#endregion
+//#region packages/core/src/types/resource-metrics.d.ts
+/** Configured public admission policy used for one measured operation. */
+interface OoxmlResourcePolicySnapshot {
+    readonly maxArchiveEntryBytes: number | null;
+    readonly maxTotalInflatedBytes: number | null;
+}
+interface OoxmlResourceMetricsCheckpoint {
+    readonly name: string;
+    readonly elapsedMs: number;
+    readonly usage?: OoxmlResourceUsageSnapshot;
+}
+/**
+ * Content-free, machine-readable resource report for an OOXML load or bounded
+ * Node session. Byte counters describe measured package work, not the JavaScript
+ * heap, WASM allocator overhead, decoded images, canvas, or GPU. Browser engines
+ * and Viewers can return a newer snapshot after lazy package access.
+ *
+ * No source URL, filename, OOXML part name, document text, password, or raw
+ * error message is included. Sizes, counts, and timings are still
+ * document-derived metadata; applications apply their own consent, retention,
+ * and telemetry policy.
+ */
+interface OoxmlResourceMetrics {
+    /** Version of this metrics payload, independent of the package version. */
+    readonly schemaVersion: 1;
+    /**
+     * Browser factories report `load`; bounded Node sessions report `session`.
+     */
+    readonly scope: 'load' | 'session';
+    readonly format: OoxmlFormat;
+    readonly mode: 'main' | 'worker' | 'node';
+    /** Outcome of this measured load/session, not of later render operations. */
+    readonly status: 'ok' | 'error';
+    /** Compressed or decrypted OOXML container bytes supplied to the parser. */
+    readonly sourceBytes?: number;
+    readonly elapsedMs: number;
+    readonly policy: Readonly<OoxmlResourcePolicySnapshot>;
+    /** Last complete observed package-usage checkpoint. */
+    readonly usage?: OoxmlResourceUsageSnapshot;
+    readonly checkpoints: readonly OoxmlResourceMetricsCheckpoint[];
+    readonly outcome?: Readonly<Record<string, number>>;
+    readonly error?: Readonly<{
+        readonly code?: string;
+        readonly stage?: string;
+        readonly resource?: string;
+        readonly metric?: string;
+    }>;
+}
+//#endregion
 //#region packages/core/src/types/load-options.d.ts
+/** A positive safe-integer byte count, or `null` to disable one public limit. */
+type OoxmlResourceLimit = number | null;
+/** Admission limits for the inflated contents of one OOXML package session. */
+interface OoxmlResourceLimits {
+    /**
+     * Maximum permitted inflated size for any one archive entry, including
+     * media. Enforced against both the ZIP declaration and actual output.
+     */
+    maxArchiveEntryBytes?: OoxmlResourceLimit;
+    /** Maximum actual inflated bytes across distinct entries in the session. */
+    maxTotalInflatedBytes?: OoxmlResourceLimit;
+}
 /**
  * Common load-time options shared by the docx / pptx / xlsx
  * `Document.load` / `Presentation.load` / `Workbook.load` factories and their
@@ -1030,12 +1180,44 @@ interface LoadOptions$1 {
      */
     wasmUrl?: string | URL;
     /**
-     * Override the per-entry ZIP decompression cap (bytes) used by the zip-bomb
-     * guard in the Rust parser. Defaults to 512 MiB. Raise it to load documents
-     * with very large embedded media, or lower it to tighten the budget for
-     * untrusted input. Zero / negative values fall back to the default.
+     * @deprecated Use `resourceLimits.maxArchiveEntryBytes`. Scheduled for
+     * removal in a future breaking release.
+     *
+     * Existing positive safe-integer values remain an all-entry inflated-byte
+     * limit. Zero, negative, and NaN values retain their historical fallback
+     * behavior; other invalid positive values reject during `load()`.
      */
     maxZipEntryBytes?: number;
+    /**
+     * Inflated archive admission limits for one document session. Omitted fields
+     * use the library defaults. A positive safe integer overrides a default;
+     * `null` disables that configurable limit only. Limits are admission policy,
+     * not guarantees of exact browser-process memory use.
+     */
+    resourceLimits?: OoxmlResourceLimits;
+    /**
+     * Emit one content-free resource-usage card after load succeeds or fails.
+     * Includes observed archive counters and configured limits, but never source
+     * URLs, part names, document text, passwords, or error messages.
+     */
+    debug?: boolean;
+    /**
+     * Receive the initial content-free, machine-readable report that powers the
+     * debug card, without enabling console output. After resource options validate,
+     * the callback runs once when the current load settles, including failed loads
+     * for which no renderer instance is returned. The callback is not awaited;
+     * synchronous exceptions and rejected promises are ignored and never change
+     * load results.
+     *
+     * A browser report covers the underlying document/workbook/presentation
+     * factory. It does not wait for a Viewer's first canvas paint; that paint and
+     * later lazy worksheet, slide, image, or media access may increase counters or
+     * surface a separate render error. Successfully opened packages include the
+     * declared package total and source byte size in the report. On a successful
+     * load, call `getResourceMetrics()` on the returned engine or Viewer for a fresh
+     * snapshot that includes subsequently observed lazy package work.
+     */
+    onResourceMetrics?: (metrics: OoxmlResourceMetrics) => void;
     /**
      * Reject the parse request if the parser worker does not answer within this
      * many milliseconds. Opt-in safety net for a wedged or crashed worker that
@@ -1058,44 +1240,81 @@ interface LoadOptions$1 {
     math?: MathRenderer;
 }
 //#endregion
-//#region packages/core/src/errors/ooxml-error.d.ts
+//#region packages/core/src/image/pixel-budget.d.ts
+type OoxmlDecodedImageLimitMetric = 'image-pixels' | 'active-decoded-bytes';
+/** Catchable hard-quota crossing for decoded image surfaces. */
+declare class OoxmlDecodedImageLimitError extends RangeError {
+    readonly metric: OoxmlDecodedImageLimitMetric;
+    readonly limit: number;
+    readonly observed: number;
+    readonly code: "ooxml-decoded-image-limit";
+    constructor(metric: OoxmlDecodedImageLimitMetric, limit: number, observed: number);
+}
+declare function isOoxmlDecodedImageLimitError(error: unknown): error is OoxmlDecodedImageLimitError;
+//#endregion
+//#region packages/core/src/interaction/hyperlink.d.ts
 /**
- * Machine-readable code for a typed load-time failure.
+ * Shared hyperlink model + URL sanitisation for docx / pptx / xlsx (IX1).
  *
- * The container-level failures the `load()` factories detect on the main thread
- * before handing bytes to the parser worker (see `sniffCfb` / `decryptOoxml`).
- * This is the seed of the broader typed-error surface tracked as PD4 (OoxmlError
- * typed errors). Add codes here rather than throwing bare `Error(string)`, so
- * callers can `switch` on `err.code` instead of matching message text.
+ * All three formats carry the same two ECMA-376 concepts:
+ *   - an **external** hyperlink — an absolute URL resolved from a relationship
+ *     part target (`document.xml.rels` for docx §17.16.22, the slide rels for
+ *     pptx §21.1.2.3.5, the worksheet rels for xlsx §18.3.1.47), with
+ *     `TargetMode="External"`.
+ *   - an **internal** hyperlink — a jump within the document itself:
+ *     docx `w:anchor` -> a `<w:bookmarkStart w:name>` (§17.16.23), pptx
+ *     `action="ppaction://hlinksldjump"` -> a slide, xlsx `location` -> a defined
+ *     name or a `Sheet!A1` cell reference.
  *
- *   - `'encrypted'`             — password-protected, but no `password` was
- *     supplied (pass `LoadOptions.password` to decrypt).
- *   - `'invalid-password'`      — a `password` was supplied but did not match.
- *   - `'unsupported-encryption'`— encrypted with a scheme other than Agile
- *     (Standard / Extensible / a legacy binary encryptor), which this library
- *     cannot decrypt (PD8 implements Agile only).
- *   - `'legacy-binary-format'`  — a raw .doc / .xls / .ppt (not OOXML).
- *   - `'not-ooxml'`             — a CFB of an unrecognised kind, or otherwise
- *     not an OOXML ZIP.
+ * The parsers (Rust, one per format) do the format-specific rels lookup and hand
+ * each run / shape / cell a {@link HyperlinkTarget}. Everything downstream — the
+ * text-layer overlay, the viewer default click behaviour, and any integrator
+ * callback — is format-agnostic and consumes this one shape. Keeping the type +
+ * the pure `sanitizeHyperlinkUrl` predicate here (not duplicated per package)
+ * follows the cross-package unification principle: a scheme-allowlist bug fixed
+ * once is fixed everywhere.
  */
-type OoxmlErrorCode = 'encrypted' | 'invalid-password' | 'unsupported-encryption' | 'legacy-binary-format' | 'not-ooxml';
 /**
- * Typed error thrown by the docx / pptx / xlsx `load()` factories for failures
- * that carry a stable, programmatic {@link OoxmlErrorCode} (e.g. a
- * password-protected or legacy-binary file detected from its container magic).
+ * A resolved hyperlink attached to a run, shape, or cell.
  *
- * Note on workers: `instanceof OoxmlError` does not survive a structured-clone
- * across the worker boundary. Detection that needs a typed error is therefore
- * done on the main thread (before the worker is involved) so a genuine
- * `OoxmlError` instance is thrown to the caller. Errors that must cross the
- * worker boundary should carry the `code` string and be reconstructed on the
- * main side.
+ *   - `external` — `url` is the raw target as authored in the file. It is NOT
+ *     guaranteed safe; run it through {@link sanitizeHyperlinkUrl} before
+ *     navigating. It is kept verbatim here so an integrator can apply its own
+ *     policy (e.g. allow `file:` on a trusted intranet viewer).
+ *   - `internal` — `ref` is the in-document destination, verbatim from the file:
+ *       docx: the bookmark name (`w:anchor`).
+ *       pptx: the internal action (e.g. `ppaction://hlinksldjump`), with the
+ *             resolved 0-based `slideIndex` when the rels target names a slide.
+ *       xlsx: the `location` string (a defined name or `Sheet1!A1`).
  */
-declare class OoxmlError extends Error {
-    readonly code: OoxmlErrorCode;
-    constructor(code: OoxmlErrorCode, message: string);
-}
+type HyperlinkTarget = {
+    kind: 'external';
+    url: string;
+} | {
+    kind: 'internal';
+    ref: string;
+    slideIndex?: number;
+};
+/**
+ * The default action a viewer takes for an **external** hyperlink click when
+ * the integrator supplies no `onHyperlinkClick` handler: sanitise the URL and,
+ * if allowed, open it in a new tab with `noopener,noreferrer` so the opened page
+ * gets no `window.opener` handle back into this document. A blocked scheme is a
+ * silent no-op (returns `false`) — the click does nothing rather than navigate
+ * somewhere dangerous.
+ *
+ * Internal targets are intentionally NOT handled here: the in-document jump
+ * (page / slide / cell) is format-specific and lives in each viewer.
+ *
+ * Split out (not inlined in three viewers) so the "open in new tab, drop opener,
+ * refuse unsafe schemes" policy is defined once. `win` is injected for tests;
+ * defaults to the ambient `window`.
+ *
+ * @returns `true` if navigation was initiated, `false` if the URL was blocked.
+ */
+declare function openExternalHyperlink(url: string, allowed?: readonly string[], win?: Pick<Window, 'open'> | undefined): boolean;
 //#endregion
+//#region dist/.types-work/find-highlight-gMP3FAnW.d.ts
 //#region packages/core/src/autoResize.d.ts
 interface AutoResizeOptions {
     /**
@@ -1208,68 +1427,6 @@ interface ZoomableViewer {
     fitPage(): void | Promise<void>;
 }
 //#endregion
-//#region packages/core/src/interaction/hyperlink.d.ts
-/**
- * Shared hyperlink model + URL sanitisation for docx / pptx / xlsx (IX1).
- *
- * All three formats carry the same two ECMA-376 concepts:
- *   - an **external** hyperlink — an absolute URL resolved from a relationship
- *     part target (`document.xml.rels` for docx §17.16.22, the slide rels for
- *     pptx §21.1.2.3.5, the worksheet rels for xlsx §18.3.1.47), with
- *     `TargetMode="External"`.
- *   - an **internal** hyperlink — a jump within the document itself:
- *     docx `w:anchor` -> a `<w:bookmarkStart w:name>` (§17.16.23), pptx
- *     `action="ppaction://hlinksldjump"` -> a slide, xlsx `location` -> a defined
- *     name or a `Sheet!A1` cell reference.
- *
- * The parsers (Rust, one per format) do the format-specific rels lookup and hand
- * each run / shape / cell a {@link HyperlinkTarget}. Everything downstream — the
- * text-layer overlay, the viewer default click behaviour, and any integrator
- * callback — is format-agnostic and consumes this one shape. Keeping the type +
- * the pure `sanitizeHyperlinkUrl` predicate here (not duplicated per package)
- * follows the cross-package unification principle: a scheme-allowlist bug fixed
- * once is fixed everywhere.
- */
-/**
- * A resolved hyperlink attached to a run, shape, or cell.
- *
- *   - `external` — `url` is the raw target as authored in the file. It is NOT
- *     guaranteed safe; run it through {@link sanitizeHyperlinkUrl} before
- *     navigating. It is kept verbatim here so an integrator can apply its own
- *     policy (e.g. allow `file:` on a trusted intranet viewer).
- *   - `internal` — `ref` is the in-document destination, verbatim from the file:
- *       docx: the bookmark name (`w:anchor`).
- *       pptx: the internal action (e.g. `ppaction://hlinksldjump`), with the
- *             resolved 0-based `slideIndex` when the rels target names a slide.
- *       xlsx: the `location` string (a defined name or `Sheet1!A1`).
- */
-type HyperlinkTarget = {
-    kind: 'external';
-    url: string;
-} | {
-    kind: 'internal';
-    ref: string;
-    slideIndex?: number;
-};
-/**
- * The default action a viewer takes for an **external** hyperlink click when
- * the integrator supplies no `onHyperlinkClick` handler: sanitise the URL and,
- * if allowed, open it in a new tab with `noopener,noreferrer` so the opened page
- * gets no `window.opener` handle back into this document. A blocked scheme is a
- * silent no-op (returns `false`) — the click does nothing rather than navigate
- * somewhere dangerous.
- *
- * Internal targets are intentionally NOT handled here: the in-document jump
- * (page / slide / cell) is format-specific and lives in each viewer.
- *
- * Split out (not inlined in three viewers) so the "open in new tab, drop opener,
- * refuse unsafe schemes" policy is defined once. `win` is injected for tests;
- * defaults to the ambient `window`.
- *
- * @returns `true` if navigation was initiated, `false` if the URL was blocked.
- */
-declare function openExternalHyperlink(url: string, allowed?: readonly string[], win?: Pick<Window, 'open'> | undefined): boolean;
-//#endregion
 //#region packages/core/src/search/text-index.d.ts
 /**
  * The slice of one run a match covers: the run's index in the original `runs[]`
@@ -1344,7 +1501,7 @@ interface FindHighlightColors {
     active?: string;
 }
 //#endregion
-//#region dist/.types-work/docx-BatSd3II.d.ts
+//#region dist/.types-work/renderer-CU7Ays06.d.ts
 //#region packages/docx/src/types.d.ts
 interface DocxDocumentModel {
     section: SectionProps;
@@ -2875,14 +3032,15 @@ interface DocxTextRunInfo {
     eastAsianVert?: boolean;
 }
 //#endregion
+//#region dist/.types-work/docx-VDKt2JLe.d.ts
 //#region packages/docx/src/worker-protocol.d.ts
 /** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
 type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
 //#endregion
 //#region packages/docx/src/document.d.ts
 /** Options for {@link DocxDocument.load}. Extends the shared load-options type
- *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`) with the
- *  opt-in math engine. */
+ *  from `@silurus/ooxml-core` (`useGoogleFonts`, `resourceLimits`, and the
+ *  deprecated `maxZipEntryBytes` alias) with the opt-in math engine. */
 interface LoadOptions extends LoadOptions$1 {
     /**
      * Opt-in OMML equation engine. Import it from the separate `@silurus/ooxml/math`
@@ -2910,7 +3068,9 @@ type RenderPageToBitmapOptions = WireRenderPageOptions & {
     onTextRun?: (run: DocxTextRunInfo) => void;
 };
 declare class DocxDocument {
+    private _metrics;
     private _document;
+    private _source;
     private _meta;
     /** Lazily-built `bookmarkName → 0-based page index` map for internal hyperlink
      *  anchors (IX-nav). Built on first {@link getBookmarkPage} from the paginated
@@ -2920,7 +3080,7 @@ declare class DocxDocument {
     private _mode;
     private _worker;
     private _bridge;
-    private _imageCache;
+    private readonly _rawParts;
     /** Embedded `FontFace` objects this document registered into `document.fonts`
      *  (main mode only — in worker mode the worker owns them and terminates with
      *  its own FontFaceSet). Released in {@link destroy} so they do not leak into
@@ -2962,6 +3122,11 @@ declare class DocxDocument {
      * which de-obfuscates (ECMA-376 §17.8.1) and registers each as a FontFace.
      */
     getFontBytes(partPath: string): Promise<Uint8Array>;
+    private _resourceUsage;
+    /** Return a fresh content-free metrics snapshot, including lazy archive work
+     * completed since load. Collection is always active; `debug` only controls
+     * console presentation. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Project the document to GitHub-flavoured markdown: headings (from
      * `<w:outlineLvl>`), bullet / numbered lists, tables (with vMerge
@@ -3116,7 +3281,19 @@ interface DocxViewerOptions extends RenderPageOptions, LoadOptions {
      *  text. Set it to disable clickable links entirely — e.g. in a preview where
      *  navigation must not leave the current view. */
     enableHyperlinks?: boolean;
-    /** Called on parse or render errors. */
+    /**
+     * Receives load failures and asynchronous render failures handled by the
+     * Viewer. Supplying this callback changes load-failure delivery: `load()`
+     * invokes it and resolves; without it, the same load/parse failure rejects
+     * `load()`. Viewer-managed render failures invoke it, or fall back to
+     * `console.error` when omitted.
+     *
+     * Stable cases can be narrowed with `OoxmlError`,
+     * `OoxmlResourceLimitError`, or `OoxmlDecodedImageLimitError` re-exported by
+     * this package. Other failures remain `Error` values; do not parse message
+     * text as an API. A `code` of `parser-crashed` identifies a recognized WASM
+     * trap, not a reliably classified OOM.
+     */
     onError?: (err: Error) => void;
 }
 declare class DocxViewer implements ZoomableViewer {
@@ -3287,6 +3464,8 @@ declare class DocxViewer implements ZoomableViewer {
     /** Rebuild the highlight overlay for the current page from cached runs
      *  (no page re-render). */
     private _redrawHighlights;
+    /** Latest content-free resource metrics for the loaded document. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Terminate the parser worker and release resources.
      *
@@ -3457,7 +3636,11 @@ interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTextRun'>,
      *  per-slot render failures (both main `renderPage` and worker
      *  `renderPageToBitmap` rejections); a failed page is left blank rather than
      *  crashing the loop. Without an `onError`, render failures are logged via
-     *  `console.error` so they are never fully silent. */
+     *  `console.error` so they are never fully silent. Stable cases can be
+     *  narrowed with `OoxmlError`, `OoxmlResourceLimitError`, or
+     *  `OoxmlDecodedImageLimitError` re-exported by this package. Other failures
+     *  remain `Error` values; a `code` of `parser-crashed` identifies a recognized
+     *  WASM trap, not a reliably classified OOM. */
     onError?: (err: Error) => void;
 }
 declare class DocxScrollViewer implements ZoomableViewer {
@@ -3918,6 +4101,8 @@ declare class DocxScrollViewer implements ZoomableViewer {
      */
     private _onResize;
     get topVisiblePage(): number;
+    /** Return the owning engine's latest content-free package-usage snapshot. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Tear down the viewer: remove the DOM subtree and (only for a self-loaded
      * engine) destroy the engine. An injected engine is left intact — the caller
@@ -4004,4 +4189,4 @@ type DocxHighlightColors = FindHighlightColors;
  */
 declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
 //#endregion
-export { type AnchorHostMetrics, type AutoResizeOptions, type BodyElement, type BorderSpec, type CellBorders, type CellElement, type ChartRun, type ColSpec, type ColumnsSpec, type DocComment, type DocNote, type DocParagraph, type DocRevision, type DocRun, type DocSettings, type DocTable, type DocTableCell, type DocTableRow, DocxDocument, type DocxDocumentModel, type DocxHighlightColors, type DocxHighlightMatch, type DocxMatchLocation, type DocxRunBorder, DocxScrollViewer, type DocxScrollViewerOptions, type DocxTextRun, type DocxTextRunInfo, DocxViewer, type DocxViewerOptions, type EmbeddedFontRef, type FieldRun, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type FramePr, type GradientStop, type HeaderFooter, type HeadersFooters, type HyperlinkTarget, type ImageRun, type LineEnd, type LineNumbering, type LineSpacing, type LoadOptions, type NoteRef, type NumberingInfo, OoxmlError, type OoxmlErrorCode, type PTabRun, type PageBorderEdge, type PageBorders, type PageNumType, type ParaBorderEdge, type ParagraphBorders, type PathCmd, type RenderPageOptions, type RenderPageToBitmapOptions, type RubyAnnotation, type RunRevision, type SectionGeom, type SectionProps, type ShapeRun, type ShapeText, type ShapeTextRun, type TabStop, type TableBorders, type TblpPr, type TextPath, type WireRenderPageOptions, autoResize, buildDocxHighlightLayer, buildDocxTextLayer, noteText, openExternalHyperlink };
+export { type AnchorHostMetrics, type AutoResizeOptions, type BodyElement, type BorderSpec, type CellBorders, type CellElement, type ChartRun, type ColSpec, type ColumnsSpec, type DocComment, type DocNote, type DocParagraph, type DocRevision, type DocRun, type DocSettings, type DocTable, type DocTableCell, type DocTableRow, DocxDocument, type DocxDocumentModel, type DocxHighlightColors, type DocxHighlightMatch, type DocxMatchLocation, type DocxRunBorder, DocxScrollViewer, type DocxScrollViewerOptions, type DocxTextRun, type DocxTextRunInfo, DocxViewer, type DocxViewerOptions, type EmbeddedFontRef, type FieldRun, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type FramePr, type GradientStop, type HeaderFooter, type HeadersFooters, type HyperlinkTarget, type ImageRun, type LineEnd, type LineNumbering, type LineSpacing, type LoadOptions, type NoteRef, type NumberingInfo, OoxmlDecodedImageLimitError, type OoxmlDecodedImageLimitMetric, OoxmlError, type OoxmlErrorCode, type OoxmlErrorSource, type OoxmlErrorStage, type OoxmlFormat, type OoxmlResourceLimit, OoxmlResourceLimitError, type OoxmlResourceLimitErrorDetails, type OoxmlResourceLimits, type OoxmlResourceMetric, type OoxmlResourceMetrics, type OoxmlResourceMetricsCheckpoint, type OoxmlResourceName, type OoxmlResourcePolicySnapshot, type OoxmlResourceUsageSnapshot, type OoxmlResourceViolation, type PTabRun, type PageBorderEdge, type PageBorders, type PageNumType, type ParaBorderEdge, type ParagraphBorders, type PathCmd, type RenderPageOptions, type RenderPageToBitmapOptions, type RubyAnnotation, type RunRevision, type SectionGeom, type SectionProps, type ShapeRun, type ShapeText, type ShapeTextRun, type TabStop, type TableBorders, type TblpPr, type TextPath, type WireRenderPageOptions, autoResize, buildDocxHighlightLayer, buildDocxTextLayer, isOoxmlDecodedImageLimitError, noteText, openExternalHyperlink };