@silurus/ooxml 0.69.0 → 0.70.1

package/dist/types/pptx.d.ts

@@ -68,6 +68,25 @@ export declare interface BlipBullet {
     sizePct: number | null;
 }
 
+/**
+ * Build the transparent text-selection overlay for a rendered pptx slide. Unlike
+ * docx (flat spans), pptx groups runs into one positioned `<div>` per shape frame
+ * (keyed by the shape's geometry + total rotation) and applies a CSS `rotate()` to
+ * the group when the shape is rotated, so the browser selection tracks the drawn,
+ * rotated text as a unit. Each run's `<span>` is absolutely positioned INSIDE its
+ * shape div (`inShapeX`/`inShapeY`). Extracted verbatim from
+ * `PptxViewer._buildTextLayer` so the pager (PptxViewer) and the continuous-scroll
+ * viewer (PptxScrollViewer, WS4) share one implementation; public API for
+ * integrators (design §10). MAIN render mode only — `onTextRun` cannot cross the
+ * worker boundary.
+ *
+ * @param layer     the overlay div.
+ * @param runs      per-run + per-shape geometry from `renderSlide({ onTextRun })`.
+ * @param cssWidth  the rendered canvas's CSS width (px, number).
+ * @param cssHeight the rendered canvas's CSS height (px, number).
+ */
+export declare function buildPptxTextLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], cssWidth: number, cssHeight: number): void;
+
 /**
  * PPTX bullet marker. The shared core {@link CoreBullet} union
  * (none/inherit/char/autoNum) plus the PPTX-only picture bullet
@@ -136,117 +155,19 @@ declare interface ChartDataPointOverride {
  */
 export declare interface ChartElement {
     type: 'chart';
+    /** Frame geometry on the slide, in EMU. */
     x: number;
     y: number;
     width: number;
     height: number;
-    chartType: string;
-    title: string | null;
-    categories: string[];
-    series: ChartSeries[];
-    valMax: number | null;
-    valMin: number | null;
-    subtotalIndices: number[];
-    showDataLabels: boolean;
-    catAxisHidden: boolean;
-    valAxisHidden: boolean;
-    /** `<c:catAx><c:spPr><a:ln><a:noFill>` — line-only hide; labels stay. */
-    catAxisLineHidden?: boolean;
-    /** `<c:valAx><c:spPr><a:ln><a:noFill>` — line-only hide; labels stay. */
-    valAxisLineHidden?: boolean;
-    plotAreaBg: string | null;
-    /** Outer chartSpace background (hex without '#'). null when noFill/absent. */
-    chartBg: string | null;
-    /** True when <c:legend> is declared; false suppresses the legend entirely. */
-    showLegend: boolean;
-    /** catAx crossBetween: "between" (default, 0.5-step padding) or "midCat". */
-    catAxisCrossBetween: 'between' | 'midCat' | string;
-    /** `<c:valAx><c:majorTickMark>`. "cross" (default) | "out" | "in" | "none". */
-    valAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
-    /** `<c:catAx><c:majorTickMark>`. */
-    catAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
-    /** Title font size in OOXML hundredths of a point (1600 = 16pt). null = default. */
-    titleFontSizeHpt: number | null;
-    /** Title font color as a hex string without '#'. null = default/theme. */
-    titleFontColor?: string | null;
-    /** Title font family (`<a:latin typeface>`). null = default/theme. */
-    titleFontFace?: string | null;
-    /** `<c:catAx><c:txPr>` font size (hpt). null = proportional default. */
-    catAxisFontSizeHpt: number | null;
-    /** `<c:valAx><c:txPr>` font size (hpt). null = proportional default. */
-    valAxisFontSizeHpt: number | null;
-    /** `<c:catAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#'). */
-    catAxisFontColor?: string | null;
-    /** `<c:valAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#'). */
-    valAxisFontColor?: string | null;
-    /** `<c:catAx><c:spPr><a:ln><a:solidFill>` axis-line color (hex without '#'). */
-    catAxisLineColor?: string | null;
-    /** `<c:catAx><c:spPr><a:ln w>` axis-line width in EMU. */
-    catAxisLineWidthEmu?: number | null;
-    /** `<c:valAx><c:spPr><a:ln><a:solidFill>` axis-line color (hex without '#'). */
-    valAxisLineColor?: string | null;
-    /** `<c:valAx><c:spPr><a:ln w>` axis-line width in EMU. */
-    valAxisLineWidthEmu?: number | null;
-    /** `<c:dLbls><c:txPr>` font size (hpt) for data-point value labels. */
-    dataLabelFontSizeHpt: number | null;
-    /** `<c:legend><c:legendPos val>` — "r" (default) | "l" | "t" | "b" | "tr". */
-    legendPos?: 'r' | 'l' | 't' | 'b' | 'tr' | null;
-    /** `<c:barChart><c:gapWidth val>` — % of bar width between category groups (default 150). */
-    barGapWidth?: number | null;
-    /** `<c:barChart><c:overlap val>` — signed % of bar width for cluster overlap. */
-    barOverlap?: number | null;
-    /** `<c:dLbls><c:dLblPos val>` — data label placement ("ctr" | "inEnd" | "outEnd" | …). */
-    dataLabelPosition?: string | null;
-    /** `<c:dLbls><c:txPr>…<a:solidFill>` resolved to hex (no '#'). null = renderer default. */
-    dataLabelFontColor?: string | null;
-    /** `<c:dLbls><c:numFmt formatCode>` — data label number format. */
-    dataLabelFormatCode?: string | null;
-    /** `<c:valAx><c:numFmt formatCode>` — value-axis tick label number format. */
-    valAxisFormatCode?: string | null;
-    /** `<c:plotArea><c:layout><c:manualLayout>` (ECMA-376 §21.2.2.32) — explicit
-     * plot-area placement so bars don't extend past the chart-frame's intended
-     * inner region (sample-2 slide-16 horizontal bar chart). */
-    plotAreaManualLayout?: ChartManualLayout | null;
-    /** `<c:scatterChart><c:scatterStyle val>` (ECMA-376 §21.2.2.42) — drives
-     * whether scatter charts connect points with straight or smooth lines. */
-    scatterStyle?: string | null;
-    /** `<c:radarChart><c:radarStyle val>` (ECMA-376 §21.2.3.10). */
-    radarStyle?: string | null;
-    /** `<c:catAx><c:title>` plain text (ECMA-376 §21.2.2.6). For scatter the
-     * bottom `<c:valAx>` (axPos b/t) feeds this. null = no title. */
-    catAxisTitle?: string | null;
-    /** `<c:valAx><c:title>` plain text. For scatter the left `<c:valAx>`
-     * (axPos l/r) feeds this. null = no title. */
-    valAxisTitle?: string | null;
-    /** `<c:catAx><c:title>` run-prop font size (hpt). Distinct from
-     * `catAxisFontSizeHpt` (tick labels). null = renderer default. */
-    catAxisTitleSize?: number | null;
-    /** `<c:catAx><c:title>` run-prop bold flag. null = not bold. */
-    catAxisTitleBold?: boolean | null;
-    /** `<c:catAx><c:title>` run-prop color (hex without '#'). null = default. */
-    catAxisTitleColor?: string | null;
-    /** `<c:valAx><c:title>` run-prop font size (hpt). null = renderer default. */
-    valAxisTitleSize?: number | null;
-    /** `<c:valAx><c:title>` run-prop bold flag. null = not bold. */
-    valAxisTitleBold?: boolean | null;
-    /** `<c:valAx><c:title>` run-prop color (hex without '#'). null = default. */
-    valAxisTitleColor?: string | null;
-    /** `<c:title>...defRPr@b` chart title bold flag. null = not bold. */
-    titleFontBold?: boolean | null;
-    /** `<c:catAx><c:txPr>...defRPr@b` X-axis tick-label bold flag. null = not bold. */
-    catAxisFontBold?: boolean | null;
-    /** `<c:valAx><c:txPr>...defRPr@b` Y-axis tick-label bold flag. null = not bold. */
-    valAxisFontBold?: boolean | null;
-    /** Explicit chart border color (hex without '#') from
-     * `<c:chartSpace><c:spPr><a:ln><a:solidFill><a:srgbClr>`. Only set when the
-     * XML explicitly declares a paintable line; null otherwise (no default border). */
-    chartBorderColor?: string | null;
-    /** `<c:chartSpace><c:spPr><a:ln@w>` border width in EMU. null = 1px hairline
-     * when a color is present. */
-    chartBorderWidthEmu?: number | null;
-    /** Secondary value axis for combo charts (bar + line with a right-hand
-     * axis). null/absent for the common single value-axis case. */
-    secondaryValAxis?: SecondaryValueAxis | null;
+    /**
+     * The chart payload, already in the canonical {@link ChartModel} shape emitted
+     * by the Rust parser (`ooxml_common::chart::ChartModel`). Passed straight to
+     * `@silurus/ooxml-core`'s `renderChart` — no per-field adapter. The former
+     * 60-field flat copy on this interface is gone; all chart properties now live
+     * on `chart`.
+     */
+    chart: ChartModel;
 }
 
 declare interface ChartErrBars {
@@ -600,6 +521,20 @@ declare interface ChartSeriesDataLabels {
  */
 declare type ChartType = 'line' | 'stackedLine' | 'stackedLinePct' | 'clusteredBar' | 'clusteredBarH' | 'stackedBar' | 'stackedBarH' | 'stackedBarPct' | 'stackedBarHPct' | 'area' | 'stackedArea' | 'stackedAreaPct' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'radar' | 'waterfall' | string;
 
+/**
+ * Translucent overlay drawn over a finished slide so it reads faintly
+ * (PowerPoint's hidden-slide thumbnail look). A pure render mechanism: the
+ * renderer never decides *when* to dim — the caller ({@link PptxViewer}'s
+ * `'dim'` mode) does. Both fields are required at the engine boundary; the
+ * viewer-facing override (`PptxViewerOptions.hiddenSlideDim`) is partial.
+ */
+export declare interface DimOptions {
+    /** CSS color of the overlay (e.g. `'#ffffff'`). */
+    color: string;
+    /** Overlay opacity 0..1 (e.g. `0.6` ⇒ underlying content shows at 40%). */
+    opacity: number;
+}
+
 /**
  * An OMML equation embedded in a paragraph (ECMA-376 §22.1). Parsed into the
  * shared math AST and rendered by `@silurus/ooxml-core`'s math engine.
@@ -654,6 +589,9 @@ export declare interface GradientStop {
     color: string;
 }
 
+/** How {@link PptxViewer} presents hidden slides (`<p:sld show="0">`). */
+export declare type HiddenSlideMode = 'show' | 'skip' | 'dim';
+
 /**
  * Image fill — ECMA-376 §20.1.8.14 (CT_BlipFillProperties). The embedded blip
  * is carried as a zip path + MIME; the renderer fetches the bytes on demand via
@@ -746,6 +684,21 @@ declare interface LoadOptions_2 {
      * via `@font-face` in your application CSS.
      */
     useGoogleFonts?: boolean;
+    /**
+     * Override the URL the parser worker fetches the WebAssembly module from.
+     *
+     * By default each format resolves the `.wasm` asset that ships next to its
+     * bundle (relative to the module URL), so no configuration is needed. Set
+     * this to serve the parser WASM from a CDN or a self-hosted path instead — a
+     * relative value is resolved against the current document URL. The same
+     * dependency-injection contract across docx / pptx / xlsx.
+     *
+     * The referenced file must be the matching format's `*_parser_bg.wasm`
+     * artifact (the one wasm-bindgen emitted for that parser); pointing it at a
+     * mismatched or missing file makes `load()` reject when the worker
+     * instantiates it.
+     */
+    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
@@ -753,6 +706,16 @@ declare interface LoadOptions_2 {
      * untrusted input. Zero / negative values fall back to the default.
      */
     maxZipEntryBytes?: number;
+    /**
+     * 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
+     * would otherwise leave `load()` pending forever. **Default: unlimited** —
+     * parsing a large document with heavy embedded media can legitimately take
+     * tens of seconds, so no timeout is imposed unless you set one. A worker that
+     * throws or fails to load already rejects immediately regardless of this
+     * value; this bound only covers the "silent, never-responds" case.
+     */
+    workerTimeoutMs?: number;
     /**
      * Opt-in OMML equation engine (MathJax + STIX Two Math, ~3 MB). Inject it
      * **once** here and every render of this document / presentation / workbook
@@ -1177,6 +1140,11 @@ export declare class PptxPresentation {
     get slideWidth(): number;
     /** Slide height in EMU. */
     get slideHeight(): number;
+    /** The render mode this engine was loaded with ('main' | 'worker'). A fact for
+     *  integrators and the scroll viewer: an injected engine's mode decides whether
+     *  slides render via renderSlide (main) or renderSlideToBitmap (worker) — no
+     *  probing (design §11: no silent mis-pathing). */
+    get mode(): 'main' | 'worker';
     /**
      * Speaker-notes text for a slide (`ppt/notesSlides/notesSlideN.xml`,
      * ECMA-376 §13.3.5 — Notes Slide). Returns the notes-body text as a single
@@ -1197,6 +1165,14 @@ export declare class PptxPresentation {
      * }
      */
     getNotes(slideIndex: number): string | null;
+    /**
+     * Whether the slide at `slideIndex` (0-based, absolute) is marked hidden
+     * (`<p:sld show="0">`, ECMA-376 §19.3.1.38). Like {@link getNotes} the index
+     * is NOT clamped — out-of-range / non-integer ⇒ `false`. This is a *fact*
+     * about the model; deciding what to do with a hidden slide (skip / dim) is the
+     * caller's policy (see {@link PptxViewer}'s `hiddenSlideMode` modes).
+     */
+    isHidden(slideIndex: number): boolean;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement | OffscreenCanvas, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
     /**
@@ -1234,6 +1210,475 @@ export declare class PptxPresentation {
     destroy(): void;
 }
 
+export declare class PptxScrollViewer {
+    private _pres;
+    private readonly _injected;
+    private readonly _opts;
+    private readonly _container;
+    private readonly _wrapper;
+    private readonly _scrollHost;
+    private readonly _spacer;
+    /** Resolved render mode. When an engine is injected the engine's own `mode`
+     *  is authoritative (design §11 — no silent mis-pathing / no probing); an
+     *  explicitly conflicting `opts.mode` is rejected at construction. When self-
+     *  loading, `opts.mode` decides and `load()` passes it to `PptxPresentation.load`. */
+    private _mode;
+    /** Dimensionless zoom multiplier over the 96-dpi natural slide size (mirrors
+     *  `DocxScrollViewer`, whose `_scale` multiplies `widthPt × PT_TO_PX`). The
+     *  natural (1×) slide width in CSS px is `slideEmu / EMU_PER_PX`; the base fit
+     *  sets `_scale` so that natural width maps to the container width, and zoom
+     *  multiplies it further (design §7). */
+    private _scale;
+    /** Whether the base fit scale has been established. Set true the first time
+     *  `relayout()` resolves a positive base scale. We use an explicit flag rather
+     *  than a `_scale === 1` sentinel because a fit scale of exactly 1 is a valid
+     *  established state (a 1× fit would otherwise be re-fit forever). */
+    private _scaleEstablished;
+    /** Live slots keyed by slide index. */
+    private readonly _slots;
+    /** Recyclable detached slots (canvas + textLayer reused across slides). */
+    private readonly _free;
+    /** Cached per-slide heights in px at the current scale (index-aligned). All
+     *  slides are the same size, so every entry equals the uniform slide height. */
+    private _heights;
+    private _lastRange;
+    private _lastTopIndex;
+    private _scrollListener;
+    /** Set by `destroy()`. Async render callbacks (main + worker) check it before
+     *  reporting an error so a rejection that lands after teardown is swallowed
+     *  rather than surfaced to a `onError` on a dead viewer. */
+    private _destroyed;
+    /** Worker mode: slide indices whose bitmap render is currently dispatched to the
+     *  engine. Coalesces a scroll storm — we never dispatch a second render for a
+     *  slide whose first is still in flight — and lets us drop slides that scrolled
+     *  out of the window before dispatch (design §11 worker coalescing).
+     *
+     *  T4 ZOOM HAZARD (RESOLVED by the render epoch below): coalescing keys on slide
+     *  INDEX only, with no notion of the scale a dispatch was made at. Once
+     *  `setScale` can change the zoom mid-flight, an in-flight bitmap dispatched at
+     *  the OLD scale can still pass the on-resolution identity check if the SAME
+     *  slot object is re-mounted for slide `i` (the pool reuses slot objects, so
+     *  `_slots.get(i) === slot && slot.renderedSlide === i` can hold for an old
+     *  dispatch), and get painted at the WRONG resolution. We fix this with a render
+     *  epoch (`_renderEpoch`): each dispatch captures the epoch, and on resolution a
+     *  moved epoch ⇒ STALE (close + re-dispatch the live slot). See
+     *  `_renderSlotBitmap`. */
+    private readonly _slideInFlight;
+    /** Render generation, bumped on every effective `setScale` (and the resize
+     *  re-fit in `_onResize`, which routes through `setScale`). Stamped into each async render
+     *  dispatch; a resolution whose captured epoch ≠ this value is STALE — its
+     *  pixels/geometry are at a superseded scale. Worker path: close the orphan
+     *  bitmap + re-dispatch the live slot. Main path: skip the (stale) text-layer
+     *  build; the engine's per-canvas token already discards the stale pixels. */
+    private _renderEpoch;
+    /** Pending settle-render timer handle (design §7 mechanism 2). Set by
+     *  `_scheduleSettle` after each `setScale`, reset on the next one so a burst
+     *  dispatches ONE settle at the end, and cleared in `destroy()`. `ReturnType`
+     *  of `setTimeout` (a number in the DOM, a Timeout object in node) so the type
+     *  is host-agnostic. */
+    private _settleTimer;
+    private _wheelListener;
+    /** One-shot latch for the worker-mode text-selection warning. The overlay is a
+     *  main-mode-only feature: in worker mode the per-run `onTextRun` geometry
+     *  cannot cross the worker boundary, so an `enableTextSelection` overlay stays
+     *  empty. We warn once (parity with `PptxViewer`) rather than per slot. */
+    private _warnedNoTextSelection;
+    /** Observes the container so a width change re-fits the base scale. Disconnected
+     *  in `destroy()`. */
+    private _resizeObserver;
+    /** The base fit scale at the last established/re-fit layout. `_onResize` divides
+     *  `_scale` by this to recover the current zoom multiplier so a width change
+     *  re-fits the base while preserving the user's zoom (design §11). */
+    private _prevBase;
+    /** The fit width (px) the base scale was last established at. Lets `_onResize`
+     *  skip the re-fit when only the height changed (a ResizeObserver fires on ANY
+     *  box change, but only a WIDTH change alters the fit-to-width base scale). */
+    private _lastFitWidth;
+    /** Resolved slide-canvas `box-shadow` (design: the recipe drop shadow by
+     *  default). Resolved ONCE with `??` — NOT `||` — so `pageShadow: false`
+     *  survives as the "no shadow" sentinel (a `||` would treat `false` as absent
+     *  and wrongly re-apply the default). Applied by `_applyPageShadow` at EVERY
+     *  canvas-creation site (`_acquireSlot` and the double-buffer spare in
+     *  `_settleSlot`) so a recycled/re-mounted slot and a settle-swapped spare all
+     *  carry it. */
+    private readonly _pageShadow;
+    constructor(container: HTMLElement, opts?: PptxScrollViewerOptions);
+    /**
+     * Load a PPTX from URL or ArrayBuffer and render the first window.
+     * UNSUPPORTED when an engine was injected via `opts.presentation` (throws) — the
+     * caller already owns the parsed engine.
+     */
+    load(source: string | ArrayBuffer): Promise<void>;
+    get slideCount(): number;
+    /** Uniform slide width in CSS px at the current scale. `_scale` is a
+     *  dimensionless multiplier over the natural 96-dpi width (`slideEmu /
+     *  EMU_PER_PX`), mirroring docx's `widthPt × PT_TO_PX × _scale`. */
+    private _slideWidthPx;
+    /** Uniform slide height in CSS px at the current scale. */
+    private _slideHeightPx;
+    /** The fit width (px), deferring when the container is unlaid-out. An EXPLICIT
+     *  `opts.width` is the slide's CSS-width contract and is returned UNCHANGED (the
+     *  gutters still apply around placement, not to the width). The container-derived
+     *  default instead targets `containerWidth − padL − padR` so a slide sits INSIDE
+     *  the horizontal gutters at 100%. A non-positive result (gutters wider than the
+     *  container) is treated as unlaid-out — the same deferral as a zero-width box. */
+    private _fitWidthPx;
+    /** Base scale: the DIMENSIONLESS multiplier that fits the (uniform) slide
+     *  width to the fit-width. `natural = slideWidthEmu / EMU_PER_PX` is the 96-dpi
+     *  CSS-px width; `base = fitWidth / natural` (mirrors docx's `w / (widthPt ×
+     *  PT_TO_PX)`). Returns 0 when the container has no width yet (deferral). */
+    private _baseScale;
+    /**
+     * Recompute per-slide heights + the spacer and re-mount the visible window.
+     *
+     * The viewer already calls this automatically after `load()`, an injected
+     * engine, a container resize, and a zoom, so most integrations never need it.
+     * It is public as a deliberate escape hatch: if the host mutates the layout in
+     * a way the `ResizeObserver` cannot observe (e.g. a CSS change on an ancestor
+     * that resizes the container without a box-size event, or a font that finishes
+     * loading after first paint), call `relayout()` to force a re-fit. Idempotent —
+     * safe to call repeatedly, and a no-op while the container has zero width (the
+     * fit is deferred until width appears, design §11).
+     */
+    relayout(): void;
+    /** All slides are the same size, so heights = n × uniform. We still feed this
+     *  full array to computeVisibleRange (never special-case uniform) so offsets /
+     *  topIndex live in one tested place (design §5.1). */
+    private _recomputeHeights;
+    private _gap;
+    private _overscan;
+    /** Desk padding fed to `computeVisibleRange`: `paddingTop`/`paddingBottom`,
+     *  each defaulting to `gap` (uniform rhythm). Resolved here (not stored) to
+     *  mirror `_gap()`/`_overscan()`, and consumed at EVERY `computeVisibleRange`
+     *  call site so the padded offsets are the single source of geometry. */
+    private _pad;
+    /** Horizontal desk gutters: `paddingLeft`/`paddingRight`, each defaulting to
+     *  `gap` (uniform rhythm — the horizontal gutters match the vertical padding).
+     *  Consumed by `_fitWidthPx` (to shrink the container-derived fit), by
+     *  `_positionSlot` (the flush-left floor), and by `_syncSpacerWidth` (the spacer
+     *  width). Resolved here (not stored) to mirror `_gap()`/`_pad()`. */
+    private _padH;
+    private _range;
+    private _syncSpacer;
+    /** Horizontal scroll extent: the (uniform deck-wide) slide width plus both
+     *  gutters. A spacer NARROWER than the container never creates a scrollbar
+     *  (scrollWidth = max(clientWidth, content)), so it is always safe to set — it
+     *  only matters when a zoomed-in slide grows past the viewport, where it gives
+     *  the gutters something to scroll to on either side. Called from `_syncSpacer`
+     *  and after every scale change (zoom / resize re-fit) so the extent tracks the
+     *  current slide px width. */
+    private _syncSpacerWidth;
+    private _onScroll;
+    /** Mount/recycle slots for the current visible window. */
+    private _mountVisible;
+    /** Apply the resolved slide-canvas shadow (design: recipe drop shadow by
+     *  default, `false` ⇒ none). Single source so `_acquireSlot` and the
+     *  double-buffer spare in `_settleSlot` stay in lock-step — a spare that missed
+     *  this would lose the shadow on the settle swap. `box-shadow` never affects
+     *  layout, so this is safe to (re)set on a live/pooled canvas without shifting
+     *  any offset. */
+    private _applyPageShadow;
+    private _acquireSlot;
+    private _recycleSlot;
+    private _positionSlot;
+    /** Device-pixel ratio for a render (opts override → window → 1). */
+    private _dpr;
+    /**
+     * Render slide `i` into `slot`. Routes strictly on the constructor-resolved
+     * `_mode` (design §11 — no probing, no silent mis-pathing): `main` ⇒ paint the
+     * slot's canvas directly via `renderSlide`; `worker` ⇒ transfer an ImageBitmap
+     * from `renderSlideToBitmap`.
+     *
+     * Slot-identity guard: a slot recycled to a DIFFERENT slide while a previous
+     * render is in flight must not repaint the stale slide. `slot.renderedSlide`
+     * tracks the slide this slot is committed to; we stamp it up-front and bail on
+     * resolution if it changed (the engine's own token guard is per-canvas; this is
+     * the viewer's per-slot slide-identity check).
+     *
+     * Render epoch (main path): pixel staleness after a mid-flight `setScale` is
+     * already handled by the engine's per-canvas token (the newer renderSlide on the
+     * same canvas wins) — `setScale` recycles + re-mounts, and the re-mount always
+     * re-dispatches `renderSlide` (renderedSlide reset to -1), so a fresh render is
+     * always issued. But the viewer-side side effects of a STALE resolution — the
+     * text-layer build (its run geometry is at the OLD scale) and the renderedSlide
+     * bookkeeping — must NOT run, or a superseded render would rebuild the overlay
+     * with stale x/y/w/h (the pool reuses slot objects, so the identity check alone
+     * can pass for an old-epoch resolution). We gate them on the captured epoch.
+     */
+    private _renderSlot;
+    /** Warn once when an `enableTextSelection` overlay was requested but the render
+     *  mode is `worker` (so the overlay stays empty). Same wording as
+     *  `PptxViewer` — one warning per viewer, not per slot. */
+    private _maybeWarnNoTextSelection;
+    /** Route an async render failure to `onError`, or `console.error` when none is
+     *  set (so failures are never fully silent), and never after teardown. */
+    private _reportRenderError;
+    /**
+     * Worker-mode slot render: dispatch `renderSlideToBitmap`, transfer the result
+     * via a per-slot `bitmaprenderer` context, and manage the ImageBitmap lifecycle.
+     *
+     * Coalescing / drop-stale (design §11):
+     *  - Skip if slide `i` is already in flight (a scroll storm won't double-dispatch).
+     *  - Skip if slide `i` already left the mounted window before dispatch.
+     *  - On resolution, if `slot` is no longer THIS slide's live slot (it recycled to
+     *    another slide, or slide `i` re-mounted onto a DIFFERENT slot while this render
+     *    was in flight), close the orphan bitmap and skip the paint. In that
+     *    re-mount case a live slot for `i` still awaits a render, so once we clear
+     *    the in-flight guard we re-dispatch it — a slide that recycled and re-mounted
+     *    mid-flight must never stay blank.
+     *  - RENDER EPOCH: the dispatch captures `this._renderEpoch`. `setScale` bumps
+     *    the epoch, so a resolution whose captured epoch ≠ the live epoch is STALE
+     *    even when the SAME slot object is still mounted for slide `i` (the pool
+     *    reuses slot objects, so the identity check alone can't catch a zoom that
+     *    happened mid-flight). A moved epoch ⇒ close the orphan + re-dispatch the
+     *    live slot at the new scale, never paint the old-scale bitmap.
+     *
+     * Do NOT pass `dim` or `skipMediaControls` to `renderSlideToBitmap`. The scroll
+     * viewer never dims slides (design §8.2 / Delta 6); passing neither means the
+     * static play-badge renders on media slides (matching `PptxViewer`'s
+     * non-media-playback path) — acceptable for v1.
+     */
+    private _renderSlotBitmap;
+    /**
+     * Set the absolute (dimensionless) zoom scale — a multiplier over the 96-dpi
+     * natural slide size, matching `DocxScrollViewer` — clamped inline to
+     * `[zoomMin ?? 0.1, zoomMax ?? 4]` (absolute bounds, XlsxViewer convention — NOT
+     * multiples of the base fit; design §3 keeps the clamp in the viewer, not core),
+     * then re-anchor VERTICALLY so the slide currently under the viewport top stays
+     * fixed. A no-op when nothing is loaded or when the clamped scale is unchanged.
+     *
+     * FLICKER-FREE (design §7): this does NOT re-render the visible slides inline.
+     * It shows an immediate CSS preview (stretch the existing bitmaps, scale the
+     * overlays) and DEBOUNCES a full-resolution settle re-render for ZOOM_SETTLE_MS,
+     * so a wheel/pinch burst never blanks a slide and coalesces into one crisp render.
+     *
+     * Re-anchor (written from scratch — XlsxViewer only re-anchors horizontally):
+     * capture `top = topIndex` and the intra-slide fraction `intraFrac` from the
+     * CURRENT range BEFORE rescale; after recomputing heights at the new scale,
+     * `newScrollTop = offsets'[top] + intraFrac × heights'[top]`, clamped to
+     * `[0, totalHeight' − viewportHeight]`. Because a slide's height scales linearly
+     * with `_scale`, the same fractional position maps exactly to the new geometry.
+     *
+     * CAVEAT — base fit below the floor: `relayout()` sets `_scale = base` WITHOUT
+     * clamping to `[zoomMin, zoomMax]`. If the base fit is below `zoomMin` (a wide
+     * slide in a narrow container), the initial scale sits under the floor, but once
+     * the user zooms via `setScale` the clamp pins the minimum to `zoomMin`, so they
+     * can no longer return below the floor to the original base fit through this API.
+     */
+    setScale(scale: number): void;
+    /**
+     * CSS preview of the visible window at the current `_scale` (design §7
+     * mechanism 1), WITHOUT re-rendering. Slots leaving the window recycle normally;
+     * slots ENTERING the window mount fresh (rendered at the current scale directly,
+     * so they never need a preview); slots that STAY are repositioned and their
+     * canvas + text overlay are CSS-transformed to the new size (the device buffer
+     * is untouched — that is the whole point: no synchronous clear, no blank frame).
+     */
+    private _previewVisible;
+    /**
+     * CSS-preview a single already-mounted slot at the new geometry (design §7): the
+     * wrapper is repositioned + sized (via `_positionSlot`), the canvas bitmap is
+     * STRETCHED to the new CSS size (no `canvas.width` — the device buffer, and thus
+     * the drawn pixels, are left intact, just scaled by the browser), and the text
+     * overlay is scaled by `newScale / renderedScale` so it tracks the stretched
+     * slide. `renderedScale <= 0` means the slot's first render hasn't resolved yet
+     * (nothing to stretch); the pending render captured the current scale, so it
+     * lands correct and no preview is needed.
+     */
+    private _previewSlot;
+    /** (Re)schedule the debounced settle re-render (design §7 mechanism 2). Resets
+     *  the timer on every call so a burst of `setScale` dispatches ONE settle
+     *  ZOOM_SETTLE_MS after the LAST call. Cleared in `destroy()`. */
+    private _scheduleSettle;
+    /** Full-resolution settle re-render of the visible window (design §7 mechanisms
+     *  2+3). Re-renders each mounted slot at the current scale via the double-buffer
+     *  swap (main) / same-canvas transfer (worker). Main mode also rebuilds the text
+     *  overlay and clears its preview transform; in worker mode the overlay is
+     *  permanently empty (text selection is main-mode-only), so the transform is
+     *  inert there and is reset on recycle. Dispatched at the CURRENT epoch; the
+     *  existing epoch gate discards it if a later `setScale` supersedes it
+     *  mid-render. */
+    private _settleRender;
+    /**
+     * Settle-render one slot at the current scale (design §7 mechanism 3).
+     *
+     * WORKER: re-dispatch the bitmap render into the SAME canvas. The worker path
+     * sizes the device buffer and `transferFromImageBitmap`s it in ONE synchronous
+     * step (no await between `canvas.width = …` and the transfer), so the browser
+     * never composites an intermediate blank frame — no spare canvas is needed. The
+     * `renderedScale === _scale` gate in `_settleRender` plus the epoch gate inside
+     * `_renderSlotBitmap` keep this correct and idempotent.
+     *
+     * MAIN: `renderSlide` synchronously sets `canvas.width = …` (which CLEARS the
+     * backing store to blank) BEFORE its first await and paints AFTER — so rendering
+     * into the on-screen canvas would flash it white. Render into a SPARE off-DOM
+     * canvas instead; only once it resolves at the current epoch do we swap it into
+     * the wrapper (replacing the old canvas). The old canvas keeps showing the
+     * stretched preview until the instant of the swap — blank-free.
+     */
+    private _settleSlot;
+    /**
+     * Scroll so slide `index`'s top edge sits at the viewport top. Clamps `index` to
+     * `[0, slideCount-1]` (the pager convention) and the resulting scrollTop to
+     * `[0, totalHeight − viewportHeight]` so the last slides don't scroll past the
+     * end. A no-op when nothing is loaded or the deck is empty.
+     *
+     * `opts.behavior` ('auto' | 'smooth', default 'auto') is honoured via
+     * `scrollHost.scrollTo({ top, behavior })` when the host supports it (a real
+     * browser); the stub-DOM has no `scrollTo`, so the fallback sets `scrollTop`
+     * directly (which is what the tests assert). We then call `_mountVisible` once.
+     *
+     * MOUNTING CAVEAT: synchronous mounting of the target slide is guaranteed only on
+     * the DEFAULT/'auto' path — there `scrollTop` has already jumped to `top`, so the
+     * `_mountVisible` call reads the final scroll position and the target slide's slots
+     * exist immediately. With `behavior: 'smooth'` the scroll animates ASYNCHRONOUSLY:
+     * `scrollTop` is still near the old position when `_mountVisible` runs, so the
+     * target slide mounts lazily via the animation's subsequent `scroll` events, not
+     * from this call.
+     */
+    scrollToSlide(index: number, opts?: {
+        behavior?: 'auto' | 'smooth';
+    }): void;
+    /**
+     * Re-fit the base scale on a container resize while PRESERVING the current zoom
+     * multiplier (design §11), then re-anchor + re-render. A `ResizeObserver` fires
+     * on any box change, but only a WIDTH change alters the fit-to-width base scale;
+     * a height-only change skips the re-fit yet STILL re-mounts the visible window
+     * (via `_mountVisible`), because a taller viewport reveals rows that were below
+     * the fold and would otherwise stay blank until the next scroll. Empty/unloaded
+     * ⇒ no-op; a still-zero width ⇒ defer.
+     *
+     * Zero-width recovery: a container that was 0-wide at construction never
+     * established a scale (`_scaleEstablished` is false), so the first non-zero
+     * resize establishes it here via `relayout()` — completing the T2 deferral.
+     *
+     * Re-fit math (zoom multiplier preserved):
+     *   mult      = _scale / _prevBase            (the user's zoom over the old base)
+     *   newScale  = newBase × mult
+     * Routing through `setScale(newScale)` bumps `_renderEpoch` (resize IS an epoch
+     * event — T4 banner) and re-anchors + CSS-previews + debounces a settle re-render
+     * of every slot at the new geometry, exactly like a zoom (design §7 flicker-free
+     * path — a rapid ResizeObserver burst therefore also coalesces into one settle).
+     * `setScale`'s clamp/no-op guards apply: an unchanged newScale (identical width)
+     * is a no-op there — so we short-circuit BEFORE it when the fit-width is
+     * unchanged (mounting the revealed window without a needless re-render), and
+     * after it we call `_mountVisible` again to cover the case where the clamp made
+     * `setScale` no-op yet the viewport still grew.
+     */
+    private _onResize;
+    get topVisibleSlide(): number;
+    /* Excluded from this release type: mountedSlideIndicesForTest */
+    /* Excluded from this release type: scaleForTest */
+    /* Excluded from this release type: baseScaleForTest */
+    /* Excluded from this release type: renderEpochForTest */
+    /* Excluded from this release type: resizeForTest */
+    /**
+     * 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
+     * owns its lifecycle. Per-slot worker ImageBitmaps are closed on recycle.
+     */
+    destroy(): void;
+}
+
+/**
+ * Options for {@link PptxScrollViewer}. Extends `RenderSlideOptions` (per-slide
+ * render knobs, minus `onTextRun`) and `LoadOptions` (parse/worker knobs). See
+ * design §8.2.
+ *
+ * `onTextRun` is omitted deliberately: the viewer drives it internally per
+ * mounted slot to build the optional per-slide selection overlay (gated by
+ * `enableTextSelection`), so exposing it here would let a caller's callback be
+ * silently overridden.
+ *
+ * NOTE: `RenderSlideOptions` also carries `dim` and `skipMediaControls`. The v1
+ * scroll viewer never sets `dim` or `skipMediaControls` (hidden-slide dimming is
+ * a PAGER policy, not a scroll-viewer feature — design §8.2 / Delta 6). These
+ * inherited fields are accepted for type-compatibility but are not part of the
+ * scroll-viewer's supported API.
+ */
+export declare interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTextRun'>, LoadOptions {
+    /** Base fit width in CSS px → base zoom scale. Default: the container's width
+     *  at first non-zero layout (design §7/§11 zero-width deferral). */
+    width?: number;
+    /** Vertical gap (px) between consecutive slides. Default 16. */
+    gap?: number;
+    /** Desk padding (px) ABOVE the FIRST slide — the margin a presentation viewer
+     *  leaves between the top of the scroll surface and the first slide. Default:
+     *  `gap` (uniform desk rhythm — the first slide sits the same distance from the
+     *  top as slides sit from each other). Pass `0` for a flush-top layout. */
+    paddingTop?: number;
+    /** Desk padding (px) BELOW the LAST slide — the margin below the final slide.
+     *  Default: `gap`. Pass `0` for a flush-bottom layout. */
+    paddingBottom?: number;
+    /** Desk gutter (px) to the LEFT of the slides — the horizontal margin between
+     *  the left edge of the scroll surface and a slide sitting flush-left (i.e. once
+     *  zoomed wide enough that centering no longer applies). Default: `gap` (uniform
+     *  desk rhythm — the horizontal gutters match the vertical ones). It also shrinks
+     *  the container-derived FIT width so a slide sits inside the gutters at 100%
+     *  (an EXPLICIT `opts.width` is the slide's CSS-width contract and is NOT reduced;
+     *  the gutters still apply around placement). Pass `0` for a flush-left layout. */
+    paddingLeft?: number;
+    /** Desk gutter (px) to the RIGHT of the slides. Default: `gap`. Shrinks the
+     *  container-derived fit width symmetrically with `paddingLeft`. Pass `0` for a
+     *  flush-right layout. */
+    paddingRight?: number;
+    /** Slides kept mounted beyond the viewport on each side. Default 1. */
+    overscan?: number;
+    /** Per-slide transparent text-selection overlay. MAIN render mode only:
+     *  in worker mode `onTextRun` cannot cross the worker boundary, so the overlay
+     *  stays empty and the viewer logs one warning (design §11). */
+    enableTextSelection?: boolean;
+    /** Minimum zoom scale — a DIMENSIONLESS multiplier over the 96-dpi natural
+     *  slide size (10% = 0.1), matching `DocxScrollViewer`. Default 0.1. */
+    zoomMin?: number;
+    /** Maximum zoom scale (dimensionless multiplier, 400% = 4). Default 4. */
+    zoomMax?: number;
+    /** Enable `Ctrl`/`Cmd`+wheel zoom. Default true. */
+    enableZoom?: boolean;
+    /**
+     * CSS `background` shorthand for the scroll surface (the "desk") visible
+     * behind and between slides — the gray a presentation viewer paints around the
+     * slide. Applied to the viewer-owned scroll host. The slides themselves are
+     * always drawn on their own white canvas and are unaffected. Default
+     * `undefined`: the scroll surface stays transparent so the host container's
+     * background shows through (non-breaking).
+     */
+    background?: string;
+    /**
+     * CSS `box-shadow` painted on every slide CANVAS (not the wrapper — the
+     * text-selection overlay must not cast its own shadow). The soft drop shadow a
+     * presentation viewer leaves under each slide.
+     *
+     * - Default (`undefined`): `'0 1px 3px rgba(0,0,0,0.2)'` — the recipe look, so
+     *   the scroll viewer reproduces the Examples appearance with zero config.
+     * - `false`: NO shadow (flat slides).
+     * - A custom string is applied verbatim. A spread-only ring such as
+     *   `'0 0 0 1px #c8ccd0'` gives a crisp 1px BORDER look — and because
+     *   `box-shadow` never affects layout (unlike `border`, which would grow the
+     *   box and shift every offset), a border and a drop shadow are the SAME knob
+     *   here rather than two competing options.
+     */
+    pageShadow?: string | false;
+    /**
+     * Inject an already-loaded engine to share one parse across panes (design §14).
+     * When set: `load()` is unsupported (throws), the engine's own `mode` wins (an
+     * explicitly conflicting `opts.mode` throws at construction, design §11), and
+     * `destroy()` does NOT destroy this engine (the caller owns its lifecycle).
+     */
+    presentation?: PptxPresentation;
+    /** Fires when the top-most visible slide changes. `topIndex` from
+     *  `computeVisibleRange` (the first slide intersecting the viewport top,
+     *  EXCLUDING overscan). */
+    onVisibleSlideChange?: (topIndex: number, total: number) => void;
+    /** Error callback. When set, `load()` invokes it and resolves (otherwise the
+     *  error is rethrown — shared viewer error contract). It ALSO fires for async
+     *  per-slot render failures (both main `renderSlide` and worker
+     *  `renderSlideToBitmap` rejections); a failed slide is left blank rather than
+     *  crashing the loop. Without an `onError`, render failures are logged via
+     *  `console.error` so they are never fully silent. */
+    onError?: (err: Error) => void;
+}
+
 /** Information about a rendered text segment for building a transparent selection overlay. */
 export declare interface PptxTextRunInfo {
     text: string;
@@ -1279,10 +1724,20 @@ export declare interface PptxTextRunInfo {
 export declare class PptxViewer {
     private readonly canvas;
     private readonly wrapper;
+    /** The canvas's DOM position BEFORE the constructor reparented it into
+     *  {@link wrapper}, captured so {@link destroy} can return the caller-owned
+     *  canvas to exactly where it was. `null` parent = canvas was passed
+     *  detached. */
+    private readonly _originalParent;
+    private readonly _originalNextSibling;
+    /** The canvas's inline `display` before the constructor forced `block`
+     *  (empty string if it was unset), restored on {@link destroy}. */
+    private readonly _originalDisplay;
     private textLayer;
     private engine;
     private readonly opts;
     private currentSlide;
+    private _hiddenMode;
     private handle;
     private readonly _mode;
     /** The canvas's bitmaprenderer context, used only by the static worker-mode
@@ -1303,6 +1758,21 @@ export declare class PptxViewer {
     goToSlide(index: number): Promise<void>;
     nextSlide(): Promise<void>;
     prevSlide(): Promise<void>;
+    /** Next index for sequential nav: skip mode jumps over hidden slides. */
+    private _step;
+    /** Initial slide for load() / mode switch: skip mode lands on a visible one. */
+    private _initialSlide;
+    /** Resolved `'dim'` overlay (defaults merged with the `hiddenSlideDim` option). */
+    private _dim;
+    /**
+     * Switch the hidden-slide mode at runtime and re-render. Entering `'skip'`
+     * while on a hidden slide advances to the nearest visible slide.
+     */
+    setHiddenSlideMode(mode: HiddenSlideMode): Promise<void>;
+    /** The current hidden-slide mode. */
+    get hiddenSlideMode(): HiddenSlideMode;
+    /** Number of non-hidden slides (absolute `slideCount` is unchanged). */
+    get visibleSlideCount(): number;
     get slideIndex(): number;
     get slideCount(): number;
     /**
@@ -1316,7 +1786,15 @@ export declare class PptxViewer {
     get canvasElement(): HTMLCanvasElement;
     private renderCurrentSlide;
     private _buildTextLayer;
-    /** Clean up the viewer and terminate the background worker. */
+    /**
+     * Clean up the viewer and terminate the background worker.
+     *
+     * The caller-owned `<canvas>` is returned to the DOM position it held before
+     * the constructor was called (same parent, same next-sibling) and its inline
+     * `display` is restored, so the canvas can be reused — e.g. to construct a new
+     * viewer on the same element. If the canvas was passed detached (no parent) it
+     * is simply removed from the internal wrapper. Safe to call more than once.
+     */
     destroy(): void;
 }
 
@@ -1338,6 +1816,24 @@ export declare interface PptxViewerOptions extends RenderOptions, LoadOptions {
      * browser's native text selection works on slide content.
      */
     enableTextSelection?: boolean;
+    /**
+     * How hidden slides (`<p:sld show="0">`, §19.3.1.38) are presented:
+     * - `'show'` (default): drawn like any other slide.
+     * - `'skip'`: sequential navigation (`nextSlide`/`prevSlide`, initial load)
+     *   jumps over them; absolute indices are unchanged, and an explicit
+     *   `goToSlide(i)` to a hidden slide is still honored.
+     * - `'dim'`: drawn under a translucent overlay (PowerPoint thumbnail look).
+     *
+     * Named to match the {@link PptxViewer.hiddenSlideMode} getter and
+     * {@link PptxViewer.setHiddenSlideMode} setter.
+     */
+    hiddenSlideMode?: HiddenSlideMode;
+    /**
+     * Overrides for the `'dim'` overlay. Merged over the default
+     * `{ color: '#ffffff', opacity: 0.6 }`. A `Partial<DimOptions>` so it stays
+     * in sync if {@link DimOptions} gains a field.
+     */
+    hiddenSlideDim?: Partial<DimOptions>;
 }
 
 export declare interface Presentation {
@@ -1440,6 +1936,8 @@ export declare interface RenderSlideOptions {
      * its own play/pause chrome without duplication.
      */
     skipMediaControls?: boolean;
+    /** Translucent overlay drawn over the finished slide (hidden-slide dimming). */
+    dim?: DimOptions;
 }
 
 /** Options for {@link PptxPresentation.renderSlideToBitmap}. */
@@ -1449,6 +1947,8 @@ export declare interface RenderSlideToBitmapOptions {
     /** Device pixel ratio. Defaults to window.devicePixelRatio (workers have none). */
     dpr?: number;
     /* Excluded from this release type: skipMediaControls */
+    /** Translucent overlay drawn over the finished slide (hidden-slide dimming). */
+    dim?: DimOptions;
 }
 
 /**
@@ -1599,6 +2099,13 @@ export declare interface Slide {
      * when the slide has no comments.
      */
     comments?: PptxComment[];
+    /**
+     * `<p:sld show="0">` — the slide is marked hidden in the slide show
+     * (ECMA-376 §19.3.1.38). Absent (`undefined`) ⇒ shown. The renderer ignores
+     * this; it is a fact surfaced for tools and for {@link PptxViewer}'s hidden-
+     * slide modes (read it via `PptxPresentation.isHidden`).
+     */
+    hidden?: boolean;
 }
 
 export declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
@@ -1611,6 +2118,7 @@ export declare type SlideElement = ShapeElement | PictureElement | TableElement
  */
 declare type SlideRenderOptions = RenderOptions & {
     math?: MathRenderer;
+    dim?: DimOptions;
 };
 
 /** ECMA-376 §20.1.8.31 (CT_SoftEdgesEffect) — feather radius in EMU. */