@silurus/ooxml 0.74.6 → 0.75.0

package/dist/types/xlsx.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 {
@@ -949,7 +949,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
@@ -1016,12 +1166,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
@@ -1044,44 +1226,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 {
     /**
@@ -1193,68 +1412,6 @@ interface ZoomableViewer {
      *  after a layout change to re-fit. */
     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;
 /** Options for {@link findMatches}. */
 interface FindMatchesOptions {
     /**
@@ -1312,7 +1469,7 @@ interface FindHighlightColors {
     active?: string;
 }
 //#endregion
-//#region dist/.types-work/common-Bva7_XCn.d.ts
+//#region dist/.types-work/common-Bgczc_Eb.d.ts
 type SpaceLine = {
     type: 'pct';
     val: number;
@@ -1321,7 +1478,7 @@ type SpaceLine = {
     val: number;
 };
 //#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[];
@@ -1734,18 +1891,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;
@@ -2473,8 +2636,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$1 {
     /**
      * 'main' (default): parse in a worker, render on the main thread (current
@@ -2486,25 +2649,28 @@ interface LoadOptions extends LoadOptions$1 {
     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. */
@@ -2516,6 +2682,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>;
@@ -2541,6 +2717,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
@@ -2549,11 +2731,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
@@ -2620,7 +2803,9 @@ declare class XlsxWorkbook {
         width: number;
         height: number;
     }): Promise<ImageBitmap>;
+    private withWorksheetArchiveOperation;
     destroy(): void;
+    private assertResourceHealthy;
 }
 //#endregion
 //#region packages/xlsx/src/find.d.ts
@@ -2679,6 +2864,19 @@ interface XlsxViewerOptions extends LoadOptions$1 {
      * `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;
@@ -3320,6 +3518,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.
      *
@@ -3353,4 +3553,4 @@ declare class XlsxViewer implements ZoomableViewer {
  */
 declare function resolveSharedStrings(ws: Worksheet, sharedStrings: SharedString[]): Worksheet;
 //#endregion
-export { type AutoResizeOptions, type Border, type BorderEdge, type Cell, type CellAddress, type CellFill, type CellFont, type CellRange, type CellValue, type CellXf, type CfIcon, type CfRule, type CfStop, type CfValue, type ChartAnchor, type ChartDataLabelOverride, type ChartDataPointOverride, type ChartErrBars, type ChartManualLayout, type ChartModel, type ChartSeries, type ChartSeriesDataLabels, type ConditionalFormat, type DataLabelOverride, type DataPointOverride, type DataValidation, type DefinedName, type Duotone, type Dxf, type ErrBars, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type GradientFillSpec, type HiddenSheetMode, type Hyperlink, type HyperlinkTarget, type ImageAnchor, type LegendManualLayout, type LoadOptions, type ManualLayout, type MergeCell, type NumFmt, OoxmlError, type OoxmlErrorCode, type OutlinePr, type ParsedWorkbook, type PathCmd, type PathInfo, type PhoneticAlignment, type PhoneticProperties, type PhoneticRun, type PhoneticType, type PivotCacheSource, type PivotDataField, type PivotDiagnostic, type PivotLocation, type PivotMetadataStatus, type PivotPageField, type PivotPartialReason, type PivotTableMetadata, type RenderViewportOptions, type ResolvedList, type Row, type Run, type RunFont, type SelectionMode, type SeriesDataLabels, type ShapeAnchor, type ShapeGeom, type ShapeInfo, type ShapeParagraph, type ShapeText, type ShapeTextRun, type SharedString, type SheetMeta, type SheetVisibility, type SlicerAnchor, type SlicerElementStyle, type SlicerItem, type SlicerStyle, type Sparkline, type SparklineGroup, type Styles, type TableColumnInfo, type TableInfo, type ViewportRange, type WireRenderViewportOptions, type WireSizeOverrides, type Workbook, type Worksheet, type XlsxChartSeries, type XlsxComment, type XlsxMatchLocation, type XlsxTextRunInfo, XlsxViewer, type XlsxViewerOptions, XlsxWorkbook, autoResize, openExternalHyperlink, resolveSharedStrings };
+export { type AutoResizeOptions, type Border, type BorderEdge, type Cell, type CellAddress, type CellFill, type CellFont, type CellRange, type CellValue, type CellXf, type CfIcon, type CfRule, type CfStop, type CfValue, type ChartAnchor, type ChartDataLabelOverride, type ChartDataPointOverride, type ChartErrBars, type ChartManualLayout, type ChartModel, type ChartSeries, type ChartSeriesDataLabels, type ConditionalFormat, type DataLabelOverride, type DataPointOverride, type DataValidation, type DefinedName, type Duotone, type Dxf, type ErrBars, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type GradientFillSpec, type HiddenSheetMode, type Hyperlink, type HyperlinkTarget, type ImageAnchor, type LegendManualLayout, type LoadOptions, type ManualLayout, type MergeCell, type NumFmt, 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 OutlinePr, type ParsedWorkbook, type PathCmd, type PathInfo, type PhoneticAlignment, type PhoneticProperties, type PhoneticRun, type PhoneticType, type PivotCacheSource, type PivotDataField, type PivotDiagnostic, type PivotLocation, type PivotMetadataStatus, type PivotPageField, type PivotPartialReason, type PivotTableMetadata, type RenderViewportOptions, type ResolvedList, type Row, type Run, type RunFont, type SelectionMode, type SeriesDataLabels, type ShapeAnchor, type ShapeGeom, type ShapeInfo, type ShapeParagraph, type ShapeText, type ShapeTextRun, type SharedString, type SheetMeta, type SheetVisibility, type SlicerAnchor, type SlicerElementStyle, type SlicerItem, type SlicerStyle, type Sparkline, type SparklineGroup, type Styles, type TableColumnInfo, type TableInfo, type ViewportRange, type WireRenderViewportOptions, type WireSizeOverrides, type Workbook, type Worksheet, type XlsxChartSeries, type XlsxComment, type XlsxMatchLocation, type XlsxTextRunInfo, XlsxViewer, type XlsxViewerOptions, XlsxWorkbook, autoResize, isOoxmlDecodedImageLimitError, openExternalHyperlink, resolveSharedStrings };

package/dist/visible-index-CKvgpUrf.js

@@ -0,0 +1,17 @@
+//#region packages/core/src/nav/visible-index.ts
+function e(e, t, n, r) {
+	for (let i = e + t; i >= 0 && i < r; i += t) if (!n(i)) return i;
+	return e;
+}
+function t(t, n, r) {
+	if (r === 0 || !n(t)) return t;
+	let i = e(t, 1, n, r);
+	return i === t ? e(t, -1, n, r) : i;
+}
+function n(e, t) {
+	let n = 0;
+	for (let r = 0; r < t; r++) e(r) || n++;
+	return n;
+}
+//#endregion
+export { e as n, t as r, n as t };