@silurus/ooxml 0.74.5 → 0.75.0

package/dist/types/pptx.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,155 +1240,17 @@ interface LoadOptions$1 {
     math?: MathRenderer;
 }
 //#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';
-/**
- * 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);
-}
-//#endregion
-//#region packages/core/src/autoResize.d.ts
-interface AutoResizeOptions {
-    /**
-     * Skip rendering while `document.hidden` is true and fire once with the latest
-     * observed size when the tab becomes visible again. Default: true.
-     */
-    pauseWhenHidden?: boolean;
-}
-/**
- * Observe an element's size and invoke a render callback, coalescing bursts to
- * one call per animation frame and serializing overlapping async renders.
- *
- * Framework-agnostic: call from any mount/setup hook and invoke the returned
- * disposer in the corresponding teardown hook.
- *
- * @example
- * const detach = autoResize(
- *   (width) => pres.renderSlide(canvas, 0, { width }),
- *   canvas,
- * );
- * // later
- * detach();
- */
-declare function autoResize(render: (width: number, height: number) => void | Promise<void>, element: Element, opts?: AutoResizeOptions): () => void;
-//#endregion
-//#region packages/core/src/interaction/zoomable.d.ts
-/**
- * IX9 — the shared zoom API contract for every viewer (DocxViewer, PptxViewer,
- * DocxScrollViewer, PptxScrollViewer, XlsxViewer).
- *
- * This module owns ONLY the pure, DOM-free pieces of the contract: the type
- * ({@link ZoomableViewer}), the discrete zoom-step ladder ({@link nextZoomStep} /
- * {@link prevZoomStep}), the fit-to-content scale math ({@link fitScale}), and the
- * range clamp ({@link clampScale}). Each viewer implements the interface with its
- * own scale field and re-render path; this keeps ONE definition of "what a zoom
- * factor means" and "what the +/- steps are" across all five, so a host can drive
- * any viewer through the same six calls without special-casing the format.
- *
- * SCALE SEMANTICS (the contract): a scale of `1` means 100% — the content at its
- * natural size (a docx page at `widthPt × PT_TO_PX`, a pptx slide at
- * `slideWidth / EMU_PER_PX`, an xlsx grid at `cellScale` 1). `getScale()` and
- * `setScale(n)` speak this user-facing factor for EVERY viewer.
- *
- * KNOWN FAMILY DIFFERENCE — the INITIAL scale right after load (deliberate,
- * documented rather than papered over): the single-canvas viewers (DocxViewer /
- * PptxViewer) and XlsxViewer start at `1` (or the effective factor implied by an
- * explicit `width` option); the continuous-scroll viewers (DocxScrollViewer /
- * PptxScrollViewer) AUTO-FIT to the container on first layout, so their
- * `getScale()` right after load reports the fit-to-width BASE factor (≠ 1 unless
- * the container happens to match the natural width). The unit is identical — only
- * the starting point differs, because fit-to-width is the natural resting state
- * of a continuous document viewer.
- *
- * PRE-LOAD `setScale` (family-unified, IX9 F1): a `setScale` called before the
- * content is loaded / before the layout is established is LATCHED — never
- * silently dropped — and applied once the viewer establishes its scale (the
- * single-canvas viewers honour it on the first render; the scroll viewers apply
- * it right after the base fit establishes, firing `onScaleChange` at application
- * time). `getScale()` reports the latched factor while it is pending.
- *
- * API SHAPE (idiomatic default — the integrator MAY veto; see the IX9 PR): a
- * six-method surface plus one change notification (`onScaleChange`). Deliberately
- * NO new UI here — the contract is API only (design decision IX9 §4). Touch-pinch
- * (IX8) is out of scope.
- */
-/**
- * The zoom contract every viewer satisfies. All scales are the user-facing factor
- * where `1` = 100% (see the module note). `fitWidth`/`fitPage` are async because a
- * fit re-renders at the new scale; the getters/steppers resolve synchronously.
- */
-interface ZoomableViewer {
-    /** The current zoom factor (`1` = 100%). Never throws — returns the default
-     *  (`1`) before anything is loaded, or the latched pending factor when a
-     *  pre-load `setScale` is waiting to be applied (see the module note). */
-    getScale(): number;
-    /** Set the absolute zoom factor (`1` = 100%), clamped to the viewer's
-     *  `[zoomMin, zoomMax]`. Re-renders at the new scale and fires `onScaleChange`
-     *  when the clamped value actually changes. Called BEFORE the content is
-     *  loaded / the layout is established, the (clamped) factor is LATCHED and
-     *  applied once the viewer establishes its scale — family-unified semantics
-     *  (IX9 F1): never silently dropped by any viewer. */
-    setScale(scale: number): void | Promise<void>;
-    /** Step up to the next larger rung of the shared zoom ladder (25 %→400 %),
-     *  clamped to `zoomMax`. Equivalent to `setScale(nextZoomStep(getScale()))`. */
-    zoomIn(): void | Promise<void>;
-    /** Step down to the next smaller ladder rung, clamped to `zoomMin`. */
-    zoomOut(): void | Promise<void>;
-    /** Fit the content's WIDTH to the container (the common "fit width" / "fit
-     *  page width" verb). Sets the scale so one page/slide/sheet-column-run spans
-     *  the available width, then re-renders. Resolves once the fit render settles.
-     *
-     *  PERSISTENCE is viewer-implementation-dependent (deliberate, by family): the
-     *  single-canvas viewers (DocxViewer / PptxViewer) and XlsxViewer apply the fit
-     *  ONE-SHOT — they observe no container resizes, so a later resize does NOT
-     *  re-fit (call `fitWidth()` again after a layout change). The continuous-
-     *  scroll viewers (DocxScrollViewer / PptxScrollViewer) re-fit their width-fit
-     *  base on every container resize, so a `fitWidth()` there effectively
-     *  PERSISTS across resizes (the resize re-fit preserves the width-fit state). */
-    fitWidth(): void | Promise<void>;
-    /** Fit the WHOLE content (width AND height) inside the container, so an entire
-     *  page/slide is visible without scrolling. Sets the scale to the smaller of the
-     *  width- and height-fit factors, then re-renders.
-     *
-     *  PERSISTENCE is viewer-implementation-dependent, and — unlike `fitWidth` —
-     *  a page fit does NOT persist across container resizes on ANY viewer: the
-     *  single-canvas viewers and XlsxViewer observe no resizes at all (one-shot),
-     *  and the continuous-scroll viewers' resize handler re-applies the WIDTH fit
-     *  (preserving the zoom multiplier), not the page fit. Re-invoke `fitPage()`
-     *  after a layout change to re-fit. */
-    fitPage(): void | Promise<void>;
-}
+//#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
 /**
@@ -1270,81 +1314,7 @@ type HyperlinkTarget = {
  */
 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[]`
- * and the `[start, end)` character range within that run's own `text`. A match
- * that straddles N runs yields N of these (the first sliced from its start
- * offset to the run end, the last from 0 to its end offset, any middle run
- * whole). The viewer measures each slice against that run's font to get a pixel
- * rectangle.
- */
-interface MatchRunSlice {
-    /** Index into the original `runs[]` handed to {@link buildTextIndex}. */
-    runIndex: number;
-    /** Start offset within `runs[runIndex].text` (inclusive). */
-    start: number;
-    /** End offset within `runs[runIndex].text` (exclusive). */
-    end: number;
-}
-/** Options for {@link findMatches}. */
-interface FindMatchesOptions {
-    /**
-     * Match case exactly. Default `false` (case-insensitive, like a browser's
-     * find-in-page). IX2 default — an integrator can pass `true`.
-     */
-    caseSensitive?: boolean;
-}
-//#endregion
-//#region packages/core/src/search/find-match.d.ts
-/**
- * IX2 public find-result shape, shared by all three viewers.
- *
- * `findText` returns an ordered list of {@link FindMatch}. Every match carries
- * its ordinal position (`matchIndex`, 0-based, document order — the same index
- * `findNext` / `findPrev` cycle through), the matched `text`, and a
- * format-specific `location`. The location is where the three formats
- * legitimately differ — a docx match lives on a page, a pptx match on a slide,
- * an xlsx match in a sheet cell — so `FindMatch` is generic over it rather than
- * forcing an artificial common shape. Each viewer instantiates it with its own
- * location type:
- *
- *   - `DocxViewer.findText` → `FindMatch<DocxMatchLocation>`  ({ page })
- *   - `PptxViewer.findText` → `FindMatch<PptxMatchLocation>`  ({ slide })
- *   - `XlsxViewer.findText` → `FindMatch<XlsxMatchLocation>`  ({ sheet, ref, … })
- *
- * The generic default is `unknown` so `FindMatch` can be referenced without a
- * type argument (e.g. in generic UI code) while each viewer's return type stays
- * precise.
- */
-interface FindMatch<Loc = unknown> {
-    /** 0-based ordinal among all matches, in document order. This is the index
-     *  `findNext`/`findPrev` make active, so a caller can correlate the array it
-     *  got from `findText` with the active-match reported by navigation. */
-    matchIndex: number;
-    /** The text that matched (the query as it appears in the document — its
-     *  original case, not the folded form used for case-insensitive matching). */
-    text: string;
-    /** Where the match is, in the format's own coordinates. */
-    location: Loc;
-}
-//#endregion
-//#region packages/core/src/search/find-highlight.d.ts
-/**
- * CSS colours used by in-document search overlays.
- *
- * The values are applied as the overlay backgrounds verbatim. Use an alpha
- * colour (`rgba(...)`, 8-digit hex, or `color-mix(...)`) when the rendered text
- * should remain visible through the highlight.
- */
-interface FindHighlightColors {
-    /** Background for every match except the active one. */
-    match?: string;
-    /** Background for the match selected by findNext/findPrev. */
-    active?: string;
-}
-//#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 = {
     cmd: 'moveTo';
@@ -1816,7 +1786,194 @@ interface RenderOptions {
     skipMediaControls?: boolean;
 }
 //#endregion
-//#region dist/.types-work/pptx-lmtZXJAj.d.ts
+//#region dist/.types-work/find-highlight-gMP3FAnW.d.ts
+//#region packages/core/src/autoResize.d.ts
+interface AutoResizeOptions {
+    /**
+     * Skip rendering while `document.hidden` is true and fire once with the latest
+     * observed size when the tab becomes visible again. Default: true.
+     */
+    pauseWhenHidden?: boolean;
+}
+/**
+ * Observe an element's size and invoke a render callback, coalescing bursts to
+ * one call per animation frame and serializing overlapping async renders.
+ *
+ * Framework-agnostic: call from any mount/setup hook and invoke the returned
+ * disposer in the corresponding teardown hook.
+ *
+ * @example
+ * const detach = autoResize(
+ *   (width) => pres.renderSlide(canvas, 0, { width }),
+ *   canvas,
+ * );
+ * // later
+ * detach();
+ */
+declare function autoResize(render: (width: number, height: number) => void | Promise<void>, element: Element, opts?: AutoResizeOptions): () => void;
+//#endregion
+//#region packages/core/src/interaction/zoomable.d.ts
+/**
+ * IX9 — the shared zoom API contract for every viewer (DocxViewer, PptxViewer,
+ * DocxScrollViewer, PptxScrollViewer, XlsxViewer).
+ *
+ * This module owns ONLY the pure, DOM-free pieces of the contract: the type
+ * ({@link ZoomableViewer}), the discrete zoom-step ladder ({@link nextZoomStep} /
+ * {@link prevZoomStep}), the fit-to-content scale math ({@link fitScale}), and the
+ * range clamp ({@link clampScale}). Each viewer implements the interface with its
+ * own scale field and re-render path; this keeps ONE definition of "what a zoom
+ * factor means" and "what the +/- steps are" across all five, so a host can drive
+ * any viewer through the same six calls without special-casing the format.
+ *
+ * SCALE SEMANTICS (the contract): a scale of `1` means 100% — the content at its
+ * natural size (a docx page at `widthPt × PT_TO_PX`, a pptx slide at
+ * `slideWidth / EMU_PER_PX`, an xlsx grid at `cellScale` 1). `getScale()` and
+ * `setScale(n)` speak this user-facing factor for EVERY viewer.
+ *
+ * KNOWN FAMILY DIFFERENCE — the INITIAL scale right after load (deliberate,
+ * documented rather than papered over): the single-canvas viewers (DocxViewer /
+ * PptxViewer) and XlsxViewer start at `1` (or the effective factor implied by an
+ * explicit `width` option); the continuous-scroll viewers (DocxScrollViewer /
+ * PptxScrollViewer) AUTO-FIT to the container on first layout, so their
+ * `getScale()` right after load reports the fit-to-width BASE factor (≠ 1 unless
+ * the container happens to match the natural width). The unit is identical — only
+ * the starting point differs, because fit-to-width is the natural resting state
+ * of a continuous document viewer.
+ *
+ * PRE-LOAD `setScale` (family-unified, IX9 F1): a `setScale` called before the
+ * content is loaded / before the layout is established is LATCHED — never
+ * silently dropped — and applied once the viewer establishes its scale (the
+ * single-canvas viewers honour it on the first render; the scroll viewers apply
+ * it right after the base fit establishes, firing `onScaleChange` at application
+ * time). `getScale()` reports the latched factor while it is pending.
+ *
+ * API SHAPE (idiomatic default — the integrator MAY veto; see the IX9 PR): a
+ * six-method surface plus one change notification (`onScaleChange`). Deliberately
+ * NO new UI here — the contract is API only (design decision IX9 §4). Touch-pinch
+ * (IX8) is out of scope.
+ */
+/**
+ * The zoom contract every viewer satisfies. All scales are the user-facing factor
+ * where `1` = 100% (see the module note). `fitWidth`/`fitPage` are async because a
+ * fit re-renders at the new scale; the getters/steppers resolve synchronously.
+ */
+interface ZoomableViewer {
+    /** The current zoom factor (`1` = 100%). Never throws — returns the default
+     *  (`1`) before anything is loaded, or the latched pending factor when a
+     *  pre-load `setScale` is waiting to be applied (see the module note). */
+    getScale(): number;
+    /** Set the absolute zoom factor (`1` = 100%), clamped to the viewer's
+     *  `[zoomMin, zoomMax]`. Re-renders at the new scale and fires `onScaleChange`
+     *  when the clamped value actually changes. Called BEFORE the content is
+     *  loaded / the layout is established, the (clamped) factor is LATCHED and
+     *  applied once the viewer establishes its scale — family-unified semantics
+     *  (IX9 F1): never silently dropped by any viewer. */
+    setScale(scale: number): void | Promise<void>;
+    /** Step up to the next larger rung of the shared zoom ladder (25 %→400 %),
+     *  clamped to `zoomMax`. Equivalent to `setScale(nextZoomStep(getScale()))`. */
+    zoomIn(): void | Promise<void>;
+    /** Step down to the next smaller ladder rung, clamped to `zoomMin`. */
+    zoomOut(): void | Promise<void>;
+    /** Fit the content's WIDTH to the container (the common "fit width" / "fit
+     *  page width" verb). Sets the scale so one page/slide/sheet-column-run spans
+     *  the available width, then re-renders. Resolves once the fit render settles.
+     *
+     *  PERSISTENCE is viewer-implementation-dependent (deliberate, by family): the
+     *  single-canvas viewers (DocxViewer / PptxViewer) and XlsxViewer apply the fit
+     *  ONE-SHOT — they observe no container resizes, so a later resize does NOT
+     *  re-fit (call `fitWidth()` again after a layout change). The continuous-
+     *  scroll viewers (DocxScrollViewer / PptxScrollViewer) re-fit their width-fit
+     *  base on every container resize, so a `fitWidth()` there effectively
+     *  PERSISTS across resizes (the resize re-fit preserves the width-fit state). */
+    fitWidth(): void | Promise<void>;
+    /** Fit the WHOLE content (width AND height) inside the container, so an entire
+     *  page/slide is visible without scrolling. Sets the scale to the smaller of the
+     *  width- and height-fit factors, then re-renders.
+     *
+     *  PERSISTENCE is viewer-implementation-dependent, and — unlike `fitWidth` —
+     *  a page fit does NOT persist across container resizes on ANY viewer: the
+     *  single-canvas viewers and XlsxViewer observe no resizes at all (one-shot),
+     *  and the continuous-scroll viewers' resize handler re-applies the WIDTH fit
+     *  (preserving the zoom multiplier), not the page fit. Re-invoke `fitPage()`
+     *  after a layout change to re-fit. */
+    fitPage(): void | Promise<void>;
+}
+//#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[]`
+ * and the `[start, end)` character range within that run's own `text`. A match
+ * that straddles N runs yields N of these (the first sliced from its start
+ * offset to the run end, the last from 0 to its end offset, any middle run
+ * whole). The viewer measures each slice against that run's font to get a pixel
+ * rectangle.
+ */
+interface MatchRunSlice {
+    /** Index into the original `runs[]` handed to {@link buildTextIndex}. */
+    runIndex: number;
+    /** Start offset within `runs[runIndex].text` (inclusive). */
+    start: number;
+    /** End offset within `runs[runIndex].text` (exclusive). */
+    end: number;
+}
+/** Options for {@link findMatches}. */
+interface FindMatchesOptions {
+    /**
+     * Match case exactly. Default `false` (case-insensitive, like a browser's
+     * find-in-page). IX2 default — an integrator can pass `true`.
+     */
+    caseSensitive?: boolean;
+}
+//#endregion
+//#region packages/core/src/search/find-match.d.ts
+/**
+ * IX2 public find-result shape, shared by all three viewers.
+ *
+ * `findText` returns an ordered list of {@link FindMatch}. Every match carries
+ * its ordinal position (`matchIndex`, 0-based, document order — the same index
+ * `findNext` / `findPrev` cycle through), the matched `text`, and a
+ * format-specific `location`. The location is where the three formats
+ * legitimately differ — a docx match lives on a page, a pptx match on a slide,
+ * an xlsx match in a sheet cell — so `FindMatch` is generic over it rather than
+ * forcing an artificial common shape. Each viewer instantiates it with its own
+ * location type:
+ *
+ *   - `DocxViewer.findText` → `FindMatch<DocxMatchLocation>`  ({ page })
+ *   - `PptxViewer.findText` → `FindMatch<PptxMatchLocation>`  ({ slide })
+ *   - `XlsxViewer.findText` → `FindMatch<XlsxMatchLocation>`  ({ sheet, ref, … })
+ *
+ * The generic default is `unknown` so `FindMatch` can be referenced without a
+ * type argument (e.g. in generic UI code) while each viewer's return type stays
+ * precise.
+ */
+interface FindMatch<Loc = unknown> {
+    /** 0-based ordinal among all matches, in document order. This is the index
+     *  `findNext`/`findPrev` make active, so a caller can correlate the array it
+     *  got from `findText` with the active-match reported by navigation. */
+    matchIndex: number;
+    /** The text that matched (the query as it appears in the document — its
+     *  original case, not the folded form used for case-insensitive matching). */
+    text: string;
+    /** Where the match is, in the format's own coordinates. */
+    location: Loc;
+}
+//#endregion
+//#region packages/core/src/search/find-highlight.d.ts
+/**
+ * CSS colours used by in-document search overlays.
+ *
+ * The values are applied as the overlay backgrounds verbatim. Use an alpha
+ * colour (`rgba(...)`, 8-digit hex, or `color-mix(...)`) when the rendered text
+ * should remain visible through the highlight.
+ */
+interface FindHighlightColors {
+    /** Background for every match except the active one. */
+    match?: string;
+    /** Background for the match selected by findNext/findPrev. */
+    active?: string;
+}
+//#endregion
+//#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
@@ -2515,18 +2672,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
@@ -2538,11 +2699,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): Promise<PptxPresentation>;
     private _parse;
