@silurus/ooxml 0.70.2 → 0.72.0

package/dist/types/index.d.ts

@@ -61,11 +61,18 @@ declare interface BlipBullet {
     /** MIME type of the blip at {@link BlipBullet.imagePath} (e.g. `image/png`). */
     mimeType: string;
     /**
-     * `<a:buSzPct val>` (ECMA-376 §21.1.2.4.3) as a percentage of the text size
+     * `<a:buSzPct val>` (ECMA-376 §21.1.2.4.9) as a percentage of the text size
      * (100 = same size). `null` when no explicit `<a:buSzPct>` is present, in
      * which case the renderer uses the spec default of 100%.
      */
     sizePct: number | null;
+    /**
+     * `<a:buSzPts val>` (ECMA-376 §21.1.2.4.10) — an ABSOLUTE marker size in
+     * points, independent of the text size. Mutually exclusive with {@link
+     * BlipBullet.sizePct} (both are the one `EG_TextBulletSize` choice). Omitted
+     * when no explicit `<a:buSzPts>` is present; when present it takes precedence.
+     */
+    sizePts?: number;
 }
 
 declare type BodyElement = {
@@ -109,6 +116,19 @@ declare type BodyElement = {
      *  (size + margins). Absent when the sectPr inherits both pgSz and pgMar
      *  (the renderer then falls back to the body-level section geometry). */
     geom?: SectionGeom;
+    /** ECMA-376 §17.6.12 `<w:pgNumType>` — this ENDING section's page-numbering
+     *  settings (start / fmt). Absent ⇒ numbering continues; decimal. Carried
+     *  separately from `geom` because a section may inherit its geometry yet
+     *  still restart / re-format its page numbers. */
+    pageNumType?: PageNumType | null;
+    /** ECMA-376 §17.6.20 `<w:textDirection w:val>` — this ENDING section's
+     *  flow direction (TRANSITIONAL ST_TextDirection, same enum and semantics
+     *  as {@link SectionProps.textDirection}), so a vertical (tbRl/btLr)
+     *  non-final section can coexist with a horizontal final section (issue
+     *  #1000). Absent ⇒ horizontal ("lrTb" is collapsed by the parser).
+     *  Carried separately from `geom` (like `pageNumType`) because a section
+     *  may inherit its page geometry yet still set its own flow direction. */
+    textDirection?: string | null;
 };
 
 declare interface Border {
@@ -137,6 +157,27 @@ declare interface BorderSpec {
     style: string;
 }
 
+/**
+ * Populate a highlight overlay layer with one box per matched run-slice.
+ *
+ * Every box is positioned as a PERCENTAGE of `cssWidth`/`cssHeight`, and the
+ * container's own size is left untouched (`width:100%;height:100%` from the
+ * caller), so the highlights track the canvas's ACTUAL rendered box even when a
+ * consumer scales the canvas down with external CSS — mirroring
+ * {@link buildDocxTextLayer}.
+ *
+ * @param layer    the overlay div (cleared here; sized `100%` by the caller).
+ * @param runs     the page's runs (same array the page was rendered/text-layered from).
+ * @param matches  the page's matches (run-slices + active flag).
+ * @param cssWidth  the page's intended CSS width (px, number) — the x-axis % denominator.
+ * @param cssHeight the page's intended CSS height (px, number) — the y-axis % denominator.
+ * @param measureForFont  returns a width-measurer primed with a run's `font`
+ *                        (the viewer closes over a canvas 2d context). Kept as a
+ *                        factory so the font is set once per run, not per glyph.
+ * @param colors   optional colour overrides.
+ */
+declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
+
 /**
  * Build the transparent text-selection overlay for a rendered docx page: one
  * absolutely-positioned, color-transparent `<span>` per {@link DocxTextRunInfo}
@@ -144,16 +185,65 @@ declare interface BorderSpec {
  * 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.
+ * overlay (design §10). IX6 — usable in BOTH render modes: worker mode collects
+ * the same `DocxTextRunInfo[]` off-thread and ships it back beside the bitmap, so
+ * the overlay is built from identical geometry regardless of thread.
+ *
+ * Every span is positioned as a PERCENTAGE of `cssWidth`/`cssHeight` (the page's
+ * intended CSS-px box), never literal px, and the container's own width/height are
+ * left untouched (the caller sizes it `width:100%;height:100%`). This lets the
+ * overlay track the canvas's ACTUAL rendered box even when a consumer scales the
+ * canvas down with external CSS (`width:100%!important; height:auto`): the
+ * `display:inline-block` wrapper shrinks with the canvas, the `100%` container
+ * follows, and every `%`-placed span scales with it, so nothing overflows the
+ * wrapper into an ancestor's scroll area.
  *
- * @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.
+ * @param layer            the overlay div (sized `width:100%;height:100%` by the caller).
+ * @param runs             per-run geometry from `renderPage({ onTextRun })`.
+ * @param cssWidth         the page's intended CSS width (px, number) — the %
+ *                         denominator for the x axis.
+ * @param cssHeight        the page's intended CSS height (px, number) — the %
+ *                         denominator for the y axis.
+ * @param onHyperlinkClick IX1 — invoked when a run carrying a resolved
+ *                         {@link HyperlinkTarget} is clicked. A hyperlink run's
+ *                         span keeps its transparent glyphs (the visible link
+ *                         colour/underline is already drawn on the canvas) but
+ *                         gains `cursor:pointer`, a `title` tooltip (the URL or
+ *                         bookmark ref) and this click handler. A plain
+ *                         `<span>` — not an `<a href>` — is used deliberately so
+ *                         the browser's own navigation can never bypass the
+ *                         caller's URL sanitisation. When omitted, link runs are
+ *                         rendered exactly like plain runs (no click affordance).
+ * @param measureForFont   optional width-measurer factory (primed with a run's
+ *                         `font`), used ONLY to clamp a §17.3.2.10 縦中横
+ *                         (eastAsianVert) span to its drawn one-em cell (#836):
+ *                         the span composes a `scaleX(run.w / naturalWidth)` so
+ *                         its selection extent matches the compressed glyphs
+ *                         instead of the run's natural ~2× width. When omitted,
+ *                         a 縦中横 span keeps the bare rotate (no regression for
+ *                         callers that do not thread a measurer).
  */
-declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string): void;
+declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], cssWidth: number, cssHeight: number, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
+
+/**
+ * Populate a highlight overlay layer with a box per matched run-slice, grouped
+ * by shape frame (with the shape's rotation) so each box lands on the drawn
+ * glyphs.
+ *
+ * All coordinates are PERCENTAGES of `cssWidth`/`cssHeight`, and the container's
+ * own size is left untouched (`width:100%;height:100%` from the caller), so the
+ * highlights track the canvas's ACTUAL rendered box even when a consumer scales
+ * the canvas down with external CSS — mirroring {@link buildPptxTextLayer}.
+ *
+ * @param layer     the overlay div (cleared here; sized `100%` by the caller).
+ * @param runs      the slide's runs (same array the slide was rendered from).
+ * @param matches   the slide's matches (run-slices + active flag).
+ * @param cssWidth  the slide's intended CSS width (px, number) — the % denominator.
+ * @param cssHeight the slide's intended CSS height (px, number) — the % denominator.
+ * @param measureForFont returns a width-measurer primed with a run's font.
+ * @param colors    optional colour overrides.
+ */
+declare function buildPptxHighlightLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], matches: PptxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: PptxHighlightColors): void;
 
 /**
  * Build the transparent text-selection overlay for a rendered pptx slide. Unlike
@@ -164,16 +254,42 @@ declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo
  * 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.
+ * integrators (design §10). IX6 — usable in BOTH render modes: worker mode
+ * collects the same `PptxTextRunInfo[]` off-thread and ships it back beside the
+ * bitmap, so the overlay is built from identical geometry regardless of thread.
+ *
+ * IX1 — when a run carries a resolved `hyperlink` (from `<a:hlinkClick>`) and an
+ * `onHyperlinkClick` callback is supplied, its span becomes a click target
+ * (`cursor:pointer`, a `title` tooltip, and a `click` handler). A plain span
+ * (no hyperlink) is byte-identical to before. A JS click handler is used rather
+ * than an `<a href>` so the URL never bypasses the viewer's sanitisation.
+ *
+ * The overlay's coordinates are all PERCENTAGES of `cssWidth`/`cssHeight` (the
+ * slide's intended CSS-px box), never literal px, and the container's own
+ * `width`/`height` are left untouched (the caller sizes it `width:100%;
+ * height:100%` so it fills the wrapper). This lets the overlay track the canvas's
+ * ACTUAL rendered box even when a consumer scales the canvas down with external
+ * CSS (e.g. `width:100%!important;height:auto`): the wrapper (and therefore the
+ * `100%` container) shrinks with the canvas, and every `%`-placed child scales
+ * with it, so nothing overflows the wrapper into an ancestor's scroll area.
  *
- * @param layer     the overlay div.
+ * @param layer     the overlay div (sized `width:100%;height:100%` by the caller).
  * @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).
+ * @param cssWidth  the slide's intended CSS width (px, number) — the % denominator.
+ * @param cssHeight the slide's intended CSS height (px, number) — the % denominator.
+ * @param onHyperlinkClick called with the run's resolved {@link HyperlinkTarget}
+ *                         when a hyperlink span is clicked. Omit to leave links
+ *                         non-interactive (spans stay plain, selectable text).
  */
-declare function buildPptxTextLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], cssWidth: number, cssHeight: number): void;
+declare function buildPptxTextLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], cssWidth: number, cssHeight: number, onHyperlinkClick?: (target: HyperlinkTarget) => void): void;
 
