@silurus/ooxml 0.69.0 → 0.70.1

package/dist/types/index.d.ts

@@ -105,6 +105,10 @@ declare type BodyElement = {
     headers?: HeadersFooters;
     footers?: HeadersFooters;
     titlePage?: boolean;
+    /** ECMA-376 §17.6.13 / §17.6.11 — this ENDING section's page geometry
+     *  (size + margins). Absent when the sectPr inherits both pgSz and pgMar
+     *  (the renderer then falls back to the body-level section geometry). */
+    geom?: SectionGeom;
 };
 
 declare interface Border {
@@ -133,6 +137,43 @@ declare interface BorderSpec {
     style: string;
 }
 
+/**
+ * Build the transparent text-selection overlay for a rendered docx page: one
+ * absolutely-positioned, color-transparent `<span>` per {@link DocxTextRunInfo}
+ * (emitted by `renderPage`'s `onTextRun`), so the browser's native selection
+ * lands on the drawn glyphs. Extracted verbatim from `DocxViewer._buildTextLayer`
+ * so both the pager (DocxViewer) and the continuous-scroll viewer (DocxScrollViewer)
+ * share one implementation; also public API for integrators building their own
+ * overlay (design §10). MAIN render mode only — `onTextRun` cannot cross the
+ * worker boundary.
+ *
+ * @param layer           the overlay div (position:relative parent expected).
+ * @param runs            per-run geometry from `renderPage({ onTextRun })`.
+ * @param canvasCssWidth  the rendered canvas's CSS width (e.g. `"700px"`), used
+ *                        to size the overlay to match the canvas.
+ * @param canvasCssHeight the rendered canvas's CSS height.
+ */
+declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string): void;
+
+/**
+ * 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).
+ */
+declare function buildPptxTextLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], cssWidth: number, cssHeight: number): void;
+
 declare type Bullet = {
     type: 'none';
 } | {
@@ -357,140 +398,11 @@ declare interface ChartAnchor {
     toColOff: number;
     toRow: number;
     toRowOff: number;
-    chart: ChartData;
-}
-
-/**
- * XLSX parser's raw chart output. Retains parser-native `barDir` + `grouping`
- * which the renderer combines into a canonical `ChartModel.chartType` (e.g.
- * `clusteredBarH`, `stackedBarPct`) at render time.
- */
-declare interface ChartData {
-    /** Primary chart type: "bar"|"line"|"area"|"pie"|"doughnut"|"radar"|"scatter" */
-    chartType: string;
-    /** "col" (vertical bars) | "row" (horizontal bars) */
-    barDir: string;
-    /** "clustered"|"stacked"|"standard"|"percentStacked" */
-    grouping: string;
-    title: string | null;
-    categories: string[];
-    series: XlsxChartSeries[];
-    /** Whether data labels are enabled (c:dLbls showVal/showPercent). */
-    showDataLabels?: boolean;
-    /** Category axis title (c:catAx/c:title). */
-    catAxisTitle?: string | null;
-    /** Value axis title (c:valAx/c:title). */
-    valAxisTitle?: string | null;
-    /** `<c:catAx><c:title>` run-prop font size (hpt), from the parser's
-     *  catAxisTitleSize. Distinct from `catAxisFontSizeHpt` (tick labels). */
-    catAxisTitleSize?: number | null;
-    /** `<c:catAx><c:title>` run-prop bold flag. */
-    catAxisTitleBold?: boolean | null;
-    /** `<c:catAx><c:title>` run-prop color (hex without '#'). */
-    catAxisTitleColor?: string | null;
-    /** `<c:valAx><c:title>` run-prop font size (hpt). */
-    valAxisTitleSize?: number | null;
-    /** `<c:valAx><c:title>` run-prop bold flag. */
-    valAxisTitleBold?: boolean | null;
-    /** `<c:valAx><c:title>` run-prop color (hex without '#'). */
-    valAxisTitleColor?: string | null;
-    /** True when <c:legend> is present. Absence means the legend is hidden. */
-    showLegend?: boolean;
-    /** `<c:legendPos val>` — "r"|"l"|"t"|"b"|"tr". null/undefined = default ("r"). */
-    legendPos?: 'r' | 'l' | 't' | 'b' | 'tr' | null;
-    /** Chart title font size in OOXML hundredths of a point (e.g. 1400 = 14pt). */
-    titleFontSizeHpt?: number | null;
-    /** Chart title font color as a hex string without '#' (srgbClr only). */
-    titleFontColor?: string | null;
-    /** Chart title font family from `<a:latin typeface>` (ECMA-376 §20.1.4.2.24). */
-    titleFontFace?: string | null;
-    /** Category axis tick-label font size in hpt (ECMA-376 §21.2.2.17 c:txPr). */
-    catAxisFontSizeHpt?: number | null;
-    /** Value axis tick-label font size in hpt. */
-    valAxisFontSizeHpt?: number | null;
-    /** Outer chartSpace background (ECMA-376 §21.2.2.5 `<c:spPr>`). Hex without
-     *  '#' for a solid fill, undefined for `<a:noFill/>` or an absent spPr.
-     *  Combine with `hasChartSpPr` to distinguish explicit-transparent from
-     *  default-opaque-white. */
-    chartBg?: string | null;
-    /** True when the parser saw a `<c:chartSpace><c:spPr>` element. Lets the
-     *  adapter tell "spec said noFill → transparent" from "no spPr → default". */
-    hasChartSpPr?: boolean;
-    /** `<c:legend><c:manualLayout>` fractions of chart space (§21.2.2.31). */
-    legendManualLayout?: LegendManualLayout_2 | null;
-    /** `<c:catAx><c:delete val="1"/>` — hide the category axis (§21.2.2.40). */
-    catAxisHidden?: boolean;
-    /** `<c:valAx><c:delete val="1"/>` — hide the value axis (§21.2.2.40). */
-    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;
-    /** `<c:radarChart><c:radarStyle val>` — "standard" (line only, default),
-     *  "marker" (line + markers), "filled" (closed polygon with area fill).
-     *  Sample-1 "Biodiversity Index" uses "marker" — Excel renders no area
-     *  fill, but our renderer was filling at 25 % opacity regardless. */
-    radarStyle?: string | null;
-    /** `<c:valAx><c:numFmt@formatCode>` — number format for value-axis tick
-     *  labels (ECMA-376 §21.2.2.21). */
-    valAxisFormatCode?: string | null;
-    /** `<c:barChart><c:gapWidth>` — space between category groups as a percent
-     *  of bar width (§21.2.2.13). */
-    barGapWidth?: number | null;
-    /** `<c:barChart><c:overlap>` — signed percent overlap between bars in a
-     *  cluster (§21.2.2.25). Negative = gap. */
-    barOverlap?: number | null;
-    /** `<c:dLbls><c:dLblPos>` — data label position (§21.2.2.16). */
-    dataLabelPosition?: string | null;
-    /** Hex (no `#`) for data label text color, resolved from `<c:dLbls><c:txPr>`. */
-    dataLabelFontColor?: string | null;
-    /** `<c:dLbls><c:numFmt@formatCode>` — chart-level override for data label
-     *  number format (§21.2.2.35). */
-    dataLabelFormatCode?: string | null;
-    /** `<c:title>...defRPr@b>` chart title bold flag. */
-    titleFontBold?: boolean;
-    /** `<c:catAx><c:txPr>...defRPr@b>` X-axis tick label bold flag. */
-    catAxisFontBold?: boolean;
-    /** `<c:valAx><c:txPr>...defRPr@b>` Y-axis tick label bold flag. */
-    valAxisFontBold?: boolean;
-    /** `<c:catAx><c:crosses val>` (`autoZero` | `min` | `max`). Drives where
-     *  the X axis sits along the Y axis. Default `autoZero`. */
-    catAxisCrosses?: string;
-    /** `<c:catAx><c:crossesAt val>` explicit numeric crossing. */
-    catAxisCrossesAt?: number;
-    valAxisCrosses?: string;
-    valAxisCrossesAt?: number;
-    /** Axis line color (hex without `#`) and width in EMU, from
-     *  `<c:catAx|valAx><c:spPr><a:ln>`. */
-    catAxisLineColor?: string;
-    catAxisLineWidthEmu?: number;
-    valAxisLineColor?: string;
-    valAxisLineWidthEmu?: number;
-    /** 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 (no default border). */
-    chartBorderColor?: string | null;
-    /** `<c:chartSpace><c:spPr><a:ln@w>` border width in EMU. */
-    chartBorderWidthEmu?: number | null;
-    /** `<c:catAx | valAx><c:majorTickMark val>` / `<c:minorTickMark val>` —
-     *  one of `none`/`out`/`in`/`cross` (ECMA-376 §21.2.2.49). */
-    catAxisMajorTickMark?: string;
-    catAxisMinorTickMark?: string;
-    valAxisMajorTickMark?: string;
-    valAxisMinorTickMark?: string;
-    /** `<c:catAx><c:numFmt@formatCode>` (or scatter X-axis valAx). */
-    catAxisFormatCode?: string;
-    /** `<c:catAx><c:scaling><c:min/max>` — explicit X-axis range. */
-    catAxisMin?: number;
-    catAxisMax?: number;
-    /** `<c:valAx><c:scaling><c:min/max>` — explicit Y-axis range. */
-    valAxisMin?: number;
-    valAxisMax?: number;
-    /** `<c:title><c:layout><c:manualLayout>` (§21.2.2.27) absolute placement. */
-    titleManualLayout?: ManualLayout;
-    /** `<c:plotArea><c:layout><c:manualLayout>` — `layoutTarget=inner` /
-     *  `outer` controls whether axes are inside the rect or outside. */
-    plotAreaManualLayout?: ManualLayout;
+    /** The chart payload, already in the canonical {@link ChartModel} shape the
+     *  Rust parser emits. The parser adapts its internal parse structure into
+     *  `ChartModel` (formerly the TS `adaptChartData`); this is passed straight
+     *  to `renderChart`. */
+    chart: ChartModel;
 }
 
 declare interface ChartDataLabelOverride {
@@ -522,117 +434,19 @@ declare interface ChartDataPointOverride {
  */
 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 {
@@ -1014,24 +828,11 @@ declare interface ConditionalFormat {
     rules: CfRule[];
 }
 
-declare interface DataLabelOverride {
-    idx: number;
-    text: string;
-    /** "l"|"r"|"t"|"b"|"ctr"|"outEnd"|"bestFit" or undefined → inherit. */
-    position?: string;
-    fontColor?: string;
-    fontSizeHpt?: number;
-    fontBold?: boolean;
-}
+/** @deprecated Use `ChartDataLabelOverride` from @silurus/ooxml-core. */
+declare type DataLabelOverride = ChartDataLabelOverride;
 
-declare interface DataPointOverride {
-    idx: number;
-    color?: string;
-    markerSymbol?: string;
-    markerSize?: number;
-    markerFill?: string;
-    markerLine?: string;
-}
+/** @deprecated Use `ChartDataPointOverride` from @silurus/ooxml-core. */
+declare type DataPointOverride = ChartDataPointOverride;
 
 /** One `<dataValidation>` rule (ECMA-376 §18.3.1.33). `type` is the constraint
  *  class (`list` | `whole` | `decimal` | `date` | `time` | `textLength` |
@@ -1060,6 +861,20 @@ declare interface DefinedName {
     formula: 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.
+ */
+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;
+}
+
 declare interface DocComment {
     id: string;
     author?: string;
@@ -1270,12 +1085,16 @@ export declare namespace docx {
         WireRenderPageOptions,
         DocxViewer,
         DocxViewerOptions,
+        DocxScrollViewer,
+        DocxScrollViewerOptions,
+        buildDocxTextLayer,
         autoResize,
         AutoResizeOptions,
         noteText,
         DocxDocumentModel,
         DocSettings,
         SectionProps,
+        SectionGeom,
         ColumnsSpec,
         ColSpec,
         HeadersFooters,
@@ -1345,6 +1164,11 @@ declare class DocxDocument {
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
     get pageCount(): 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
+     *  pages render via renderPage (main) or renderPageToBitmap (worker) — no
+     *  probing (design §11: no silent mis-pathing). */
+    get mode(): 'main' | 'worker';
     /**
      * The raw parsed document model. Available only in `mode: 'main'`; in
      * `mode: 'worker'` the model stays in the worker and this throws.
@@ -1374,6 +1198,20 @@ declare class DocxDocument {
      */
     get endnotes(): DocNote[];
     private _getPages;
+    /**
+     * ECMA-376 §17.6.13 / §17.6.11 — the page size (pt) of page `pageIndex`, per
+     * section (a mixed portrait/landscape document returns different sizes per page).
+     * Available in BOTH modes: worker mode reads the worker-built `pageSizes` meta;
+     * main mode reads the paginated pages' stamped geometry. Returns the body-level
+     * section size for an out-of-range index (clamped) or a page with no stamped
+     * geometry. `{ 0, 0 }` means "not loaded" (before `load()` resolves or after
+     * `destroy()`). Returns a fresh object per call — safe to mutate.
+     * The recommended way to ask "how big is page i?" for layout.
+     */
+    pageSize(pageIndex: number): {
+        widthPt: number;
+        heightPt: number;
+    };
     renderPage(target: HTMLCanvasElement | OffscreenCanvas, pageIndex: number, opts?: RenderPageOptions): Promise<void>;
     /**
      * Render a page and return it as an ImageBitmap. Works in both modes; in
@@ -1439,6 +1277,453 @@ declare interface DocxRunBorder {
     space: number;
 }
 
+declare class DocxScrollViewer {
+    private _doc;
+    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 `DocxDocument.load`. */
+    private _mode;
+    /** px-per-pt zoom multiplier. Base fit maps the first page's width to the
+     *  container width (or opts.width). Zoom multiplies this (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 page index. */
+    private readonly _slots;
+    /** Recyclable detached slots (canvas + textLayer reused across pages). */
+    private readonly _free;
+    /** Cached per-page heights in px at the current scale (index-aligned). */
+    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: page indices whose bitmap render is currently dispatched to the
+     *  engine. Coalesces a scroll storm — we never dispatch a second render for a
+     *  page whose first is still in flight — and lets us drop pages that scrolled
+     *  out of the window before dispatch (design §11 worker coalescing).
+     *
+     *  T4 ZOOM HAZARD (RESOLVED by the render epoch below): coalescing keys on page
+     *  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 page `i` (the pool reuses slot objects, so
+     *  `_slots.get(i) === slot && slot.renderedPage === 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 _bitmapInFlight;
+    /** 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 `DocxViewer`) 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 page-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?: DocxScrollViewerOptions);
+    /**
+     * Load a DOCX from URL or ArrayBuffer and render the first window.
+     * UNSUPPORTED when an engine was injected via `opts.document` (throws) — the
+     * caller already owns the parsed engine.
+     */
+    load(source: string | ArrayBuffer): Promise<void>;
+    get pageCount(): number;
+    /** CSS px width of page `i` at the current scale. */
+    private _pageWidthPx;
+    /** CSS px height of page `i` at the current scale. */
+    private _pageHeightPx;
+    /** The fit width (px), deferring when the container is unlaid-out. An EXPLICIT
+     *  `opts.width` is the page'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 page 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: first page's width fit to the fit-width. Returns 0 when the
+     *  container has no width yet (deferral). */
+    private _baseScale;
+    /**
+     * Recompute per-page 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;
+    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 `_syncSpacer` (the spacer
+     *  width). Resolved here (not stored) to mirror `_gap()`/`_pad()`. */
+    private _padH;
+    private _range;
+    private _syncSpacer;
+    /** Horizontal scroll extent: the widest page (docx pages can differ in 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 page grows past the viewport, where it
+     *  gives the gutters something to scroll to on either side. Max over per-page
+     *  widths so the extent covers the widest page in the document. Called from
+     *  `_syncSpacer` and after every scale change (zoom / resize re-fit) so the
+     *  extent tracks the current page px width. */
+    private _syncSpacerWidth;
+    private _onScroll;
+    /** Mount/recycle slots for the current visible window. */
+    private _mountVisible;
+    /** Apply the resolved page-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 page `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 `renderPage`; `worker` ⇒ transfer an ImageBitmap
+     * from `renderPageToBitmap`.
+     *
+     * Slot-identity guard: a slot recycled to a DIFFERENT page while a previous
+     * render is in flight must not repaint the stale page. `slot.renderedPage`
+     * tracks the page 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 page-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 renderPage on the
+     * same canvas wins) — `setScale` recycles + re-mounts, and the re-mount always
+     * re-dispatches `renderPage` (renderedPage 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 renderedPage
+     * 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
+     *  `DocxViewer._render` — 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 `renderPageToBitmap`, transfer the result
+     * via a per-slot `bitmaprenderer` context, and manage the ImageBitmap lifecycle.
+     *
+     * Coalescing / drop-stale (design §11):
+     *  - Skip if page `i` is already in flight (a scroll storm won't double-dispatch).
+     *  - Skip if page `i` already left the mounted window before dispatch.
+     *  - On resolution, if `slot` is no longer THIS page's live slot (it recycled to
+     *    another page, or page `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 page 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 page `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.
+     */
+    private _renderSlotBitmap;
+    /**
+     * Set the absolute px-per-pt zoom scale, 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 page 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 pages 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 page and coalesces into one crisp render.
+     *
+     * Re-anchor (written from scratch — XlsxViewer only re-anchors horizontally):
+     * capture `top = topIndex` and the intra-page 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 page'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
+     * page 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
+     * page. `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: `renderPage` (via renderDocumentToCanvas) 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, which is
+     * DISCARDED — the pooled unit is the slot, not the canvas). The old canvas keeps
+     * showing the stretched preview until the instant of the swap — blank-free.
+     */
+    private _settleSlot;
+    /**
+     * Scroll so page `index`'s top edge sits at the viewport top. Clamps `index` to
+     * `[0, pageCount-1]` (the pager convention) and the resulting scrollTop to
+     * `[0, totalHeight − viewportHeight]` so the last pages don't scroll past the
+     * end. A no-op when nothing is loaded or the document 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 page 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 page's slots
+     * exist immediately. With `behavior: 'smooth'` the scroll animates ASYNCHRONOUSLY:
+     * `scrollTop` is still near the old position when `_mountVisible` runs, so the
+     * target page mounts lazily via the animation's subsequent `scroll` events, not
+     * from this call.
+     */
+    scrollToPage(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 topVisiblePage(): number;
+    /* Excluded from this release type: mountedPageIndicesForTest */
+    /* 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 DocxScrollViewer}. Extends `RenderPageOptions` (per-page
+ * render knobs, minus `onTextRun`) and `LoadOptions` (parse/worker knobs). See
+ * design §8.1.
+ *
+ * `onTextRun` is omitted deliberately: the viewer drives it internally per
+ * mounted slot to build the optional per-page selection overlay (gated by
+ * `enableTextSelection`), so exposing it here would let a caller's callback be
+ * silently overridden.
+ */
+declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTextRun'>, LoadOptions_4 {
+    /** 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 pages. Default 16. */
+    gap?: number;
+    /** Desk padding (px) ABOVE the FIRST page — the margin a PDF reader leaves
+     *  between the top of the scroll surface and the first sheet. Default: `gap`
+     *  (uniform desk rhythm — the first page sits the same distance from the top as
+     *  pages sit from each other). Pass `0` for a flush-top layout. */
+    paddingTop?: number;
+    /** Desk padding (px) BELOW the LAST page — the margin below the final sheet.
+     *  Default: `gap`. Pass `0` for a flush-bottom layout. */
+    paddingBottom?: number;
+    /** Desk gutter (px) to the LEFT of the pages — the horizontal margin between the
+     *  left edge of the scroll surface and a page 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 page sits inside the gutters at 100%
+     *  (an EXPLICIT `opts.width` is the page'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 pages. Default: `gap`. Shrinks the
+     *  container-derived fit width symmetrically with `paddingLeft`. Pass `0` for a
+     *  flush-right layout. */
+    paddingRight?: number;
+    /** Pages kept mounted beyond the viewport on each side. Default 1. */
+    overscan?: number;
+    /** Per-page 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 (px-per-pt multiplier floor). Default 0.1. */
+    zoomMin?: number;
+    /** Maximum zoom scale. 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 pages — the gray a PDF reader paints around the sheet.
+     * Applied to the viewer-owned scroll host. The pages themselves are always
+     * drawn on the document's 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 page CANVAS (not the wrapper — the
+     * text-selection overlay must not cast its own shadow). The soft drop shadow a
+     * PDF reader leaves under each sheet.
+     *
+     * - 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 pages).
+     * - 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).
+     */
+    document?: DocxDocument;
+    /** Fires when the top-most visible page changes. `topIndex` from
+     *  `computeVisibleRange` (the first page intersecting the viewport top,
+     *  EXCLUDING overscan). */
+    onVisiblePageChange?: (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 `renderPage` and worker
+     *  `renderPageToBitmap` rejections); a failed page is left blank rather than
+     *  crashing the loop. Without an `onError`, render failures are logged via
+     *  `console.error` so they are never fully silent. */
+    onError?: (err: Error) => void;
+}
+
 declare interface DocxTextRun {
     text: string;
     bold: boolean;
@@ -1536,6 +1821,15 @@ declare class DocxViewer {
     private _currentPage;
     private _canvas;
     private _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 _originalParent;
+    private _originalNextSibling;
+    /** The canvas's inline `display` before the constructor forced `block`
+     *  (empty string if it was unset), restored on {@link destroy}. */
+    private _originalDisplay;
     private _textLayer;
     private _opts;
     private readonly _mode;
@@ -1560,7 +1854,15 @@ declare class DocxViewer {
     goToPage(index: number): Promise<void>;
     nextPage(): Promise<void>;
     prevPage(): Promise<void>;
-    /** Terminate the parser worker and release resources. */
+    /**
+     * Terminate the parser worker and release resources.
+     *
+     * 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;
     private _render;
     private _buildTextLayer;
@@ -1607,19 +1909,8 @@ declare interface EquationRun {
     color?: string | null;
 }
 
-declare interface ErrBars {
-    /** "x" | "y". */
-    dir: string;
-    /** "plus" | "minus" | "both". */
-    barType: string;
-    plus: (number | null)[];
-    minus: (number | null)[];
-    noEndCap: boolean;
-    /** Resolved RGB hex (no `#`). */
-    color?: string;
-    lineWidthEmu?: number;
-    dash?: string;
-}
+/** @deprecated Use `ChartErrBars` from @silurus/ooxml-core. */
+declare type ErrBars = ChartErrBars;
 
 declare interface FieldRun {
     /** "page" | "numPages" | "other" */
@@ -1750,6 +2041,12 @@ declare interface HeadersFooters {
     even: HeaderFooter | null;
 }
 
+/** How {@link XlsxViewer} presents hidden sheets (`<sheet state>`, §18.2.19). */
+declare type HiddenSheetMode = 'show' | 'skip' | 'dim';
+
+/** How {@link PptxViewer} presents hidden slides (`<p:sld show="0">`). */
+declare type HiddenSlideMode = 'show' | 'skip' | 'dim';
+
 declare interface Hyperlink {
     col: number;
     row: number;
@@ -1955,15 +2252,6 @@ declare interface LegendManualLayout {
     h: number;
 }
 
-declare interface LegendManualLayout_2 {
-    xMode: string;
-    yMode: string;
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
-
 /**
  * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Drives the bevel-lip
  * lighting (Phase B): `dir` selects the key-light octant.
@@ -2034,6 +2322,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
@@ -2041,6 +2344,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
@@ -2087,15 +2400,8 @@ declare interface LoadOptions_4 extends LoadOptions_2 {
     mode?: 'main' | 'worker';
 }
 
-declare interface ManualLayout {
-    xMode: string;
-    yMode: string;
-    layoutTarget?: string;
-    x: number;
-    y: number;
-    w?: number;
-    h?: number;
-}
+/** @deprecated Use `ChartManualLayout` from @silurus/ooxml-core. */
+declare type ManualLayout = ChartManualLayout;
 
 /** Accent (`m:acc`), e.g. hat, bar, vector arrow over the base. */
 declare interface MathAccent {
@@ -2612,6 +2918,9 @@ export declare namespace pptx {
     export {
         PptxViewer,
         PptxViewerOptions,
+        HiddenSlideMode,
+        PptxScrollViewer,
+        PptxScrollViewerOptions,
         PptxPresentation,
         LoadOptions,
         RenderSlideOptions,
@@ -2620,6 +2929,7 @@ export declare namespace pptx {
         RenderOptions,
         PptxTextRunInfo,
         TextRunCallback,
+        buildPptxTextLayer,
         PresentationHandle,
         autoResize,
         AutoResizeOptions,
@@ -2665,7 +2975,8 @@ export declare namespace pptx {
         TextRunData,
         LineBreak,
         ChartModel,
-        ChartSeries
+        ChartSeries,
+        DimOptions
     }
 }
 
@@ -2725,6 +3036,11 @@ 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
@@ -2745,6 +3061,14 @@ 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>;
     /**
@@ -2782,6 +3106,475 @@ declare class PptxPresentation {
     destroy(): void;
 }
 
+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.
+ */
+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. */
 declare interface PptxTextRunInfo {
     text: string;
@@ -2827,10 +3620,20 @@ declare interface PptxTextRunInfo {
 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
@@ -2851,6 +3654,21 @@ 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;
     /**
@@ -2864,7 +3682,15 @@ 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;
 }
 
@@ -2886,6 +3712,24 @@ 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>;
 }
 
 declare interface Presentation {
@@ -2969,7 +3813,11 @@ declare interface RenderOptions {
 }
 
 declare interface RenderPageOptions {
-    /** Canvas CSS width in px; height is auto-computed from page aspect ratio */
+    /** Canvas CSS width in px; height is auto-computed from page aspect ratio.
+     *  Applies per CALL — pages of different physical widths (per-section pgSz,
+     *  §17.6.13) rendered at the same `width` get different px-per-pt scales.
+     *  For a uniform document scale, derive a per-page width from
+     *  `DocxDocument.pageSize(i)` instead of passing a constant. */
     width?: number;
     dpr?: number;
     defaultTextColor?: string;
@@ -3009,6 +3857,8 @@ 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}. */
@@ -3018,6 +3868,8 @@ 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;
 }
 
 declare interface RenderViewportOptions {
@@ -3181,6 +4033,32 @@ declare interface SecondaryValueAxis {
     titleFontColor?: string | null;
 }
 
+/** ECMA-376 §17.6.13 `<w:pgSz>` + §17.6.11 `<w:pgMar>` — a section's page
+ *  geometry: page size + margins + header/footer distances (pt). Mirrors the Rust
+ *  `SectionGeom`. Carried on a {@link BodyElement} `sectionBreak` arm (`geom`) so a
+ *  mid-body section keeps its own page size; the FINAL section's geometry lives on
+ *  {@link DocxDocumentModel.section}. Also stamped per {@link PaginatedBodyElement}
+ *  (`sectionGeom`) by the paginator so the renderer sizes each page from its own
+ *  section. `orient` is omitted — Word swaps w/h for landscape, so verbatim w/h
+ *  already give the correct dims.
+ *
+ *  ⚠ Spread over the body-level {@link SectionProps} in `renderDocumentToCanvas`
+ *  (`{ ...doc.section, ...pageGeom }`): only add per-section PAGE-BOX fields that
+ *  exist on `SectionProps` with the same name and semantics — an optional field
+ *  colliding with a non-geometry `SectionProps` name would silently override the
+ *  body-level value the renderer promises to preserve. */
+declare interface SectionGeom {
+    pageWidth: number;
+    pageHeight: number;
+    /** §17.6.11 — top/bottom MAY be negative (ST_SignedTwipsMeasure); keep the sign. */
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+    headerDistance: number;
+    footerDistance: number;
+}
+
 declare interface SectionProps {
     pageWidth: number;
     pageHeight: number;
@@ -3221,17 +4099,8 @@ declare interface SectionProps {
 
 declare type SelectionMode_2 = 'cells' | 'rows' | 'cols' | 'all';
 
-declare interface SeriesDataLabels {
-    showVal: boolean;
-    showCatName: boolean;
-    showSerName: boolean;
-    showPercent: boolean;
-    position?: string;
-    fontColor?: string;
-    formatCode?: string;
-    fontBold?: boolean;
-    fontSizeHpt?: number;
-}
+/** @deprecated Use `ChartSeriesDataLabels` from @silurus/ooxml-core. */
+declare type SeriesDataLabels = ChartSeriesDataLabels;
 
 declare interface Shadow {
     color: string;
@@ -3405,6 +4274,9 @@ declare interface ShapeParagraph {
     /** `<a:pPr@indent>` — first-line indent in EMU (negative = hanging),
      *  ECMA-376 §21.1.2.2.7. Omitted (undefined) when unset. */
     indent?: number;
+    /** `<a:pPr>/<a:lnSpc>` line spacing (ECMA-376 §21.1.2.2.5). Direct-only;
+     *  omitted when unset. */
+    spaceLine?: SpaceLine | null;
     runs: ShapeTextRun[];
 }
 
@@ -3490,6 +4362,12 @@ declare interface ShapeRun {
     textBlocks?: ShapeText_2[];
     /** "t" | "ctr" | "b" — vertical anchor for the shape's text body (`<wps:bodyPr @anchor>`). */
     textAnchor?: string | null;
+    /** ECMA-376 §21.1.2.1.1 auto-fit mode from `<wps:bodyPr>`, normalized to the
+     *  shared core `autoFit` vocabulary (core `src/types/common.ts`): "none"
+     *  (`<a:noAutofit/>`, fixed box — overflowing text is CLIPPED to the box),
+     *  "sp" (`<a:spAutoFit/>`, box grows to text), or "norm" (`<a:normAutofit/>`,
+     *  text shrinks). Absent ⇒ overflow visible. */
+    textAutofit?: string | null;
     textInsetL?: number;
     textInsetT?: number;
     textInsetR?: number;
@@ -3502,6 +4380,27 @@ declare interface ShapeText {
     anchor: string;
     /** `<a:bodyPr@wrap>` — `square` (wrap to width) | `none`. */
     wrap: string;
+    /** `<a:bodyPr>` autofit child — `'sp'` (`spAutoFit`), `'norm'` (`normAutofit`),
+     *  or `'none'` (`noAutofit`/absent). ECMA-376 §21.1.2.1.1-.3. Always present
+     *  (default `'none'`), mirroring the core `TextBody.autoFit`. */
+    autoFit?: string;
+    /** `<a:normAutofit@fontScale>` — stored font-shrink fraction (e.g. 0.625 for
+     *  `fontScale="62500"`). Null/absent when unset. Modeled for parity with
+     *  pptx; the xlsx renderer does not currently apply it. */
+    fontScale?: number | null;
+    /** `<a:normAutofit@lnSpcReduction>` — stored line-spacing reduction fraction
+     *  (e.g. 0.20 for `lnSpcReduction="20000"`). Null/absent when unset. */
+    lnSpcReduction?: number | null;
+    /** `<a:bodyPr@lIns>` — left text inset in EMU (ECMA-376 §21.1.2.1.1). Always
+     *  present; the spec default 91440 EMU (7.2 pt) when the attribute is absent.
+     *  Same EMU convention as `ShapeParagraph.marL`. */
+    lIns: number;
+    /** `<a:bodyPr@tIns>` — top text inset in EMU. Default 45720 (3.6 pt). */
+    tIns: number;
+    /** `<a:bodyPr@rIns>` — right text inset in EMU. Default 91440 (7.2 pt). */
+    rIns: number;
+    /** `<a:bodyPr@bIns>` — bottom text inset in EMU. Default 45720 (3.6 pt). */
+    bIns: number;
     paragraphs: ShapeParagraph[];
 }
 
@@ -3525,6 +4424,12 @@ declare interface ShapeText_2 {
     /** ECMA-376 §17.3.1.33 `<w:spacing w:after>` of this text-box paragraph, in
      *  pt — reserved BELOW the paragraph. Absent/0 ⇒ no offset. */
     spaceAfter?: number;
+    /** ECMA-376 §17.3.1.33 line spacing value (style-chain resolved). Encoded per
+     *  {@link lineSpacingRule}: "auto" ⇒ a MULTIPLIER on the natural line box
+     *  (1.15 = 276/240), "exact"/"atLeast" ⇒ pt. Absent ⇒ single (natural). */
+    lineSpacingVal?: number;
+    /** "auto" | "exact" | "atLeast" — see {@link lineSpacingVal}. */
+    lineSpacingRule?: string;
     /** ECMA-376 §17.3.1.12 `<w:ind w:left/@start>` — paragraph left indent (pt).
      *  Absent/0 ⇒ flush to the box's inner left edge. */
     indentLeft?: number;
@@ -3537,6 +4442,18 @@ declare interface ShapeText_2 {
      *  applies a signed hanging first-line list-independently). Absent/0 ⇒ the
      *  first line aligns with the continuation lines. */
     indentFirst?: number;
+    /** ECMA-376 §17.3.1.37 `<w:tabs>` — explicit tab stops of this text-box
+     *  paragraph, resolved through the style chain like {@link DocParagraph.tabStops}.
+     *  Absent/empty ⇒ only the automatic default-tab grid applies. The renderer
+     *  feeds these to the SAME line engine the body uses so a `\t` inside a text box
+     *  advances to its stop (the old shape wrapper dropped tabs entirely). */
+    tabStops?: TabStop_2[];
+    /** ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left text-box paragraph, resolved
+     *  through the style chain like {@link DocParagraph.bidi}. `true` = RTL,
+     *  `false` = explicitly LTR, absent = unspecified. Consumed as the paragraph
+     *  base direction for the UAX#9 reordering pass (the body renderer reads the
+     *  identical field). */
+    bidi?: boolean;
     /** Zip path of an inline image inside this text-box paragraph
      *  (`<w:drawing><wp:inline><a:blip r:embed>`), e.g. `word/media/image1.emf`.
      *  Absent for a text-only paragraph. */
@@ -3566,6 +4483,18 @@ declare type ShapeTextRun = {
     size: number;
     color?: string;
     fontFace?: string;
+    /** East-Asian typeface (`<a:ea@typeface>`, ECMA-376 §21.1.2.3.1). The
+     *  common Japanese encoding sets Meiryo here while leaving `<a:latin>`
+     *  default; the renderer floors the line box by this face's design line
+     *  too (see `drawShapeText`). Undefined when the run declares no `<a:ea>`. */
+    fontFaceEa?: string;
+    /** Complex-script typeface (`<a:cs@typeface>`, ECMA-376 §21.1.2.3.1).
+     *  Parsed/modeled but NOT used in the line-box floor: the cs face renders
+     *  only complex-script glyphs (Arabic/Hebrew/Thai), so flooring the whole
+     *  line box by it would over-grow Latin/CJK runs (deferred to per-glyph
+     *  handling — see `drawShapeText`). Undefined when the run declares no
+     *  `<a:cs>`. */
+    fontFaceCs?: string;
 } | {
     type: 'break';
 } | {
@@ -3611,8 +4540,16 @@ declare interface SheetMeta {
      *  `#RRGGBB`. Surfaced at workbook-list time so tabs can be painted up front.
      *  Absent when the sheet declares no tab color. */
     tabColor?: string | null;
+    /** Sheet visibility (`<sheet state>`, ECMA-376 §18.2.19 `ST_SheetState`).
+     *  Absent ⇒ visible. `'veryHidden'` sheets are revealable only
+     *  programmatically in Excel. Read via `XlsxWorkbook.isHidden` /
+     *  `XlsxWorkbook.sheetVisibility`. */
+    visibility?: 'hidden' | 'veryHidden';
 }
 
+/** Sheet visibility (`<sheet state>`, ECMA-376 §18.2.19 `ST_SheetState`). */
+declare type SheetVisibility = 'visible' | 'hidden' | 'veryHidden';
+
 declare interface SlicerAnchor {
     fromCol: number;
     fromColOff: number;
@@ -3651,6 +4588,13 @@ 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;
 }
 
 declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
@@ -3663,6 +4607,7 @@ declare type SlideElement = ShapeElement | PictureElement | TableElement | Chart
  */
 declare type SlideRenderOptions = RenderOptions & {
     math?: MathRenderer;
+    dim?: DimOptions;
 };
 
 /** ECMA-376 §20.1.8.31 (CT_SoftEdgesEffect) — feather radius in EMU. */
@@ -4225,6 +5170,7 @@ export declare namespace xlsx {
         XlsxViewer,
         ResolvedList,
         XlsxViewerOptions,
+        HiddenSheetMode,
         CellAddress,
         CellRange_2 as CellRange,
         SelectionMode_2 as SelectionMode,
@@ -4232,6 +5178,7 @@ export declare namespace xlsx {
         AutoResizeOptions,
         Workbook,
         SheetMeta,
+        SheetVisibility,
         Worksheet,
         Row,
         Cell,
@@ -4278,63 +5225,28 @@ export declare namespace xlsx {
         ShapeTextRun,
         PathInfo,
         PathCmd_2 as PathCmd,
-        ChartData,
+        ChartModel,
+        ChartSeries,
+        ChartSeriesDataLabels,
+        ChartDataLabelOverride,
+        ChartDataPointOverride,
+        ChartErrBars,
+        ChartManualLayout,
+        LegendManualLayout,
         XlsxChartSeries,
         SeriesDataLabels,
         DataLabelOverride,
         DataPointOverride,
         ErrBars,
-        ManualLayout,
-        LegendManualLayout_2 as LegendManualLayout
+        ManualLayout
     }
 }
 
 /**
- * XLSX parser's raw chart series (includes XLSX-only `seriesType` for mixed
- * charts). Adapted to `ChartSeries` from @silurus/ooxml-core before rendering.
+ * @deprecated Chart series are now the core {@link ChartModel}'s `ChartSeries`.
+ * Kept as an alias for backward-compatible imports.
  */
-declare interface XlsxChartSeries {
-    name: string;
-    /** Chart sub-type for this series (allows mixed charts). */
-    seriesType: string;
-    categories: string[];
-    values: (number | null)[];
-    /** Explicit fill color hex (from c:spPr). Undefined = use palette. */
-    color?: string | null;
-    /** Marker visibility resolved from `<c:marker>`/chart-level default
-     *  (ECMA-376 §21.2.2.32). */
-    showMarker?: boolean;
-    /** `<c:val>/<c:numRef>/<c:formatCode>` — Excel number format for series
-     *  values (ECMA-376 §21.2.2.37). */
-    valFormatCode?: string | null;
-    /** `<c:ser><c:dLbls><c:txPr>…solidFill` — per-series data-label text color
-     *  (ECMA-376 §21.2.2.216). Takes precedence over the chart-level color so
-     *  each series can color its labels independently. */
-    labelColor?: string | null;
-    /** `<c:ser><c:order>` — stacking/legend display order (§21.2.2.28). */
-    order?: number;
-    /** `<c:marker><c:symbol val>` — point marker shape (ECMA-376 §21.2.2.32). */
-    markerSymbol?: string;
-    /** `<c:marker><c:size val>` — point marker side length in pt (§21.2.2.34). */
-    markerSize?: number;
-    /** `<c:marker><c:spPr>` resolved fill (no `#`). */
-    markerFill?: string;
-    /** `<c:marker><c:spPr><a:ln>` resolved stroke (no `#`). */
-    markerLine?: string;
-    /** `<c:dPt>` per-data-point overrides (§21.2.2.39). */
-    dataPointOverrides?: DataPointOverride[];
-    /** Per-idx custom data labels (`<c:dLbl idx>`, §21.2.2.45). Custom rich
-     *  text is flattened to plain string at parse time; CELLRANGE field
-     *  placeholders are resolved against the series' `<c15:datalabelsRange>`
-     *  cache. */
-    dataLabelOverrides?: DataLabelOverride[];
-    /** Series-level `<c:dLbls>` defaults applied to every point lacking its
-     *  own override. */
-    seriesDataLabels?: SeriesDataLabels;
-    /** `<c:errBars>` (§21.2.2.20). At parse time, plus / minus deltas are
-     *  resolved into absolute per-point values regardless of `errValType`. */
-    errBars?: ErrBars[];
-}
+declare type XlsxChartSeries = ChartSeries;
 
 /** One cell comment. Sourced from the classic notes file `xl/commentsN.xml`
  *  (ECMA-376 §18.7) when present, otherwise from the Office-365 threaded
@@ -4371,6 +5283,10 @@ declare interface XlsxTextRunInfo {
 
 declare class XlsxViewer {
     private wb;
+    /** The single subtree root the constructor appended to the caller's
+     *  container. destroy() removes it to return the container to its original
+     *  (empty) state. */
+    private wrapper;
     private canvas;
     private canvasArea;
     private scrollHost;
@@ -4386,6 +5302,7 @@ declare class XlsxViewer {
     private zoomSlider;
     private zoomLabel;
     private currentSheet;
+    private _hiddenSheetMode;
     private currentWorksheet;
     private opts;
     /** 'main' renders on this thread; 'worker' paints worker-produced bitmaps. */
@@ -4395,6 +5312,32 @@ declare class XlsxViewer {
      *  main-mode 2d render path is never used on the same canvas. */
     private _bitmapCtx;
     private resizeObserver;
+    /**
+     * Pending `requestAnimationFrame` handle for a coalesced re-render, or `null`
+     * when none is scheduled. High-frequency event-driven repaints (scroll, live
+     * resize drag, selection drag, container resize) route through
+     * {@link scheduleRender} so at most one render runs per animation frame: a
+     * burst of scroll events within a single frame collapses to one draw at the
+     * frame's latest scroll position (`renderCurrentSheet` reads the live scroll
+     * offset, so "latest wins" needs no stored position). Explicit API calls
+     * (`showSheet`/`goToSheet`, `select`, `setScale`) stay synchronous — they must
+     * paint immediately, not a frame later. `destroy()` cancels any pending frame.
+     */
+    private _rafId;
+    /**
+     * Monotonic render-request counter for worker-mode stale-frame dropping.
+     * Every {@link renderCurrentSheet} bumps it and captures the value before it
+     * awaits the worker's bitmap; on resolution a captured value below the current
+     * one means a newer render was requested meanwhile (scroll moved on, the sheet
+     * switched, a zoom changed), so that bitmap is stale and must be closed and
+     * dropped instead of painted over the fresher frame. The WorkerBridge already
+     * correlates each request↔response by id, but requests overlap — a slow bitmap
+     * for an old scroll position can resolve after a newer one — so the viewer
+     * needs this generation guard, the single-canvas analogue of the pptx
+     * scroll-viewer's per-slot render epoch (PR #663). The main-thread path renders
+     * synchronously and cannot interleave, so it needs no guard.
+     */
+    private _renderSeq;
     /**
      * Start-anchored horizontal scroll position (the {@link effectiveScrollLeft}
      * value last produced by a real user scroll or a programmatic reset), kept
@@ -4503,6 +5446,10 @@ declare class XlsxViewer {
     goToSheet(index: number): Promise<void>;
     nextSheet(): Promise<void>;
     prevSheet(): Promise<void>;
+    /** Next sheet index for sequential nav: skip mode jumps over hidden sheets. */
+    private _stepSheet;
+    /** Initial sheet for load() / entering skip mode: land on a visible sheet. */
+    private _initialSheet;
     /** Returns the cell at canvas-client coordinates, or null if outside the cell grid. */
     getCellAt(clientX: number, clientY: number): CellAddress | null;
     /** Returns the CSS-pixel rect of a cell within canvasArea, or null if not
@@ -4554,6 +5501,15 @@ declare class XlsxViewer {
      * immediately.
      */
     setSelectionColor(color: string): void;
+    /**
+     * Switch the hidden-sheet mode at runtime: restyle the tabs and re-render.
+     * Entering `'skip'` while on a hidden sheet advances to the nearest visible.
+     */
+    setHiddenSheetMode(mode: HiddenSheetMode): Promise<void>;
+    /** The current hidden-sheet mode. */
+    get hiddenSheetMode(): HiddenSheetMode;
+    /** Number of non-hidden sheets (absolute `sheetCount` is unchanged). */
+    get visibleSheetCount(): number;
     /** Copy the selected cell range as tab-separated text to the clipboard. */
     private copySelection;
     private updateSelectionOverlay;
@@ -4609,6 +5565,13 @@ declare class XlsxViewer {
     private updateNavButtons;
     private updateTabActive;
     private tabStyle;
+    /**
+     * Full inline style for the tab of sheet `i`, honoring the hidden-sheet mode:
+     * `'skip'` hides the tab of a hidden/veryHidden sheet (`display:none`); `'dim'`
+     * greys it but leaves it clickable; `'show'` styles every tab normally. Used
+     * by both buildTabs and updateTabActive so navigation never wipes the styling.
+     */
+    private tabCss;
     /** Excel-style zoom control pinned to the right end of the tab bar:
      *  `−  [────slider────]  +  100%`. Live-updates the cell scale on input. */
     private buildZoomControl;
@@ -4622,11 +5585,39 @@ declare class XlsxViewer {
      *  aligned tab-nav width in sync. */
     setScale(scale: number): void;
     private updateSpacerSize;
+    /**
+     * Coalesce a re-render into the next animation frame. Called from the
+     * high-frequency event-driven paths (scroll, live column/row resize, drag-
+     * selection, container resize); a burst of these within one frame schedules a
+     * single {@link renderCurrentSheet}, avoiding the previous behavior where every
+     * scroll event forced its own synchronous full redraw. Already-scheduled frames
+     * are not re-scheduled — the one pending render reads the live scroll/scale
+     * state when it runs, so the most recent position always wins without threading
+     * a coordinate through. Falls back to a synchronous render when
+     * `requestAnimationFrame` is unavailable (e.g. a non-DOM host), preserving the
+     * old semantics there.
+     */
+    private scheduleRender;
     private renderCurrentSheet;
     private computeHeaderHighlight;
     get sheetNames(): string[];
     /** The underlying <canvas> element the grid is drawn on. */
     get canvasElement(): HTMLCanvasElement;
+    /**
+     * Tear down the viewer and release resources.
+     *
+     * The caller's container is returned to the state it had before construction
+     * (empty): the entire wrapper subtree the constructor appended is removed.
+     * All document-level listeners are detached — the keydown handler here, and
+     * the validation-panel outside-click handler via {@link hideValidationPanel}.
+     * Listeners on elements inside the wrapper (scrollHost, tabs, …) need no
+     * explicit removal: removing the subtree makes them unreachable and eligible
+     * for GC. Safe to call more than once.
+     *
+     * NOTE: the shared `<style>` in `document.head` is intentionally NOT removed —
+     * it is a class constant that any still-live viewer may depend on, and one
+     * leftover sheet is a bounded, harmless cost (see {@link ensureViewerStyleInjected}).
+     */
     destroy(): void;
 }
 
@@ -4679,6 +5670,19 @@ declare interface XlsxViewerOptions extends LoadOptions_2 {
      * require `'main'` (the math engine cannot cross the worker boundary).
      */
     mode?: 'main' | 'worker';
+    /**
+     * How hidden / veryHidden sheets (`<sheet state>`, ECMA-376 §18.2.19) are
+     * presented:
+     * - `'show'` (default): every sheet gets a tab — current behavior.
+     * - `'skip'`: hidden/veryHidden sheets get no tab and are jumped over by
+     *   `nextSheet`/`prevSheet` and initial load; absolute indices are unchanged,
+     *   and an explicit `goToSheet(i)` to a hidden sheet is still honored.
+     * - `'dim'`: hidden/veryHidden tabs are shown greyed but stay selectable.
+     *
+     * Named to match the {@link XlsxViewer.hiddenSheetMode} getter and
+     * {@link XlsxViewer.setHiddenSheetMode} setter. Mirrors pptx `hiddenSlideMode`.
+     */
+    hiddenSheetMode?: HiddenSheetMode;
 }
 
 declare class XlsxWorkbook {
@@ -4715,6 +5719,21 @@ declare class XlsxWorkbook {
     /** Per-sheet tab colors (`#RRGGBB`) parallel to {@link sheetNames}.
      *  `null` for sheets that declare no tab color. */
     get tabColors(): (string | null)[];
+    /**
+     * Full visibility fact for the sheet at `sheetIndex` (0-based):
+     * `'visible'` | `'hidden'` | `'veryHidden'` (`<sheet state>`, ECMA-376
+     * §18.2.19). NOT clamped — out-of-range / non-integer ⇒ `'visible'`. This is a
+     * *fact*; deciding what to do with a hidden sheet (hide/skip/dim its tab) is
+     * {@link XlsxViewer}'s policy. `'veryHidden'` is revealable only
+     * programmatically in Excel; it is surfaced distinctly here.
+     */
+    sheetVisibility(sheetIndex: number): SheetVisibility;
+    /**
+     * Whether the sheet at `sheetIndex` is hidden or veryHidden. Convenience over
+     * {@link sheetVisibility}; mirrors {@link PptxPresentation.isHidden} (non-
+     * clamped: out-of-range / non-integer ⇒ `false`).
+     */
+    isHidden(sheetIndex: number): boolean;
     getWorksheet(sheetIndex: number): Promise<Worksheet>;
     /**
      * Fetch an embedded image's bytes by zip path (e.g. `xl/media/image1.png`),