@@ -2585,8 +2749,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. */
@@ -2598,7 +2761,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;
     /**
@@ -2647,7 +2810,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;
@@ -2655,10 +2818,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`,
@@ -2693,7 +2859,19 @@ type HiddenSlideMode = 'show' | 'skip' | 'dim';
 interface PptxViewerOptions extends RenderOptions, LoadOptions {
     /** 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`,
@@ -2991,6 +3169,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.
      *
@@ -3131,7 +3311,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
@@ -3645,6 +3829,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
@@ -3719,4 +3905,4 @@ 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;
 //#endregion
-export { type AutoResizeOptions, type Bevel3d, type BlipBullet, type Bullet, type Camera3d, type ChartElement, type ChartModel, type ChartSeries, type DimOptions, type Fill, type FillRect, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type Glow, type GradientFill, type GradientStop, type HiddenSlideMode, type HyperlinkTarget, type ImageFill, type LightRig, type LineBreak, type LoadOptions, type MediaElement, type NoFill, OoxmlError, type OoxmlErrorCode, type Paragraph, type PathCmd, type PictureElement, type PptxComment, type PptxHighlightColors, type PptxHighlightMatch, type PptxMatchLocation, PptxPresentation, PptxScrollViewer, type PptxScrollViewerOptions, type PptxTextRunInfo, PptxViewer, type PptxViewerOptions, type Presentation, type PresentationHandle, type Reflection, type RenderOptions, type RenderSlideOptions, type RenderSlideToBitmapOptions, type Rot3d, type Scene3d, type Shadow, type ShapeElement, type Slide, type SlideElement, type SoftEdge, type SolidFill, type Sp3d, type SpaceLine, type Stroke, type TabStop, type TableCell, type TableElement, type TableRow, type TextBody, type TextRect, type TextRun, type TextRunCallback, type TextRunData, type TileInfo, autoResize, buildPptxHighlightLayer, buildPptxTextLayer, openExternalHyperlink, renderSlide };
+export { type AutoResizeOptions, type Bevel3d, type BlipBullet, type Bullet, type Camera3d, type ChartElement, type ChartModel, type ChartSeries, type DimOptions, type Fill, type FillRect, type FindHighlightColors, type FindMatch, type FindMatchesOptions, type Glow, type GradientFill, type GradientStop, type HiddenSlideMode, type HyperlinkTarget, type ImageFill, type LightRig, type LineBreak, type LoadOptions, type MediaElement, type NoFill, 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 Paragraph, type PathCmd, type PictureElement, type PptxComment, type PptxHighlightColors, type PptxHighlightMatch, type PptxMatchLocation, PptxPresentation, PptxScrollViewer, type PptxScrollViewerOptions, type PptxTextRunInfo, PptxViewer, type PptxViewerOptions, type Presentation, type PresentationHandle, type Reflection, type RenderOptions, type RenderSlideOptions, type RenderSlideToBitmapOptions, type Rot3d, type Scene3d, type Shadow, type ShapeElement, type Slide, type SlideElement, type SoftEdge, type SolidFill, type Sp3d, type SpaceLine, type Stroke, type TabStop, type TableCell, type TableElement, type TableRow, type TextBody, type TextRect, type TextRun, type TextRunCallback, type TextRunData, type TileInfo, autoResize, buildPptxHighlightLayer, buildPptxTextLayer, isOoxmlDecodedImageLimitError, openExternalHyperlink, renderSlide };