+/**
+ * A paragraph's bullet marker. For `char`, the marker size is EITHER `sizePct`
+ * (a percentage of the run size — ECMA-376 §21.1.2.4.9 `<a:buSzPct>`) OR `sizePts`
+ * (an absolute size in points — §21.1.2.4.10 `<a:buSzPts>`), never both: they are
+ * the one `EG_TextBulletSize` xsd:choice. `sizePts` is optional (absent when no
+ * `<a:buSzPts>` was declared); when present it takes precedence over `sizePct`.
+ */
 declare type Bullet = {
     type: 'none';
 } | {
@@ -183,11 +299,13 @@ declare type Bullet = {
     char: string;
     color: string | null;
     sizePct: number | null;
+    sizePts?: number;
     fontFamily: string | null;
 } | {
     type: 'autoNum';
     numType: string;
     startAt: number | null;
+    color: string | null;
 };
 
 /**
@@ -216,14 +334,23 @@ declare interface Camera3d {
 declare interface Cell {
     col: number;
     row: number;
-    colRef: string;
     value: CellValue;
-    styleIndex: number;
+    /** Style index into the styles table. Omitted on the wire when `0` (the
+     *  common unstyled case), so read it as `styleIndex ?? 0`. */
+    styleIndex?: number;
     /** Raw `<f>` formula text (ECMA-376 §18.3.1.40), when present. The renderer
      *  uses this to recompute volatile functions (TODAY, NOW) at display time
      *  so the cached `<v>` — frozen when the file was last saved — doesn't
      *  show a stale date. */
     formula?: string;
+    /** Whether this cell displays its phonetic hint (furigana). The parser
+     *  resolves it as `cell/@ph ?? row/@ph ?? false` — the per-cell `<c ph>`
+     *  (ECMA-376 §18.3.1.4) wins when present (an explicit `ph="0"` overrides an
+     *  enabled row), otherwise the row-level `<row ph>` (§18.3.1.73) is inherited,
+     *  otherwise the schema default (false). Omitted on the wire when false, so
+     *  read as `showPhonetic ?? false`. A cell whose String Item carries `<rPh>`
+     *  runs still shows NO furigana unless the resolved value is true. */
+    showPhonetic?: boolean;
 }
 
 declare interface CellAddress {
@@ -294,6 +421,15 @@ declare type CellValue = {
     type: 'text';
     text: string;
     runs?: Run[];
+    /** ECMA-376 §18.4.6 phonetic runs (furigana) carried over from the
+     *  resolved String Item. Present for inline strings, and populated by
+     *  {@link resolveSharedStrings} for shared-string cells. Absent when the
+     *  string has no furigana. */
+    phoneticRuns?: PhoneticRun[];
+    /** ECMA-376 §18.4.3 phonetic display properties (font index / char set /
+     *  alignment) for the furigana above. Absent when the `<si>` had no
+     *  `<phoneticPr>`. */
+    phoneticPr?: PhoneticProperties;
 } | {
     type: 'number';
     number: number;
@@ -303,6 +439,14 @@ declare type CellValue = {
 } | {
     type: 'error';
     error: string;
+}
+/** Shared-string reference into `ParsedWorkbook.sharedStrings` (ECMA-376
+*  §18.4.8). Resolved to `{ type: 'text', ... }` by the workbook before the
+*  renderer (or any other consumer) sees it, so downstream code never
+*  encounters this variant. */
+| {
+    type: 'shared';
+    si: number;
 };
 
 declare interface CellXf {
@@ -415,6 +559,30 @@ declare interface ChartDataLabelOverride {
     fontSizeHpt?: number;
     /** `<a:defRPr b="1">` inside the per-idx rich text. */
     fontBold?: boolean;
+    /** Per-point callout box (`<c:dLbl><c:spPr>`, ECMA-376 §21.2.2.47/§21.2.2.197):
+     *  overrides the series-default box for this one slice. */
+    labelBox?: ChartLabelBox;
+    /**
+     * Per-point label-content flags (`<c:dLbl>` §21.2.2.47 carries the same
+     * show-flag group as the series `<c:dLbls>` §21.2.2.49: §21.2.2.189
+     * `<c:showVal>`, §21.2.2.177 `<c:showCatName>`, §21.2.2.180 `<c:showSerName>`,
+     * §21.2.2.187 `<c:showPercent>`). When present they OVERRIDE the series-level
+     * defaults for that one point (e.g. sample-14 slide-7's pie sets
+     * `showCatName=0 showPercent=1` per slice while the series default is
+     * `showCatName=1`, so each label is percent only). undefined = inherit the
+     * series default for that flag.
+     */
+    showVal?: boolean;
+    showCatName?: boolean;
+    showSerName?: boolean;
+    showPercent?: boolean;
+    /**
+     * `<c:dLbl><c:delete val="1"/>` (ECMA-376 §21.2.2.43) — the point's label is
+     * removed. Distinguishes a genuine delete from a `<c:dLbl>` that only carries
+     * style / flag overrides with no `<c:tx>` (both otherwise present as
+     * `text === ''`). true = skip the label; undefined/absent = not deleted.
+     */
+    deleted?: boolean;
 }
 
 declare interface ChartDataPointOverride {
@@ -425,6 +593,18 @@ declare interface ChartDataPointOverride {
     markerSize?: number;
     markerFill?: string;
     markerLine?: string;
+    /**
+     * `<c:dPt><c:explosion val>` (ECMA-376 §21.2.2.61) — the amount this
+     * pie/doughnut slice is moved out from the center. The schema type is
+     * `CT_UnsignedInt` (unbounded `xsd:unsignedInt`); the spec text only says
+     * "the amount the data point shall be moved from the center of the pie"
+     * and does not itself define units or a 0–100 range. We treat it as a
+     * de-facto percentage of the outer radius (0–100 typical), matching
+     * Office's UI (the Point Explosion slider caps at 100%) rather than a
+     * spec-mandated bound. undefined/absent = 0 (no explosion, flush with the
+     * ring). Only consulted by the pie/doughnut renderer.
+     */
+    explosion?: number;
 }
 
 /**
@@ -464,6 +644,74 @@ declare interface ChartErrBars {
     dash?: string;
 }
 
+/**
+ * One box-and-whisker series (chartEx `boxWhisker`, MS 2014 chartex ext). Each
+ * `<cx:series>` references its own raw sample points via `<cx:dataId>`; the
+ * parser groups them by category and threads the `<cx:layoutPr>` flags. The
+ * renderer derives the statistics.
+ */
+declare interface ChartexBoxSeries {
+    /** Series display name (`<cx:tx><cx:v>`). */
+    name: string;
+    /** Fill (hex, no '#') — theme accent cycled by series index. null = fall
+     *  back to the renderer palette. */
+    color?: string | null;
+    /** Raw sample values grouped by category (outer = category index parallel to
+     *  {@link ChartexBoxWhisker.categories}, inner = the points in that group). */
+    valuesByCategory: number[][];
+    /** `<cx:visibility meanMarker>` — draw the mean `×`. */
+    meanMarker: boolean;
+    /** `<cx:visibility meanLine>` — draw a mean connector line across categories. */
+    meanLine: boolean;
+    /** `<cx:visibility outliers>` — draw outlier points. */
+    showOutliers: boolean;
+    /** `<cx:visibility nonoutliers>` — draw the interior (non-outlier) sample
+     *  points as jittered dots on top of the box. Flag parsed; interior-dot
+     *  rendering is pending a fixture that enables it (every sample-24 series
+     *  ships `nonoutliers="0"`, so there is nothing to verify against yet). */
+    showNonoutliers: boolean;
+    /** `<cx:statistics quartileMethod>` — "exclusive" (Excel default) | "inclusive". */
+    quartileMethod: string;
+}
+
+/** A chartEx box-and-whisker chart: unique categories + one series per column. */
+declare interface ChartexBoxWhisker {
+    /** Unique category labels in first-seen order. */
+    categories: string[];
+    /** One entry per `<cx:series>`. */
+    series: ChartexBoxSeries[];
+}
+
+/** A chartEx sunburst: the flat rows the renderer folds into a ring tree. */
+declare interface ChartexSunburst {
+    rows: ChartexSunburstRow[];
+}
+
+/**
+ * One row of a chartEx `sunburst`: the branch→…→leaf label chain (empty
+ * trailing segments trimmed) and its size value.
+ */
+declare interface ChartexSunburstRow {
+    /** Label chain root→leaf. */
+    path: string[];
+    /** `<cx:numDim type="size">` value attaching to the deepest node in `path`. */
+    size: number;
+}
+
+/** Callout-box style for a pie/doughnut data label — the white (or themed)
+ *  rounded rectangle with a thin border Word draws around a `bestFit` label
+ *  placed outside its slice. From the label's `<c:spPr>` (§21.2.2.197). All
+ *  fields optional: absent → transparent / unbordered. Mirror of Rust
+ *  `ChartLabelBox`. */
+declare interface ChartLabelBox {
+    /** `<a:solidFill>` resolved hex (no `#`). Box background. */
+    fill?: string;
+    /** `<a:ln><a:solidFill>` resolved hex (no `#`). Border stroke. */
+    borderColor?: string;
+    /** `<a:ln w>` border width in EMU (12700 EMU = 1 pt). */
+    borderWidthEmu?: number;
+}
+
 /**
  * `<c:manualLayout>` block. Fractions are of the chart-space rect.
  * `xMode`/`yMode`: "edge" = absolute fraction from top-left, "factor" =
@@ -484,6 +732,14 @@ declare interface ChartModel {
     title: string | null;
     categories: string[];
     series: ChartSeries[];
+    /**
+     * §21.2.2.227 `<c:varyColors val="1"/>` on a SINGLE-series bar/column chart:
+     * color each data point (bar) from the theme/palette sequence and list one
+     * legend entry per point, matching Office. Set by the shared parser ONLY for
+     * that non-pie, single-series case (pie/doughnut already vary by point via
+     * `chartType` + `dataPointColors`); absent/false otherwise.
+     */
+    varyColors?: boolean | null;
     /** Show data labels on bars / points / slices. */
     showDataLabels: boolean;
     /** Explicit Y-axis minimum (OOXML `<c:valAx><c:min>`). */
@@ -594,6 +850,35 @@ declare interface ChartModel {
     valAxisTitleFontBold?: boolean | null;
     /** `<c:valAx><c:title>` run-prop color (hex without '#'). null = default. */
     valAxisTitleFontColor?: string | null;
+    /** `<c:catAx><c:txPr>…<a:latin typeface>` tick-label font. */
+    catAxisFontFace?: string | null;
+    /** `<c:valAx><c:txPr>…<a:latin typeface>` tick-label font. */
+    valAxisFontFace?: string | null;
+    /** `<c:catAx><c:title>…<a:latin typeface>` axis-title font. */
+    catAxisTitleFontFace?: string | null;
+    /** `<c:valAx><c:title>…<a:latin typeface>` axis-title font. */
+    valAxisTitleFontFace?: string | null;
+    /** `<c:dLbls><c:txPr>…<a:latin typeface>` data-label font. */
+    dataLabelFontFace?: string | null;
+    /** `<c:legend><c:txPr>…<a:latin typeface>` legend font. */
+    legendFontFace?: string | null;
+    /** `<c:legend><c:txPr>…<a:solidFill>` legend text color (hex without '#'). */
+    legendFontColor?: string | null;
+    /** `<c:legend><c:txPr>` legend font size (OOXML hundredths of a point). */
+    legendFontSizeHpt?: number | null;
+    /** `<c:legend><c:txPr>…defRPr@b` legend bold flag. */
+    legendFontBold?: boolean | null;
+    /**
+     * Theme font-scheme faces (`<a:fontScheme>`, ECMA-376 §20.1.4.2). Latin
+     * heading (majorFont) and body (minorFont) typefaces, used as the fallback
+     * for any chart text element whose own `<c:txPr>` supplies no `<a:latin>`.
+     * null when the theme is not threaded to the chart (then the renderer's
+     * built-in sans-serif remains, byte-stable). Axis titles / chart title use
+     * the major (heading) face; tick labels / data labels / legend use the
+     * minor (body) face — matching Office's default chart text styling.
+     */
+    themeMajorFontLatin?: string | null;
+    themeMinorFontLatin?: string | 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
@@ -668,6 +953,218 @@ declare interface ChartModel {
      * value axis (the common case). See {@link SecondaryValueAxis}.
      */
     secondaryValAxis?: SecondaryValueAxis | null;
+    /**
+     * `<c:date1904>` (ECMA-376 §21.2.2.38). When true the chart's serial
+     * date-times resolve against the 1904 date system (base 1904-01-01) instead
+     * of the default 1900 system. Threaded to the date formatters for date-axis
+     * category labels and value-axis tick labels. Omitted/false ⇒ 1900 system.
+     * Note: per §21.2.2.38 the element's `val` defaults to true when present but
+     * the attribute is omitted, so `<c:date1904/>` alone means date1904=true.
+     */
+    date1904?: boolean;
+    /**
+     * `<c:doughnutChart><c:holeSize val>` (ECMA-376 §21.2.2.60,
+     * `ST_HoleSizePercent` §21.2.3.55) — the doughnut hole diameter as a
+     * percentage 1–90 of the outer diameter. Ignored for pie (which has no
+     * hole). null/undefined = use the renderer's doughnut default when the
+     * element is absent. Note the ECMA `CT_HoleSize` schema default is 10%, but
+     * a real doughnut file always writes an explicit `<c:holeSize>` (Excel /
+     * PowerPoint emit 50–75%); the renderer falls back to 50% only for the
+     * pathological absent case.
+     */
+    holeSize?: number | null;
+    /**
+     * `<c:pieChart | doughnutChart><c:firstSliceAng val>` (ECMA-376 §21.2.2.52,
+     * `ST_FirstSliceAng` §21.2.3.15) — the angle in degrees (0–360, clockwise
+     * from the 12 o'clock position) at which the first slice begins.
+     * null/undefined = 0 (start at 12 o'clock), which matches the renderer's
+     * historical fixed −90° (canvas up) start.
+     */
+    firstSliceAngle?: number | null;
+    /**
+     * `<c:chartSpace><c:chart><c:dispBlanksAs val>` (ECMA-376 §21.2.2.42,
+     * `ST_DispBlanksAs` §21.2.3.10) — how blank (null) cells are plotted on
+     * line/area charts:
+     *   - "gap"  → leave a gap (break the line). The renderer's historical
+     *              behavior and the model default when the element is absent.
+     *   - "zero" → plot the blank as the value 0 (the point drops to the axis).
+     *   - "span" → skip the blank but connect its neighbours with a straight
+     *              line (bridge the gap).
+     * Note the XSD `@val` default is "zero" (applies when `<c:dispBlanksAs/>` is
+     * present but the attribute is omitted); when the ELEMENT is absent entirely
+     * Office falls back to "gap", which is what we model as the default. Only
+     * consulted for the line and area families. null/undefined = "gap".
+     */
+    dispBlanksAs?: string | null;
+    /**
+     * `<c:valAx><c:majorGridlines>` presence (ECMA-376 §21.2.2.100). `false` when
+     * the value axis exists but omits the element (Office suppresses value
+     * gridlines). null/undefined ⇒ the renderer's historical always-on value
+     * gridlines (byte-stable). `true` is redundant with the default but honored.
+     */
+    valAxisMajorGridlines?: boolean | null;
+    /**
+     * `<c:catAx><c:majorGridlines>` presence (§21.2.2.100). `true` turns on
+     * category-axis gridlines (Office omits them by default). null/undefined/false
+     * ⇒ no category gridlines (the historical default, byte-stable).
+     */
+    catAxisMajorGridlines?: boolean | null;
+    /**
+     * `<c:valAx><c:majorGridlines><c:spPr><a:ln><a:solidFill>` resolved gridline
+     * color (hex without `#`) — ECMA-376 §21.2.2.100. When set, the value-axis
+     * major gridlines are stroked in this color instead of the renderer's faint
+     * `#e0e0e0` default (e.g. sample-1 slide 5's `accent3` gridlines). null/absent
+     * ⇒ the historical default (byte-stable).
+     */
+    valAxisGridlineColor?: string | null;
+    /**
+     * `<c:valAx><c:majorGridlines><c:spPr><a:ln w>` gridline width in EMU. When
+     * set, the value-axis gridline stroke width is derived from this (floored so a
+     * hairline stays visible). null/absent ⇒ the renderer's 0.5 px default.
+     */
+    valAxisGridlineWidthEmu?: number | null;
+    /**
+     * `<c:catAx><c:majorGridlines><c:spPr><a:ln><a:solidFill>` resolved gridline
+     * color (hex without `#`). Only meaningful when {@link catAxisMajorGridlines}
+     * is on. null/absent ⇒ the faint default.
+     */
+    catAxisGridlineColor?: string | null;
+    /** `<c:catAx><c:majorGridlines><c:spPr><a:ln w>` gridline width in EMU. */
+    catAxisGridlineWidthEmu?: number | null;
+    /** `<c:valAx><c:minorGridlines>` presence (§21.2.2.109). Only drawn when a
+     *  minor step is resolvable (see {@link valAxisMinorUnit}). */
+    valAxisMinorGridlines?: boolean | null;
+    /**
+     * `<c:valAx><c:majorUnit val>` (§21.2.2.103) — explicit distance between major
+     * gridlines/ticks, overriding the Excel-style auto "nice" step. null/undefined
+     * ⇒ auto step (byte-stable).
+     */
+    valAxisMajorUnit?: number | null;
+    /** `<c:valAx><c:minorUnit val>` (§21.2.2.112) — explicit minor step. Drives
+     *  minor gridlines/ticks when present. null ⇒ no minor divisions. */
+    valAxisMinorUnit?: number | null;
+    /**
+     * `<c:valAx><c:scaling><c:logBase val>` (§21.2.2.98, `ST_LogBase` §21.2.3.25)
+     * — logarithmic value-axis base (>= 2). When set, values map to pixels in log
+     * space and gridlines fall on powers of the base. null/undefined ⇒ linear
+     * (byte-stable).
+     */
+    valAxisLogBase?: number | null;
+    /**
+     * `<c:valAx><c:scaling><c:orientation val>` (§21.2.2.130, `ST_Orientation`
+     * §21.2.3.30) — "minMax" (normal) | "maxMin" (reversed, so the value axis runs
+     * top→bottom max→min). null/undefined/"minMax" ⇒ normal (byte-stable).
+     */
+    valAxisOrientation?: 'minMax' | 'maxMin' | string | null;
+    /** `<c:catAx><c:scaling><c:orientation val>` — "maxMin" reverses the category
+     *  axis left↔right. null/"minMax" ⇒ normal. */
+    catAxisOrientation?: 'minMax' | 'maxMin' | string | null;
+    /**
+     * `<c:catAx><c:tickLblPos val>` (§21.2.2.207, `ST_TickLblPos` §21.2.3.47) —
+     * "nextTo" (default) | "low" | "high" | "none". "none" hides the category tick
+     * labels. null/undefined ⇒ nextTo (byte-stable).
+     */
+    catAxisTickLabelPos?: string | null;
+    /** `<c:valAx><c:tickLblPos val>` (§21.2.2.207). "none" hides value tick labels. */
+    valAxisTickLabelPos?: string | null;
+    /**
+     * `<c:catAx><c:txPr><a:bodyPr rot>` (DrawingML `ST_Angle`, 60000ths of a
+     * degree) — category tick-label rotation. e.g. -2700000 = -45°. null/undefined
+     * /0 ⇒ horizontal labels (byte-stable).
+     */
+    catAxisLabelRotation?: number | null;
+    /**
+     * `<c:stockChart><c:hiLowLines>` presence (ECMA-376 §21.2.2.60). When true
+     * the stock renderer draws a vertical line spanning each category's low↔high
+     * value. Only set for `chartType === "stock"`; null/undefined on every other
+     * chart type (byte-stable).
+     */
+    stockHiLowLines?: boolean | null;
+    /**
+     * `<c:hiLowLines><c:spPr><a:ln><a:solidFill>` resolved color (hex, no `#`).
+     * null = the renderer's default gray hi-lo line.
+     */
+    stockHiLowLineColor?: string | null;
+    /**
+     * `<c:stockChart><c:upDownBars>` presence (ECMA-376 §21.2.2.227). Parsed so a
+     * stock file carrying open-close up/down bars is recognized; the renderer does
+     * NOT yet draw them (tracked follow-up). null/undefined when absent.
+     */
+    stockUpDownBars?: boolean | null;
+    /**
+     * Structured box-and-whisker data (`chartType === 'boxWhisker'`). Present
+     * ONLY for boxWhisker charts; null/absent otherwise so the flat
+     * `categories`/`series` model the other chartEx renderers consume is
+     * untouched. The renderer computes quartiles / mean / whiskers / outliers.
+     */
+    chartexBox?: ChartexBoxWhisker | null;
+    /**
+     * Structured sunburst hierarchy (`chartType === 'sunburst'`). Present ONLY
+     * for sunburst charts; null/absent otherwise.
+     */
+    chartexSunburst?: ChartexSunburst | null;
+    /**
+     * Theme accent palette (`accent1..6`, hex without '#') for chartEx charts
+     * that color by branch/series index (boxWhisker series, sunburst branches).
+     * null/absent when the resolver supplies no default palette (pptx); the
+     * renderer then falls back to its own `CHART_PALETTE`.
+     */
+    chartexAccents?: string[] | null;
+}
+
+/** ECMA-376 §21.2 — a DrawingML chart embedded in the run flow via
+ *  `<w:drawing><wp:inline|wp:anchor>…<a:graphicData uri=".../chart"><c:chart r:id>`.
+ *  Mirrors the Rust `ChartRun`. `chart` is the shared {@link ChartModel} the
+ *  core `renderChart` consumes (identical to what pptx/xlsx pass), so a docx
+ *  chart draws at the same quality through the same code path. `widthPt`/
+ *  `heightPt` are the `<wp:extent>` natural size. An inline chart flows as an
+ *  inline box of that size; an anchored chart (§20.4.2.3) is painted via
+ *  `registerAnchorFloats` when it wraps text, or by `renderAnchorImages` for
+ *  wrapNone/no-wrap anchors — all paths use `renderChart`. */
+declare interface ChartRun {
+    chart: ChartModel;
+    widthPt: number;
+    heightPt: number;
+    /** true = `<wp:anchor>` (absolute page position, drawn by the anchor path);
+     *  false = `<wp:inline>` (flows with text). */
+    anchor: boolean;
+    anchorXPt?: number;
+    anchorYPt?: number;
+    anchorXFromMargin?: boolean;
+    anchorYFromPara?: boolean;
+    /**
+     * Wrap mode for anchored charts (ECMA-376 §20.4.2.16/.17):
+     *   "square" | "topAndBottom" | "none" | "tight" | "through"
+     * Inline charts and undetermined cases leave this undefined. The renderer
+     * treats "tight" and "through" as "square", matching anchored images.
+     */
+    wrapMode?: string;
+    /** Padding top (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distTop?: number;
+    /** Padding bottom (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distBottom?: number;
+    /** Padding left (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distLeft?: number;
+    /** Padding right (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distRight?: number;
+    /** wrapText attribute: "bothSides" | "left" | "right" | "largest". */
+    wrapSide?: string;
+    /**
+     * ECMA-376 §20.4.2.3 `wp:anchor/@allowOverlap`. The parser omits this
+     * field when true, so renderers must read it as `allowOverlap ?? true`.
+     */
+    allowOverlap?: boolean;
+    /** ECMA-376 §20.4.3.1 wp:align horizontal: "left" | "center" | "right" |
+     *  "inside" | "outside". */
+    anchorXAlign?: string | null;
+    /** Vertical equivalent of anchorXAlign: "top" | "center" | "bottom". */
+    anchorYAlign?: string | null;
+    /**
+     * ECMA-376 §20.4.3.2 `<wp:positionH/@relativeFrom>` / §20.4.3.5
+     * `<wp:positionV/@relativeFrom>` — the raw anchor placement containers.
+     */
+    anchorXRelativeFrom?: string | null;
+    anchorYRelativeFrom?: string | null;
 }
 
 declare interface ChartSeries {
@@ -777,6 +1274,31 @@ declare interface ChartSeries {
      * series.
      */
     bubbleSizes?: (number | null)[] | null;
+    /**
+     * `<c:ser><c:smooth val>` (ECMA-376 §21.2.2.194) — line/area series flag
+     * requesting a smoothed (spline) curve through the points instead of straight
+     * segments. Only consulted for the line and area families (scatter carries its
+     * smoothing in `ChartModel.scatterStyle`). null/undefined/false = straight
+     * polyline (the default; byte-stable for series that never set it).
+     */
+    smooth?: boolean | null;
+    /**
+     * `<c:ser><c:trendline>` per-series trendlines (ECMA-376 §21.2.2.211,
+     * `CT_Trendline`). A series can carry several (e.g. a linear fit + a moving
+     * average). null/undefined/empty = no trendline (the default; byte-stable for
+     * series that never declare one).
+     */
+    trendLines?: ChartTrendline[] | null;
+    /**
+     * `<c:ser><c:spPr><a:ln><a:noFill/>` (ECMA-376 §21.2.2.198 CT_ShapeProperties
+     * → DrawingML §20.1.2.2.24 CT_LineProperties). true when the series connecting
+     * line is explicitly turned OFF. For a scatter/line series this OVERRIDES the
+     * chart-group `<c:scatterStyle>` (§21.2.2.42) / line default — Excel and
+     * PowerPoint draw markers only (no connecting line) even when the group style
+     * is `lineMarker`. null/undefined = no explicit line-off, so the group default
+     * governs (byte-stable for series that carry a paintable line).
+     */
+    lineHidden?: boolean | null;
 }
 
 declare interface ChartSeriesDataLabels {
@@ -791,6 +1313,51 @@ declare interface ChartSeriesDataLabels {
     fontBold?: boolean;
     /** Series-level font size for data labels (OOXML hundredths of a point). */
     fontSizeHpt?: number;
+    /** Series-default callout box (`<c:dLbls><c:spPr>`, ECMA-376 §21.2.2.49/
+     *  §21.2.2.197). When present the pie/doughnut renderer draws Word's boxed
+     *  callout layout (box + optional leader line) instead of plain text. */
+    labelBox?: ChartLabelBox;
+    /** `<c:dLbls><c:showLeaderLines val>` (§21.2.2.183) — draw leader lines from
+     *  a pulled-away label back to its slice. Default false. */
+    showLeaderLines?: boolean;
+    /** `<c:leaderLines><c:spPr><a:ln><a:solidFill>` (§21.2.2.92) resolved hex
+     *  (no `#`). undefined → renderer uses a neutral grey. */
+    leaderLineColor?: string;
+    /** `<c:leaderLines><c:spPr><a:ln w>` leader-line width in EMU. */
+    leaderLineWidthEmu?: number;
+}
+
+/**
+ * `<c:ser><c:trendline>` (ECMA-376 §21.2.2.211). A regression/smoothing curve
+ * fitted to the series' data points.
+ */
+declare interface ChartTrendline {
+    /**
+     * `<c:trendlineType val>` (§21.2.2.213, `ST_TrendlineType` §21.2.3.50):
+     * "linear" | "exp" | "log" | "power" | "poly" | "movingAvg". The renderer
+     * currently draws "linear" (least squares) and "movingAvg"; other types parse
+     * but are not yet plotted (tracked as a follow-up).
+     */
+    trendlineType: string;
+    /** `<c:order val>` — polynomial order (`poly`, default 2). */
+    order?: number | null;
+    /** `<c:period val>` — moving-average window (`movingAvg`, default 2). */
+    period?: number | null;
+    /** `<c:forward val>` — units to extend the line past the last point. */
+    forward?: number | null;
+    /** `<c:backward val>` — units to extend the line before the first point. */
+    backward?: number | null;
+    /** `<c:intercept val>` — forced y-intercept (linear/exp). null = free fit. */
+    intercept?: number | null;
+    /** `<c:dispRSqr val="1">` — show the R² value (label; not yet rendered). */
+    dispRSqr?: boolean | null;
+    /** `<c:dispEq val="1">` — show the fit equation (label; not yet rendered). */
+    dispEq?: boolean | null;
+    /** `<c:spPr><a:ln><a:solidFill>` trendline color (hex without '#'). null =
+     *  inherit the series color. */
+    lineColor?: string | null;
+    /** `<c:spPr><a:ln w>` trendline width in EMU. */
+    lineWidthEmu?: number | null;
 }
 
 /**
@@ -798,7 +1365,7 @@ declare interface ChartSeriesDataLabels {
  * grouping (`Pct` = percent-stacked) so renderers do not need to inspect
  * separate `barDir`/`grouping` fields.
  */
-declare type ChartType = 'line' | 'stackedLine' | 'stackedLinePct' | 'clusteredBar' | 'clusteredBarH' | 'stackedBar' | 'stackedBarH' | 'stackedBarPct' | 'stackedBarHPct' | 'area' | 'stackedArea' | 'stackedAreaPct' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'radar' | 'waterfall' | string;
+declare type ChartType = 'line' | 'stackedLine' | 'stackedLinePct' | 'clusteredBar' | 'clusteredBarH' | 'stackedBar' | 'stackedBarH' | 'stackedBarPct' | 'stackedBarHPct' | 'area' | 'stackedArea' | 'stackedAreaPct' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'radar' | 'waterfall' | 'stock' | 'boxWhisker' | 'sunburst' | string;
 
 /** ECMA-376 §17.6.3 `<w:col>` — one column's width and trailing space (pt). */
 declare interface ColSpec {
@@ -899,7 +1466,7 @@ declare interface DocParagraph {
      * both, distribute. Other values (kashida variants, numTab, thaiDistribute)
      * are treated as start-aligned.
      */
-    alignment: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | 'both' | 'distribute' | string;
+    alignment: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | 'both' | 'distribute' | 'lowKashida' | 'mediumKashida' | 'highKashida' | 'thaiDistribute' | string;
     indentLeft: number;
     indentRight: number;
     indentFirst: number;
@@ -909,16 +1476,33 @@ declare interface DocParagraph {
     numbering: NumberingInfo | null;
     tabStops: TabStop_2[];
     runs: DocRun[];
+    /**
+     * ECMA-376 §17.13.6.2 `<w:bookmarkStart w:name>` — names of the bookmarks that
+     * start within (or at the head of) this paragraph, in document order. A
+     * `<w:hyperlink w:anchor="X">` internal link (§17.16.23) targets the paragraph
+     * whose `bookmarks` contains `"X"`; {@link buildBookmarkPageMap} turns these
+     * into a `bookmarkName → pageIndex` map after pagination. Absent (`undefined`)
+     * for the common paragraph that anchors nothing.
+     */
+    bookmarks?: string[];
     /** Paragraph background hex color (w:shd fill) */
     shading?: string | null;
     /** Force a page break before this paragraph (w:pageBreakBefore) */
     pageBreakBefore?: boolean;
-    /** Suppress spacing between adjacent same-style paragraphs (w:contextualSpacing) */
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — between adjacent SAME-style
+     *  paragraphs, a toggling paragraph drops its OWN contribution to the
+     *  collapsed inter-paragraph gap (per-side, Word-adjudicated — issue #1015;
+     *  see the renderer's `contextualSpacingAdjust`). */
     contextualSpacing?: boolean;
     /** Keep paragraph on same page as the next paragraph (w:keepNext) */
     keepNext?: boolean;
     /** Keep all lines of this paragraph on the same page (w:keepLines) */
     keepLines?: boolean;
+    /** ECMA-376 §17.3.1.29 + §17.3.2.41 — the paragraph MARK's resolved `w:vanish`
+     *  (hidden text). An inkless paragraph whose mark is vanished collapses to zero
+     *  height in the normal/print view (hidden-text off), the same way the parser
+     *  strips hidden runs; the paginator drops it whole. Absent = mark is visible. */
+    markVanish?: boolean;
     /** Widow/orphan control (w:widowControl). ECMA-376 default is true. */
     widowControl?: boolean;
     /** Paragraph borders (w:pBdr) */
@@ -930,6 +1514,17 @@ declare interface DocParagraph {
     /** Default font family resolved from the style chain. Used to size empty
      *  paragraphs (no runs) with the intended font's line metrics. */
     defaultFontFamily?: string | null;
+    /** Default East Asian font family resolved from the style chain. Empty /
+     *  anchor-only paragraph marks in East Asian documents use this axis for line
+     *  metrics instead of the ASCII fallback. */
+    defaultFontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.3.1.29 — the paragraph MARK run's resolved `w:color` (direct
+     *  pPr/rPr → pStyle chain → docDefaults; hex 6 without `#`, lowercased; an
+     *  explicit `auto` surfaces as absent, §17.3.2.6). Word formats a numbering
+     *  marker with the level rPr (§17.9.24) layered over the mark's run
+     *  properties, so the renderer uses this as the marker-color fallback when
+     *  {@link NumberingInfo.color} is absent. */
+    paragraphMarkColor?: string | null;
     /**
      * ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left paragraph. `true` = RTL,
      * `false` = explicitly LTR, absent = unspecified (inherit). The renderer uses
@@ -970,6 +1565,8 @@ declare type DocRun = {
 } & DocxTextRun | {
     type: 'image';
 } & ImageRun | {
+    type: 'chart';
+} & ChartRun | {
     type: 'break';
     breakType: 'line' | 'page' | 'column';
 } | {
@@ -982,7 +1579,9 @@ declare type DocRun = {
     display: boolean;
     fontSize: number;
     jc?: string;
-};
+} | {
+    type: 'ptab';
+} & PTabRun;
 
 declare interface DocSettings {
     /** §17.15.1.58 `w:kinsoku` — East-Asian line-breaking toggle. `undefined`
@@ -1003,6 +1602,17 @@ declare interface DocSettings {
      *  tab stops generated after all custom stops. `undefined` ⇒ the renderer
      *  uses the spec default of 720 twips (36pt). */
     defaultTabStop?: number;
+    /** §17.15.1.18 `w:characterSpacingControl@w:val` — East Asian punctuation /
+     *  character-spacing control. */
+    characterSpacingControl?: string;
+    /** §17.15.3.1 `w:compat/w:useFELayout` — Far East layout compatibility. */
+    useFeLayout?: boolean;
+    /** §17.15.3.1 `w:compat/w:balanceSingleByteDoubleByteWidth` — balance
+     *  single-byte and double-byte widths for East Asian layout. */
+    balanceSingleByteDoubleByteWidth?: boolean;
+    /** §17.15.3.1 `w:compat/w:adjustLineHeightInTable` — apply the section
+     *  document-grid line pitch to text in table cells. */
+    adjustLineHeightInTable?: boolean;
 }
 
 declare interface DocTable {
@@ -1015,6 +1625,14 @@ declare interface DocTable {
     cellMarginRight: number;
     /** table horizontal alignment on the page: 'left' | 'center' | 'right'. */
     jc: string;
+    /** ECMA-376 §17.4.50 `<w:tblInd>` — indentation added before the table's
+     *  LEADING edge (left in an LTR table, right in an RTL/`bidiVisual` table), in
+     *  pt. SIGNED: a negative value pulls the table outward past the leading margin
+     *  toward the page edge (Word writes this for a header banner that must reach
+     *  the physical page edge). `type="dxa"` only; `pct`/`auto` are dropped by the
+     *  parser per §17.4.50. Absent ⇒ no direct indent. The renderer applies it only
+     *  when the resolved `jc` is left/leading (§17.4.50). */
+    tblInd?: number;
     /** ECMA-376 §17.4.52 `<w:tblLayout w:type>` — 'fixed' | 'autofit'. Absent
      *  (undefined) ⇒ spec default 'autofit'. Both paths size columns from the
      *  tblGrid (§17.4.48) scaled to fit: 'fixed' uses the grid verbatim; 'autofit'
@@ -1076,25 +1694,44 @@ declare interface DocTableRow {
      *  lower bound; "exact" = fixed clip. */
     rowHeightRule: 'auto' | 'atLeast' | 'exact' | string;
     isHeader: boolean;
+    /** ECMA-376 §17.4.6 `<w:cantSplit>` — when true, the row must not be split
+     *  across page boundaries. Omitted/false rows may split at page boundaries. */
+    cantSplit?: boolean;
 }
 
 export declare namespace docx {
     export {
         DocxDocument,
         LoadOptions_4 as LoadOptions,
+        RenderPageToBitmapOptions,
         WireRenderPageOptions,
         DocxViewer,
         DocxViewerOptions,
         DocxScrollViewer,
         DocxScrollViewerOptions,
         buildDocxTextLayer,
+        buildDocxHighlightLayer,
+        DocxHighlightMatch,
+        DocxHighlightColors,
+        DocxMatchLocation,
+        FindMatch,
+        FindMatchesOptions,
         autoResize,
         AutoResizeOptions,
+        HyperlinkTarget,
+        openExternalHyperlink,
+        OoxmlError,
+        OoxmlErrorCode,
         noteText,
         DocxDocumentModel,
         DocSettings,
+        EmbeddedFontRef,
         SectionProps,
         SectionGeom,
+        PageNumType,
+        PageBorders,
+        PageBorderEdge,
+        LineNumbering,
         ColumnsSpec,
         ColSpec,
         HeadersFooters,
@@ -1103,10 +1740,13 @@ export declare namespace docx {
         BodyElement,
         DocParagraph,
         DocRun,
+        PTabRun,
         DocxTextRun,
         FieldRun,
         ImageRun,
+        ChartRun,
         ShapeRun,
+        TextPath,
         ShapeText_2 as ShapeText,
         ShapeTextRun_2 as ShapeTextRun,
         RubyAnnotation,
@@ -1141,10 +1781,27 @@ declare class DocxDocument {
     private _document;
     private _meta;
     private _pages;
+    /** Lazily-built `bookmarkName → 0-based page index` map for internal hyperlink
+     *  anchors (IX-nav). Built on first {@link getBookmarkPage} from the paginated
+     *  pages (main) or the worker meta's `bookmarkPages` (worker). Nulled by
+     *  {@link destroy} so a reused reference never serves a stale document. */
+    private _bookmarkPages;
     private _mode;
     private _worker;
     private _bridge;
     private _imageCache;
+    /** Embedded `FontFace` objects this document registered into `document.fonts`
+     *  (main mode only — in worker mode the worker owns them and terminates with
+     *  its own FontFaceSet). Released in {@link destroy} so they do not leak into
+     *  the shared FontFaceSet for the lifetime of the SPA (deduped + refcounted in
+     *  core, so a font shared with another open document survives until both go). */
+    private _embeddedFontFaces;
+    /** Google-Fonts `FontFace` objects this document preloaded into `document.fonts`
+     *  (main mode only — in worker mode the worker owns them and terminates with its
+     *  own FontFaceSet). Released in {@link destroy} so they do not leak into the
+     *  shared FontFaceSet for the lifetime of the SPA (deduped + refcounted in core,
+     *  so a web font shared with another open document survives until both go). */
+    private _googleFontFaces;
     /** One stable closure per instance: core's path-keyed SVG cache namespaces on
      *  this identity, so two open documents never swap a shared zip path (e.g.
      *  word/media/image1.svg). Reusing one reference also lets the SVG cache hit
@@ -1163,6 +1820,32 @@ declare class DocxDocument {
      * are decoded lazily rather than inlined as base64 at parse time.
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
+    /**
+     * Extract raw bytes for an embedded font part by zip path (e.g.
+     * `word/fonts/font1.odttf`). Routes through the SAME persistent-worker
+     * `extractImage` message as {@link getImage} — `DocxArchive.extract_image`
+     * reads ANY zip entry, not just media — returning the raw (still obfuscated)
+     * `.odttf` bytes rather than a Blob. Consumed by {@link loadEmbeddedFonts},
+     * which de-obfuscates (ECMA-376 §17.8.1) and registers each as a FontFace.
+     */
+    getFontBytes(partPath: string): Promise<Uint8Array>;
+    /**
+     * Project the document to GitHub-flavoured markdown: headings (from
+     * `<w:outlineLvl>`), bullet / numbered lists, tables (with vMerge
+     * continuation), and rich-text formatting (bold / italic / strikethrough /
+     * hyperlink), with footnotes / endnotes / comments collated at the end.
+     * Positioning, section properties, fonts, and drawing shapes are discarded —
+     * the projection is meant for AI ingestion and full-text search, not layout.
+     *
+     * Runs entirely in the worker off the archive opened at {@link load} (no
+     * re-copy of the file, no re-parse of the model on the main thread), so it
+     * works in BOTH `mode: 'main'` and `mode: 'worker'`.
+     *
+     * @example
+     * const doc = await DocxDocument.load(buffer);
+     * const md = await doc.toMarkdown();
+     */
+    toMarkdown(): Promise<string>;
     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
@@ -1198,6 +1881,23 @@ declare class DocxDocument {
      */
     get endnotes(): DocNote[];
     private _getPages;
+    /** Lazily build (and cache) the `bookmarkName → page index` map from either
+     *  the worker meta (worker mode) or the paginated pages (main mode). */
+    private _getBookmarkPages;
+    /**
+     * ECMA-376 §17.13.6.2 / §17.16.23 — resolve a bookmark name (a
+     * `<w:hyperlink w:anchor>` internal-link target) to the 0-based index of the
+     * page its `<w:bookmarkStart w:name>` destination falls on, or `undefined`
+     * when the document has no bookmark of that name. When a bookmark's paragraph
+     * spans a page break, the page where it *begins* is returned.
+     *
+     * This is the map an internal-hyperlink click resolves against: a viewer's
+     * `onHyperlinkClick` default (or an integrator) turns the anchor into a page
+     * and calls {@link DocxViewer.goToPage} (or scrolls the scroll viewer to it).
+     * Works in BOTH `main` and `worker` mode (the map rides along in the worker
+     * meta, built from the same paginated pages as `pageSizes`).
+     */
+    getBookmarkPage(bookmarkName: string): number | undefined;
     /**
      * 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).
@@ -1221,8 +1921,23 @@ declare class DocxDocument {
      * The returned ImageBitmap is owned by the caller: pass it to
      * `transferFromImageBitmap` (which consumes it) or call `bitmap.close()`
      * when done, or its backing memory is held until GC.
+     *
+     * IX6 — an optional `onTextRun` in `opts` receives the page's text-run
+     * geometry (the same stream `renderPage` emits in main mode), so a caller can
+     * build the selection / find overlay from a worker-rendered page on the SAME
+     * code path as main mode. In worker mode the runs ride back beside the bitmap
+     * (one round-trip, no second render).
      */
-    renderPageToBitmap(pageIndex: number, opts?: WireRenderPageOptions): Promise<ImageBitmap>;
+    renderPageToBitmap(pageIndex: number, opts?: RenderPageToBitmapOptions): Promise<ImageBitmap>;
+    /**
+     * IX6 — collect a page's text-run geometry (`DocxTextRunInfo[]`) without
+     * painting a visible canvas. Works in BOTH modes: worker mode renders the page
+     * off-thread and ships only the runs (no bitmap transfer); main mode renders
+     * to a throwaway offscreen canvas. Used by the find controller to scan every
+     * page for matches. The geometry is identical to a `renderPage` of the same
+     * page at the same width/dpr.
+     */
+    collectPageRuns(pageIndex: number, opts?: WireRenderPageOptions): Promise<DocxTextRunInfo[]>;
 }
 
 declare interface DocxDocumentModel {
@@ -1243,6 +1958,21 @@ declare interface DocxDocumentModel {
      * entry is absent or classified as "auto".
      */
     fontFamilyClasses?: Record<string, string>;
+    /**
+     * ECMA-376 §17.8.3.29 — per-font pitch from `word/fontTable.xml`
+     * (`<w:pitch>`, ST_Pitch §17.18.66): font name → "fixed" | "variable" |
+     * "default". Present only for fonts that declare `<w:pitch>`. The renderer
+     * pairs this with {@link fontFamilyClasses}: a `family="modern"` face is
+     * treated as monospace ONLY when its pitch is "fixed"; "variable" /
+     * "default" / absent fall through to name-pattern / CJK-sans classification
+     * (§17.8.3.10 `family` classifies the design, not the pitch — issue #855).
+     */
+    fontFamilyPitches?: Record<string, string>;
+    /** ECMA-376 §17.8.3.3-.6 — embedded fonts from `word/fontTable.xml`, resolved
+     *  to their `.odttf` part paths + fontKey. The viewer de-obfuscates (§17.8.1)
+     *  and registers each as a FontFace before pagination so text measures/draws
+     *  with the authored typeface. */
+    embeddedFonts?: EmbeddedFontRef[];
     /** ECMA-376 §17.13.5 — flat list of `<w:ins>` / `<w:del>` events in the
      *  body. Each entry carries author / date / text. The renderer marks
      *  runs inline via {@link DocxTextRun.revision}; this array is primarily for
@@ -1262,6 +1992,31 @@ declare interface DocxDocumentModel {
      *  (kinsoku) configuration. Absent when settings.xml has no relevant
      *  elements (the renderer then uses spec defaults: kinsoku ON). */
     settings?: DocSettings;
+    /** RB7 partial degradation: set when `word/document.xml` (the body part) could
+     *  not be read or parsed. The document still "opens" — `body` is empty and this
+     *  part-tagged error (e.g. `"word/document.xml: <detail>"`) is carried — so the
+     *  viewer shows a visible placeholder page instead of throwing. Absent
+     *  (`undefined`) for every healthy document. */
+    parseError?: string;
+}
+
+declare interface DocxHighlightColors {
+    /** Fill for non-active matches. */
+    match?: string;
+    /** Fill for the active match. */
+    active?: string;
+}
+
+/** One page's highlight input: the run-slices a match covers, and whether that
+ *  match is the active one (emphasis colour). */
+declare interface DocxHighlightMatch {
+    slices: MatchRunSlice[];
+    active: boolean;
+}
+
+/** Where a docx match lives: its 0-based page index. */
+declare interface DocxMatchLocation {
+    page: number;
 }
 
 /** ECMA-376 §17.3.2.4 `<w:bdr>` — a run-level border drawn as a box around the
@@ -1277,7 +2032,7 @@ declare interface DocxRunBorder {
     space: number;
 }
 
-declare class DocxScrollViewer {
+declare class DocxScrollViewer implements ZoomableViewer {
     private _doc;
     private readonly _injected;
     private readonly _opts;
@@ -1298,6 +2053,18 @@ declare class DocxScrollViewer {
      *  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;
+    /**
+     * IX9 F1 — a `setScale` factor requested BEFORE the base fit is established
+     * (pre-load, or a zero-width container), already clamped to
+     * `[zoomMin, zoomMax]`, or `null` when none is pending. The single-canvas
+     * viewers latch a pre-load `setScale` and honour it on the first render; the
+     * scroll viewers used to silently DROP it — the family-unified semantics are
+     * "latch and apply once the layout establishes". `relayout()` applies (and
+     * clears) this right after establishing the base, firing `onScaleChange` at
+     * application time; `getScale()` reports it while pending so the caller sees
+     * the same value a single-canvas viewer would show.
+     */
+    private _pendingScale;
     /** Live slots keyed by page index. */
     private readonly _slots;
     /** Recyclable detached slots (canvas + textLayer reused across pages). */
@@ -1311,6 +2078,27 @@ declare class DocxScrollViewer {
      *  reporting an error so a rejection that lands after teardown is swallowed
      *  rather than surfaced to a `onError` on a dead viewer. */
     private _destroyed;
+    /** Throwaway 2D context reused to measure text for the §17.3.2.10 縦中横 overlay
+     *  clamp (#836). Lazily created; `null` when canvas metrics are unavailable
+     *  (headless), in which case the overlay degrades to the un-clamped span. */
+    private _measureCtx;
+    /**
+     * Concurrent-load latch (generation token). Every self-loading `load()`
+     * increments this and captures the value; after its engine finishes loading it
+     * re-checks the live value and BAILS (destroying its own just-loaded engine) if
+     * a newer `load()` has since started. Without it, two overlapping
+     * `load(A)`/`load(B)` calls race the WASM parse / worker init, and whichever
+     * RESOLVES last wins the swap — even the stale `load(A)` resolving after
+     * `load(B)`; the loser's freshly created engine (never installed, or installed
+     * then overwritten) then leaks its worker + pinned WASM allocation. The latch
+     * composes with SC20: the check runs AFTER the new engine loads but BEFORE the
+     * field assignment, `previous?.destroy()`, and the recycle/relayout post-load
+     * work, so a superseded load never touches `this._doc` nor frees the current
+     * (newer) engine. Only the self-loading path uses it — the injected path throws
+     * up-front and never reaches here. `destroy()` also bumps it so a load in flight
+     * at teardown is treated as superseded and its engine cleaned up.
+     */
+    private _loadGen;
     /** 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
@@ -1341,11 +2129,14 @@ declare class DocxScrollViewer {
      *  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;
+    /** Gesture-only pointer anchor for the NEXT `setScale`, in scrollHost-viewport
+     *  px (`{ x, y }` from the wheel event, relative to the scroll host's top-left).
+     *  Set by the Ctrl/⌘+wheel handler right before it calls `setScale` so the zoom
+     *  pivots on the cursor ("zoom toward the pointer") in BOTH axes; consumed and
+     *  cleared by `setScale`. `null` for every non-gesture source (the public
+     *  `setScale`, the +/- steppers, `fitWidth`/`fitPage`, the resize re-fit), which
+     *  keep the historical viewport-TOP re-anchor so their behaviour is unchanged. */
+    private _pendingZoomAnchor;
     /** Observes the container so a width change re-fits the base scale. Disconnected
      *  in `destroy()`. */
     private _resizeObserver;
@@ -1414,6 +2205,12 @@ declare class DocxScrollViewer {
      *  `_positionSlot` (the flush-left floor), and by `_syncSpacer` (the spacer
      *  width). Resolved here (not stored) to mirror `_gap()`/`_pad()`. */
     private _padH;
+    /** Index of the page whose slot spans content-offset `y` (largest `i` with
+     *  `offsets[i] <= y`), for the pointer-anchored zoom re-anchor. Mirrors the
+     *  `topIndex` search `computeVisibleRange` runs for the scrollTop, but for an
+     *  ARBITRARY content-y (the pointer, not the viewport top). Clamped into
+     *  `[0, n-1]`; a `y` below the first page (inside the leading pad) yields 0. */
+    private _pageIndexAtOffset;
     private _range;
     private _syncSpacer;
     /** Horizontal scroll extent: the widest page (docx pages can differ in width)
@@ -1463,10 +2260,34 @@ declare class DocxScrollViewer {
      * 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;
+    /**
+     * IX1/IX-nav — the click handler passed to the text-layer overlay. When the
+     * caller supplied `onHyperlinkClick`, it fully owns the behaviour (the default
+     * is suppressed). Otherwise the built-in default is: an external link opens in
+     * a new tab through core `openExternalHyperlink` (URL sanitised against the
+     * safe scheme allowlist, `noopener,noreferrer`); an internal `<w:anchor>` link
+     * resolves its bookmark name to its destination page via
+     * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and scrolls there
+     * with {@link scrollToPage}. An anchor naming no known bookmark is a safe no-op
+     * rather than a scroll to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
+     */
+    private _hyperlinkHandler;
+    /** A width-measurer primed with a run's `font` — used ONLY to clamp a §17.3.2.10
+     *  縦中横 selection span to its drawn one-em cell (#836). Mirrors DocxViewer's
+     *  `_measureForFont`. Returns a length-based fallback when canvas metrics are
+     *  unavailable so the caller still gets a callable (the overlay then sees scale
+     *  1 and leaves the span un-clamped). */
+    private _measureForFont;
+    /** A canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path,
+     *  falling back to the backing-store size when unset; tolerates the `px` suffix. */
+    private _canvasCssPx;
     /** 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;
@@ -1496,7 +2317,10 @@ declare class DocxScrollViewer {
      * `[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.
+     * fixed. A no-op when the clamped scale is unchanged. Called BEFORE the doc is
+     * loaded / the base fit is established, the clamped factor is LATCHED (IX9 F1,
+     * family-unified with the single-canvas viewers) and applied by `relayout()`
+     * once the layout establishes — `onScaleChange` fires then.
      *
      * 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
@@ -1517,6 +2341,38 @@ declare class DocxScrollViewer {
      * can no longer return below the floor to the original base fit through this API.
      */
     setScale(scale: number): void;
+    /** IX9 {@link ZoomableViewer} — the current zoom factor, where `1` = 100% (a
+     *  page at its natural pt→px width). This is the viewer's absolute `_scale`
+     *  (`widthPt × PT_TO_PX × _scale` is the drawn width), so it reads `1` at true
+     *  100% and, after the initial fit-to-width, the base fit factor. Before the
+     *  fit is established it reports a latched pre-load `setScale` (IX9 F1) if one
+     *  is pending — matching what a single-canvas viewer would show — else `1`. */
+    getScale(): number;
+    /** IX9 {@link ZoomableViewer} — step up to the next rung of the shared zoom
+     *  ladder above the current factor (clamped to `zoomMax` by {@link setScale}). */
+    zoomIn(): void;
+    /** IX9 {@link ZoomableViewer} — step down to the next lower ladder rung. */
+    zoomOut(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit a page's WIDTH to the container (the classic
+     * continuous-scroll "fit width"). Sets the scale to the width-fit base for the
+     * current container, then re-anchors + re-renders via {@link setScale}. Defers
+     * (no-op) while the container is unlaid-out. Note the `zoomMin`/`zoomMax` clamp
+     * still applies, so a fit below `zoomMin` pins to `zoomMin`.
+     */
+    fitWidth(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit a WHOLE page (width and height) inside the
+     * container so one page is visible without scrolling; takes the tighter of the
+     * width/height fit. Uses the FIRST page's size (the continuous viewer's fit
+     * reference, matching the base-fit convention). Defers while unlaid-out.
+     */
+    fitPage(): void;
+    /** Shared fit for {@link fitWidth}/{@link fitPage}: the width-fit factor is the
+     *  established base (`_baseScale`); the page-fit additionally bounds by the
+     *  container height against the first page's height. Applies via {@link setScale}
+     *  so the flicker-free re-anchor / settle path and `onScaleChange` all run. */
+    private _fit;
     /**
      * CSS preview of the visible window at the current `_scale` (design §7
      * mechanism 1), WITHOUT re-rendering. Slots leaving the window recycle normally;
@@ -1543,12 +2399,11 @@ declare class DocxScrollViewer {
     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. */
+     *  swap (main) / same-canvas transfer (worker). Both modes rebuild the text
+     *  overlay from the fresh render's run geometry (IX6 — worker mode collects the
+     *  runs off-thread via `_renderSlotBitmap`) and clear the preview transform.
+     *  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).
@@ -1624,6 +2479,8 @@ declare class DocxScrollViewer {
     /* Excluded from this release type: baseScaleForTest */
     /* Excluded from this release type: renderEpochForTest */
     /* Excluded from this release type: resizeForTest */
+    /* Excluded from this release type: contentAtViewportYForTest */
+    /* Excluded from this release type: viewportYOfForTest */
     /**
      * 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
@@ -1670,9 +2527,10 @@ declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTex
     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). */
+    /** Per-page transparent text-selection overlay. IX6 — works in BOTH render
+     *  modes: in worker mode the per-run geometry is collected off-thread and
+     *  shipped back beside the page bitmap, so the overlay is populated identically
+     *  to main mode (no more empty overlay / one-time warning). */
     enableTextSelection?: boolean;
     /** Minimum zoom scale (px-per-pt multiplier floor). Default 0.1. */
     zoomMin?: number;
@@ -1715,6 +2573,24 @@ declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTex
      *  `computeVisibleRange` (the first page intersecting the viewport top,
      *  EXCLUDING overscan). */
     onVisiblePageChange?: (topIndex: number, total: number) => void;
+    /** IX9 — fires whenever the zoom factor actually changes (`1` = 100% = a page
+     *  at its natural pt→px size): from {@link DocxScrollViewer.setScale},
+     *  `zoomIn`/`zoomOut`, `fitWidth`/`fitPage`, a Ctrl/⌘+wheel gesture, or a
+     *  container-resize re-fit. Named `onScaleChange` to match the single-canvas
+     *  viewers so all five share one notification shape. */
+    onScaleChange?: (scale: number) => void;
+    /** IX1 (design decision — NOT user-confirmed, integrator may veto). Called when
+     *  a hyperlink run is clicked. When omitted, the default is: external → open in a
+     *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
+     *  internal → jump to the page whose text contains the bookmark (best-effort). */
+    onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  but are inert, like plain text. */
+    enableHyperlinks?: boolean;
     /** 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
@@ -1729,6 +2605,15 @@ declare interface DocxTextRun {
     bold: boolean;
     italic: boolean;
     underline: boolean;
+    /** ECMA-376 §17.3.2.40 `<w:u w:val>` — the raw ST_Underline (§17.18.99) style
+     *  value (`double` / `thick` / `dotted` / `wave` / `dashLong` / …). Absent for
+     *  the plain single rule (or no underline). The renderer normalizes this
+     *  WordprocessingML vocabulary to the shared DrawingML ST_TextUnderlineType
+     *  (§20.1.10.82) that `core.drawUnderline` dispatches on. */
+    underlineStyle?: string;
+    /** ECMA-376 §17.3.2.40 `<w:u w:color>` — underline-only colour (hex 6, or the
+     *  literal `auto`). Absent ⇒ the underline follows the glyph colour. */
+    underlineColor?: string;
     strikethrough: boolean;
     fontSize: number;
     color: string | null;
@@ -1756,10 +2641,23 @@ declare interface DocxTextRun {
     vertAlign: 'super' | 'sub' | null;
     /** Target URL for hyperlinks (resolved from relationships.xml) */
     hyperlink: string | null;
+    /** ECMA-376 §17.16.23 `<w:hyperlink w:anchor>` — internal bookmark name this
+     *  link jumps to (a `<w:bookmarkStart w:name>` in the same document). Set for an
+     *  internal cross-reference / TOC entry. When a link carries both `r:id` and
+     *  `w:anchor`, {@link DocxTextRun.hyperlink} (external) wins and this still
+     *  records the anchor. Absent when the link has no anchor. */
+    hyperlinkAnchor?: string | null;
     allCaps?: boolean;
     smallCaps?: boolean;
     doubleStrikethrough?: boolean;
     highlight?: string | null;
+    /** ECMA-376 §17.3.2.12 `<w:em w:val>` — emphasis (boten / 圏点) mark drawn on
+     *  every non-space character of the run (§17.18.24 ST_Em). `'dot'` = filled
+     *  dot above, `'comma'` = sesame/comma above, `'circle'` = hollow circle
+     *  above, `'underDot'` = filled dot below (horizontal writing). Absent (or the
+     *  authored `val="none"`) ⇒ no mark. The renderer stamps the mark per glyph
+     *  after the text and does NOT change the glyph advance. */
+    emphasisMark?: EmphasisMark;
     /** ECMA-376 §17.3.3.25 ruby annotation (furigana). Renders above the
      *  base text in a smaller font; line height is expanded to fit it. */
     ruby?: RubyAnnotation;
@@ -1791,6 +2689,52 @@ declare interface DocxTextRun {
     /** ECMA-376 §17.3.2.20 `<w:lang w:bidi>` — complex-script (RTL) language tag,
      *  lower-cased (e.g. "ar-sa", "ae-ar"). Drives Word's AN digit ordering. */
     langBidi?: string;
+    /** ECMA-376 §17.3.2.34 `<w:snapToGrid>` — false opts this run out of the
+     *  section character grid; absent inherits participation. */
+    snapToGrid?: boolean;
+    /** ECMA-376 §17.3.2.35 `<w:spacing w:val>` — character-spacing adjustment in
+     *  POINTS (signed): the extra pitch added after each character before the next
+     *  is rendered. The renderer feeds it to `ctx.letterSpacing` on BOTH the
+     *  measure and paint passes so line breaking / pagination stay consistent.
+     *  Absent ⇒ no extra pitch. */
+    charSpacing?: number;
+    /** ECMA-376 §17.3.2.14 `<w:fitText>` — manual run-width target in TWIPS
+     *  (`w:val`, 1/20 pt) plus the optional `w:id` that links consecutive runs
+     *  into one region. The arbitrary-precision XSD integer id is serialized as a
+     *  string; numeric synthetic inputs remain supported for layout tests and
+     *  direct model construction. An id-less run is always standalone. */
+    fitTextVal?: number;
+    fitTextId?: string | number;
+    /** ECMA-376 §17.3.2.43 `<w:w w:val>` — horizontal text scale as a FRACTION of
+     *  normal character width (0.67 = 67%, 2.0 = 200%). Stretches each glyph's
+     *  width, not the gap between glyphs. Absent ⇒ 100%. */
+    charScale?: number;
+    /** ECMA-376 §17.3.2.24 `<w:position w:val>` — baseline raise (positive) /
+     *  lower (negative) in POINTS, without changing the font size or line box.
+     *  Absent ⇒ no shift. */
+    position?: number;
+    /** ECMA-376 §17.3.2.19 `<w:kern w:val>` — font-kerning threshold in POINTS
+     *  (the smallest font size that is kerned). Presence enables kerning subject
+     *  to the threshold; absent ⇒ kerning off (the hierarchy default). `0` = kern
+     *  at all sizes. */
+    kerning?: number;
+    /** ECMA-376 §17.3.2.10 `<w:eastAsianLayout w:vert>` — horizontal-in-vertical
+     *  (縦中横 / tate-chū-yoko). `true` means that in a VERTICAL (tbRl) page this
+     *  run's characters are laid out horizontally side by side within ONE cell of
+     *  the vertical line (rotated 90° relative to the vertical flow). Absent ⇒
+     *  normal vertical stacking. Inert in a horizontal page. */
+    eastAsianVert?: boolean;
+    /** ECMA-376 §17.3.2.10 `<w:eastAsianLayout w:vertCompress>` — compress the
+     *  縦中横 run to fit the existing line height without growing the line. Ignored
+     *  unless {@link eastAsianVert} is set. Absent ⇒ not compressed. */
+    eastAsianVertCompress?: boolean;
+    /** ECMA-376 §17.3.2.10 `<w:eastAsianLayout w:combine>` — two-lines-in-one.
+     *  PARSED for completeness; not yet rendered (no fixture). */
+    eastAsianCombine?: boolean;
+    /** ECMA-376 §17.3.2.10 `<w:eastAsianLayout w:combineBrackets>` (§17.18.8) —
+     *  bracket style around two-lines-in-one text. PARSED for completeness; the
+     *  two-lines-in-one draw is a follow-up. */
+    eastAsianCombineBrackets?: string;
     /** ECMA-376 §17.11.6/.7/.16/.17 — set when this run is a footnote/endnote
      *  reference marker (`<w:footnoteReference>` in the body, `<w:footnoteRef>` at
      *  the start of the note's content, and the endnote equivalents). `text` holds
@@ -1814,11 +2758,43 @@ declare interface DocxTextRunInfo {
     fontSize: number;
     /** CSS `font` shorthand used for canvas drawing (e.g. `"bold 16px Arial"`). */
     font: string;
-}
-
-declare class DocxViewer {
+    /** Uniform per-code-point pitch in CSS px used to draw a horizontal run.
+     *  Absent when the pitch is zero or the run uses vertical / 縦中横 paint. */
+    letterSpacingPx?: number;
+    /** ECMA-376 §17.6.20 (tbRl) — when the page is vertical the canvas is the
+     *  physical landscape page rotated +90° at paint, so this run's `x`/`y` are the
+     *  PHYSICAL top-left the overlay span must sit at, and `transform` is the CSS
+     *  rotation (`"rotate(90deg)"`, applied about the span's top-left) that lays the
+     *  horizontal DOM span along the drawn (rotated) glyph run. Absent for
+     *  horizontal pages (the span is placed at `x`/`y` untransformed). */
+    transform?: string;
+    /** IX1 — the resolved hyperlink target of this run (ECMA-376 §17.16.22
+     *  external URL / §17.16.23 internal `w:anchor` bookmark), or absent for a
+     *  non-link run. The text-layer overlay turns a run carrying this into a
+     *  clickable region; the drawn glyphs are unaffected. */
+    hyperlink?: HyperlinkTarget;
+    /** ECMA-376 §17.3.2.10 eastAsianLayout `w:vert` (縦中横 / horizontal-in-vertical):
+     *  `true` when this run was drawn as tate-chu-yoko — its glyphs laid out
+     *  horizontally, side by side, COMPRESSED into ONE em cell of the vertical
+     *  column (see {@link drawTateChuYokoRun}). `w` is the drawn cell extent (one
+     *  em), NOT the natural text width, so the find / selection overlays must clamp
+     *  their horizontal extent to `w` rather than re-measuring the run's natural
+     *  glyphs (issue #836). Absent for every ordinary run. */
+    eastAsianVert?: boolean;
+}
+
+declare class DocxViewer implements ZoomableViewer {
     private _doc;
     private _currentPage;
+    /**
+     * IX9 explicit zoom factor (`1` = 100% = the page at its natural pt→px width),
+     * or `null` when the caller has never invoked a zoom method. `null` preserves
+     * the pre-IX9 render path EXACTLY: the page renders at `opts.width` (or its
+     * natural width when that is unset), so default rendering is byte-identical. The
+     * first `setScale`/`zoomIn`/`zoomOut`/`fitWidth`/`fitPage` call latches a number
+     * here, after which `_renderPage` derives the canvas width from it instead.
+     */
+    private _scale;
     private _canvas;
     private _wrapper;
     /** The canvas's DOM position BEFORE the constructor reparented it into
@@ -1831,20 +2807,56 @@ declare class DocxViewer {
      *  (empty string if it was unset), restored on {@link destroy}. */
     private _originalDisplay;
     private _textLayer;
+    /** IX2 — the find-highlight overlay layer. Always created (independent of
+     *  `enableTextSelection`): highlights ride the same positioned-DOM overlay
+     *  mechanism as the selection layer but are visible boxes, not transparent
+     *  spans. Sits above the text layer so a highlight shows over a link's hit
+     *  region without stealing its clicks (`pointer-events:none`). */
+    private _highlightLayer;
+    /** IX2 — find state (per-page runs, matches, active cursor). */
+    private _find;
+    /** A 2d context used only to measure text for highlight geometry (its own
+     *  1×1 offscreen canvas, so measuring never touches the visible canvas). */
+    private _measureCtx;
     private _opts;
     private readonly _mode;
     /** The canvas's bitmaprenderer context, used only in worker mode (a canvas
      *  holds one context type for its lifetime; the main-mode 2d render path is
      *  never used on the same canvas). */
     private _bitmapCtx;
-    private _warnedNoTextSelection;
+    /** Set by {@link destroy} (first line). Guards {@link _reportRenderError} so a
+     *  render rejection that lands AFTER teardown is swallowed rather than surfaced
+     *  to an `onError` / `console.error` on a dead viewer — parity with the scroll
+     *  viewers' `_destroyed` flag. */
+    private _destroyed;
+    /**
+     * Concurrent-load latch (generation token). Every {@link load} increments this
+     * and captures the value; after its engine finishes loading it re-checks the
+     * live value and BAILS (destroying its own just-loaded engine) if a newer
+     * `load()` has since started. Without it, two overlapping `load(A)`/`load(B)`
+     * calls race the WASM parse / worker init, and whichever RESOLVES last wins the
+     * swap — even the stale `load(A)` resolving after `load(B)`; the loser's freshly
+     * created engine (never installed, or installed then overwritten) then leaks its
+     * worker + pinned WASM allocation. The latch composes with SC20: the check runs
+     * AFTER the new engine loads but BEFORE the field assignment and
+     * `previous?.destroy()`, so a superseded load never touches `this._doc` nor
+     * frees the current (newer) engine. {@link destroy} also bumps it so a load in
+     * flight at teardown is treated as superseded and its engine cleaned up.
+     */
+    private _loadGen;
     constructor(canvas: HTMLCanvasElement, opts?: DocxViewerOptions);
     /**
      * Load a DOCX from URL or ArrayBuffer and render the first page.
      *
-     * Error contract (shared by all three viewers): on failure, if an `onError`
-     * callback was provided it is invoked and `load` resolves normally; if not,
-     * the error is rethrown so it is never silently swallowed.
+     * Error contract (shared by all three viewers):
+     * - Parse/load failure (the underlying `DocxDocument.load()` call itself
+     *   rejects): if an `onError` callback was provided it is invoked and `load`
+     *   resolves normally; if not, the error is rethrown so it is never silently
+     *   swallowed.
+     * - Render failure (the first page fails to draw AFTER a successful
+     *   parse/load): routed to the shared `_reportRenderError` contract (`onError`
+     *   if provided, else `console.error` — never silent) and `load` still
+     *   RESOLVES, matching every subsequent navigation call.
      */
     load(source: string | ArrayBuffer): Promise<void>;
     get pageCount(): number;
@@ -1854,6 +2866,91 @@ declare class DocxViewer {
     goToPage(index: number): Promise<void>;
     nextPage(): Promise<void>;
     prevPage(): Promise<void>;
+    /** Natural (100%) CSS-px width of the current page — `widthPt × PT_TO_PX`.
+     *  This is the scale-1 reference every zoom factor multiplies. 0 when nothing
+     *  is loaded. */
+    private _naturalWidthPx;
+    /**
+     * The width (CSS px) `_renderPage` renders the current page at, honouring the
+     * zoom state. `_scale === null` (no zoom method ever called) ⇒ the pre-IX9
+     * value `opts.width` verbatim (byte-identical default: `undefined` lets the
+     * renderer use the page's natural width). Once a factor latched ⇒
+     * `naturalWidth × scale` (rounded), so the on-screen page is exactly `scale ×`
+     * its natural size regardless of the original `opts.width`.
+     */
+    private _renderWidth;
+    /** IX9 {@link ZoomableViewer} — the current zoom factor (`1` = 100%). Before
+     *  any zoom method is called this is the EFFECTIVE scale implied by the current
+     *  render width: `opts.width / naturalWidth`, or `1` when `opts.width` is unset
+     *  (the page renders at its natural size) or nothing is loaded. */
+    getScale(): number;
+    private _zoomMin;
+    private _zoomMax;
+    /**
+     * IX9 {@link ZoomableViewer} — set the absolute zoom factor (`1` = 100% = the
+     * page at its natural pt→px width), clamped to `[zoomMin, zoomMax]`, and
+     * re-render the current page at the new size. Fires `onScaleChange` when the
+     * clamped factor actually changes. Resolves once the re-render settles. A no-op
+     * (but still latches the scale) when nothing is loaded.
+     */
+    setScale(scale: number): Promise<void>;
+    /** IX9 {@link ZoomableViewer} — step up to the next rung of the shared zoom
+     *  ladder (clamped to `zoomMax`). */
+    zoomIn(): Promise<void>;
+    /** IX9 {@link ZoomableViewer} — step down to the next lower ladder rung. */
+    zoomOut(): Promise<void>;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the current page's WIDTH to the host
+     * container (the element the canvas lives in, or `opts.container` if supplied),
+     * then re-render. Defers (no-op) when nothing is loaded or the container is
+     * unlaid-out. Routes through {@link setScale}, so the factor is clamped and
+     * `onScaleChange` fires.
+     */
+    fitWidth(): Promise<void>;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the WHOLE current page (width and height)
+     * inside the container so it is visible without scrolling; takes the tighter of
+     * the width/height fit. Defers when unloaded / unlaid-out.
+     */
+    fitPage(): Promise<void>;
+    /** Shared fit for {@link fitWidth}/{@link fitPage}: measure the natural page
+     *  size + the container box, ask core's pure `fitScale`, apply via setScale. */
+    private _fit;
+    /** The element a fit measures against: the explicit `opts.container`, else the
+     *  host the wrapper was inserted into (`_wrapper.parentElement`). `null` when
+     *  the canvas was mounted detached (no host to fit to). */
+    private _fitContainer;
+    /**
+     * IX2 — find every occurrence of `query` in the document and highlight them
+     * all (a soft box per match, drawn on the highlight overlay over the drawn
+     * glyphs). Returns every match in document order, each tagged with its
+     * `{ page }` (0-based). Case-insensitive by default (browser find-in-page);
+     * pass `{ caseSensitive: true }` to match case exactly.
+     *
+     * Scans all pages, so a large document renders each page once (offscreen) to
+     * read its text (the visible page reuses its on-screen render). IX6 — works in
+     * BOTH `mode: 'main'` and `mode: 'worker'`: in worker mode each page's run
+     * geometry is collected off-thread and shipped back, so find returns the same
+     * matches on the same code path. An empty query clears the find and returns `[]`.
+     */
+    findText(query: string, opts?: FindMatchesOptions): Promise<FindMatch<DocxMatchLocation>[]>;
+    /**
+     * IX2 — move to the next match (wrap-around from last to first), navigating to
+     * its page if needed, and draw it in the distinct active-match colour. Returns
+     * the now-active match, or `null` when there are no matches. Call
+     * {@link findText} first.
+     */
+    findNext(): Promise<FindMatch<DocxMatchLocation> | null>;
+    /** IX2 — move to the previous match (wrap-around from first to last). */
+    findPrev(): Promise<FindMatch<DocxMatchLocation> | null>;
+    /** IX2 — clear all highlights and reset the find state. */
+    clearFind(): void;
+    /** Navigate to the active match's page (if not already there) and redraw the
+     *  highlights so the active box shows in the emphasis colour. */
+    private _activateMatch;
+    /** Rebuild the highlight overlay for the current page from cached runs
+     *  (no page re-render). */
+    private _redrawHighlights;
     /**
      * Terminate the parser worker and release resources.
      *
@@ -1865,7 +2962,45 @@ declare class DocxViewer {
      */
     destroy(): void;
     private _render;
+    /** Route a render failure to `onError`, or `console.error` when none is given
+     *  (never fully silent), and never after teardown. Mirrors the scroll viewers'
+     *  `_reportRenderError`. */
+    private _reportRenderError;
+    private _renderPage;
+    /** Draw the find-highlight boxes for the current page from its runs. Clears
+     *  the overlay when there is no active find. */
+    private _buildHighlightLayer;
+    /** The canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path
+     *  (which mirror the render's logical size), falling back to the backing-store
+     *  dimensions when unset. Parsing tolerates the trailing `px`. */
+    private _canvasCssPx;
+    /** A width-measurer primed with `font`, backed by a private 1×1 canvas so it
+     *  never disturbs the visible canvas's context state. */
+    private _measureForFont;
+    /** Render a page to a throwaway offscreen canvas purely to collect its runs
+     *  (text + geometry) for search, without touching the visible canvas. Used by
+     *  the find controller for pages other than the one on screen. */
+    private _collectPageRuns;
     private _buildTextLayer;
+    /**
+     * IX1/IX-nav — the click handler passed to the text-layer overlay. When the
+     * caller supplied `onHyperlinkClick`, it fully owns the behaviour (the default
+     * is suppressed). Otherwise the built-in default is: an external link opens in
+     * a new tab through core `openExternalHyperlink` (URL sanitised against the
+     * safe scheme allowlist, `noopener,noreferrer`); an internal `<w:anchor>` link
+     * resolves its bookmark name to a page via
+     * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and jumps there
+     * with {@link goToPage}. An anchor naming no known bookmark is a safe no-op
+     * rather than a jump to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
+     */
+    private _hyperlinkHandler;
 }
 
 declare interface DocxViewerOptions extends RenderPageOptions, LoadOptions_4 {
@@ -1877,10 +3012,58 @@ declare interface DocxViewerOptions extends RenderPageOptions, LoadOptions_4 {
     enableTextSelection?: boolean;
     /** Called when a page finishes rendering. */
     onPageChange?: (index: number, total: number) => void;
+    /** IX9 zoom contract ({@link ZoomableViewer}) — the clamp range for
+     *  {@link DocxViewer.setScale} / `zoomIn` / `zoomOut` / `fitWidth` / `fitPage`,
+     *  as user-facing zoom factors (`1` = 100% = the page at its natural pt→px
+     *  size). Defaults 0.1–4 (10%–400%), matching the other viewers. */
+    zoomMin?: number;
+    zoomMax?: number;
+    /** IX9 — fires whenever the zoom factor actually changes (`1` = 100%): from
+     *  {@link DocxViewer.setScale}, `zoomIn`/`zoomOut`, or `fitWidth`/`fitPage`.
+     *  Named `onScaleChange` to match the pptx/xlsx viewers so all five share one
+     *  notification shape. */
+    onScaleChange?: (scale: number) => void;
+    /** IX1 (design decision — NOT user-confirmed, integrator may veto). Called when
+     *  a hyperlink run is clicked. When omitted, the default is: external → open in a
+     *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
+     *  internal → jump to the page whose text contains the bookmark (best-effort). */
+    onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  (their colour/underline are painted on the canvas) but are inert, like plain
+     *  text. Set it to disable clickable links entirely — e.g. in a preview where
+     *  navigation must not leave the current view. */
+    enableHyperlinks?: boolean;
     /** Called on parse or render errors. */
     onError?: (err: Error) => void;
 }
 
+/** A duotone effect resolved to its two endpoint colours. Both are 6-char
+ *  uppercase hex WITHOUT a leading `#` (the form the Rust parsers emit). `clr1`
+ *  is the dark endpoint (luminance 0), `clr2` the light endpoint (luminance 1),
+ *  matching the child order of `<a:duotone>` in §20.1.8.23. Any per-colour
+ *  transforms (lumMod/lumOff/tint/satMod/…) are already baked into these hexes
+ *  by the parser's colour-resolution machinery. */
+declare interface Duotone {
+    /** First `EG_ColorChoice` child — the dark endpoint. 6-char hex, no `#`. */
+    clr1: string;
+    /** Second `EG_ColorChoice` child — the light endpoint. 6-char hex, no `#`. */
+    clr2: string;
+}
+
+/** ECMA-376 §20.1.8.23 `<a:duotone>` image effect, resolved to its two endpoint
+ *  colours (mirrors the shared Rust `ooxml_common::blip::Duotone`). `clr1` is the
+ *  dark endpoint (luminance 0), `clr2` the light endpoint (luminance 1); both are
+ *  6-char uppercase hex WITHOUT a leading `#`, with per-colour transforms already
+ *  applied by the parser. */
+declare interface Duotone_2 {
+    clr1: string;
+    clr2: string;
+}
+
 declare interface Dxf {
     font: CellFont | null;
     fill: CellFill | null;
@@ -1892,6 +3075,20 @@ declare interface Dxf {
     numFmt?: NumFmt | null;
 }
 
+/** ECMA-376 §17.8.3.3-.6 — one embedded font-style slot from
+ *  `word/fontTable.xml`, resolved to its obfuscated part path + fontKey. */
+declare interface EmbeddedFontRef {
+    fontName: string;
+    style: 'regular' | 'bold' | 'italic' | 'boldItalic';
+    partPath: string;
+    fontKey: string;
+}
+
+/** ECMA-376 §17.18.24 ST_Em — the emphasis-mark styles a run may carry via
+ *  `<w:em w:val>` (§17.3.2.12). `'none'` is filtered out by the parser, so the
+ *  model only ever carries one of these four positive marks (or `undefined`). */
+declare type EmphasisMark = 'dot' | 'comma' | 'circle' | 'underDot';
+
 /**
  * An OMML equation embedded in a paragraph (ECMA-376 §22.1). Parsed into the
  * shared math AST and rendered by `@silurus/ooxml-core`'s math engine.
@@ -1930,6 +3127,10 @@ declare interface FieldRun {
     smallCaps?: boolean;
     doubleStrikethrough?: boolean;
     highlight?: string | null;
+    /** ECMA-376 §17.3.2.12 `<w:em w:val>` — emphasis (boten / 圏点) mark, mirrors
+     *  {@link DocxTextRun.emphasisMark} (§17.18.24 ST_Em). Absent (or the
+     *  authored `val="none"`) ⇒ no mark. */
+    emphasisMark?: EmphasisMark;
 }
 
 declare type Fill = SolidFill | NoFill | GradientFill | PatternFill | ImageFill;
@@ -1947,6 +3148,47 @@ declare interface FillRect {
     b?: number;
 }
 
+/**
+ * IX2 public find-result shape, shared by all three viewers.
+ *
+ * `findText` returns an ordered list of {@link FindMatch}. Every match carries
+ * its ordinal position (`matchIndex`, 0-based, document order — the same index
+ * `findNext` / `findPrev` cycle through), the matched `text`, and a
+ * format-specific `location`. The location is where the three formats
+ * legitimately differ — a docx match lives on a page, a pptx match on a slide,
+ * an xlsx match in a sheet cell — so `FindMatch` is generic over it rather than
+ * forcing an artificial common shape. Each viewer instantiates it with its own
+ * location type:
+ *
+ *   - `DocxViewer.findText` → `FindMatch<DocxMatchLocation>`  ({ page })
+ *   - `PptxViewer.findText` → `FindMatch<PptxMatchLocation>`  ({ slide })
+ *   - `XlsxViewer.findText` → `FindMatch<XlsxMatchLocation>`  ({ sheet, ref, … })
+ *
+ * The generic default is `unknown` so `FindMatch` can be referenced without a
+ * type argument (e.g. in generic UI code) while each viewer's return type stays
+ * precise.
+ */
+declare interface FindMatch<Loc = unknown> {
+    /** 0-based ordinal among all matches, in document order. This is the index
+     *  `findNext`/`findPrev` make active, so a caller can correlate the array it
+     *  got from `findText` with the active-match reported by navigation. */
+    matchIndex: number;
+    /** The text that matched (the query as it appears in the document — its
+     *  original case, not the folded form used for case-insensitive matching). */
+    text: string;
+    /** Where the match is, in the format's own coordinates. */
+    location: Loc;
+}
+
+/** Options for {@link findMatches}. */
+declare interface FindMatchesOptions {
+    /**
+     * Match case exactly. Default `false` (case-insensitive, like a browser's
+     * find-in-page). IX2 default — an integrator can pass `true`.
+     */
+    caseSensitive?: boolean;
+}
+
 /**
  * ECMA-376 §17.3.1.11 `<w:framePr>` — text-frame / drop-cap properties.
  *
@@ -2050,9 +3292,60 @@ declare type HiddenSlideMode = 'show' | 'skip' | 'dim';
 declare interface Hyperlink {
     col: number;
     row: number;
+    /** External target (ECMA-376 §18.3.1.47 `r:id`, resolved via worksheet rels).
+     *  `null` for a purely internal hyperlink. */
     url: string | null;
+    /** Internal target (§18.3.1.47 `location`): a defined name or a cell reference
+     *  such as `Sheet1!A1`. Present when the hyperlink navigates within the
+     *  workbook rather than to an external URL. */
+    location?: string | null;
+    /** Optional display text (§18.3.1.47 `display`). Not used for rendering. */
+    display?: string | null;
 }
 
+/**
+ * Shared hyperlink model + URL sanitisation for docx / pptx / xlsx (IX1).
+ *
+ * All three formats carry the same two ECMA-376 concepts:
+ *   - an **external** hyperlink — an absolute URL resolved from a relationship
+ *     part target (`document.xml.rels` for docx §17.16.22, the slide rels for
+ *     pptx §21.1.2.3.5, the worksheet rels for xlsx §18.3.1.47), with
+ *     `TargetMode="External"`.
+ *   - an **internal** hyperlink — a jump within the document itself:
+ *     docx `w:anchor` -> a `<w:bookmarkStart w:name>` (§17.16.23), pptx
+ *     `action="ppaction://hlinksldjump"` -> a slide, xlsx `location` -> a defined
+ *     name or a `Sheet!A1` cell reference.
+ *
+ * The parsers (Rust, one per format) do the format-specific rels lookup and hand
+ * each run / shape / cell a {@link HyperlinkTarget}. Everything downstream — the
+ * text-layer overlay, the viewer default click behaviour, and any integrator
+ * callback — is format-agnostic and consumes this one shape. Keeping the type +
+ * the pure `sanitizeHyperlinkUrl` predicate here (not duplicated per package)
+ * follows the cross-package unification principle: a scheme-allowlist bug fixed
+ * once is fixed everywhere.
+ */
+/**
+ * A resolved hyperlink attached to a run, shape, or cell.
+ *
+ *   - `external` — `url` is the raw target as authored in the file. It is NOT
+ *     guaranteed safe; run it through {@link sanitizeHyperlinkUrl} before
+ *     navigating. It is kept verbatim here so an integrator can apply its own
+ *     policy (e.g. allow `file:` on a trusted intranet viewer).
+ *   - `internal` — `ref` is the in-document destination, verbatim from the file:
+ *       docx: the bookmark name (`w:anchor`).
+ *       pptx: the internal action (e.g. `ppaction://hlinksldjump`), with the
+ *             resolved 0-based `slideIndex` when the rels target names a slide.
+ *       xlsx: the `location` string (a defined name or `Sheet1!A1`).
+ */
+declare type HyperlinkTarget = {
+    kind: 'external';
+    url: string;
+} | {
+    kind: 'internal';
+    ref: string;
+    slideIndex?: number;
+};
+
 /**
  * Image anchored to a rectangle of cells (EMU offsets within the anchor cells).
  * 914400 EMU = 1 inch, 9525 EMU = 1 px @ 96 DPI.
@@ -2101,6 +3394,15 @@ declare interface ImageAnchor {
         r: number;
         b: number;
     };
+    /** ECMA-376 §20.1.8.6 `<a:alphaModFix@amt>` — the blip's overall opacity as a
+     *  fraction (0..1). Absent ⇒ opaque. The renderer sets `ctx.globalAlpha` so the
+     *  picture composites over the cells beneath it (e.g. a pink translucent photo
+     *  over a matching cell fill). */
+    alpha?: number;
+    /** ECMA-376 §20.1.8.23 `<a:duotone>` recolour effect. Absent (the common case)
+     *  ⇒ no effect. When present, the renderer remaps the image along the
+     *  `clr1`→`clr2` luminance ramp before drawing. */
+    duotone?: Duotone_2;
 }
 
 /**
@@ -2132,6 +3434,14 @@ declare interface ImageFill {
     tile?: TileInfo;
     /** `a:blip > a:alphaModFix@amt` as a fraction (0.0–1.0). Absent = opaque. */
     alpha?: number;
+    /**
+     * ECMA-376 §20.1.8.23 `<a:duotone>` recolour, resolved to its two endpoint
+     * colours (through the slide theme). Absent ⇒ no duotone. When present the
+     * renderer maps the blip's luminance ramp between the two colours (core
+     * `applyDuotone`) — the same recolour a `<p:pic>` duotone applies, wired onto
+     * the picture-FILL path (§20.1.8.14) by issue #889.
+     */
+    duotone?: Duotone;
 }
 
 declare interface ImageRun {
@@ -2191,6 +3501,19 @@ declare interface ImageRun {
      * transparency. Implements a:clrChange (make-background-transparent).
      */
     colorReplaceFrom?: string;
+    /**
+     * ECMA-376 §20.1.8.23 `<a:duotone>` recolour, resolved to its two endpoint
+     * colours (through the document theme). Absent ⇒ no duotone. When present the
+     * renderer decodes the raster once, remaps it along the `clr1`→`clr2`
+     * luminance ramp, and caches the recoloured bitmap under a colour-suffixed key.
+     */
+    duotone?: Duotone;
+    /**
+     * ECMA-376 §20.1.8.6 `<a:alphaModFix@amt>` opacity as 0..1. Absent ⇒ fully
+     * opaque. When present the renderer multiplies the picture's `globalAlpha` by
+     * this fraction.
+     */
+    alpha?: number;
     /**
      * Wrap mode for anchor images:
      *   "square" | "topAndBottom" | "none" | "tight" | "through"
@@ -2280,6 +3603,24 @@ declare interface LineEnd {
     len: string;
 }
 
+/** ECMA-376 §17.6.8 `<w:lnNumType>` — line numbering for a section. Mirrors the
+ *  Rust `LineNumbering`. A number is drawn in the left margin of each body line
+ *  whose count is a multiple of `countBy`. Absent on {@link SectionProps}
+ *  (`lineNumbering` undefined) ⇒ line numbering off. */
+declare interface LineNumbering {
+    /** `@w:countBy` — only lines whose number is a multiple of this display a
+     *  number. Required (absent ⇒ the whole struct is absent per §17.6.8). */
+    countBy: number;
+    /** `@w:start` — the starting number after each restart. Default 1. */
+    start: number;
+    /** `@w:distance` in pt (twips ÷ 20) — gap between the text margin and the
+     *  number glyphs. Absent ⇒ implementation-defined (renderer uses a default). */
+    distance?: number;
+    /** `@w:restart` (§17.18.47): "newPage" (default) | "newSection" |
+     *  "continuous" — when the counter resets to `start`. */
+    restart: string;
+}
+
 declare interface LineSpacing {
     value: number;
     rule: 'auto' | 'exact' | 'atLeast';
@@ -2322,6 +3663,35 @@ declare interface LoadOptions_2 {
      * via `@font-face` in your application CSS.
      */
     useGoogleFonts?: boolean;
+    /**
+     * Password for an encrypted OOXML file ([MS-OFFCRYPTO] Agile Encryption).
+     *
+     * Password-protected Office documents are CFB (OLE2) containers, not ZIPs.
+     * When this is set and the input is Agile-encrypted, `load()` decrypts it on
+     * the main thread (via WebCrypto) and parses the recovered plaintext ZIP.
+     *
+     * Errors (thrown as {@link import('../errors/ooxml-error').OoxmlError}):
+     *   - no `password` on an encrypted file → code `'encrypted'`
+     *   - wrong `password`                   → code `'invalid-password'`
+     *   - a non-Agile scheme (Standard / Extensible / legacy) → code
+     *     `'unsupported-encryption'`
+     *
+     * Note: Agile Encryption uses a high password-hash spin count (commonly
+     * 100,000), so decryption of a protected file adds roughly a second of
+     * WebCrypto work before parsing begins.
+     *
+     * Security notes:
+     *   - This value is held as an ordinary JS `string` in memory for the
+     *     duration of key derivation. The library does not zero it, and does
+     *     not wrap it in a `SecureString`-equivalent — it becomes eligible for
+     *     garbage collection like any other string once nothing references it,
+     *     but no explicit wipe is performed. It is never logged or included in
+     *     thrown errors.
+     *   - Decryption recovers the plaintext but does not verify the file's HMAC
+     *     data-integrity tag ([MS-OFFCRYPTO] §2.3.4.14), so ciphertext tampering
+     *     is not detected — see "Security & Privacy" in the README.
+     */
+    password?: string;
     /**
      * Override the URL the parser worker fetches the WebAssembly module from.
      *
@@ -2403,6 +3773,23 @@ declare interface LoadOptions_4 extends LoadOptions_2 {
 /** @deprecated Use `ChartManualLayout` from @silurus/ooxml-core. */
 declare type ManualLayout = ChartManualLayout;
 
+/**
+ * The slice of one run a match covers: the run's index in the original `runs[]`
+ * and the `[start, end)` character range within that run's own `text`. A match
+ * that straddles N runs yields N of these (the first sliced from its start
+ * offset to the run end, the last from 0 to its end offset, any middle run
+ * whole). The viewer measures each slice against that run's font to get a pixel
+ * rectangle.
+ */
+declare interface MatchRunSlice {
+    /** Index into the original `runs[]` handed to {@link buildTextIndex}. */
+    runIndex: number;
+    /** Start offset within `runs[runIndex].text` (inclusive). */
+    start: number;
+    /** End offset within `runs[runIndex].text` (exclusive). */
+    end: number;
+}
+
 /** Accent (`m:acc`), e.g. hat, bar, vector arrow over the base. */
 declare interface MathAccent {
     kind: 'accent';
@@ -2425,6 +3812,31 @@ declare interface MathBar {
     base: MathNode[];
 }
 
+/** Border-box object (`m:borderBox`, §22.1.2.11): a border/strikes around the
+ *  base. Absent flags ⇒ a full rectangular box. */
+declare interface MathBorderBox {
+    kind: 'borderBox';
+    /** §22.1.2 hide* — when true the corresponding edge is NOT drawn. */
+    hideTop?: boolean;
+    hideBot?: boolean;
+    hideLeft?: boolean;
+    hideRight?: boolean;
+    /** §22.1.2 strike* — strikeBLTR = bottom-left→top-right, strikeTLBR =
+     *  top-left→bottom-right diagonal. */
+    strikeH?: boolean;
+    strikeV?: boolean;
+    strikeBltr?: boolean;
+    strikeTlbr?: boolean;
+    base: MathNode[];
+}
+
+/** Box object (`m:box`, §22.1.2.13): a logical grouping (operator emulator /
+ *  line-break control). Draws NO border — a transparent group around `base`. */
+declare interface MathBox {
+    kind: 'box';
+    base: MathNode[];
+}
+
 declare interface MathDelimiter {
     kind: 'delimiter';
     /** opening char (default '('). */
@@ -2482,7 +3894,23 @@ declare interface MathNary {
     body: MathNode[];
 }
 
-declare type MathNode = MathRun | MathFraction | MathScript | MathNary | MathDelimiter | MathRadical | MathLimit | MathArray | MathGroupChr | MathBar | MathAccent | MathFunc | MathGroup;
+declare type MathNode = MathRun | MathFraction | MathScript | MathNary | MathDelimiter | MathRadical | MathLimit | MathArray | MathGroupChr | MathBar | MathAccent | MathFunc | MathGroup | MathPhant | MathSPre | MathBox | MathBorderBox;
+
+/** Phantom object (`m:phant`, §22.1.2.81): contributes the spacing of `base`
+ *  while optionally hiding it and/or zeroing individual dimensions. */
+declare interface MathPhant {
+    kind: 'phant';
+    /** §22.1.2.96 `m:show` — `false` hides the base (invisible but occupies space,
+     *  i.e. `<mphantom>`); `true` (default) shows it and the phant only tweaks
+     *  spacing. */
+    show: boolean;
+    /** §22.1.2 zeroWid / zeroAsc / zeroDesc — suppress width / ascent / descent so
+     *  the base takes no space along that axis. Omitted ⇒ false. */
+    zeroWid?: boolean;
+    zeroAsc?: boolean;
+    zeroDesc?: boolean;
+    base: MathNode[];
+}
 
 declare interface MathRadical {
     kind: 'radical';
@@ -2525,6 +3953,15 @@ declare interface MathScript {
     sub?: MathNode[];
 }
 
+/** Pre-sub-superscript object (`m:sPre`, §22.1.2.99): sub + sup to the LEFT of
+ *  the base (e.g. ²₁A). */
+declare interface MathSPre {
+    kind: 'sPre';
+    sub: MathNode[];
+    sup: MathNode[];
+    base: MathNode[];
+}
+
 declare type MathStyle = 'roman' | 'italic' | 'bold' | 'boldItalic';
 
 declare interface MathSvg {
@@ -2606,6 +4043,19 @@ declare interface NumberingInfo {
      *  this family. Absent ⇒ the renderer falls back to
      *  {@link NumberingInfo.fontFamily}. */
     fontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.9.24 — the numbering level rPr's `w:color` (hex 6 without
+     *  `#`, lowercased). Colors the marker glyph only, never the paragraph's
+     *  runs. Absent ⇒ the renderer falls back to
+     *  {@link DocParagraph.paragraphMarkColor} (§17.3.1.29 — Word layers the
+     *  level rPr over the paragraph mark's run properties) and finally to its
+     *  default ink. An explicit `w:val="auto"` is absent here + {@link colorAuto}. */
+    color?: string | null;
+    /** ECMA-376 §17.3.2.6 / ST_HexColorAuto (§17.18.39) — true when the level
+     *  rPr carries an EXPLICIT `w:color w:val="auto"`. Auto names no concrete
+     *  color but is not "unset": it breaks the paragraph-mark fallback, so the
+     *  marker draws the automatic (default) ink instead of
+     *  {@link DocParagraph.paragraphMarkColor}. */
+    colorAuto?: boolean;
     /** ECMA-376 §17.9.9/§17.9.20 — when the level uses a `<w:lvlPicBulletId>`,
      *  the marker is this image (zip path, e.g. `word/media/image1.gif`), drawn in
      *  place of {@link NumberingInfo.text}. Absent ⇒ ordinary text/glyph marker. */
@@ -2623,6 +4073,124 @@ declare interface NumFmt {
     formatCode: string;
 }
 
+/**
+ * Typed error thrown by the docx / pptx / xlsx `load()` factories for failures
+ * that carry a stable, programmatic {@link OoxmlErrorCode} (e.g. a
+ * password-protected or legacy-binary file detected from its container magic).
+ *
+ * Note on workers: `instanceof OoxmlError` does not survive a structured-clone
+ * across the worker boundary. Detection that needs a typed error is therefore
+ * done on the main thread (before the worker is involved) so a genuine
+ * `OoxmlError` instance is thrown to the caller. Errors that must cross the
+ * worker boundary should carry the `code` string and be reconstructed on the
+ * main side.
+ */
+declare class OoxmlError extends Error {
+    readonly code: OoxmlErrorCode;
+    constructor(code: OoxmlErrorCode, message: string);
+}
+
+/**
+ * Machine-readable code for a typed load-time failure.
+ *
+ * The container-level failures the `load()` factories detect on the main thread
+ * before handing bytes to the parser worker (see `sniffCfb` / `decryptOoxml`).
+ * This is the seed of the broader typed-error surface tracked as PD4 (OoxmlError
+ * typed errors). Add codes here rather than throwing bare `Error(string)`, so
+ * callers can `switch` on `err.code` instead of matching message text.
+ *
+ *   - `'encrypted'`             — password-protected, but no `password` was
+ *     supplied (pass `LoadOptions.password` to decrypt).
+ *   - `'invalid-password'`      — a `password` was supplied but did not match.
+ *   - `'unsupported-encryption'`— encrypted with a scheme other than Agile
+ *     (Standard / Extensible / a legacy binary encryptor), which this library
+ *     cannot decrypt (PD8 implements Agile only).
+ *   - `'legacy-binary-format'`  — a raw .doc / .xls / .ppt (not OOXML).
+ *   - `'not-ooxml'`             — a CFB of an unrecognised kind, or otherwise
+ *     not an OOXML ZIP.
+ */
+declare type OoxmlErrorCode = 'encrypted' | 'invalid-password' | 'unsupported-encryption' | 'legacy-binary-format' | 'not-ooxml';
+
+/**
+ * The default action a viewer takes for an **external** hyperlink click when
+ * the integrator supplies no `onHyperlinkClick` handler: sanitise the URL and,
+ * if allowed, open it in a new tab with `noopener,noreferrer` so the opened page
+ * gets no `window.opener` handle back into this document. A blocked scheme is a
+ * silent no-op (returns `false`) — the click does nothing rather than navigate
+ * somewhere dangerous.
+ *
+ * Internal targets are intentionally NOT handled here: the in-document jump
+ * (page / slide / cell) is format-specific and lives in each viewer.
+ *
+ * Split out (not inlined in three viewers) so the "open in new tab, drop opener,
+ * refuse unsafe schemes" policy is defined once. `win` is injected for tests;
+ * defaults to the ambient `window`.
+ *
+ * @returns `true` if navigation was initiated, `false` if the URL was blocked.
+ */
+declare function openExternalHyperlink(url: string, allowed?: readonly string[], win?: Pick<Window, 'open'> | undefined): boolean;
+
+/** `<sheetPr><outlinePr>` flags (ECMA-376 §18.3.1.61). Both default to `true`. */
+declare interface OutlinePr {
+    /** `true` (default) ⇒ a group's summary row sits *below* its detail rows;
+     *  `false` ⇒ above. */
+    summaryBelow: boolean;
+    /** `true` (default) ⇒ a group's summary column sits to the *right* of its
+     *  detail columns; `false` ⇒ to the left. */
+    summaryRight: boolean;
+}
+
+/** ECMA-376 §17.18.4 CT_Border for one edge of `<w:pgBorders>`. Mirrors the Rust
+ *  `PageBorderEdge`. Same shape as a paragraph border edge. */
+declare interface PageBorderEdge {
+    /** `@w:val` — ST_Border line style ("single" | "double" | "dashed" | …). */
+    style: string;
+    /** `@w:color` hex 6, or absent for "auto" (renderer defaults to black). */
+    color?: string;
+    /** `@w:sz` in pt (eighths of a point ÷ 8). */
+    width: number;
+    /** `@w:space` in pt — a POINT measure (§17.18.68, 0–31) for page borders, NOT
+     *  twips — the inset from the `offsetFrom` reference. */
+    space: number;
+}
+
+/** ECMA-376 §17.6.10 `<w:pgBorders>` — page borders drawn around each page of a
+ *  section. Mirrors the Rust `PageBorders`. Each edge is a CT_Border (§17.18.4);
+ *  the container carries the placement globals. Absent on {@link SectionProps}
+ *  (`pageBorders` undefined) ⇒ no page border (the common case). Art borders
+ *  (§17.18.2 decorative-image styles) are unsupported — the renderer draws only
+ *  the standard line styles (single/double/dashed/dotted/thick/…). */
+declare interface PageBorders {
+    /** `@w:offsetFrom` (§17.18.63): "page" ⇒ each edge's `space` is from the PAGE
+     *  edge; "text" (the default) ⇒ from the text margin. */
+    offsetFrom: string;
+    /** `@w:display` (§17.18.62): "allPages" (default) | "firstPage" |
+     *  "notFirstPage" — which physical pages of the section show the border. */
+    display: string;
+    /** `@w:zOrder` (§17.18.64): "front" (default; over text) | "back" (under). */
+    zOrder: string;
+    top?: PageBorderEdge;
+    bottom?: PageBorderEdge;
+    left?: PageBorderEdge;
+    right?: PageBorderEdge;
+}
+
+/** ECMA-376 §17.6.12 `<w:pgNumType>` — a section's page-numbering settings.
+ *  Mirrors the Rust `PageNumType`. Only the two attributes that change the
+ *  DISPLAYED page number are carried:
+ *  - `start` — the number shown on the FIRST page of the section (§17.6.12);
+ *    absent ⇒ numbering continues from the previous section's highest number.
+ *    Kept as a possibly-zero / possibly-negative integer (Word writes `start="0"`).
+ *  - `fmt` — the ST_NumberFormat (§17.18.59) for the section's page numbers
+ *    (decimal / upperRoman / lowerLetter / …); absent ⇒ decimal.
+ *  `chapStyle`/`chapSep` (chapter-prefixed numbering) are out of scope for this
+ *  pass and never surfaced. Field names match the Rust `PageNumType` serialization
+ *  (`start`, `fmt`). */
+declare interface PageNumType {
+    start?: number;
+    fmt?: string;
+}
+
 declare interface ParaBorderEdge {
     style: string;
     color: string | null;
@@ -2685,6 +4253,14 @@ declare interface Paragraph_2 extends Paragraph {
      * emits an effective boolean.
      */
     eaLnBrk: boolean;
+    /**
+     * `<a:pPr defTabSz>` (ECMA-376 §21.1.2.2.7) — the default tab-stop interval in
+     * EMU. When a `\t` has no reachable explicit `a:tabLst` stop, it advances to
+     * the next multiple of this grid (issue #1006). Absent ⇒ the renderer uses the
+     * PowerPoint universal default of 914400 EMU (1 inch). Omitted from JSON when
+     * the parser found no explicit value.
+     */
+    defTabSz?: number;
 }
 
 declare interface ParagraphBorders {
@@ -2808,6 +4384,38 @@ declare interface PatternFill {
     preset: string;
 }
 
+/** ECMA-376 §18.18.56 ST_PhoneticAlignment — how the furigana is aligned over
+ *  the base text. Absent on {@link PhoneticProperties} defaults to `'left'`. */
+declare type PhoneticAlignment = 'left' | 'center' | 'distributed' | 'noControl';
+
+/** ECMA-376 §18.4.3 `<phoneticPr>` — phonetic display properties. */
+declare interface PhoneticProperties {
+    /** Zero-based index into `Styles.fonts` (§18.18.32 ST_FontId). Out of bounds
+     *  falls back to font 0 (§18.4.3). Drives the furigana font size / family. */
+    fontId: number;
+    /** §18.18.57 — absent means `'fullwidthKatakana'` (schema default). */
+    type?: PhoneticType;
+    /** §18.18.56 — absent means `'left'` (schema default). */
+    alignment?: PhoneticAlignment;
+}
+
+/** ECMA-376 §18.4.6 `<rPh sb=".." eb="..">` — one furigana run. `sb`/`eb` are
+ *  zero-based character offsets into the base text; the hint `text` is shown
+ *  over base characters `[sb, eb)`. */
+declare interface PhoneticRun {
+    /** Zero-based start character offset into the base text (inclusive). */
+    sb: number;
+    /** Zero-based end character offset into the base text (exclusive). */
+    eb: number;
+    /** The phonetic hint text (e.g. the katakana reading). */
+    text: string;
+}
+
+/** ECMA-376 §18.18.57 ST_PhoneticType — the East-Asian character set the
+ *  furigana is displayed in. Absent on {@link PhoneticProperties} defaults to
+ *  `'fullwidthKatakana'` per the CT_PhoneticPr schema. */
+declare type PhoneticType = 'fullwidthKatakana' | 'halfwidthKatakana' | 'Hiragana' | 'noConversion';
+
 declare interface PictureElement {
     type: 'picture';
     x: number;
@@ -2883,6 +4491,13 @@ declare interface PictureElement {
     };
     /** a:blip > a:alphaModFix@amt as 0..1. Undefined = fully opaque. */
     alpha?: number;
+    /**
+     * ECMA-376 §20.1.8.23 `<a:duotone>` recolour, resolved to its two endpoint
+     * colours (through the slide theme). Undefined ⇒ no duotone. When present the
+     * renderer decodes the raster once, remaps it along the `clr1`→`clr2`
+     * luminance ramp, and caches the recoloured bitmap under a colour-suffixed key.
+     */
+    duotone?: Duotone;
     /**
      * `<p:spPr><a:custGeom>` clipping path. Same `PathCmd` model as
      * `ShapeElement.custGeom` (one entry per `<a:path>`; coords normalized
@@ -2930,9 +4545,19 @@ export declare namespace pptx {
         PptxTextRunInfo,
         TextRunCallback,
         buildPptxTextLayer,
+        buildPptxHighlightLayer,
+        PptxHighlightMatch,
+        PptxHighlightColors,
+        PptxMatchLocation,
+        FindMatch,
+        FindMatchesOptions,
         PresentationHandle,
         autoResize,
         AutoResizeOptions,
+        HyperlinkTarget,
+        openExternalHyperlink,
+        OoxmlError,
+        OoxmlErrorCode,
         Presentation,
         Slide,
         PptxComment,
@@ -2991,6 +4616,21 @@ declare interface PptxComment {
     text: string;
 }
 
+declare interface PptxHighlightColors {
+    match?: string;
+    active?: string;
+}
+
+declare interface PptxHighlightMatch {
+    slices: MatchRunSlice[];
+    active: boolean;
+}
+
+/** Where a pptx match lives: its 0-based slide index. */
+declare interface PptxMatchLocation {
+    slide: number;
+}
+
 /**
  * Headless PPTX rendering engine.
  *
@@ -3012,15 +4652,24 @@ declare class PptxPresentation {
     private _mode;
     private _presentation;
     private _meta;
+    /** Lazily-built `partName → slide index` map for internal hyperlink slide
+     *  jumps (IX-nav). Cleared on {@link destroy}; built on first
+     *  {@link getSlideIndexByPartName}/{@link resolveInternalTarget} from either
+     *  the parsed slides (main) or the worker meta's `partNames` (worker). */
+    private _slidePartIndex;
     private _mediaCache;
     private _imageCache;
+    /** Google-Fonts `FontFace` objects this deck preloaded into `document.fonts`
+     *  (main mode only — in worker mode the worker owns them and terminates with
+     *  its own FontFaceSet). Released in {@link destroy} so they do not leak into
+     *  the shared FontFaceSet for the lifetime of the SPA (deduped + refcounted in
+     *  core, so a web font shared with another open deck survives until both go). */
+    private _googleFontFaces;
     /** One stable closure per instance: the decoded-bitmap and SVG caches key on
      *  this identity to scope decodes per deck (so two open decks never swap
      *  images for a shared zip path like ppt/media/image1.png). Reusing the same
      *  reference across every render also lets those caches hit across slides. */
     private readonly _fetchImage;
-    private _workerReady;
-    private _workerReadyCallbacks;
     /** Opt-in OMML equation engine, injected once at {@link load}. Every
      *  `renderSlide` / `presentSlide` reuses it — equations render when present,
      *  and are skipped (engine tree-shaken) when omitted. */
@@ -3028,7 +4677,6 @@ declare class PptxPresentation {
     private constructor();
     /** Parse a PPTX from URL or ArrayBuffer. */
     static load(source: string | ArrayBuffer, opts?: LoadOptions): Promise<PptxPresentation>;
-    private _waitForWorker;
     private _parse;
     /** Total number of slides in the loaded presentation. */
     get slideCount(): number;
@@ -3069,6 +4717,44 @@ declare class PptxPresentation {
      * caller's policy (see {@link PptxViewer}'s `hiddenSlideMode` modes).
      */
     isHidden(slideIndex: number): boolean;
+    /** The per-slide `partName` array (`sldIdLst` order) from either the parsed
+     *  model (main) or the worker meta (worker). Backs the lazy part-index map. */
+    private _partNames;
+    /** Lazily build (and cache) the `partName → index` map. Nulled by
+     *  {@link destroy} so a reused reference never serves a stale deck's indices. */
+    private _partIndex;
+    /**
+     * Resolve a slide's OPC part name (e.g. `ppt/slides/slide3.xml`) to its
+     * 0-based index in `sldIdLst` order, or `undefined` when no slide has that
+     * part name. This is the map an internal hyperlink slide jump
+     * (`<a:hlinkClick action="ppaction://hlinksldjump" r:id>`, ECMA-376
+     * §21.1.2.3.5) resolves against: the click's rel Target names a slide part, and
+     * this turns it into the index a viewer can navigate to. Works in both `main`
+     * and `worker` mode (the part names ride along in the worker meta).
+     */
+    getSlideIndexByPartName(partName: string): number | undefined;
+    /**
+     * Resolve an internal hyperlink target string to a 0-based slide index, or
+     * `undefined` when it names no reachable slide. Handles both
+     * `<a:hlinkClick @action>` classes (§21.1.2.3.5):
+     *
+     *   - a **relative** show jump — `ppaction://hlinkshowjump?jump=firstslide |
+     *     lastslide | nextslide | previousslide` — resolved arithmetically from
+     *     `currentIndex` (clamped at the deck ends);
+     *   - a **specific** slide-part jump — `ppaction://hlinksldjump`, whose
+     *     resolved target is a slide-rel part name like `../slides/slide3.xml` —
+     *     resolved through {@link getSlideIndexByPartName}.
+     *
+     * `ref` is the internal reference a `HyperlinkTarget` of kind `'internal'`
+     * carries: the raw `ppaction://…` action string for a relative jump, or the
+     * resolved slide-part target string for a specific jump. A viewer's
+     * `onHyperlinkClick` default calls this with `ref` and the current slide, then
+     * navigates to the returned index.
+     *
+     * @param ref          the internal action/target string.
+     * @param currentIndex the 0-based slide the jump is relative to (default 0).
+     */
+    resolveInternalTarget(ref: string, currentIndex?: number): number | undefined;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement | OffscreenCanvas, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
     /**
@@ -3081,6 +4767,16 @@ declare class PptxPresentation {
      * when done, or its backing memory is held until GC.
      */
     renderSlideToBitmap(slideIndex: number, opts?: RenderSlideToBitmapOptions): Promise<ImageBitmap>;
+    /**
+     * IX6 — collect a slide's text-run geometry (`PptxTextRunInfo[]`) without
+     * painting a visible canvas. Works in BOTH modes: worker mode renders the
+     * slide off-thread and ships only the runs (no bitmap transfer); main mode
+     * renders to a throwaway offscreen canvas. Used by the find controller to scan
+     * every slide for matches. Run geometry is in CSS px (independent of dpr) and
+     * dimming does not move glyphs, so only `width` is threaded — matching the
+     * historical main-mode `_collectSlideRuns`.
+     */
+    collectSlideRuns(slideIndex: number, width?: number): Promise<PptxTextRunInfo[]>;
     /**
      * Extract raw media bytes for a zip path referenced by {@link MediaElement}.
      * Results are cached by path for the lifetime of this instance.
@@ -3095,6 +4791,23 @@ declare class PptxPresentation {
      * decoded lazily rather than inlined as base64 at parse time.
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
+    /**
+     * Project the presentation to GitHub-flavoured markdown: title slides become
+     * `#` headings, body shapes become nested bullets at each paragraph's `lvl`,
+     * tables become pipe tables, charts become summarised bullets, and speaker
+     * notes and comments are collated. Positioning, animations, images, and
+     * drawing detail are discarded — the projection is meant for AI ingestion and
+     * full-text search, not layout.
+     *
+     * Runs entirely in the worker off the archive opened at {@link load} (no
+     * re-copy of the file, no re-parse of the model on the main thread), so it
+     * works in BOTH `mode: 'main'` and `mode: 'worker'`.
+     *
+     * @example
+     * const pres = await PptxPresentation.load(buffer);
+     * const md = await pres.toMarkdown();
+     */
+    toMarkdown(): Promise<string>;
     /**
      * Render a slide and attach canvas-native playback controls for any
      * embedded audio/video. Returns a {@link PresentationHandle} that owns the
@@ -3106,7 +4819,7 @@ declare class PptxPresentation {
     destroy(): void;
 }
 
-declare class PptxScrollViewer {
+declare class PptxScrollViewer implements ZoomableViewer {
     private _pres;
     private readonly _injected;
     private readonly _opts;
@@ -3130,6 +4843,18 @@ declare class PptxScrollViewer {
      *  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;
+    /**
+     * IX9 F1 — a `setScale` factor requested BEFORE the base fit is established
+     * (pre-load, or a zero-width container), already clamped to
+     * `[zoomMin, zoomMax]`, or `null` when none is pending. The single-canvas
+     * viewers latch a pre-load `setScale` and honour it on the first render; the
+     * scroll viewers used to silently DROP it — the family-unified semantics are
+     * "latch and apply once the layout establishes". `relayout()` applies (and
+     * clears) this right after establishing the base, firing `onScaleChange` at
+     * application time; `getScale()` reports it while pending so the caller sees
+     * the same value a single-canvas viewer would show.
+     */
+    private _pendingScale;
     /** Live slots keyed by slide index. */
     private readonly _slots;
     /** Recyclable detached slots (canvas + textLayer reused across slides). */
@@ -3144,6 +4869,23 @@ declare class PptxScrollViewer {
      *  reporting an error so a rejection that lands after teardown is swallowed
      *  rather than surfaced to a `onError` on a dead viewer. */
     private _destroyed;
+    /**
+     * Concurrent-load latch (generation token). Every self-loading `load()`
+     * increments this and captures the value; after its engine finishes loading it
+     * re-checks the live value and BAILS (destroying its own just-loaded engine) if
+     * a newer `load()` has since started. Without it, two overlapping
+     * `load(A)`/`load(B)` calls race the WASM parse / worker init, and whichever
+     * RESOLVES last wins the swap — even the stale `load(A)` resolving after
+     * `load(B)`; the loser's freshly created engine (never installed, or installed
+     * then overwritten) then leaks its worker + pinned WASM allocation. The latch
+     * composes with SC20: the check runs AFTER the new engine loads but BEFORE the
+     * field assignment, `previous?.destroy()`, and the recycle/relayout post-load
+     * work, so a superseded load never touches `this._pres` nor frees the current
+     * (newer) engine. Only the self-loading path uses it — the injected path throws
+     * up-front and never reaches here. `destroy()` also bumps it so a load in flight
+     * at teardown is treated as superseded and its engine cleaned up.
+     */
+    private _loadGen;
     /** 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
@@ -3174,11 +4916,14 @@ declare class PptxScrollViewer {
      *  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;
+    /** Gesture-only pointer anchor for the NEXT `setScale`, in scrollHost-viewport
+     *  px (`{ x, y }` from the wheel event, relative to the scroll host's top-left).
+     *  Set by the Ctrl/⌘+wheel handler right before it calls `setScale` so the zoom
+     *  pivots on the cursor ("zoom toward the pointer") in BOTH axes; consumed and
+     *  cleared by `setScale`. `null` for every non-gesture source (the public
+     *  `setScale`, the +/- steppers, `fitWidth`/`fitPage`, the resize re-fit), which
+     *  keep the historical viewport-TOP re-anchor so their behaviour is unchanged. */
+    private _pendingZoomAnchor;
     /** Observes the container so a width change re-fits the base scale. Disconnected
      *  in `destroy()`. */
     private _resizeObserver;
@@ -3254,6 +4999,12 @@ declare class PptxScrollViewer {
      *  `_positionSlot` (the flush-left floor), and by `_syncSpacerWidth` (the spacer
      *  width). Resolved here (not stored) to mirror `_gap()`/`_pad()`. */
     private _padH;
+    /** Index of the slide whose slot spans content-offset `y` (largest `i` with
+     *  `offsets[i] <= y`), for the pointer-anchored zoom re-anchor. Mirrors the
+     *  `topIndex` search `computeVisibleRange` runs for the scrollTop, but for an
+     *  ARBITRARY content-y (the pointer, not the viewport top). Clamped into
+     *  `[0, n-1]`; a `y` below the first slide (inside the leading pad) yields 0. */
+    private _slideIndexAtOffset;
     private _range;
     private _syncSpacer;
     /** Horizontal scroll extent: the (uniform deck-wide) slide width plus both
@@ -3302,10 +5053,6 @@ declare class PptxScrollViewer {
      * 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;
@@ -3341,7 +5088,10 @@ declare class PptxScrollViewer {
      * `[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.
+     * fixed. A no-op when the clamped scale is unchanged. Called BEFORE the deck is
+     * loaded / the base fit is established, the clamped factor is LATCHED (IX9 F1,
+     * family-unified with the single-canvas viewers) and applied by `relayout()`
+     * once the layout establishes — `onScaleChange` fires then.
      *
      * 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
@@ -3362,6 +5112,39 @@ declare class PptxScrollViewer {
      * can no longer return below the floor to the original base fit through this API.
      */
     setScale(scale: number): void;
+    /** IX9 {@link ZoomableViewer} — the current zoom factor, where `1` = 100% (a
+     *  slide at its natural EMU→px size). This is the viewer's absolute `_scale`
+     *  (`slideWidth/EMU_PER_PX × _scale` is the drawn width), so it reads `1` at
+     *  true 100% and, after the initial fit-to-width, the base fit factor. Before
+     *  the fit is established it reports a latched pre-load `setScale` (IX9 F1) if
+     *  one is pending — matching what a single-canvas viewer would show — else `1`. */
+    getScale(): number;
+    /** IX9 {@link ZoomableViewer} — step up to the next rung of the shared zoom
+     *  ladder above the current factor (clamped to `zoomMax` by {@link setScale}). */
+    zoomIn(): void;
+    /** IX9 {@link ZoomableViewer} — step down to the next lower ladder rung. */
+    zoomOut(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit a slide's WIDTH to the container (the classic
+     * continuous-scroll "fit width"). Sets the scale to the width-fit base for the
+     * current container, then re-anchors + re-renders via {@link setScale}. Defers
+     * (no-op) while the container is unlaid-out. The `zoomMin`/`zoomMax` clamp still
+     * applies, so a fit below `zoomMin` pins to `zoomMin`.
+     */
+    fitWidth(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit a WHOLE slide (width and height) inside the
+     * container so one slide is visible without scrolling; takes the tighter of the
+     * width/height fit. Uses the deck-wide (uniform) slide size. Defers while
+     * unlaid-out.
+     */
+    fitPage(): void;
+    /** Shared fit for {@link fitWidth}/{@link fitPage}: the width-fit factor is the
+     *  established base (`_baseScale`); the page-fit additionally bounds by the
+     *  container height against the (uniform) slide height. Applies via
+     *  {@link setScale} so the flicker-free re-anchor / settle path and
+     *  `onScaleChange` all run. */
+    private _fit;
     /**
      * CSS preview of the visible window at the current `_scale` (design §7
      * mechanism 1), WITHOUT re-rendering. Slots leaving the window recycle normally;
@@ -3388,12 +5171,11 @@ declare class PptxScrollViewer {
     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. */
+     *  swap (main) / same-canvas transfer (worker). Both modes rebuild the text
+     *  overlay from the fresh render's run geometry (IX6 — worker mode collects the
+     *  runs off-thread via `_renderSlotBitmap`) and clear the preview transform.
+     *  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).
@@ -3435,6 +5217,31 @@ declare class PptxScrollViewer {
     scrollToSlide(index: number, opts?: {
         behavior?: 'auto' | 'smooth';
     }): void;
+    /**
+     * IX1 hyperlink click dispatch (mirrors {@link PptxViewer._onHyperlinkClick}).
+     * When the integrator supplies `opts.onHyperlinkClick` it OWNS the click (no
+     * default). Otherwise: an external link opens in a new tab via the shared,
+     * scheme-sanitised {@link openExternalHyperlink}; an internal slide jump scrolls
+     * to the target slide via {@link scrollToSlide} once the action resolves to a
+     * slide index (a jump resolving to no reachable slide is a safe no-op).
+     */
+    /**
+     * IX1 — the click handler passed to the text-layer overlay, or `undefined` when
+     * `enableHyperlinks` is `false`. This is the single gate that disables hyperlink
+     * interactivity: {@link buildPptxTextLayer} renders link runs exactly like plain
+     * runs when no handler is supplied, so no hit region, cursor, tooltip, listener,
+     * or navigation is wired (a custom `onHyperlinkClick` is suppressed too). When
+     * enabled, the returned handler dispatches through {@link _onHyperlinkClick}.
+     */
+    private _hyperlinkHandler;
+    private _onHyperlinkClick;
+    /** Populate an internal {@link HyperlinkTarget}'s `slideIndex` from its `ref`
+     *  via the engine's stamped part names. Relative `hlinkshowjump` verbs are
+     *  resolved against the slide currently at the viewport top
+     *  (`_range().topIndex`); a `../slides/slideN.xml` part target resolves through
+     *  the part-name map. An already-set index, an external target, and an
+     *  unresolvable ref all pass through unchanged (safe no-op). */
+    private _resolveInternalSlideIndex;
     /**
      * 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
@@ -3468,6 +5275,8 @@ declare class PptxScrollViewer {
     /* Excluded from this release type: baseScaleForTest */
     /* Excluded from this release type: renderEpochForTest */
     /* Excluded from this release type: resizeForTest */
+    /* Excluded from this release type: contentAtViewportYForTest */
+    /* Excluded from this release type: viewportYOfForTest */
     /**
      * 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
@@ -3520,9 +5329,10 @@ declare interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTe
     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). */
+    /** Per-slide transparent text-selection overlay. IX6 — works in BOTH render
+     *  modes: in worker mode the per-run geometry is collected off-thread and
+     *  shipped back beside the slide bitmap, so the overlay is populated identically
+     *  to main mode (no more empty overlay / one-time warning). */
     enableTextSelection?: boolean;
     /** Minimum zoom scale — a DIMENSIONLESS multiplier over the 96-dpi natural
      *  slide size (10% = 0.1), matching `DocxScrollViewer`. Default 0.1. */
@@ -3566,6 +5376,12 @@ declare interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTe
      *  `computeVisibleRange` (the first slide intersecting the viewport top,
      *  EXCLUDING overscan). */
     onVisibleSlideChange?: (topIndex: number, total: number) => void;
+    /** IX9 — fires whenever the zoom factor actually changes (`1` = 100% = a slide
+     *  at its natural EMU→px size): from {@link PptxScrollViewer.setScale},
+     *  `zoomIn`/`zoomOut`, `fitWidth`/`fitPage`, a Ctrl/⌘+wheel gesture, or a
+     *  container-resize re-fit. Named `onScaleChange` to match the single-canvas
+     *  viewers so all five share one notification shape. */
+    onScaleChange?: (scale: 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
@@ -3573,6 +5389,24 @@ declare interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTe
      *  crashing the loop. Without an `onError`, render failures are logged via
      *  `console.error` so they are never fully silent. */
     onError?: (err: Error) => void;
+    /**
+     * IX1 (design decision — NOT user-confirmed, integrator may veto). Fires on a
+     * hyperlink click in any mounted slide's text overlay (requires
+     * {@link enableTextSelection}). Default when omitted: external →
+     * {@link openExternalHyperlink} (new tab, sanitised, noopener); internal
+     * slide-jump → {@link scrollToSlide} once the action resolves to a slide index
+     * via {@link PptxPresentation.resolveInternalTarget} (a jump that resolves to
+     * no reachable slide is a safe no-op). When provided, the viewer calls this
+     * instead and takes NO default action.
+     */
+    onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: the overlay's link
+     *  spans are non-interactive, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal slide jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  but are inert, like plain text. */
+    enableHyperlinks?: boolean;
 }
 
 /** Information about a rendered text segment for building a transparent selection overlay. */
@@ -3605,6 +5439,14 @@ declare interface PptxTextRunInfo {
      * `vert="vert270"` → -90). The CSS overlay must add this to `rotation`.
      */
     textBodyRotation?: number;
+    /**
+     * Resolved hyperlink target for this run (IX1), classified into the shared
+     * {@link HyperlinkTarget} shape. Present only for runs whose `<a:rPr>` carried
+     * an `<a:hlinkClick>`; the overlay makes such spans clickable. The glyph
+     * drawing (colour + underline) is unaffected — this is metadata for the
+     * transparent overlay only.
+     */
+    hyperlink?: HyperlinkTarget;
 }
 
 /**
@@ -3617,9 +5459,18 @@ declare interface PptxTextRunInfo {
  *
  * For custom layouts (multi-canvas, thumbnails, scroll view) use PptxPresentation directly.
  */
-declare class PptxViewer {
+declare class PptxViewer implements ZoomableViewer {
     private readonly canvas;
     private readonly wrapper;
+    /**
+     * IX9 explicit zoom factor (`1` = 100% = the slide at its natural EMU→px
+     * width), or `null` when the caller has never invoked a zoom method. `null`
+     * preserves the pre-IX9 render path EXACTLY: the slide renders at `opts.width`
+     * (or `canvas.offsetWidth || 960` when unset), so default rendering is
+     * byte-identical. The first zoom call latches a number here, after which
+     * {@link _targetWidth} derives the render width from it.
+     */
+    private _scale;
     /** 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
@@ -3630,6 +5481,13 @@ declare class PptxViewer {
      *  (empty string if it was unset), restored on {@link destroy}. */
     private readonly _originalDisplay;
     private textLayer;
+    /** IX2 — the find-highlight overlay layer (always created, above the text
+     *  layer, `pointer-events:none`). */
+    private highlightLayer;
+    /** IX2 — find state (per-slide runs, matches, active cursor). */
+    private _find;
+    /** Private 2d context for measuring highlight text (own 1×1 canvas). */
+    private _measureCtx;
     private engine;
     private readonly opts;
     private currentSlide;
@@ -3640,14 +5498,39 @@ declare class PptxViewer {
      *  render path. The media-playback path keeps a 2d context (via presentSlide),
      *  so this is obtained only when worker mode renders without media playback. */
     private _bitmapCtx;
-    private _warnedNoTextSelection;
+    /** Set by {@link destroy} (first line). Guards {@link _reportRenderError} so a
+     *  render rejection that lands AFTER teardown is swallowed rather than surfaced
+     *  to an `onError` / `console.error` on a dead viewer — parity with the scroll
+     *  viewers' `_destroyed` flag. */
+    private _destroyed;
+    /**
+     * Concurrent-load latch (generation token). Every {@link load} increments this
+     * and captures the value; after its engine finishes loading it re-checks the
+     * live value and BAILS (destroying its own just-loaded engine) if a newer
+     * `load()` has since started. Without it, two overlapping `load(A)`/`load(B)`
+     * calls race the WASM parse / worker init, and whichever RESOLVES last wins the
+     * swap — even the stale `load(A)` resolving after `load(B)`; the loser's freshly
+     * created engine (never installed, or installed then overwritten) then leaks its
+     * worker + pinned WASM allocation. The latch composes with SC20: the check runs
+     * AFTER the new engine loads but BEFORE the field assignment and
+     * `previous?.destroy()`, so a superseded load never touches `this.engine` nor
+     * frees the current (newer) engine. {@link destroy} also bumps it so a load in
+     * flight at teardown is treated as superseded and its engine cleaned up.
+     */
+    private _loadGen;
     constructor(canvas: HTMLCanvasElement, opts?: PptxViewerOptions);
     /**
      * Load a PPTX from URL or ArrayBuffer and render the first slide.
      *
-     * Error contract (shared by all three viewers): on failure, if an `onError`
-     * callback was provided it is invoked and `load` resolves normally; if not,
-     * the error is rethrown so it is never silently swallowed.
+     * Error contract (shared by all three viewers):
+     * - Parse/load failure (the underlying `PptxPresentation.load()` call itself
+     *   rejects): if an `onError` callback was provided it is invoked and `load`
+     *   resolves normally; if not, the error is rethrown so it is never silently
+     *   swallowed.
+     * - Render failure (the first slide fails to draw AFTER a successful
+     *   parse/load): routed to the shared `_reportRenderError` contract (`onError`
+     *   if provided, else `console.error` — never silent) and `load` still
+     *   RESOLVES, matching every subsequent navigation call.
      */
     load(source: string | ArrayBuffer): Promise<void>;
     /** Navigate to a specific slide (0-indexed). */
@@ -3680,8 +5563,124 @@ declare class PptxViewer {
     getNotes(slideIndex: number): string | null;
     /** The underlying <canvas> element. */
     get canvasElement(): HTMLCanvasElement;
+    /** Natural (100%) CSS-px width of a slide — `slideWidth(EMU) / EMU_PER_PX`.
+     *  0 when nothing is loaded. The scale-1 reference every zoom factor
+     *  multiplies. */
+    private _naturalWidthPx;
+    /**
+     * The width (CSS px) the render paths draw the slide at, honouring the zoom
+     * state. `_scale === null` (no zoom method ever called) ⇒ the pre-IX9 value
+     * `opts.width ?? (canvas.offsetWidth || 960)` verbatim (byte-identical
+     * default). Once a factor latched ⇒ `naturalWidth × scale` (rounded), so the
+     * slide is exactly `scale ×` its natural size regardless of `opts.width`.
+     */
+    private _targetWidth;
+    /** IX9 {@link ZoomableViewer} — the current zoom factor (`1` = 100%). Before
+     *  any zoom method is called this is the EFFECTIVE scale implied by the render
+     *  width: `targetWidth / naturalWidth`, or `1` when nothing is loaded. */
+    getScale(): number;
+    private _zoomMin;
+    private _zoomMax;
+    /**
+     * IX9 {@link ZoomableViewer} — set the absolute zoom factor (`1` = 100% = the
+     * slide at its natural EMU→px width), clamped to `[zoomMin, zoomMax]`, and
+     * re-render the current slide at the new size. Fires `onScaleChange` when the
+     * clamped factor actually changes. Resolves once the re-render settles.
+     */
+    setScale(scale: number): Promise<void>;
+    /** IX9 {@link ZoomableViewer} — step up to the next rung of the shared zoom
+     *  ladder (clamped to `zoomMax`). */
+    zoomIn(): Promise<void>;
+    /** IX9 {@link ZoomableViewer} — step down to the next lower ladder rung. */
+    zoomOut(): Promise<void>;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the current slide's WIDTH to the host
+     * container (the element the canvas lives in), then re-render. Defers (no-op)
+     * when nothing is loaded or the container is unlaid-out. Routes through
+     * {@link setScale}.
+     */
+    fitWidth(): Promise<void>;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the WHOLE current slide (width and height)
+     * inside the container so it is fully visible; takes the tighter of the
+     * width/height fit. Defers when unloaded / unlaid-out.
+     */
+    fitPage(): Promise<void>;
+    /** Shared fit for {@link fitWidth}/{@link fitPage}: measure the natural slide
+     *  size + the container box, ask core's pure `fitScale`, apply via setScale. */
+    private _fit;
     private renderCurrentSlide;
+    /** Draw the find-highlight boxes for the current slide from its runs. */
+    private _buildHighlightLayer;
+    /** A width-measurer primed with `font`, backed by a private 1×1 canvas. */
+    private _measureForFont;
+    /** IX6 — collect a slide's runs for search without touching the visible
+     *  canvas. Delegates to `collectSlideRuns`, which works in BOTH modes (worker:
+     *  off-thread, ships only the runs; main: throwaway offscreen canvas). Used for
+     *  slides other than the one on screen. */
+    private _collectSlideRuns;
+    /**
+     * IX2 — find every occurrence of `query` across all slides and highlight them
+     * (a soft box per match on the highlight overlay). Returns every match in
+     * document order, each tagged with its `{ slide }` (0-based). Case-insensitive
+     * by default; pass `{ caseSensitive: true }` for an exact match.
+     *
+     * Scans all slides (each rendered once offscreen to read its text; the visible
+     * slide reuses its on-screen render). IX6 — works in BOTH `mode: 'main'` and
+     * `mode: 'worker'`: in worker mode each slide's run geometry is collected
+     * off-thread and shipped back, so find returns the same matches on the same
+     * code path. An empty query clears the find.
+     */
+    findText(query: string, opts?: FindMatchesOptions): Promise<FindMatch<PptxMatchLocation>[]>;
+    /**
+     * IX2 — move to the next match (wrap-around), navigating to its slide if
+     * needed, and draw it in the active-match colour. Returns the now-active
+     * match, or `null` when there are none. Call {@link findText} first.
+     */
+    findNext(): Promise<FindMatch<PptxMatchLocation> | null>;
+    /** IX2 — move to the previous match (wrap-around). */
+    findPrev(): Promise<FindMatch<PptxMatchLocation> | null>;
+    /** IX2 — clear all highlights and reset the find state. */
+    clearFind(): void;
+    private _activateMatch;
+    /** Rebuild the highlight overlay for the current slide from cached runs. */
+    private _redrawHighlights;
     private _buildTextLayer;
+    /**
+     * IX1 — the click handler passed to the text-layer overlay, or `undefined` when
+     * `enableHyperlinks` is `false`. This is the single gate that disables hyperlink
+     * interactivity: {@link buildPptxTextLayer} renders link runs exactly like plain
+     * runs when no handler is supplied, so no hit region, cursor, tooltip, listener,
+     * or navigation is wired (a custom `onHyperlinkClick` is suppressed too). When
+     * enabled, the returned handler dispatches through {@link _onHyperlinkClick}.
+     */
+    private _hyperlinkHandler;
+    /**
+     * IX1/IX-nav hyperlink click dispatch. An internal target is first *enriched*
+     * with its resolved 0-based `slideIndex` (via
+     * {@link PptxPresentation.resolveInternalTarget}, relative to the current
+     * slide) so a jump verb / slide-part ref arrives already mapped — this is the
+     * field that was previously always `undefined`. When the integrator supplies
+     * `opts.onHyperlinkClick` it OWNS the (enriched) click and takes NO default
+     * action. Otherwise the viewer's default policy applies: an external link
+     * opens in a new tab via the shared, scheme-sanitised
+     * {@link openExternalHyperlink}; an internal slide jump navigates via
+     * {@link goToSlide} to the resolved index (a target that resolves to no
+     * reachable slide is a safe no-op).
+     */
+    private _onHyperlinkClick;
+    /** Populate an internal {@link HyperlinkTarget}'s `slideIndex` from its `ref`
+     *  (a `ppaction://hlinkshowjump?jump=…` verb resolved relative to the current
+     *  slide, or a `../slides/slideN.xml` part target resolved through the stamped
+     *  part-name map — no filename-suffix heuristic). Any already-set `slideIndex`
+     *  is kept; an external target and an unresolvable ref pass through unchanged so
+     *  the caller no-ops safely. */
+    private _resolveInternalSlideIndex;
+    /** PD14 render-error contract: route a render failure to `onError`, or
+     *  `console.error` when none is given (never fully silent), and never after
+     *  teardown. Mirrors the scroll viewers' `_reportRenderError` so all three
+     *  single-canvas viewers agree. */
+    private _reportRenderError;
     /**
      * Clean up the viewer and terminate the background worker.
      *
@@ -3699,6 +5698,17 @@ declare interface PptxViewerOptions extends RenderOptions, LoadOptions {
     onSlideChange?: (index: number, total: number) => void;
     /** Called on parse or render errors */
     onError?: (err: Error) => void;
+    /** IX9 zoom contract ({@link ZoomableViewer}) — the clamp range for
+     *  {@link PptxViewer.setScale} / `zoomIn` / `zoomOut` / `fitWidth` / `fitPage`,
+     *  as user-facing zoom factors (`1` = 100% = the slide at its natural
+     *  EMU→px size). Defaults 0.1–4 (10%–400%), matching the other viewers. */
+    zoomMin?: number;
+    zoomMax?: number;
+    /** IX9 — fires whenever the zoom factor actually changes (`1` = 100%): from
+     *  {@link PptxViewer.setScale}, `zoomIn`/`zoomOut`, or `fitWidth`/`fitPage`.
+     *  Named `onScaleChange` to match the docx/xlsx viewers so all five share one
+     *  notification shape. */
+    onScaleChange?: (scale: number) => void;
     /**
      * Enable interactive audio/video playback. When true, slides are rendered
      * via {@link PptxPresentation.presentSlide} so media elements become
@@ -3730,6 +5740,25 @@ declare interface PptxViewerOptions extends RenderOptions, LoadOptions {
      * in sync if {@link DimOptions} gains a field.
      */
     hiddenSlideDim?: Partial<DimOptions>;
+    /**
+     * IX1 (design decision — NOT user-confirmed, integrator may veto). Fires on a
+     * hyperlink click (a text run whose `<a:rPr>` carried an `<a:hlinkClick>`;
+     * requires {@link enableTextSelection} so the overlay spans exist). Default
+     * when omitted: external → {@link openExternalHyperlink} (new tab, sanitised,
+     * noopener); internal slide-jump → {@link goToSlide} once the action resolves
+     * to a slide index via {@link PptxPresentation.resolveInternalTarget} (a jump
+     * that resolves to no reachable slide is a safe no-op). When provided, the
+     * viewer calls this instead and takes NO default action.
+     */
+    onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: the overlay's link
+     *  spans are non-interactive, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal slide jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  (theme `hlink` colour + underline are painted on the canvas) but are inert,
+     *  like plain text. */
+    enableHyperlinks?: boolean;
 }
 
 declare interface Presentation {
@@ -3760,6 +5789,22 @@ declare interface PresentationHandle {
     destroy(): void;
 }
 
+/** ECMA-376 §17.3.3.23 `<w:ptab>` — an absolute-position tab. Advances to a
+ *  position derived from {@link PTabRun.alignment} and {@link PTabRun.relativeTo},
+ *  independent of the paragraph's custom tab stops / default-tab interval. */
+declare interface PTabRun {
+    /** ST_PTabAlignment (§17.18.71): where on the line the tab lands, and how the
+     *  following text aligns to it. */
+    alignment: 'left' | 'center' | 'right';
+    /** ST_PTabRelativeTo (§17.18.73): the base the position is measured from —
+     *  the text margins or the paragraph indents. */
+    relativeTo: 'margin' | 'indent';
+    /** ST_PTabLeader (§17.18.72): the character repeated to fill the tab gap. */
+    leader: 'none' | 'dot' | 'hyphen' | 'underscore' | 'middleDot';
+    /** Resolved run font size (pt) — matches the surrounding text's leader/gap. */
+    fontSize: number;
+}
+
 /** ECMA-376 §20.1.8.27 (CT_ReflectionEffect) — mirrored copy below the
  *  shape with a linear alpha gradient. Carries the spec attributes whose
  *  defaults the renderer needs to interpret correctly. */
@@ -3821,7 +5866,10 @@ declare interface RenderPageOptions {
     width?: number;
     dpr?: number;
     defaultTextColor?: string;
-    /** Called for each rendered text segment. Used to build a transparent text selection overlay. */
+    /** Called for each rendered text segment. Used to build a transparent text
+     *  selection overlay. On a vertical (§17.6.20 tbRl) page `x`/`y` are the
+     *  PHYSICAL top-left and `transform` is the CSS rotation the overlay span
+     *  applies about its top-left; absent for horizontal pages. */
     onTextRun?: (run: {
         text: string;
         x: number;
@@ -3830,12 +5878,27 @@ declare interface RenderPageOptions {
         h: number;
         fontSize: number;
         font: string;
+        transform?: string;
     }) => void;
     /** Default `true`. When false, ECMA-376 §17.13.5 track-changes runs render
      *  in their normal style (no author colour, no underline / strikethrough)
      *  — equivalent to Word's "Final / No Markup" view. */
     showTrackChanges?: boolean;
-}
+    /** ECMA-376 §17.16.5.16 DATE / §17.16.5.72 TIME — the "current" instant a
+     *  DATE/TIME field formats through its `\@` date picture (§17.16.4.1). A `Date`
+     *  or epoch-ms number. Default = the real current time at render. Set a fixed
+     *  value for deterministic / reproducible DATE/TIME field output. */
+    currentDate?: Date | number;
+}
+
+/** IX6 — options for {@link DocxDocument.renderPageToBitmap}: the serializable
+ *  render knobs plus an OPTIONAL `onTextRun`. The callback stays main-thread (it
+ *  never crosses the wire); in worker mode the proxy invokes it with the runs
+ *  the worker shipped back beside the bitmap, so a caller gets the selection /
+ *  find geometry on the same path in both modes. */
+declare type RenderPageToBitmapOptions = WireRenderPageOptions & {
+    onTextRun?: (run: DocxTextRunInfo) => void;
+};
 
 /**
  * Render a single slide onto a <canvas> element.
@@ -3870,6 +5933,14 @@ declare interface RenderSlideToBitmapOptions {
     /* Excluded from this release type: skipMediaControls */
     /** Translucent overlay drawn over the finished slide (hidden-slide dimming). */
     dim?: DimOptions;
+    /**
+     * IX6 — receives the slide's text-run geometry (the same stream `renderSlide`
+     * emits in main mode). Stays main-thread (never crosses the wire); in worker
+     * mode the proxy invokes it with the runs the worker shipped back beside the
+     * bitmap, so a caller builds the selection / find overlay on the SAME code
+     * path in both modes.
+     */
+    onTextRun?: TextRunCallback;
 }
 
 declare interface RenderViewportOptions {
@@ -3925,6 +5996,20 @@ declare type ResolvedList = {
     formula: string;
 };
 
+/**
+ * Resolve every `{ type: 'shared', si }` cell in `ws` to a concrete
+ * `{ type: 'text', text, runs? }` by looking `si` up in the workbook
+ * `sharedStrings` table (ECMA-376 §18.4.8). Mutates cells in place and returns
+ * `ws` for chaining. Out-of-range / missing `si` resolves to empty text —
+ * matching the parser's historical fallback. Idempotent: a `Worksheet` with no
+ * `shared` cells is returned unchanged.
+ *
+ * This keeps the dedup win on the wire (each shared string ships ONCE in the
+ * workbook) while every downstream consumer — renderer, formula engine, number
+ * formatter, markdown — still sees fully-resolved cell text.
+ */
+declare function resolveSharedStrings(ws: Worksheet, sharedStrings: SharedString[]): Worksheet;
+
 /**
  * 3D rotation in sphere coordinates — ECMA-376 §20.1.5.11 (`CT_SphereCoords`).
  * Angles are in **degrees** (the XML carries 60000ths of a degree; the parser
@@ -3944,12 +6029,26 @@ declare interface Row {
     index: number;
     height: number | null;
     cells: Cell[];
+    /** Outline (grouping) depth 0-7 (ECMA-376 §18.3.1.73 `<row outlineLevel>`).
+     *  Omitted on the wire when `0` (ungrouped); read as `outlineLevel ?? 0`. */
+    outlineLevel?: number;
+    /** `<row collapsed>` (§18.3.1.73): `true` on a summary row whose
+     *  one-level-deeper detail rows are collapsed. Omitted when false. */
+    collapsed?: boolean;
+    /** `<row hidden>` (§18.3.1.73): `true` when the row is hidden — most often
+     *  because a collapsed outline hides its detail rows. Distinct from
+     *  `height === 0`. Omitted on the wire when false. */
+    hidden?: boolean;
 }
 
 declare interface RubyAnnotation {
     text: string;
     /** Annotation font size in pt. Word stores this as half-points in `<w:hps>`. */
     fontSizePt: number;
+    /** Distance “between the phonetic guide base text and the phonetic guide
+     *  text” in pt. Word stores this as half-points in `<w:hpsRaise>`
+     *  (ECMA-376 §17.3.3.12). */
+    hpsRaisePt?: number;
 }
 
 declare interface Run {
@@ -4025,6 +6124,13 @@ declare interface SecondaryValueAxis {
     lineHidden: boolean;
     /** `<c:majorTickMark>` — "cross" (default) | "out" | "in" | "none". */
     majorTickMark: string;
+    /**
+     * `<c:valAx><c:majorUnit val>` (§21.2.2.103) — explicit distance between
+     * major ticks/gridlines on THIS secondary axis, overriding the Excel-style
+     * auto "nice" step. null/undefined ⇒ auto step (byte-stable). Symmetric with
+     * {@link ChartModel.valAxisMajorUnit} on the primary axis.
+     */
+    majorUnit?: number | null;
     /** `<c:title>` run-prop font size (hpt). */
     titleFontSizeHpt?: number | null;
     /** `<c:title>` run-prop bold flag. */
@@ -4077,6 +6183,17 @@ declare interface SectionProps {
      *  spec default). Non-final sections carry their start type on their own
      *  SectionBreak marker. */
     sectionStart?: string | null;
+    /** ECMA-376 §17.6.20 `<w:textDirection w:val>` — the section's flow direction,
+     *  using the TRANSITIONAL ST_TextDirection enum Word writes (Part 4 §14.11.7:
+     *  `lrTb`|`tbRl`|`btLr`|`lrTbV`|`tbLrV`|`tbRlV`), NOT the Part 1 §17.18.93
+     *  Strict set. Absent / `null` ⇒ "lrTb" (horizontal, left→right / top→bottom,
+     *  the default). `"tbRl"` = vertical Japanese (glyphs stack top→bottom, lines
+     *  advance right→left); the renderer (see `isVerticalSection`) lays the page out
+     *  horizontally and rotates it +90° at paint for the vertical values
+     *  (`tbRl`/`tbRlV`/`tbLrV`), keeping CJK glyphs upright and Latin sideways. Only
+     *  a non-default value is emitted by the parser, so horizontal documents keep
+     *  byte-identical rendering. */
+    textDirection?: string | null;
     /** ECMA-376 §17.6.5 w:docGrid/@w:type — "default" | "lines" | "linesAndChars" | "snapToChars". */
     docGridType?: string | null;
     /** ECMA-376 §17.6.5 w:docGrid/@w:linePitch in pt. When docGridType is "lines" or
@@ -4095,6 +6212,23 @@ declare interface SectionProps {
      *  body text flows top-to-bottom through `count` columns (newspaper fill);
      *  see {@link computeColumns}. */
     columns?: ColumnsSpec | null;
+    /** ECMA-376 §17.6.12 `<w:pgNumType>` — the body (final) section's page-numbering
+     *  settings (start / fmt). `null`/absent ⇒ numbering continues; decimal. The
+     *  renderer resolves the displayed page number per physical page from this plus
+     *  the per-section `SectionBreak.pageNumType` markers. */
+    pageNumType?: PageNumType | null;
+    /** ECMA-376 §17.6.10 `<w:pgBorders>` — page borders for this section.
+     *  `null`/absent ⇒ no page border (the common case). */
+    pageBorders?: PageBorders | null;
+    /** ECMA-376 §17.6.8 `<w:lnNumType>` — line numbering for this section.
+     *  `null`/absent ⇒ line numbering off. */
+    lineNumbering?: LineNumbering | null;
+    /** ECMA-376 §17.6.23 `<w:vAlign w:val>` — body vertical alignment between the
+     *  top/bottom margins ("top" | "center" | "both" | "bottom"). `null`/absent ⇒
+     *  "top" (body flows from the top margin unchanged). "both" (vertical
+     *  justification) is parsed but rendered as "top" until distribution is
+     *  implemented (see renderer note). */
+    vAlign?: string | null;
 }
 
 declare type SelectionMode_2 = 'cells' | 'rows' | 'cols' | 'all';
@@ -4188,6 +6322,23 @@ declare interface ShapeElement {
     /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
      *  rendered in Phase A. */
     sp3d?: Sp3d;
+    /** `<p:nvSpPr><p:cNvPr @id>` — DrawingML cNvPr id. Present for file-authored
+     *  shapes (the attribute is schema-required); absent on parser-synthesized
+     *  shapes such as the SmartArt data-model fallback. */
+    id?: string;
+    /** `<p:nvSpPr><p:cNvPr @name>` — author-visible shape name (e.g. "Title 1").
+     *  The SmartArt data-model fallback synthesizes `name: "SmartArt"` with no
+     *  {@link ShapeElement.id} (see smartart-fallback-contrast.ts). */
+    name?: string;
+    /** Shape-level hyperlink target resolved from `<p:cNvPr><a:hlinkClick @r:id>`
+     *  via slide _rels (ECMA-376 §21.1.2.3.5). For an external link this is the
+     *  URL; for an internal slide jump it is the resolved internal part name.
+     *  Undefined when the shape carries no hlinkClick. */
+    hyperlink?: string;
+    /** Raw `<a:hlinkClick @action>` (e.g. `"ppaction://hlinksldjump"`) when the
+     *  shape link is an internal PowerPoint action rather than an external URL.
+     *  Undefined when absent. */
+    hyperlinkAction?: string;
 }
 
 declare type ShapeFill = {
@@ -4238,6 +6389,12 @@ declare type ShapeGeom = {
         r: number;
         b: number;
     };
+    /** ECMA-376 §20.1.8.6 `<a:alphaModFix@amt>` opacity fraction (0..1) on the
+     *  leaf pic. Absent ⇒ opaque. Applied via `globalAlpha`. */
+    alpha?: number;
+    /** ECMA-376 §20.1.8.23 `<a:duotone>` recolour on the leaf pic. Absent ⇒
+     *  no effect. */
+    duotone?: Duotone_2;
 };
 
 declare interface ShapeInfo {
@@ -4322,7 +6479,7 @@ declare interface ShapeRun {
     groupHeightPt?: number | null;
     /** Draw behind text when true (wp:anchor behindDoc="1"). */
     behindDoc?: boolean;
-    /** Document-order index within a group; lower values render first. */
+    /** ECMA-376 §20.4.2.3 `wp:anchor/@relativeHeight`: lower values render first. */
     zOrder: number;
     /** Normalized [0,1] custom-geometry sub-paths. Empty when `presetGeometry`
      *  is set; the renderer chooses between buildCustomPath and buildShapePath. */
@@ -4330,8 +6487,10 @@ declare interface ShapeRun {
     /** OOXML <a:prstGeom prst> name (e.g. "rect", "ellipse", "rtTriangle").
      *  When set the renderer calls core's buildShapePath with `adjValues`. */
     presetGeometry?: string | null;
-    /** Up to four <a:gd name="adj{n}"> values from prstGeom/avLst (0–100000). */
-    adjValues?: number[];
+    /** <a:gd name="adj{n}"> values from prstGeom/avLst in adj1..adj8 order.
+     *  `null` preserves omitted named guides so the preset engine can use the
+     *  geometry's default for that index. */
+    adjValues?: Array<number | null>;
     fill: ShapeFill | null;
     stroke: string | null;
     strokeWidth?: number;
@@ -4360,6 +6519,15 @@ declare interface ShapeRun {
     wrapSide?: string | null;
     /** Text rendered INSIDE the shape's bounding box (`<wps:txbx><w:txbxContent>`). */
     textBlocks?: ShapeText_2[];
+    /** ECMA-376 §20.1.4.1.17 `<wps:style><a:fontRef>` — the shape's DEFAULT text
+     *  color (hex, no `#`). A text-box run ({@link ShapeTextRun}) with no explicit
+     *  {@link ShapeTextRun.color} inherits this before falling back to the
+     *  document/theme default (black); an explicit run color still wins. This is
+     *  the color axis of the fontRef only — the `@idx` (major/minor/none) font-face
+     *  selection is out of scope (fonts resolve via rFonts/docDefaults). Mirrors
+     *  pptx's per-shape default text color from the placeholder fontRef. Absent ⇒
+     *  no shape default (the run color or black applies). */
+    defaultTextColor?: string | null;
     /** "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
@@ -4372,6 +6540,24 @@ declare interface ShapeRun {
     textInsetT?: number;
     textInsetR?: number;
     textInsetB?: number;
+    /** ECMA-376 §20.1.10.83 ST_TextVerticalType — the text-body flow direction from
+     *  `<wps:bodyPr vert>` / `<a:bodyPr vert>`. Recognised vertical values:
+     *  "vert" (all glyphs 90° CW, chars T→B, lines R→L), "vert270" (all glyphs 270°
+     *  CW = 90° CCW, chars B→T, lines L→R), and "eaVert" (East-Asian upright: CJK
+     *  stands upright, non-EA rotated 90°, chars T→B, lines R→L). "horz"/absent ⇒
+     *  horizontal (unchanged). Unrecognised values ("mongolianVert", "wordArtVert",
+     *  …) fall back to horizontal until implemented. */
+    textVert?: string | null;
+    /** ECMA-376 Part 4 §19.1.2.23 `<v:textpath>` — WordArt text laid on the
+     *  shape path (a text watermark). When set the renderer draws this string,
+     *  scaled to fill the box (`fitshape`), rotated by {@link ShapeRun.rotation},
+     *  filled with {@link ShapeRun.fill} at {@link ShapeRun.fillOpacity} alpha —
+     *  INSTEAD of a fill/stroke panel + body text. */
+    textPath?: TextPath | null;
+    /** ECMA-376 Part 4 §19.1.2.5 `<v:fill opacity>` — fill alpha in `[0, 1]`
+     *  (default 1 = opaque). Used with {@link ShapeRun.textPath} to draw the
+     *  watermark semi-transparently. Absent ⇒ opaque. */
+    fillOpacity?: number | null;
 }
 
 declare interface ShapeText {
@@ -4417,6 +6603,8 @@ declare interface ShapeText_2 {
      *  (image blocks / legacy single-format paragraphs). Absent for image-only
      *  paragraphs. */
     runs?: ShapeTextRun_2[];
+    /** ECMA-376 §17.9 paragraph numbering for text-box paragraphs. */
+    numbering?: NumberingInfo | null;
     alignment: string;
     /** ECMA-376 §17.3.1.33 `<w:spacing w:before>` of this text-box paragraph, in
      *  pt — reserved ABOVE the paragraph inside the box. Absent/0 ⇒ no offset. */
@@ -4454,6 +6642,19 @@ declare interface ShapeText_2 {
      *  base direction for the UAX#9 reordering pass (the body renderer reads the
      *  identical field). */
     bidi?: boolean;
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — resolved through the style
+     *  chain in the parser. When set, this text-box paragraph drops its OWN
+     *  contribution to the collapsed gap against an ADJACENT paragraph that
+     *  shares its {@link ShapeText.styleId} (per-side, Word-adjudicated — issue
+     *  #1015; identical to {@link DocParagraph.contextualSpacing} via the
+     *  renderer's `contextualSpacingAdjust`). Absent ⇒ no suppression. */
+    contextualSpacing?: boolean;
+    /** Resolved paragraph style id of this text-box paragraph — the explicit
+     *  `<w:pStyle>`, else the document default paragraph style, else "Normal" (the
+     *  same stable id {@link DocParagraph.styleId} carries). Paired with
+     *  {@link ShapeText.contextualSpacing} to group adjacent same-style paragraphs
+     *  for §17.3.1.9. */
+    styleId?: string | null;
     /** 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. */
@@ -4525,11 +6726,19 @@ declare interface ShapeTextRun_2 {
     fontFamilyEastAsia?: string | null;
     bold?: boolean;
     italic?: boolean;
+    /** ECMA-376 §17.3.3.25 ruby annotation (furigana) for text-box runs. */
+    ruby?: RubyAnnotation | null;
 }
 
 declare interface SharedString {
     text: string;
     runs?: Run[];
+    /** ECMA-376 §18.4.6 phonetic runs (furigana). Absent when the `<si>` has no
+     *  `<rPh>`. */
+    phoneticRuns?: PhoneticRun[];
+    /** ECMA-376 §18.4.3 phonetic display properties. Absent when the `<si>` has
+     *  no `<phoneticPr>`. */
+    phoneticPr?: PhoneticProperties;
 }
 
 declare interface SheetMeta {
@@ -4572,6 +6781,17 @@ declare interface Slide {
     index: number;
     /** 1-based slide number (index + 1); used to render slidenum fields */
     slideNumber: number;
+    /**
+     * The slide's normalized OPC part name (e.g. `ppt/slides/slide3.xml`),
+     * resolved through `presentation.xml.rels` in `sldIdLst` order (ECMA-376
+     * §19.3.1.42). An internal hyperlink slide jump
+     * (`<a:hlinkClick action="ppaction://hlinksldjump" r:id>`, §21.1.2.3.5)
+     * carries a rel Target that resolves to this same part name — so
+     * {@link PptxPresentation.getSlideIndexByPartName} can turn a click into a
+     * slide index. Absent (`undefined`) only for a slide whose part path was not
+     * recorded; healthy and broken slides both carry it.
+     */
+    partName?: string;
     background: Fill | null;
     elements: SlideElement[];
     /**
@@ -4595,6 +6815,14 @@ declare interface Slide {
      * slide modes (read it via `PptxPresentation.isHidden`).
      */
     hidden?: boolean;
+    /**
+     * RB7 partial degradation: set when this slide's part could not be parsed. The
+     * deck still opens with the OTHER slides intact; this one is a placeholder
+     * (`elements` empty) whose `parseError` names the offending part (e.g.
+     * `"ppt/slides/slide3.xml: <detail>"`). Absent (`undefined`) for every healthy
+     * slide. The renderer paints a visible error box instead of slide content.
+     */
+    parseError?: string;
 }
 
 declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
@@ -4828,7 +7056,10 @@ declare interface TableRow {
 }
 
 declare interface TabStop {
-    /** Position in EMU from the left edge of the text area (after lIns) */
+    /** Position in EMU from the LEADING text-inset edge of the text area —
+     *  logical, not physical (ECMA-376 §21.1.2.1): the left edge (after lIns)
+     *  in an LTR paragraph, the right edge (before rIns) in an RTL
+     *  (`<a:pPr rtl="1">`) paragraph. */
     pos: number;
     /** Alignment: "l" | "r" | "ctr" | "dec" */
     algn: string;
@@ -4886,6 +7117,19 @@ declare interface TextBody extends TextBody_2 {
      * omitted from JSON when false. Only meaningful when `numCol > 1`.
      */
     rtlCol?: boolean;
+    /**
+     * `<a:bodyPr><a:prstTxWarp>` (ECMA-376 §20.1.9.19) — WordArt text warp. When
+     * present the renderer maps each glyph through the named envelope
+     * (presetTextWarpDefinitions) instead of laying text out flat. Omitted from
+     * JSON when the body has no warp, so unwarped bodies are byte-identical.
+     */
+    textWarp?: {
+        /** The `prst` name, e.g. `"textArchUp"`, `"textWave1"`. */
+        preset: string;
+        /** `<a:avLst>` adjust values (adj1, adj2, …) in thousandths of a percent.
+         *  Omitted when the author supplied none (preset defaults apply). */
+        adj?: number[];
+    };
     /**
      * Narrow the inherited `paragraphs` to the PPTX `Paragraph` so consumers see
      * the PPTX-only `eaLnBrk` flag. PPTX `Paragraph extends CoreParagraph`, so
@@ -4943,6 +7187,20 @@ declare interface TextOutline {
     color?: string;
 }
 
+/** ECMA-376 Part 4 §19.1.2.23 `<v:textpath>` — a WordArt vector text path,
+ *  emitted by Word for text watermarks (the `PowerPlusWaterMarkObject` shape).
+ *  The text is stretched to fit the shape box (`fitshape`, the WordArt
+ *  `#_x0000_t136` shapetype default), so its drawn size derives from the shape
+ *  geometry rather than the nominal `font-size` in the textpath style. */
+declare interface TextPath {
+    /** The `string` attribute — the watermark text (e.g. "DRAFT"). */
+    string: string;
+    /** `font-family` from the textpath style (quotes stripped). */
+    fontFamily?: string | null;
+    bold?: boolean;
+    italic?: boolean;
+}
+
 /** Absolute text-frame rectangle in EMU (from SmartArt `<dsp:txXfrm>`). */
 declare interface TextRect {
     x: number;
@@ -5018,10 +7276,19 @@ declare interface TextRunData {
     /** Set for OOXML field runs (e.g. "slidenum"). When set, renderer replaces text with field value. */
     fieldType?: string;
     /**
-     * Hyperlink target URL resolved from rPr > a:hlinkClick @r:id via the slide's _rels.
-     * Undefined for runs without a hyperlink. ECMA-376 §21.1.2.3.5 (CT_Hyperlink).
+     * Hyperlink target resolved from rPr > a:hlinkClick @r:id via the slide's _rels.
+     * For an external link this is the URL; for an internal slide jump it is the
+     * resolved internal part name (e.g. "../slides/slide3.xml"). Undefined for runs
+     * without a hyperlink. ECMA-376 §21.1.2.3.5 (CT_Hyperlink).
      */
     hyperlink?: string;
+    /**
+     * Raw `<a:hlinkClick @action>` string (e.g. "ppaction://hlinksldjump") when
+     * present — its presence marks {@link hyperlink} as an INTERNAL PowerPoint
+     * action (slide jump / first / last …) rather than an external URL. Undefined
+     * when the hlinkClick has no @action. ECMA-376 §21.1.2.3.5. (IX1)
+     */
+    hyperlinkAction?: string;
     /**
      * Run-level drop shadow on glyphs (`<a:rPr><a:effectLst><a:outerShdw>`),
      * ECMA-376 §20.1.8.45. Independent of the shape-level shadow on `spPr`.
@@ -5083,11 +7350,51 @@ declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
 
 /** Serializable subset of RenderViewportOptions: drop the callback, the image
  *  cache, and the `fetchImage` loader (all non-cloneable; the worker owns its
- *  own cache and supplies its own in-worker fetchImage). */
-declare type WireRenderViewportOptions = Omit<RenderViewportOptions, 'onTextRun' | 'loadedImages' | 'fetchImage'>;
+ *  own cache and supplies its own in-worker fetchImage). Extended with the
+ *  optional {@link WireSizeOverrides} so view-only size mutations reach the
+ *  worker's local sheet copy; absent (the common case) when nothing has been
+ *  resized or collapsed, keeping the wire payload unchanged. */
+declare type WireRenderViewportOptions = Omit<RenderViewportOptions, 'onTextRun' | 'loadedImages' | 'fetchImage'> & {
+    sizeOverrides?: WireSizeOverrides;
+};
+
+/**
+ * View-only per-band size overrides for one sheet, carried with every worker
+ * `renderViewport` request. The render worker draws from its own worker-local
+ * parsed-sheet cache, so main-thread Worksheet mutations (outline
+ * collapse/expand via the size-0 hidden encoding, drag-to-resize #567) never
+ * reach it on their own — without this channel the gutter/overlays update but
+ * the grid bitmap stays stale.
+ *
+ * Semantics: keys are 1-based band indices; a number is the band's current
+ * `rowHeights` / `colWidths` model value, `null` means "no entry — fall back
+ * to the sheet default". The main thread accumulates every band the user has
+ * touched this session (entries are updated in place, never removed), so
+ * re-applying the full map is idempotent and converges the worker's cached
+ * sheet to the main model even across worker-side re-parses.
+ */
+declare interface WireSizeOverrides {
+    rows?: Record<number, number | null>;
+    cols?: Record<number, number | null>;
+}
 
 declare interface Workbook {
     sheets: SheetMeta[];
+    /** Workbook date system (`<workbookPr date1904>`, ECMA-376 §18.2.28).
+     *  `true` selects the 1904 date system (Mac-authored workbooks); serial
+     *  dates are resolved against the 1904 epoch (§18.17.4.1). Omitted from the
+     *  parser JSON when false (default 1900 date system). */
+    date1904?: boolean;
+    /** #773 partial degradation: a WORKBOOK-LEVEL degradation that leaves every
+     *  sheet openable. Set when a shared workbook part was PRESENT but corrupt —
+     *  most commonly `xl/sharedStrings.xml` (§18.4.9): a broken shared-string table
+     *  silently blanks every string cell across ALL sheets, so unlike a per-sheet
+     *  break it can't be attributed to one placeholder sheet. Tagged with the
+     *  offending part (e.g. `"xl/sharedStrings.xml: <detail>"`) so the loss is
+     *  surfaced instead of silent, while every sheet still renders its non-string
+     *  content. Absent (`undefined`) when every shared part read cleanly. Also set
+     *  (`"(zip container): <detail>"`) for a whole-container degradation (#774). */
+    parseError?: string;
 }
 
 declare interface Worksheet {
@@ -5095,6 +7402,17 @@ declare interface Worksheet {
     rows: Row[];
     colWidths: Record<number, number>;
     rowHeights: Record<number, number>;
+    /** Per-column outline (grouping) depth 0-7 (ECMA-376 §18.3.1.13
+     *  `<col outlineLevel>`), keyed by 1-based column index. Present only for
+     *  grouped columns; absent (⇒ level 0) on outline-free sheets. */
+    colOutlineLevels?: Record<number, number>;
+    /** Per-column `<col collapsed>` (§18.3.1.13): `true` on a summary column whose
+     *  one-level-deeper detail columns are collapsed. Only `true` entries. */
+    colCollapsed?: Record<number, boolean>;
+    /** Per-column `<col hidden>` (§18.3.1.13): `true` when the column is hidden
+     *  (e.g. a collapsed outline hides its detail columns). Distinct from
+     *  `colWidths[c] === 0`. Only `true` entries. */
+    colHidden?: Record<number, boolean>;
     defaultColWidth: number;
     defaultRowHeight: number;
     mergeCells: MergeCell[];
@@ -5117,6 +7435,11 @@ declare interface Worksheet {
      *  grid so column A sits on the right (ECMA-376 §18.3.1.87
      *  `<sheetView rightToLeft>`). Defaults to false. */
     rightToLeft?: boolean;
+    /** Outline display flags from `<sheetPr><outlinePr>` (ECMA-376 §18.3.1.61).
+     *  Absent when the sheet declares no `<outlinePr>`; consumers apply the
+     *  schema defaults (`summaryBelow` / `summaryRight` both `true`). Decides
+     *  which side of a group the summary row/column (and its +/- toggle) sits. */
+    outlinePr?: OutlinePr;
     /** Sheet tab color (ECMA-376 §18.3.1.79). */
     tabColor?: string | null;
     /** AutoFilter header range (ECMA-376 §18.3.1.2). */
@@ -5160,6 +7483,17 @@ declare interface Worksheet {
     defaultFontFamily?: string;
     /** Point size of the workbook's Normal-style font (`<fonts>[N].sz.val`). */
     defaultFontSize?: number;
+    /** Workbook date system (`<workbookPr date1904>`, ECMA-376 §18.2.28),
+     *  denormalized onto every worksheet by the parser so the cell formatter can
+     *  resolve serial dates (§18.17.4.1) without a workbook back-reference.
+     *  `true` = 1904 date system. Omitted (⇒ false) for the default 1900 system. */
+    date1904?: boolean;
+    /** RB7 partial degradation: set when THIS sheet's part could not be
+     *  read/parsed. The workbook still opens with the OTHER sheets intact; this one
+     *  is an empty placeholder (`rows` empty) whose `parseError` names the offending
+     *  part (e.g. `"xl/worksheets/sheet3.xml: <detail>"`). Absent (`undefined`) for
+     *  every healthy sheet. The renderer paints a visible error overlay. */
+    parseError?: string;
 }
 
 export declare namespace xlsx {
@@ -5167,6 +7501,7 @@ export declare namespace xlsx {
         XlsxWorkbook,
         LoadOptions_3 as LoadOptions,
         WireRenderViewportOptions,
+        WireSizeOverrides,
         XlsxViewer,
         ResolvedList,
         XlsxViewerOptions,
@@ -5174,12 +7509,21 @@ export declare namespace xlsx {
         CellAddress,
         CellRange_2 as CellRange,
         SelectionMode_2 as SelectionMode,
+        XlsxMatchLocation,
+        FindMatch,
+        FindMatchesOptions,
         autoResize,
         AutoResizeOptions,
+        HyperlinkTarget,
+        openExternalHyperlink,
+        resolveSharedStrings,
+        OoxmlError,
+        OoxmlErrorCode,
         Workbook,
         SheetMeta,
         SheetVisibility,
         Worksheet,
+        OutlinePr,
         Row,
         Cell,
         CellValue,
@@ -5198,6 +7542,10 @@ export declare namespace xlsx {
         Run,
         RunFont,
         SharedString,
+        PhoneticRun,
+        PhoneticProperties,
+        PhoneticType,
+        PhoneticAlignment,
         Dxf,
         GradientFillSpec,
         ConditionalFormat,
@@ -5216,6 +7564,7 @@ export declare namespace xlsx {
         SparklineGroup,
         Sparkline,
         ImageAnchor,
+        Duotone_2 as Duotone,
         ChartAnchor,
         ShapeAnchor,
         ShapeInfo,
@@ -5266,6 +7615,20 @@ declare interface XlsxComment {
     text: string;
 }
 
+/** Where an xlsx match lives: the sheet, its name, and the cell (A1 + row/col). */
+declare interface XlsxMatchLocation {
+    /** 0-based sheet index. */
+    sheet: number;
+    /** The sheet's display name. */
+    sheetName: string;
+    /** A1 cell reference, e.g. `"B7"`. */
+    ref: string;
+    /** 1-based row. */
+    row: number;
+    /** 1-based column. */
+    col: number;
+}
+
 /** Emitted once per cell that has text, with the cell's canvas-pixel bounds. */
 declare interface XlsxTextRunInfo {
     text: string;
@@ -5281,13 +7644,53 @@ declare interface XlsxTextRunInfo {
     col: number;
 }
 
-declare class XlsxViewer {
+declare class XlsxViewer implements ZoomableViewer {
     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;
+    /** Region holding the outline gutters (top/left) and the inset {@link canvasArea}.
+     *  When the active sheet has no outlining the gutters collapse to 0 px and this
+     *  is a transparent pass-through, so an outline-free sheet lays out identically. */
+    private gridRegion;
+    /** Left gutter canvas: row group brackets + toggles (XL4). */
+    private rowGutter;
+    /** Top gutter canvas: column group brackets + toggles (XL4). */
+    private colGutter;
+    /** Top-left corner canvas: numbered level buttons (XL4). */
+    private cornerGutter;
+    /** Cached extents (unscaled CSS px) of the current sheet's gutters; both 0 for
+     *  an outline-free sheet. `w` insets {@link canvasArea} from the left, `h` from
+     *  the top. */
+    private gutter;
+    /** Per-axis outline layout (group brackets + toggles) for the current sheet,
+     *  recomputed on sheet switch and after each collapse/expand. `null` axis ⇒ no
+     *  outlining on that axis. */
+    private rowOutline;
+    private colOutline;
+    private rowOutlineBands;
+    private colOutlineBands;
+    /** Original row heights / column widths stashed the first time a band is
+     *  collapsed, so expanding restores a custom size rather than the default.
+     *  Keyed by band index; per current worksheet (cleared on sheet switch). */
+    private stashedRowHeights;
+    private stashedColWidths;
+    /**
+     * Per-sheet cumulative record of every view-only size mutation (outline
+     * collapse/expand, drag-to-resize #567), keyed by sheet index. Value = the
+     * band's current model size, or `null` when the model has no entry (default
+     * size). Serialized as {@link WireSizeOverrides} with every worker
+     * `renderViewport` so the worker's local sheet cache converges to the
+     * main-thread model — without it the worker keeps drawing the file's
+     * original sizes and the grid bitmap goes stale under the (up-to-date)
+     * gutter and overlays. Entries are updated in place and never removed
+     * (idempotent re-application); the whole store resets when a new workbook
+     * loads. Main mode never reads it (the main renderer draws from the mutated
+     * model directly).
+     */
+    private sizeOverrideStore;
     private canvasArea;
     private scrollHost;
     private spacer;
@@ -5311,6 +7714,26 @@ declare class XlsxViewer {
      *  holds one context type for its lifetime, so this is obtained once and the
      *  main-mode 2d render path is never used on the same canvas. */
     private _bitmapCtx;
+    /** Set by {@link destroy} (first line). Guards {@link _reportRenderError} so a
+     *  render rejection that lands AFTER teardown is swallowed rather than surfaced
+     *  to an `onError` / `console.error` on a dead viewer — parity with the scroll
+     *  viewers' `_destroyed` flag. */
+    private _destroyed;
+    /**
+     * Concurrent-load latch (generation token). Every {@link load} increments this
+     * and captures the value; after its workbook finishes loading it re-checks the
+     * live value and BAILS (destroying its own just-loaded workbook) if a newer
+     * `load()` has since started. Without it, two overlapping `load(A)`/`load(B)`
+     * calls race the WASM parse / worker init, and whichever RESOLVES last wins the
+     * swap — even the stale `load(A)` resolving after `load(B)`; the loser's freshly
+     * created workbook (never installed, or installed then overwritten) then leaks
+     * its worker + pinned WASM allocation. The latch composes with SC20: the check
+     * runs AFTER the new workbook loads but BEFORE the field assignment and
+     * `previous?.destroy()`, so a superseded load never touches `this.wb` nor frees
+     * the current (newer) workbook. {@link destroy} also bumps it so a load in
+     * flight at teardown is treated as superseded and its workbook cleaned up.
+     */
+    private _loadGen;
     private resizeObserver;
     /**
      * Pending `requestAnimationFrame` handle for a coalesced re-render, or `null`
@@ -5349,13 +7772,27 @@ declare class XlsxViewer {
      * strand the view at the sheet's far end once the host gains its real size.
      */
     private effectiveH;
+    /** Gesture-only pointer anchor for the NEXT `setScale`, in canvasArea-viewport
+     *  px (`{ x, y }` from the wheel event, relative to the grid's top-left). Set by
+     *  the Ctrl/⌘+wheel handler right before it calls `setScale` so the zoom pivots
+     *  on the cursor ("zoom toward the pointer") in BOTH axes, past the fixed
+     *  header + frozen-pane lead-in; consumed and cleared by `setScale`. `null` for
+     *  every non-gesture source (the public `setScale`, the +/- steppers, the zoom
+     *  slider, `fitWidth`/`fitPage`), which keep the historical START-anchored
+     *  (top-left) preservation so their behaviour is unchanged. */
+    private _pendingZoomAnchor;
     private anchorCell;
     private activeCell;
     private selectionMode;
     private isSelecting;
     private selectionOverlay;
+    /** IX2 — find-highlight overlay (matched-cell boxes). */
+    private findOverlay;
+    /** IX2 — find state (matches + active cursor). */
+    private _find;
     private keydownHandler;
     private pendingTap;
+    private pendingClick;
     private resizeDrag;
     /** DOM overlay element that shows the hovered cell's comment. Lives in
      *  canvasArea above the scrollHost; `pointer-events:none` so it never blocks
@@ -5363,6 +7800,11 @@ declare class XlsxViewer {
     private commentPopup;
     /** `"row:col"` → comment for the current sheet, rebuilt on every showSheet. */
     private commentMap;
+    /** IX1 — `"row:col"` → hyperlink for the current sheet, rebuilt on every
+     *  showSheet. Keys mirror the renderer's `hyperlinkMap` (1-based row/col, the
+     *  first cell of a hyperlink `ref` range per the parser), so a `getCellAt`
+     *  {row,col} looks up directly. */
+    private hyperlinkMap;
     /** `"row:col"` of the cell whose popup is currently shown (or pending), so a
      *  pointermove within the same cell doesn't restart the show timer. */
     private commentPopupKey;
@@ -5384,17 +7826,80 @@ declare class XlsxViewer {
      *  click; installed only while the panel is open. */
     private validationOutsideHandler;
     constructor(container: HTMLElement, opts?: XlsxViewerOptions);
+    /** Every non-empty cell of a sheet with its rendered display text (IX2 find
+     *  source). Reads the parsed worksheet model directly — no render — so search
+     *  covers the whole sheet, not just the on-screen viewport. */
+    private _collectSheetCells;
     /**
      * Load an XLSX from URL or ArrayBuffer and render the first sheet.
      *
-     * Error contract (shared by all three viewers): on failure, if an `onError`
-     * callback was provided it is invoked and `load` resolves normally; if not,
-     * the error is rethrown so it is never silently swallowed.
+     * Error contract (shared by all three viewers):
+     * - Parse/load failure (the underlying `XlsxWorkbook.load()` call itself
+     *   rejects): if an `onError` callback was provided it is invoked and `load`
+     *   resolves normally; if not, the error is rethrown so it is never silently
+     *   swallowed.
+     * - Render failure (the first sheet fails to draw AFTER a successful
+     *   parse/load): routed to the shared `_reportRenderError` contract (`onError`
+     *   if provided, else `console.error` — never silent) and `load` still
+     *   RESOLVES, matching every subsequent navigation call.
      */
     load(source: string | ArrayBuffer): Promise<void>;
     /** The loaded workbook, or throws if {@link load} has not completed. */
     private get workbook();
     showSheet(index: number): Promise<void>;
+    /** Recompute the per-axis outline layout for `ws` and cache the band lists.
+     *  Both axes are `null` (gutters collapse to 0) when the sheet has no
+     *  outlining, so an outline-free sheet is untouched. */
+    private buildOutline;
+    /** Size and place the three gutter canvases (corner / col / row) from the
+     *  current outline, and inset {@link canvasArea} by the gutter extents. When
+     *  neither axis is grouped both extents are 0 and canvasArea covers the whole
+     *  region — pixel-identical to a viewer built before XL4. */
+    private layoutGutters;
+    /** Paint all visible gutter strips for the current scroll offset. Called at the
+     *  end of every grid render so the brackets track scroll / zoom exactly. */
+    private renderGutters;
+    /** Draw one axis's group brackets and +/- toggles into its gutter canvas,
+     *  aligned to the on-screen band positions via {@link getCellRect}. */
+    private paintAxisGutter;
+    /** Draw a small square +/- toggle centered at (cx, cy) in gutter-canvas CSS px. */
+    private drawToggleBox;
+    /** Draw one numbered level button centered at (cx, cy) in gutter-canvas CSS
+     *  px. Shared by the row bank (in the row gutter's top strip) and the column
+     *  bank (in the column gutter's left strip). */
+    private drawLevelButton;
+    /** Paint the corner (intersection of the two gutters) as plain background.
+     *  The numbered level banks live in each axis gutter's own header strip
+     *  (see paintAxisGutter), so the corner carries no interactive content. */
+    private paintCornerGutter;
+    /** Handle a click in a row/col gutter: hit-test the +/- toggles and toggle the
+     *  matching group's collapse state. */
+    private onGutterPointerDown;
+    /** Flip a single group's collapse state in the in-memory model, then rebuild
+     *  the outline + repaint. View-only: the file is never written. */
+    private applyGroupToggle;
+    /** Collapse/expand the whole sheet to `level` on one axis. */
+    private applyLevelButton;
+    /** Set a row/column hidden by mapping to the size-0 encoding the axis/renderer
+     *  already understand, stashing the original size so expand can restore it. */
+    private setBandHidden;
+    /** Record band `index`'s CURRENT model size (or `null` = no entry) in the
+     *  per-sheet override store. Called after every view-only size mutation —
+     *  outline hide/show above and drag-to-resize (#567) — so worker renders
+     *  converge to the main model. */
+    private recordSizeOverride;
+    /** The current sheet's override store serialized for the wire, or undefined
+     *  when nothing has been mutated (keeps the request payload unchanged). */
+    private wireSizeOverrides;
+    /** Update the `collapsed` flag on a band's model entry so the outline rebuild
+     *  reflects the new state. */
+    private setBandCollapsed;
+    /** Shared tail of a gutter interaction: invalidate the axis cache, rebuild the
+     *  outline (collapsed flags changed), refresh dependent geometry, re-render. */
+    private afterOutlineMutation;
+    /** Rebuild only the layout + band lists (not the stashes) after a collapse
+     *  state change, so the +/- glyphs and bracket set stay in sync. */
+    private buildOutlineLayoutOnly;
     /** True when the current sheet's grid is laid out right-to-left. */
     private get isRtl();
     /** Maximum horizontal scroll offset the native scroll host allows (≥ 0). */
@@ -5519,6 +8024,46 @@ declare class XlsxViewer {
      *  whole range) to mirror Excel, which attaches the button to the active
      *  cell of the selection. */
     private maybeDrawValidationDropdown;
+    /**
+     * Redraw the find-highlight overlay: one translucent box per matched cell on
+     * the current sheet, the active match in a stronger colour. Uses the SAME
+     * `getCellRect` + `screenX` + header/frozen clamp the selection overlay uses,
+     * so a box lands exactly on the drawn cell at any scroll offset / zoom / RTL.
+     * Rebuilt on every render and scroll (cheap DOM geometry, no canvas paint).
+     */
+    private updateFindOverlay;
+    /**
+     * IX2 — find every occurrence of `query` across every sheet and highlight the
+     * matched cells. Returns every match in document order (sheet ascending, then
+     * row-major within a sheet), each tagged with its
+     * `{ sheet, sheetName, ref, row, col }`. A cell is the search unit: search
+     * runs over each cell's *rendered* display text (number formats, dates, rich
+     * text flattened), so a query matches what the grid shows. Case-insensitive by
+     * default; pass `{ caseSensitive: true }` for an exact match. An empty query
+     * clears the find.
+     */
+    findText(query: string, opts?: FindMatchesOptions): Promise<FindMatch<XlsxMatchLocation>[]>;
+    /**
+     * IX2 — move to the next match (wrap-around), switching sheets and scrolling
+     * the matched cell into view as needed, and highlight it as the active match.
+     * Returns the now-active match, or `null` when there are none. Call
+     * {@link findText} first.
+     */
+    findNext(): Promise<FindMatch<XlsxMatchLocation> | null>;
+    /** IX2 — move to the previous match (wrap-around). */
+    findPrev(): Promise<FindMatch<XlsxMatchLocation> | null>;
+    /** IX2 — clear all highlights and reset the find state. */
+    clearFind(): void;
+    private _activateMatch;
+    /**
+     * Scroll the grid so cell (row, col) is comfortably in view. Computes the
+     * cell's absolute logical offset from the axis metrics (the same the renderer
+     * uses) and nudges `scrollHost.scrollTop` / start-anchored horizontal scroll
+     * only when the cell is outside the scrollable viewport — an in-view cell is
+     * left where it is (Excel's find behaviour). Frozen cells are always visible,
+     * so they need no scroll.
+     */
+    private _scrollCellIntoView;
     /** Toggle the dropdown panel for the active cell's list validation. Called
      *  from pointerdown when the arrow rect is hit. Re-clicking the same arrow
      *  closes it. */
@@ -5546,6 +8091,37 @@ declare class XlsxViewer {
      *  collision (Excel allows at most one note per cell, so this is moot in
      *  practice). */
     private buildCommentMap;
+    /** IX1 — index the current sheet's hyperlinks by `"row:col"` (1-based, first
+     *  cell of the `ref` range) so a clicked/hovered cell resolves in O(1). Keys
+     *  match the renderer's `hyperlinkMap` exactly (`${hl.row}:${hl.col}`). */
+    private buildHyperlinkMap;
+    /** IX1 — the hyperlink at a cell, or null. `getCellAt` returns 1-based
+     *  {row,col}, matching the parser/renderer keying.
+     *
+     *  Returns null unconditionally when `enableHyperlinks` is `false`: this is the
+     *  single gate that disables hyperlink interactivity. Both consumers — the
+     *  pointermove pointer-cursor affordance and the click dispatch
+     *  ({@link dispatchHyperlink}) — funnel through this hit-test, so a null result
+     *  means no cursor change, no default navigation, and no `onHyperlinkClick`. */
+    private hyperlinkAtCell;
+    /**
+     * IX1 — dispatch a click on a hyperlinked cell. Builds a
+     * {@link HyperlinkTarget} from the parsed hyperlink (external `url` wins over
+     * internal `location`, matching Excel: a `<hyperlink>` carrying both navigates
+     * to the external target) and routes it to the caller's `onHyperlinkClick`
+     * (which fully owns behaviour) or the built-in default. Returns true when a
+     * hyperlink was found and dispatched.
+     */
+    private dispatchHyperlink;
+    /**
+     * IX1 default handler for an internal `location` target (§18.3.1.47): a defined
+     * name or a cell ref like `Sheet1!A1`. Best-effort: if the part before `!`
+     * names a sheet in the workbook, switch to it. There is no scroll-to-cell
+     * primitive on this viewer, so the cell part is not yet honoured (switching the
+     * sheet already lands the user on the right surface). A bare defined name that
+     * does not resolve to a sheet is a documented no-op.
+     */
+    private navigateInternalHyperlink;
     /** Show the popup for the comment on `cell` after the hover dwell, anchored to
      *  the cell's current on-screen rect. No-op when the cell carries no comment.
      *  Re-hovering the same cell does not restart the timer. */
@@ -5580,10 +8156,46 @@ declare class XlsxViewer {
     private zoomPosToScale;
     /** Inverse of {@link zoomPosToScale}: scale factor → slider position [0,100]. */
     private zoomScaleToPos;
-    /** Set the cell/header scale and re-lay-out the current sheet. Clamped to the
-     *  zoom bounds; keeps the slider thumb, percentage label and the row-header-
-     *  aligned tab-nav width in sync. */
+    /**
+     * IX9 {@link ZoomableViewer} — set the cell/header scale (`1` = 100%; the
+     * viewer's `cellScale`) and re-lay-out the current sheet. Clamped to the zoom
+     * bounds and snapped to whole percent; keeps the slider thumb, percentage label
+     * and the row-header-aligned tab-nav width in sync, and fires `onScaleChange`
+     * when the resolved scale actually changes.
+     */
     setScale(scale: number): void;
+    /** IX9 {@link ZoomableViewer} — the current zoom factor (`1` = 100%). This is
+     *  the viewer's `cellScale`; `1` before anything is set. */
+    getScale(): number;
+    /** IX9 {@link ZoomableViewer} — step up to the next rung of the shared zoom
+     *  ladder (clamped to `zoomMax` by {@link setScale}). */
+    zoomIn(): void;
+    /** IX9 {@link ZoomableViewer} — step down to the next lower ladder rung. */
+    zoomOut(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the used data range's WIDTH to the canvas
+     * area. The "content" is the natural (100%) width of the row header plus the
+     * used columns; the container is `canvasArea.clientWidth`. A no-op (defers) when
+     * nothing is loaded or the container is unlaid-out. Routes through
+     * {@link setScale}, so the result is clamped/snapped and fires `onScaleChange`.
+     */
+    fitWidth(): void;
+    /**
+     * IX9 {@link ZoomableViewer} — fit the used data range's WIDTH AND HEIGHT inside
+     * the canvas area (header + used columns/rows), so the whole used range is
+     * visible without scrolling. Takes the tighter of the width- and height-fit
+     * factors. Defers when unloaded / unlaid-out; routes through {@link setScale}.
+     */
+    fitPage(): void;
+    /** Shared fit implementation for {@link fitWidth} / {@link fitPage}: derive the
+     *  natural (cs=1) content extent of the used data range, ask core's pure
+     *  {@link fitScale} for the factor, and apply it via {@link setScale}. */
+    private _fit;
+    /** Natural (unscaled, cs=1) CSS-px extent of a worksheet's used data range:
+     *  the row/column header plus every used column width / row height. Mirrors
+     *  {@link updateSpacerSize} at cs=1 (same used-range detection) so the fit
+     *  targets exactly the region the spacer/scroll extent covers. */
+    private _naturalContentExtent;
     private updateSpacerSize;
     /**
      * Coalesce a re-render into the next animation frame. Called from the
@@ -5599,6 +8211,11 @@ declare class XlsxViewer {
      */
     private scheduleRender;
     private renderCurrentSheet;
+    /** Route a render failure to `onError`, or `console.error` when none is given
+     *  (never fully silent), and never after teardown. Mirrors the scroll viewers'
+     *  `_reportRenderError`. */
+    private _reportRenderError;
+    private _renderCurrentSheet;
     private computeHeaderHighlight;
     get sheetNames(): string[];
     /** The underlying <canvas> element the grid is drawn on. */
@@ -5635,9 +8252,20 @@ declare interface XlsxViewerOptions extends LoadOptions_2 {
      *  own zoom control). */
     showZoomSlider?: boolean;
     /** Lower/upper bounds for the zoom slider as scale factors. Default 0.1–4
-     *  (10%–400%, matching Excel's zoom range). */
+     *  (10%–400%, matching Excel's zoom range). Also the clamp range for the IX9
+     *  {@link ZoomableViewer} zoom contract ({@link XlsxViewer.setScale} etc.). */
     zoomMin?: number;
     zoomMax?: number;
+    /**
+     * IX9 — fires whenever the zoom factor actually changes (`1` = 100%), whatever
+     * the source: {@link XlsxViewer.setScale}, {@link XlsxViewer.zoomIn} /
+     * {@link XlsxViewer.zoomOut}, {@link XlsxViewer.fitWidth} /
+     * {@link XlsxViewer.fitPage}, the built-in zoom slider, the +/- buttons, or a
+     * Ctrl/⌘+wheel gesture. Named `onScaleChange` to match the docx/pptx viewers so
+     * all five share one notification shape. Not fired when a call resolves to the
+     * same (clamped/snapped) scale.
+     */
+    onScaleChange?: (scale: number) => void;
     onReady?: (sheetNames: string[]) => void;
     /**
      * Called when the active sheet changes, with the new sheet's zero-based
@@ -5651,6 +8279,23 @@ declare interface XlsxViewerOptions extends LoadOptions_2 {
     onError?: (err: Error) => void;
     /** Called when the selected cell range changes. null means no selection. */
     onSelectionChange?: (selection: CellRange_2 | null) => void;
+    /**
+     * IX1 (design decision — NOT user-confirmed, integrator may veto). Fires when a
+     * cell carrying a hyperlink (ECMA-376 §18.3.1.47) is clicked. Default when
+     * omitted: external → {@link openExternalHyperlink} (new tab, sanitised,
+     * noopener); internal (`location`) → navigate to the referenced sheet/cell
+     * when resolvable. When supplied, this callback fully owns the behaviour and
+     * receives the raw {@link HyperlinkTarget} verbatim (URL sanitisation is the
+     * default handler's job, so a blocked scheme still reaches a custom callback).
+     */
+    onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the cell hit-test reports no hyperlink under any cell, so hyperlink
+     *  interactivity is disabled entirely: no pointer cursor over a link, no default
+     *  navigation (external new-tab / internal sheet jump), and `onHyperlinkClick`
+     *  is never called. Hyperlinked cells still render exactly as authored but are
+     *  inert. */
+    enableHyperlinks?: boolean;
     /**
      * Color of the cell-selection highlight. A single CSS color drives both the
      * selection rectangle's border (drawn in this color) and its fill (the same
@@ -5709,6 +8354,12 @@ declare class XlsxWorkbook {
      *  `renderViewport` call reuses it — equations in shapes render when present,
      *  and are skipped (engine tree-shaken) when omitted. */
     private math;
+    /** Google-Fonts `FontFace` objects this workbook preloaded into `document.fonts`
+     *  (main mode only — in worker mode the worker owns them and terminates with its
+     *  own FontFaceSet). Released in {@link destroy} so they do not leak into the
+     *  shared FontFaceSet for the lifetime of the SPA (deduped + refcounted in core,
+     *  so a web font shared with another open workbook survives until both go). */
+    private googleFontFaces;
     private _mode;
     private constructor();
     /** Parse an XLSX from a URL or ArrayBuffer. */
@@ -5748,6 +8399,22 @@ declare class XlsxWorkbook {
      * route-through-worker decision).
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
+    /**
+     * Project the workbook to GitHub-flavoured markdown: each sheet becomes a
+     * `## SheetName` section followed by a pipe table of its populated bounding
+     * box (fully-empty middle rows trimmed, ULP noise masked). Styling, charts,
+     * and drawings are discarded — the projection is meant for AI ingestion and
+     * full-text search, not layout.
+     *
+     * Runs entirely in the worker off the archive opened at {@link load} (no
+     * re-copy of the file, no re-parse of the model on the main thread), so it
+     * works in BOTH `mode: 'main'` and `mode: 'worker'`.
+     *
+     * @example
+     * const wb = await XlsxWorkbook.load(buffer);
+     * const md = await wb.toMarkdown();
+     */
+    toMarkdown(): Promise<string>;
     /**
      * Resolve a `list`-type data-validation `formula1` (ECMA-376 §18.3.1.32) into
      * the set of allowed values to display, evaluated relative to `sheetIndex`
@@ -5764,6 +8431,24 @@ declare class XlsxWorkbook {
      * Read-only: this only reads cell values for display; it never writes.
      */
     resolveValidationList(sheetIndex: number, formula1: string | undefined): Promise<ResolvedList>;
+    /**
+     * IX2 — the display string a cell shows on the grid, i.e. exactly what
+     * {@link renderViewport} would draw (number formats, dates, booleans, rich
+     * text flattened). Used by {@link XlsxViewer.findText} to search the *rendered*
+     * text rather than the raw stored value, so a search matches what the user
+     * sees. Threads the workbook styles + the sheet's date system through the
+     * shared {@link formatCellValue} (the same call the renderer and
+     * validation-list expansion use). Returns `''` before the workbook is loaded.
+     */
+    cellText(ws: Worksheet, cell: Cell): string;
+    /**
+     * Render a sheet viewport into `target`. Note: `opts.fetchImage` is ignored
+     * here — image bytes always come from this workbook's own archive through its
+     * stable per-instance loader, whose closure identity keys the shared decoded
+     * caches, the render-pass lease, and {@link destroy}'s cache drops. Callers
+     * needing a custom byte source should use the standalone
+     * `renderWorksheetViewport` orchestrator directly.
+     */
     renderViewport(target: HTMLCanvasElement | OffscreenCanvas, sheetIndex: number, viewport: ViewportRange, opts?: RenderViewportOptions): Promise<void>;
     /**
      * Render a sheet viewport and return it as an ImageBitmap (both modes; in
@@ -5783,4 +8468,90 @@ declare class XlsxWorkbook {
     destroy(): void;
 }
 
+/**
+ * IX9 — the shared zoom API contract for every viewer (DocxViewer, PptxViewer,
+ * DocxScrollViewer, PptxScrollViewer, XlsxViewer).
+ *
+ * This module owns ONLY the pure, DOM-free pieces of the contract: the type
+ * ({@link ZoomableViewer}), the discrete zoom-step ladder ({@link nextZoomStep} /
+ * {@link prevZoomStep}), the fit-to-content scale math ({@link fitScale}), and the
+ * range clamp ({@link clampScale}). Each viewer implements the interface with its
+ * own scale field and re-render path; this keeps ONE definition of "what a zoom
+ * factor means" and "what the +/- steps are" across all five, so a host can drive
+ * any viewer through the same six calls without special-casing the format.
+ *
+ * SCALE SEMANTICS (the contract): a scale of `1` means 100% — the content at its
+ * natural size (a docx page at `widthPt × PT_TO_PX`, a pptx slide at
+ * `slideWidth / EMU_PER_PX`, an xlsx grid at `cellScale` 1). `getScale()` and
+ * `setScale(n)` speak this user-facing factor for EVERY viewer.
+ *
+ * KNOWN FAMILY DIFFERENCE — the INITIAL scale right after load (deliberate,
+ * documented rather than papered over): the single-canvas viewers (DocxViewer /
+ * PptxViewer) and XlsxViewer start at `1` (or the effective factor implied by an
+ * explicit `width` option); the continuous-scroll viewers (DocxScrollViewer /
+ * PptxScrollViewer) AUTO-FIT to the container on first layout, so their
+ * `getScale()` right after load reports the fit-to-width BASE factor (≠ 1 unless
+ * the container happens to match the natural width). The unit is identical — only
+ * the starting point differs, because fit-to-width is the natural resting state
+ * of a continuous document viewer.
+ *
+ * PRE-LOAD `setScale` (family-unified, IX9 F1): a `setScale` called before the
+ * content is loaded / before the layout is established is LATCHED — never
+ * silently dropped — and applied once the viewer establishes its scale (the
+ * single-canvas viewers honour it on the first render; the scroll viewers apply
+ * it right after the base fit establishes, firing `onScaleChange` at application
+ * time). `getScale()` reports the latched factor while it is pending.
+ *
+ * API SHAPE (idiomatic default — the integrator MAY veto; see the IX9 PR): a
+ * six-method surface plus one change notification (`onScaleChange`). Deliberately
+ * NO new UI here — the contract is API only (design decision IX9 §4). Touch-pinch
+ * (IX8) is out of scope.
+ */
+/**
+ * The zoom contract every viewer satisfies. All scales are the user-facing factor
+ * where `1` = 100% (see the module note). `fitWidth`/`fitPage` are async because a
+ * fit re-renders at the new scale; the getters/steppers resolve synchronously.
+ */
+declare interface ZoomableViewer {
+    /** The current zoom factor (`1` = 100%). Never throws — returns the default
+     *  (`1`) before anything is loaded, or the latched pending factor when a
+     *  pre-load `setScale` is waiting to be applied (see the module note). */
+    getScale(): number;
+    /** Set the absolute zoom factor (`1` = 100%), clamped to the viewer's
+     *  `[zoomMin, zoomMax]`. Re-renders at the new scale and fires `onScaleChange`
+     *  when the clamped value actually changes. Called BEFORE the content is
+     *  loaded / the layout is established, the (clamped) factor is LATCHED and
+     *  applied once the viewer establishes its scale — family-unified semantics
+     *  (IX9 F1): never silently dropped by any viewer. */
+    setScale(scale: number): void | Promise<void>;
+    /** Step up to the next larger rung of the shared zoom ladder (25 %→400 %),
+     *  clamped to `zoomMax`. Equivalent to `setScale(nextZoomStep(getScale()))`. */
+    zoomIn(): void | Promise<void>;
+    /** Step down to the next smaller ladder rung, clamped to `zoomMin`. */
+    zoomOut(): void | Promise<void>;
+    /** Fit the content's WIDTH to the container (the common "fit width" / "fit
+     *  page width" verb). Sets the scale so one page/slide/sheet-column-run spans
+     *  the available width, then re-renders. Resolves once the fit render settles.
+     *
+     *  PERSISTENCE is viewer-implementation-dependent (deliberate, by family): the
+     *  single-canvas viewers (DocxViewer / PptxViewer) and XlsxViewer apply the fit
+     *  ONE-SHOT — they observe no container resizes, so a later resize does NOT
+     *  re-fit (call `fitWidth()` again after a layout change). The continuous-
+     *  scroll viewers (DocxScrollViewer / PptxScrollViewer) re-fit their width-fit
+     *  base on every container resize, so a `fitWidth()` there effectively
+     *  PERSISTS across resizes (the resize re-fit preserves the width-fit state). */
+    fitWidth(): void | Promise<void>;
+    /** Fit the WHOLE content (width AND height) inside the container, so an entire
+     *  page/slide is visible without scrolling. Sets the scale to the smaller of the
+     *  width- and height-fit factors, then re-renders.
+     *
+     *  PERSISTENCE is viewer-implementation-dependent, and — unlike `fitWidth` —
+     *  a page fit does NOT persist across container resizes on ANY viewer: the
+     *  single-canvas viewers and XlsxViewer observe no resizes at all (one-shot),
+     *  and the continuous-scroll viewers' resize handler re-applies the WIDTH fit
+     *  (preserving the zoom multiplier), not the page fit. Re-invoke `fitPage()`
+     *  after a layout change to re-fit. */
+    fitPage(): void | Promise<void>;
+}
+
 export { }