@silurus/ooxml 0.74.5 → 0.75.0

package/dist/types/index.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$3 {
      */
     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$3 {
     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$2 extends LoadOptions$3 {
     /**
      * 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$2 {
      *  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,10 +4189,10 @@ 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;
 declare namespace docx_d_exports {
-    export { AnchorHostMetrics, AutoResizeOptions, BodyElement, BorderSpec, CellBorders, CellElement, ChartRun, ColSpec, ColumnsSpec, DocComment, DocNote, DocParagraph, DocRevision, DocRun, DocSettings, DocTable, DocTableCell, DocTableRow, DocxDocument, DocxDocumentModel, DocxHighlightColors, DocxHighlightMatch, DocxMatchLocation, DocxRunBorder, DocxScrollViewer, DocxScrollViewerOptions, DocxTextRun, DocxTextRunInfo, DocxViewer, DocxViewerOptions, EmbeddedFontRef, FieldRun, FindHighlightColors, FindMatch, FindMatchesOptions, FramePr, GradientStop$1 as GradientStop, HeaderFooter, HeadersFooters, HyperlinkTarget, ImageRun, LineEnd, LineNumbering, LineSpacing, LoadOptions$2 as LoadOptions, NoteRef, NumberingInfo, OoxmlError, OoxmlErrorCode, PTabRun, PageBorderEdge, PageBorders, PageNumType, ParaBorderEdge, ParagraphBorders, PathCmd$2 as PathCmd, RenderPageOptions, RenderPageToBitmapOptions, RubyAnnotation, RunRevision, SectionGeom, SectionProps, ShapeRun, ShapeText$1 as ShapeText, ShapeTextRun$1 as ShapeTextRun, TabStop$1 as TabStop, TableBorders, TblpPr, TextPath, WireRenderPageOptions, autoResize, buildDocxHighlightLayer, buildDocxTextLayer, noteText, openExternalHyperlink };
+    export { AnchorHostMetrics, AutoResizeOptions, BodyElement, BorderSpec, CellBorders, CellElement, ChartRun, ColSpec, ColumnsSpec, DocComment, DocNote, DocParagraph, DocRevision, DocRun, DocSettings, DocTable, DocTableCell, DocTableRow, DocxDocument, DocxDocumentModel, DocxHighlightColors, DocxHighlightMatch, DocxMatchLocation, DocxRunBorder, DocxScrollViewer, DocxScrollViewerOptions, DocxTextRun, DocxTextRunInfo, DocxViewer, DocxViewerOptions, EmbeddedFontRef, FieldRun, FindHighlightColors, FindMatch, FindMatchesOptions, FramePr, GradientStop$1 as GradientStop, HeaderFooter, HeadersFooters, HyperlinkTarget, ImageRun, LineEnd, LineNumbering, LineSpacing, LoadOptions$2 as LoadOptions, NoteRef, NumberingInfo, OoxmlDecodedImageLimitError, OoxmlDecodedImageLimitMetric, OoxmlError, OoxmlErrorCode, OoxmlErrorSource, OoxmlErrorStage, OoxmlFormat, OoxmlResourceLimit, OoxmlResourceLimitError, OoxmlResourceLimitErrorDetails, OoxmlResourceLimits, OoxmlResourceMetric, OoxmlResourceMetrics, OoxmlResourceMetricsCheckpoint, OoxmlResourceName, OoxmlResourcePolicySnapshot, OoxmlResourceUsageSnapshot, OoxmlResourceViolation, PTabRun, PageBorderEdge, PageBorders, PageNumType, ParaBorderEdge, ParagraphBorders, PathCmd$2 as PathCmd, RenderPageOptions, RenderPageToBitmapOptions, RubyAnnotation, RunRevision, SectionGeom, SectionProps, ShapeRun, ShapeText$1 as ShapeText, ShapeTextRun$1 as ShapeTextRun, TabStop$1 as TabStop, TableBorders, TblpPr, TextPath, WireRenderPageOptions, autoResize, buildDocxHighlightLayer, buildDocxTextLayer, isOoxmlDecodedImageLimitError, noteText, openExternalHyperlink };
 }
 //#endregion
-//#region dist/.types-work/common-Bva7_XCn.d.ts
+//#region dist/.types-work/common-Bgczc_Eb.d.ts
 //#region packages/core/src/types/common.d.ts
 type PathCmd$1 = {
     cmd: 'moveTo';
@@ -4479,7 +4664,7 @@ interface RenderOptions {
     skipMediaControls?: boolean;
 }
 //#endregion
-//#region dist/.types-work/pptx-lmtZXJAj.d.ts
+//#region dist/.types-work/pptx-B9ExAlcU.d.ts
 //#region packages/pptx/src/types.d.ts
 /**
  * Picture bullet — ECMA-376 §21.1.2.4.2 `<a:buBlip><a:blip r:embed>`. The
@@ -5178,18 +5363,22 @@ interface RenderSlideOptions {
  * await pres.renderSlide(canvas, 0, { width: 960 });
  */
 declare class PptxPresentation {
+    private _metrics;
     private readonly _worker;
     private readonly _bridge;
     private _mode;
-    private _presentation;
-    private _meta;
+    private _preflight;
+    private _slides;
+    private _slidePullClient;
+    /** First fatal package/model violation for this presentation generation. */
+    private _resourceFailure;
     /** Lazily-built `partName → slide index` map for internal hyperlink slide
      *  jumps (IX-nav). Cleared on {@link destroy}; built on first
-     *  {@link getSlideIndexByPartName}/{@link resolveInternalTarget} from either
-     *  the parsed slides (main) or the worker meta's `partNames` (worker). */
+     *  {@link getSlideIndexByPartName}/{@link resolveInternalTarget} from the
+     *  common compact preflight in either render mode. */
     private _slidePartIndex;
-    private _mediaCache;
-    private _imageCache;
+    /** One bounded retained-byte owner shared by images and media. */
+    private readonly _rawParts;
     /** Google-Fonts `FontFace` objects this deck preloaded 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
@@ -5201,11 +5390,14 @@ declare class PptxPresentation {
      *  images for a shared zip path like ppt/media/image1.png). Reusing the same
      *  reference across every render also lets those caches hit across slides. */
     private readonly _fetchImage;
+    private readonly _fetchMedia;
     /** Opt-in OMML equation engine, injected once at {@link load}. Every
      *  `renderSlide` / `presentSlide` reuses it — equations render when present,
      *  and are skipped (engine tree-shaken) when omitted. */
     private _math;
     private constructor();
+    private _assertResourceHealthy;
+    private _rethrowWithResourceFailure;
     /** Parse a PPTX from URL or ArrayBuffer. */
     static load(source: string | ArrayBuffer, opts?: LoadOptions$1): Promise<PptxPresentation>;
     private _parse;
@@ -5248,8 +5440,7 @@ declare class PptxPresentation {
      * caller's policy (see {@link PptxViewer}'s `hiddenSlideMode` modes).
      */
     isHidden(slideIndex: number): boolean;
-    /** The per-slide `partName` array (`sldIdLst` order) from either the parsed
-     *  model (main) or the worker meta (worker). Backs the lazy part-index map. */
+    /** The compact preflight's per-slide `partName` array (`sldIdLst` order). */
     private _partNames;
     /** Lazily build (and cache) the `partName → index` map. Nulled by
      *  {@link destroy} so a reused reference never serves a stale deck's indices. */
@@ -5261,7 +5452,7 @@ declare class PptxPresentation {
      * (`<a:hlinkClick action="ppaction://hlinksldjump" r:id>`, ECMA-376
      * §21.1.2.3.5) resolves against: the click's rel Target names a slide part, and
      * this turns it into the index a viewer can navigate to. Works in both `main`
-     * and `worker` mode (the part names ride along in the worker meta).
+     * and `worker` mode through the same compact preflight contract.
      */
     getSlideIndexByPartName(partName: string): number | undefined;
     /**
@@ -5310,7 +5501,7 @@ declare class PptxPresentation {
     collectSlideRuns(slideIndex: number, width?: number): Promise<PptxTextRunInfo[]>;
     /**
      * Extract raw media bytes for a zip path referenced by {@link MediaElement}.
-     * Results are cached by path for the lifetime of this instance.
+     * Results share a count- and byte-bounded cache with embedded images.
      */
     getMedia(mediaPath: string): Promise<Blob>;
     private _findMimeTypeForPath;
@@ -5318,10 +5509,13 @@ declare class PptxPresentation {
      * Extract raw bytes for an embedded image by zip path (e.g.
      * "ppt/media/image1.png"), wrapped in a Blob of the given MIME type. Mirrors
      * {@link getMedia}; results are cached by path for the lifetime of this
-     * instance. The renderer routes its `fetchImage` option here so images are
+     * instance within a common count and byte budget. The renderer routes its `fetchImage` option here so images are
      * decoded lazily rather than inlined as base64 at parse time.
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
+    /** Return a fresh content-free metrics snapshot, including lazy slide and
+     * media work completed since load. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Project the presentation to GitHub-flavoured markdown: title slides become
      * `#` headings, body shapes become nested bullets at each paragraph's `lvl`,
@@ -5356,7 +5550,19 @@ type HiddenSlideMode = 'show' | 'skip' | 'dim';
 interface PptxViewerOptions extends RenderOptions, LoadOptions$1 {
     /** Called when a slide finishes rendering */
     onSlideChange?: (index: number, total: number) => void;
-    /** Called on parse, render, or embedded-media playback errors. */
+    /**
+     * Receives load failures plus asynchronous render or embedded-media 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 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;
     /** IX9 zoom contract ({@link ZoomableViewer}) — the clamp range for
      *  {@link PptxViewer.setScale} / `zoomIn` / `zoomOut` / `fitWidth` / `fitPage`,
@@ -5654,6 +5860,8 @@ declare class PptxViewer implements ZoomableViewer {
      *  teardown. Mirrors the scroll viewers' `_reportRenderError` so all three
      *  single-canvas viewers agree. */
     private _reportRenderError;
+    /** Latest content-free resource metrics for the loaded presentation. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Clean up the viewer and terminate the background worker.
      *
@@ -5794,7 +6002,11 @@ interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTextRun'>,
      *  `renderSlideToBitmap` rejections) and embedded-media fetch/decode/playback
      *  failures. A failed slide is left blank rather than crashing the loop.
      *  Without an `onError`, failures are logged via `console.error` so they are
-     *  never fully silent. */
+     *  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;
     /**
      * IX1 (design decision — NOT user-confirmed, integrator may veto). Fires on a
@@ -6308,6 +6520,8 @@ declare class PptxScrollViewer implements ZoomableViewer {
      */
     private _onResize;
     get topVisibleSlide(): 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
@@ -6382,10 +6596,10 @@ type PptxHighlightColors = FindHighlightColors;
  */
 declare function buildPptxHighlightLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], matches: PptxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: PptxHighlightColors): void;
 declare namespace pptx_d_exports {
-    export { AutoResizeOptions, Bevel3d, BlipBullet, Bullet, Camera3d, ChartElement, ChartModel, ChartSeries, DimOptions, Fill, FillRect, FindHighlightColors, FindMatch, FindMatchesOptions, Glow, GradientFill, GradientStop, HiddenSlideMode, HyperlinkTarget, ImageFill, LightRig, LineBreak, LoadOptions$1 as LoadOptions, MediaElement, NoFill, OoxmlError, OoxmlErrorCode, Paragraph, PathCmd$1 as PathCmd, PictureElement, PptxComment, PptxHighlightColors, PptxHighlightMatch, PptxMatchLocation, PptxPresentation, PptxScrollViewer, PptxScrollViewerOptions, PptxTextRunInfo, PptxViewer, PptxViewerOptions, Presentation, PresentationHandle, Reflection, RenderOptions, RenderSlideOptions, RenderSlideToBitmapOptions, Rot3d, Scene3d, Shadow, ShapeElement, Slide, SlideElement, SoftEdge, SolidFill, Sp3d, SpaceLine, Stroke, TabStop, TableCell, TableElement, TableRow, TextBody, TextRect, TextRun, TextRunCallback, TextRunData, TileInfo, autoResize, buildPptxHighlightLayer, buildPptxTextLayer, openExternalHyperlink, renderSlide };
+    export { AutoResizeOptions, Bevel3d, BlipBullet, Bullet, Camera3d, ChartElement, ChartModel, ChartSeries, DimOptions, Fill, FillRect, FindHighlightColors, FindMatch, FindMatchesOptions, Glow, GradientFill, GradientStop, HiddenSlideMode, HyperlinkTarget, ImageFill, LightRig, LineBreak, LoadOptions$1 as LoadOptions, MediaElement, NoFill, OoxmlDecodedImageLimitError, OoxmlDecodedImageLimitMetric, OoxmlError, OoxmlErrorCode, OoxmlErrorSource, OoxmlErrorStage, OoxmlFormat, OoxmlResourceLimit, OoxmlResourceLimitError, OoxmlResourceLimitErrorDetails, OoxmlResourceLimits, OoxmlResourceMetric, OoxmlResourceMetrics, OoxmlResourceMetricsCheckpoint, OoxmlResourceName, OoxmlResourcePolicySnapshot, OoxmlResourceUsageSnapshot, OoxmlResourceViolation, Paragraph, PathCmd$1 as PathCmd, PictureElement, PptxComment, PptxHighlightColors, PptxHighlightMatch, PptxMatchLocation, PptxPresentation, PptxScrollViewer, PptxScrollViewerOptions, PptxTextRunInfo, PptxViewer, PptxViewerOptions, Presentation, PresentationHandle, Reflection, RenderOptions, RenderSlideOptions, RenderSlideToBitmapOptions, Rot3d, Scene3d, Shadow, ShapeElement, Slide, SlideElement, SoftEdge, SolidFill, Sp3d, SpaceLine, Stroke, TabStop, TableCell, TableElement, TableRow, TextBody, TextRect, TextRun, TextRunCallback, TextRunData, TileInfo, autoResize, buildPptxHighlightLayer, buildPptxTextLayer, isOoxmlDecodedImageLimitError, openExternalHyperlink, renderSlide };
 }
 //#endregion
-//#region dist/.types-work/xlsx-DAB_laks.d.ts
+//#region dist/.types-work/xlsx-yYJn5jBA.d.ts
 //#region packages/xlsx/src/types.d.ts
 interface Workbook {
     sheets: SheetMeta[];
@@ -6798,18 +7012,24 @@ interface DataValidation {
 }
 /**
  * @deprecated Chart series are now the core {@link ChartModel}'s `ChartSeries`.
- * Kept as an alias for backward-compatible imports.
+ * Kept as an alias for backward-compatible imports; scheduled for removal in a
+ * future breaking release.
  */
 type XlsxChartSeries = ChartSeries;
-/** @deprecated Use `ChartSeriesDataLabels` from @silurus/ooxml-core. */
+/** @deprecated Use `ChartSeriesDataLabels` from @silurus/ooxml-core. Scheduled
+ * for removal in a future breaking release. */
 type SeriesDataLabels = ChartSeriesDataLabels;
-/** @deprecated Use `ChartDataLabelOverride` from @silurus/ooxml-core. */
+/** @deprecated Use `ChartDataLabelOverride` from @silurus/ooxml-core. Scheduled
+ * for removal in a future breaking release. */
 type DataLabelOverride = ChartDataLabelOverride;
-/** @deprecated Use `ChartDataPointOverride` from @silurus/ooxml-core. */
+/** @deprecated Use `ChartDataPointOverride` from @silurus/ooxml-core. Scheduled
+ * for removal in a future breaking release. */
 type DataPointOverride = ChartDataPointOverride;
-/** @deprecated Use `ChartErrBars` from @silurus/ooxml-core. */
+/** @deprecated Use `ChartErrBars` from @silurus/ooxml-core. Scheduled for
+ * removal in a future breaking release. */
 type ErrBars = ChartErrBars;
-/** @deprecated Use `ChartManualLayout` from @silurus/ooxml-core. */
+/** @deprecated Use `ChartManualLayout` from @silurus/ooxml-core. Scheduled for
+ * removal in a future breaking release. */
 type ManualLayout = ChartManualLayout;
 interface ChartAnchor {
     fromCol: number;
@@ -7537,8 +7757,8 @@ type WireRenderViewportOptions = Omit<RenderViewportOptions, 'onTextRun' | 'load
 //#endregion
 //#region packages/xlsx/src/workbook.d.ts
 /** Options for {@link XlsxWorkbook.load}. Extends the shared load-options type
- *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`, `math`)
- *  with the worker-rendering mode. */
+ *  from `@silurus/ooxml-core` (`useGoogleFonts`, `resourceLimits`, the
+ *  deprecated `maxZipEntryBytes` alias, and `math`) with worker rendering. */
 interface LoadOptions extends LoadOptions$3 {
     /**
      * 'main' (default): parse in a worker, render on the main thread (current
@@ -7550,25 +7770,28 @@ interface LoadOptions extends LoadOptions$3 {
     mode?: 'main' | 'worker';
 }
 declare class XlsxWorkbook {
+    private metrics;
     private worker;
     private bridge;
     private parsedWorkbook;
     private sheetCache;
-    /** Cache of decoded image sources keyed by their zip `imagePath`. Shared
-     *  across sheets. */
-    private imageCache;
+    /** One materialization per sheet at a time. This becomes the ownership seam
+     * for the bounded worksheet cursor: concurrent callers share one cursor and
+     * one eventual mutable compatibility object instead of doubling peak work. */
+    private sheetLoads;
     /** Cache of fetched image *bytes* (as Blobs) keyed by zip path, populated by
      *  {@link XlsxWorkbook.getImage}. Twin of pptx/docx's per-instance
-     *  `_imageCache`; kept separate from {@link XlsxWorkbook.imageCache} (decoded
-     *  sources) so each layer dedupes independently. */
-    private imageBlobCache;
+     *  raw-part owner; decoded sources are owned separately by core. */
+    private readonly rawParts;
+    /** Public archive-queue reservations. Kept separate so an active render does
+     * not await a same-path load that is queued behind that render. */
+    private queuedImageLoads;
     /** One stable closure per instance: core's path-keyed SVG cache namespaces on
      *  this identity, so two open workbooks never swap a shared zip path (e.g.
      *  xl/media/image1.svg). Reusing one reference also lets the SVG cache hit
      *  across viewport renders. */
     private readonly _fetchImage;
-    private rawData;
-    private maxZipEntryBytes;
+    private resourcePolicy;
     /** Opt-in OMML equation engine, injected once at {@link load}. Every
      *  `renderViewport` call reuses it — equations in shapes render when present,
      *  and are skipped (engine tree-shaken) when omitted. */
@@ -7580,6 +7803,16 @@ declare class XlsxWorkbook {
      *  so a web font shared with another open workbook survives until both go). */
     private googleFontFaces;
     private _mode;
+    private generation;
+    private nextSheetSessionId;
+    private archiveOperationTail;
+    private sheetSessions;
+    private workerTimeoutMs;
+    private retainedSheetUsage;
+    /** First fatal model/package violation. Compatibility materialization happens
+     * on main, so this latch is the document-level poison boundary for every
+     * later public operation on the same workbook instance. */
+    private resourceFailure;
     private constructor();
     /** Parse an XLSX from a URL or ArrayBuffer. */
     static load(source: string | ArrayBuffer, opts?: LoadOptions): Promise<XlsxWorkbook>;
@@ -7605,6 +7838,12 @@ declare class XlsxWorkbook {
      */
     isHidden(sheetIndex: number): boolean;
     getWorksheet(sheetIndex: number): Promise<Worksheet>;
+    /** Return a fresh content-free metrics snapshot, including lazy worksheet and
+     * media work completed since load. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
+    private loadWorksheet;
+    private loadWorksheetStream;
+    private runArchiveOperation;
     /**
      * Fetch an embedded image's bytes by zip path (e.g. `xl/media/image1.png`),
      * wrapped in a Blob of the given MIME. The bytes are pulled through the
@@ -7613,11 +7852,12 @@ declare class XlsxWorkbook {
      * instance. The renderer's `fetchImage` option points here so image bytes are
      * extracted lazily rather than inlined as base64 at parse time.
      *
-     * Routed through the worker even though the main thread also retains
-     * `rawData`, to keep all WASM `extract_image` decoding on the worker (the
-     * route-through-worker decision).
+     * Routed through the persistent worker so all WASM `extract_image` decoding
+     * stays with the archive owner.
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
+    private getImageWithinArchiveOperation;
+    private requestImage;
     /**
      * Project the workbook to GitHub-flavoured markdown: each sheet becomes a
      * `## SheetName` section followed by a pipe table of its populated bounding
@@ -7684,7 +7924,9 @@ declare class XlsxWorkbook {
         width: number;
         height: number;
     }): Promise<ImageBitmap>;
+    private withWorksheetArchiveOperation;
     destroy(): void;
+    private assertResourceHealthy;
 }
 //#endregion
 //#region packages/xlsx/src/find.d.ts
@@ -7743,6 +7985,19 @@ interface XlsxViewerOptions extends LoadOptions$3 {
      * `onReady`).
      */
     onSheetChange?: (index: number, total: number) => void;
+    /**
+     * 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;
     /** Called when the selected cell range changes. null means no selection. */
     onSelectionChange?: (selection: CellRange | null) => void;
@@ -8384,6 +8639,8 @@ declare class XlsxViewer implements ZoomableViewer {
     get sheetNames(): string[];
     /** The underlying <canvas> element the grid is drawn on. */
     get canvasElement(): HTMLCanvasElement;
+    /** Latest content-free resource metrics for the loaded workbook. */
+    getResourceMetrics(): Promise<OoxmlResourceMetrics>;
     /**
      * Tear down the viewer and release resources.
      *
@@ -8417,7 +8674,7 @@ declare class XlsxViewer implements ZoomableViewer {
  */
 declare function resolveSharedStrings(ws: Worksheet, sharedStrings: SharedString[]): Worksheet;
 declare namespace xlsx_d_exports {
-    export { AutoResizeOptions, Border, BorderEdge, Cell, CellAddress, CellFill, CellFont, CellRange, CellValue, CellXf, CfIcon, CfRule, CfStop, CfValue, ChartAnchor, ChartDataLabelOverride, ChartDataPointOverride, ChartErrBars, ChartManualLayout, ChartModel, ChartSeries, ChartSeriesDataLabels, ConditionalFormat, DataLabelOverride, DataPointOverride, DataValidation, DefinedName, Duotone, Dxf, ErrBars, FindHighlightColors, FindMatch, FindMatchesOptions, GradientFillSpec, HiddenSheetMode, Hyperlink, HyperlinkTarget, ImageAnchor, LegendManualLayout, LoadOptions, ManualLayout, MergeCell, NumFmt, OoxmlError, OoxmlErrorCode, OutlinePr, ParsedWorkbook, PathCmd, PathInfo, PhoneticAlignment, PhoneticProperties, PhoneticRun, PhoneticType, PivotCacheSource, PivotDataField, PivotDiagnostic, PivotLocation, PivotMetadataStatus, PivotPageField, PivotPartialReason, PivotTableMetadata, RenderViewportOptions, ResolvedList, Row, Run, RunFont, SelectionMode, SeriesDataLabels, ShapeAnchor, ShapeGeom, ShapeInfo, ShapeParagraph, ShapeText, ShapeTextRun, SharedString, SheetMeta, SheetVisibility, SlicerAnchor, SlicerElementStyle, SlicerItem, SlicerStyle, Sparkline, SparklineGroup, Styles, TableColumnInfo, TableInfo, ViewportRange, WireRenderViewportOptions, WireSizeOverrides, Workbook, Worksheet, XlsxChartSeries, XlsxComment, XlsxMatchLocation, XlsxTextRunInfo, XlsxViewer, XlsxViewerOptions, XlsxWorkbook, autoResize, openExternalHyperlink, resolveSharedStrings };
+    export { AutoResizeOptions, Border, BorderEdge, Cell, CellAddress, CellFill, CellFont, CellRange, CellValue, CellXf, CfIcon, CfRule, CfStop, CfValue, ChartAnchor, ChartDataLabelOverride, ChartDataPointOverride, ChartErrBars, ChartManualLayout, ChartModel, ChartSeries, ChartSeriesDataLabels, ConditionalFormat, DataLabelOverride, DataPointOverride, DataValidation, DefinedName, Duotone, Dxf, ErrBars, FindHighlightColors, FindMatch, FindMatchesOptions, GradientFillSpec, HiddenSheetMode, Hyperlink, HyperlinkTarget, ImageAnchor, LegendManualLayout, LoadOptions, ManualLayout, MergeCell, NumFmt, OoxmlDecodedImageLimitError, OoxmlDecodedImageLimitMetric, OoxmlError, OoxmlErrorCode, OoxmlErrorSource, OoxmlErrorStage, OoxmlFormat, OoxmlResourceLimit, OoxmlResourceLimitError, OoxmlResourceLimitErrorDetails, OoxmlResourceLimits, OoxmlResourceMetric, OoxmlResourceMetrics, OoxmlResourceMetricsCheckpoint, OoxmlResourceName, OoxmlResourcePolicySnapshot, OoxmlResourceUsageSnapshot, OoxmlResourceViolation, OutlinePr, ParsedWorkbook, PathCmd, PathInfo, PhoneticAlignment, PhoneticProperties, PhoneticRun, PhoneticType, PivotCacheSource, PivotDataField, PivotDiagnostic, PivotLocation, PivotMetadataStatus, PivotPageField, PivotPartialReason, PivotTableMetadata, RenderViewportOptions, ResolvedList, Row, Run, RunFont, SelectionMode, SeriesDataLabels, ShapeAnchor, ShapeGeom, ShapeInfo, ShapeParagraph, ShapeText, ShapeTextRun, SharedString, SheetMeta, SheetVisibility, SlicerAnchor, SlicerElementStyle, SlicerItem, SlicerStyle, Sparkline, SparklineGroup, Styles, TableColumnInfo, TableInfo, ViewportRange, WireRenderViewportOptions, WireSizeOverrides, Workbook, Worksheet, XlsxChartSeries, XlsxComment, XlsxMatchLocation, XlsxTextRunInfo, XlsxViewer, XlsxViewerOptions, XlsxWorkbook, autoResize, isOoxmlDecodedImageLimitError, openExternalHyperlink, resolveSharedStrings };
 }
 //#endregion
 export { docx_d_exports as docx, pptx_d_exports as pptx, xlsx_d_exports as xlsx };