@silurus/ooxml 0.70.1 → 0.71.0

package/dist/types/docx.d.ts

@@ -64,6 +64,11 @@ export 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;
 };
 
 export declare interface BorderSpec {
@@ -72,6 +77,21 @@ export declare interface BorderSpec {
     style: string;
 }
 
+/**
+ * Populate a highlight overlay layer with one box per matched run-slice.
+ *
+ * @param layer    the overlay div (cleared and re-sized to the canvas here).
+ * @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 canvasCssWidth  the rendered canvas's CSS width (e.g. `"700px"`).
+ * @param canvasCssHeight the rendered canvas's CSS height.
+ * @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.
+ */
+export declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], canvasCssWidth: string, canvasCssHeight: string, 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}
@@ -79,16 +99,35 @@ export 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.
  *
- * @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 (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 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).
  */
-export declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string): void;
+export declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
 
 export declare interface CellBorders {
     top: BorderSpec | null;
@@ -112,6 +151,760 @@ export declare type CellElement = {
     type: 'table';
 } & DocTable;
 
+declare interface ChartDataLabelOverride {
+    idx: number;
+    /** Empty string = label deleted (skip drawing). */
+    text: string;
+    /** "l"|"r"|"t"|"b"|"ctr"|"outEnd"|"bestFit". undefined = inherit. */
+    position?: string;
+    fontColor?: string;
+    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 {
+    idx: number;
+    /** Resolved fill hex (no `#`). */
+    color?: string;
+    markerSymbol?: string;
+    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;
+}
+
+declare interface ChartErrBars {
+    /** "x" | "y". */
+    dir: string;
+    /** "plus" | "minus" | "both". */
+    barType: string;
+    plus: (number | null)[];
+    minus: (number | null)[];
+    noEndCap: boolean;
+    /** Resolved hex (no `#`). */
+    color?: string;
+    lineWidthEmu?: number;
+    /** "solid"|"dash"|"dot"|"dashDot"|... */
+    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" =
+ * fraction offset from default position.
+ */
+declare interface ChartManualLayout {
+    xMode: string;
+    yMode: string;
+    layoutTarget?: string;
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+}
+
+declare interface ChartModel {
+    chartType: ChartType;
+    title: string | null;
+    categories: string[];
+    series: ChartSeries[];
+    /** Show data labels on bars / points / slices. */
+    showDataLabels: boolean;
+    /** Explicit Y-axis minimum (OOXML `<c:valAx><c:min>`). */
+    valMin: number | null;
+    /** Explicit Y-axis maximum (OOXML `<c:valAx><c:max>`). */
+    valMax: number | null;
+    catAxisTitle: string | null;
+    valAxisTitle: string | null;
+    /** `<c:catAx><c:delete val="1"/>`. */
+    catAxisHidden: boolean;
+    /** `<c:valAx><c:delete val="1"/>`. */
+    valAxisHidden: boolean;
+    /** `<c:catAx><c:spPr><a:ln><a:noFill>` — hide just the axis LINE; labels
+     *  and tick marks still render. Distinct from `catAxisHidden` (which
+     *  removes everything via `<c:delete val="1"/>`). */
+    catAxisLineHidden: boolean;
+    /** `<c:valAx><c:spPr><a:ln><a:noFill>` — hide just the axis LINE; labels
+     *  and tick marks still render. */
+    valAxisLineHidden: boolean;
+    /** Hex without '#'. From `<c:plotArea><c:spPr><a:solidFill>`. */
+    plotAreaBg: string | null;
+    /** Outer chartSpace background (hex without '#'). null when noFill/absent. */
+    chartBg: string | null;
+    /** True when `<c:legend>` is declared in the chart XML. False = no legend. */
+    showLegend: boolean;
+    /** `<c:legend><c:legendPos val>` — "r"|"l"|"t"|"b"|"tr". null = default (r). */
+    legendPos: 'r' | 'l' | 't' | 'b' | 'tr' | null;
+    /** `<c:catAx><c:crossBetween val="..."/>`. "between" inserts 0.5-step padding
+     *  on each end of the category axis; "midCat" anchors endpoints to the axes. */
+    catAxisCrossBetween: 'between' | 'midCat' | string;
+    /** `<c:valAx><c:majorTickMark>`. ECMA-376 default is "cross". */
+    valAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:catAx><c:majorTickMark>`. */
+    catAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:valAx | catAx><c:minorTickMark>`. ECMA-376 default is "none". */
+    valAxisMinorTickMark?: 'cross' | 'out' | 'in' | 'none' | string | null;
+    catAxisMinorTickMark?: 'cross' | 'out' | 'in' | 'none' | string | null;
+    /** Title font size in OOXML hundredths of a point (1600 = 16pt). null = default. */
+    titleFontSizeHpt: number | null;
+    /** Title font color as a hex string without '#' (e.g. "1B4332"). null = default. */
+    titleFontColor: string | null;
+    /** Title font family from `<a:latin typeface>` (ECMA-376 §20.1.4.2.24). null = default. */
+    titleFontFace: string | null;
+    /** `<c:catAx><c:txPr>` font size (hpt). null = fall back to proportional default. */
+    catAxisFontSizeHpt: number | null;
+    /** `<c:valAx><c:txPr>` font size (hpt). null = fall back to proportional default. */
+    valAxisFontSizeHpt: number | null;
+    /** `<c:catAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#').
+     *  null = renderer default. Lets templates color category labels gray. */
+    catAxisFontColor?: string | null;
+    /** `<c:valAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#'). */
+    valAxisFontColor?: string | null;
+    /** `<c:dLbls><c:txPr>` font size (hpt) for data-point value labels. */
+    dataLabelFontSizeHpt: number | null;
+    /** Waterfall subtotal category indices. */
+    subtotalIndices: number[];
+    /** `<c:legend><c:manualLayout>` absolute placement fractions of the chart
+     *  space (ECMA-376 §21.2.2.31). Overrides the default side-based legend
+     *  rectangle while still letting `legendPos` decide which side of the plot
+     *  gets the reserved band. null = use default layout. */
+    legendManualLayout?: LegendManualLayout | null;
+    /**
+     * `<c:valAx><c:numFmt@formatCode>` — format code applied to value-axis tick
+     * labels (ECMA-376 §21.2.2.21). null = plain numeric formatting.
+     */
+    valAxisFormatCode?: string | null;
+    /**
+     * `<c:barChart><c:gapWidth>` — space between category groups as a
+     * percentage of bar width (ECMA-376 §21.2.2.13). Default per spec is 150.
+     * null = renderer default.
+     */
+    barGapWidth?: number | null;
+    /**
+     * `<c:barChart><c:overlap>` — signed percentage overlap between bars in the
+     * same category cluster (ECMA-376 §21.2.2.25). Negative = gap, positive =
+     * overlap, 0 = flush. Range [-100, 100]. null = renderer default (0).
+     */
+    barOverlap?: number | null;
+    /**
+     * `<c:dLbls><c:dLblPos>` — data label position (ECMA-376 §21.2.2.16).
+     * "ctr"|"inBase"|"inEnd"|"outEnd"|"l"|"r"|"t"|"b"|"bestFit" etc.
+     */
+    dataLabelPosition?: string | null;
+    /** Hex (no `#`) for data label text, resolved from `<c:dLbls><c:txPr>`. */
+    dataLabelFontColor?: string | null;
+    /**
+     * `<c:dLbls><c:numFmt@formatCode>` — chart-level override for data label
+     * number format (ECMA-376 §21.2.2.35). When absent, `valFormatCode` on each
+     * series is used.
+     */
+    dataLabelFormatCode?: string | null;
+    /** `<c:title>...defRPr@b>` chart title bold flag. */
+    titleFontBold?: boolean | null;
+    /** `<c:catAx><c:txPr>...defRPr@b>` X-axis tick label bold flag. */
+    catAxisFontBold?: boolean | null;
+    /** `<c:valAx><c:txPr>...defRPr@b>` Y-axis tick label bold flag. */
+    valAxisFontBold?: boolean | null;
+    /** `<c:catAx><c:title>` run-prop font size (hpt). Distinct from
+     *  `catAxisFontSizeHpt` (tick labels). null = renderer default. */
+    catAxisTitleFontSizeHpt?: number | null;
+    /** `<c:catAx><c:title>` run-prop bold flag. null = not bold. */
+    catAxisTitleFontBold?: boolean | null;
+    /** `<c:catAx><c:title>` run-prop color (hex without '#'). null = default. */
+    catAxisTitleFontColor?: string | null;
+    /** `<c:valAx><c:title>` run-prop font size (hpt). null = renderer default. */
+    valAxisTitleFontSizeHpt?: number | null;
+    /** `<c:valAx><c:title>` run-prop bold flag. null = not bold. */
+    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
+     *  border is drawn). */
+    chartBorderColor?: string | null;
+    /** `<c:chartSpace><c:spPr><a:ln@w>` border width in EMU. null = 1px hairline
+     *  when a color is present. */
+    chartBorderWidthEmu?: number | null;
+    /**
+     * `<c:catAx><c:crosses val>` (`autoZero` | `min` | `max`). Drives the Y
+     * coordinate where the X axis is drawn. Default `autoZero` puts the X
+     * axis at y=0 — that's how Excel "Project Timeline" templates split
+     * milestones (positive Y) above and tasks (negative Y) below the axis.
+     */
+    catAxisCrosses?: string | null;
+    /** `<c:catAx><c:crossesAt val>` — explicit numeric override for the
+     *  crossing point. Takes precedence over `catAxisCrosses`. */
+    catAxisCrossesAt?: number | null;
+    valAxisCrosses?: string | null;
+    valAxisCrossesAt?: number | null;
+    /** Axis line color (hex without `#`) and width in EMU from
+     *  `<c:catAx|valAx><c:spPr><a:ln>`. */
+    catAxisLineColor?: string | null;
+    catAxisLineWidthEmu?: number | null;
+    valAxisLineColor?: string | null;
+    valAxisLineWidthEmu?: number | null;
+    /**
+     * `<c:catAx><c:numFmt@formatCode>` (or scatter X-axis valAx). When set,
+     * the renderer formats X-axis tick labels with this code (e.g. dates).
+     */
+    catAxisFormatCode?: string | null;
+    /**
+     * `<c:catAx><c:scaling><c:min/max>` — explicit X-axis range. Used by
+     * scatter / bubble charts whose X axis is numeric. null = derive from
+     * data extents.
+     */
+    catAxisMin?: number | null;
+    catAxisMax?: number | null;
+    /**
+     * `<c:title><c:layout><c:manualLayout>` (ECMA-376 §21.2.2.27) absolute
+     * placement for the chart title.
+     */
+    titleManualLayout?: ChartManualLayout | null;
+    /**
+     * `<c:plotArea><c:layout><c:manualLayout>` absolute placement for the
+     * plot area. `layoutTarget="inner"` (default) describes the inner plot
+     * rect (no axes / labels); `outer` describes the outer rect (axes
+     * included).
+     */
+    plotAreaManualLayout?: ChartManualLayout | null;
+    /**
+     * `<c:scatterChart><c:scatterStyle val>` (ECMA-376 §21.2.2.42). Drives
+     * whether scatter charts connect points with lines and whether those
+     * lines are smoothed. Values: "marker" (markers only — Excel default
+     * "Scatter"), "line" / "lineMarker" (straight segments), "smooth" /
+     * "smoothMarker" (cubic Bézier through points), "lineNoMarker",
+     * "smoothNoMarker". null = renderer default ("marker"). Only consulted
+     * for `chartType === "scatter"`; bubble ignores it.
+     */
+    scatterStyle?: string | null;
+    /**
+     * `<c:radarChart><c:radarStyle val>` (ECMA-376 §21.2.3.10). Controls
+     * whether radar series render as line + markers ("standard" / "marker")
+     * or as a closed polygon with area fill ("filled"). null = default
+     * ("standard" — line, no fill). Only consulted for `chartType === "radar"`.
+     */
+    radarStyle?: string | null;
+    /**
+     * Secondary value axis for combo charts (bar + line). When present, series
+     * with `useSecondaryAxis` are plotted against this axis's independent scale
+     * and the axis is drawn on the right edge of the plot. null/absent = single
+     * 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 at its
+ *  absolute page box by `renderAnchorImages` — both via `renderChart`. */
+export 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;
+}
+
+declare interface ChartSeries {
+    name: string;
+    /** Hex without '#'. null = fall back to palette. */
+    color: string | null;
+    /** Numeric values; null = missing data point. */
+    values: (number | null)[];
+    /**
+     * Per-data-point colors (pie / doughnut). Hex without '#'. null inside the
+     * array = use palette for that slice. Omit entirely for non-pie series.
+     */
+    dataPointColors?: (string | null)[] | null;
+    /**
+     * Per-data-point data-label text colors. Used by chartEx (`<cx:dataLabel idx>`)
+     * to override label colour per bar — sample-2's waterfall paints negative
+     * △ values in red while positive values stay black. Null inside the array =
+     * fall back to the chart-level `dataLabelFontColor`.
+     */
+    dataLabelColors?: (string | null)[] | null;
+    /**
+     * Series-level data-label text colour (`<c:ser><c:dLbls><c:txPr>…solidFill`,
+     * ECMA-376 §21.2.2.216). Hex without '#'. Stacked-bar charts colour each
+     * segment's label independently (e.g. white on the dark segment, black on
+     * the light one), which a single chart-level `dataLabelFontColor` can't
+     * express. Takes precedence over `dataLabelFontColor`; null = no override.
+     */
+    labelColor?: string | null;
+    /**
+     * Mixed chart: per-series chart type override. Currently only "line" (XLSX
+     * and PPTX combo charts) is honoured; other values are treated as the
+     * chart's primary type.
+     */
+    seriesType?: string | null;
+    /**
+     * Combo chart: this series is plotted against the SECONDARY value axis
+     * (`ChartModel.secondaryValAxis`) — the `<c:valAx>` with `axPos="r"` /
+     * `<c:crosses val="max">`. When false/absent the series uses the primary
+     * (left) value-axis scale. PowerPoint's "Revenue vs. gross margin" combo
+     * (sample-14 slide-8) puts the margin line on a 0–100% secondary axis.
+     */
+    useSecondaryAxis?: boolean | null;
+    /**
+     * Scatter-only X values (as strings). When null the series uses
+     * `ChartModel.categories` as X.
+     */
+    categories?: string[] | null;
+    /**
+     * Resolved marker visibility for line/scatter series. ECMA-376 §21.2.2.32
+     * `<c:marker><c:symbol>` defaults to "none" for line charts unless the
+     * chart-level `<c:marker val="1"/>` or a per-series symbol opts in. When
+     * undefined/null the renderer uses its own default (visible) so callers
+     * that don't parse markers (e.g. pptx today) keep their existing behavior.
+     */
+    showMarker?: boolean | null;
+    /**
+     * Excel number-format code for this series' values (ECMA-376 §21.2.2.37,
+     * `<c:val>/<c:numRef>/<c:formatCode>`). Used to format data labels when the
+     * chart-level `<c:dLbls><c:numFmt>` is not set. null = no series-level code.
+     */
+    valFormatCode?: string | null;
+    /**
+     * `<c:marker><c:symbol val>` (ECMA-376 §21.2.2.32) — point marker shape.
+     * One of "circle"|"square"|"diamond"|"triangle"|"x"|"plus"|"star"|
+     * "dot"|"dash"|"picture"|"none". null = renderer default (circle when
+     * showMarker is true).
+     */
+    markerSymbol?: string | null;
+    /**
+     * `<c:marker><c:size val>` (ECMA-376 §21.2.2.34) — marker side length in
+     * points. null = renderer default (~5 pt).
+     */
+    markerSize?: number | null;
+    /** `<c:marker><c:spPr><a:solidFill>` resolved hex (no `#`). */
+    markerFill?: string | null;
+    /** `<c:marker><c:spPr><a:ln><a:solidFill>` resolved hex (no `#`). */
+    markerLine?: string | null;
+    /**
+     * Per-data-point overrides (ECMA-376 §21.2.2.39 `<c:dPt>`). Keyed by point
+     * index. Any unset field falls back to the series-level value.
+     */
+    dataPointOverrides?: ChartDataPointOverride[] | null;
+    /**
+     * Per-data-point custom labels (ECMA-376 §21.2.2.45 `<c:dLbl idx>`).
+     * `text` is the resolved plain string — `<a:fld type="CELLRANGE">`
+     * placeholders are already substituted at parse time. An empty string
+     * means the point's label was deleted with `<c:delete val="1"/>` and
+     * the renderer should skip it.
+     */
+    dataLabelOverrides?: ChartDataLabelOverride[] | null;
+    /**
+     * Series-level `<c:dLbls>` block (showVal / showSerName / position).
+     * Applied to every point lacking its own `<c:dLbl>` override.
+     */
+    seriesDataLabels?: ChartSeriesDataLabels | null;
+    /**
+     * `<c:errBars>` per-series error bars (ECMA-376 §21.2.2.20). Up to two
+     * (one per direction). Plus / minus deltas are absolute per-point values
+     * regardless of `errValType`.
+     */
+    errBars?: ChartErrBars[] | null;
+    /**
+     * `<c:bubbleSize>` per-point sizes for bubble charts (ECMA-376 §21.2.2.4).
+     * Drives marker radius — renderer treats the values as areas (radius
+     * scales by sqrt) so visual area is proportional to value, matching
+     * Excel. null / empty array = uniform marker size. Ignored for non-bubble
+     * 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 {
+    showVal: boolean;
+    showCatName: boolean;
+    showSerName: boolean;
+    showPercent: boolean;
+    position?: string;
+    fontColor?: string;
+    formatCode?: string;
+    /** Series-level bold default for data labels. */
+    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;
+}
+
+/**
+ * Canonical chart type vocabulary. Embeds direction (`H` = horizontal) and
+ * 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' | 'stock' | 'boxWhisker' | 'sunburst' | string;
+
 /** ECMA-376 §17.6.3 `<w:col>` — one column's width and trailing space (pt). */
 export declare interface ColSpec {
     widthPt: number;
@@ -159,7 +952,7 @@ export 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;
@@ -169,6 +962,15 @@ export declare interface DocParagraph {
     numbering: NumberingInfo | null;
     tabStops: TabStop[];
     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) */
@@ -230,6 +1032,8 @@ export declare type DocRun = {
 } & DocxTextRun | {
     type: 'image';
 } & ImageRun | {
+    type: 'chart';
+} & ChartRun | {
     type: 'break';
     breakType: 'line' | 'page' | 'column';
 } | {
@@ -242,7 +1046,9 @@ export declare type DocRun = {
     display: boolean;
     fontSize: number;
     jc?: string;
-};
+} | {
+    type: 'ptab';
+} & PTabRun;
 
 export declare interface DocSettings {
     /** §17.15.1.58 `w:kinsoku` — East-Asian line-breaking toggle. `undefined`
@@ -275,6 +1081,14 @@ export 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'
@@ -342,10 +1156,27 @@ export 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
@@ -364,6 +1195,32 @@ export 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
@@ -399,6 +1256,23 @@ export 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).
@@ -422,8 +1296,23 @@ export 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?: 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.
      */
-    renderPageToBitmap(pageIndex: number, opts?: WireRenderPageOptions): Promise<ImageBitmap>;
+    collectPageRuns(pageIndex: number, opts?: WireRenderPageOptions): Promise<DocxTextRunInfo[]>;
 }
 
 export declare interface DocxDocumentModel {
@@ -444,6 +1333,11 @@ export declare interface DocxDocumentModel {
      * entry is absent or classified as "auto".
      */
     fontFamilyClasses?: 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
@@ -463,6 +1357,31 @@ export 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;
+}
+
+export 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). */
+export declare interface DocxHighlightMatch {
+    slices: MatchRunSlice[];
+    active: boolean;
+}
+
+/** Where a docx match lives: its 0-based page index. */
+export declare interface DocxMatchLocation {
+    page: number;
 }
 
 /** ECMA-376 §17.3.2.4 `<w:bdr>` — a run-level border drawn as a box around the
@@ -478,7 +1397,7 @@ export declare interface DocxRunBorder {
     space: number;
 }
 
-export declare class DocxScrollViewer {
+export declare class DocxScrollViewer implements ZoomableViewer {
     private _doc;
     private readonly _injected;
     private readonly _opts;
@@ -499,6 +1418,18 @@ export 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). */
@@ -512,6 +1443,27 @@ export 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
@@ -542,11 +1494,14 @@ export 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;
@@ -615,6 +1570,12 @@ export 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)
@@ -664,10 +1625,24 @@ export 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.
+     */
+    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;
     /** 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;
@@ -697,7 +1672,10 @@ export 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
@@ -718,6 +1696,38 @@ export 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;
@@ -744,12 +1754,11 @@ export 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).
@@ -825,6 +1834,8 @@ export 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
@@ -871,9 +1882,10 @@ export declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions,
     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;
@@ -916,6 +1928,17 @@ export declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions,
      *  `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;
     /** 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
@@ -930,6 +1953,15 @@ export 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;
@@ -957,10 +1989,23 @@ export 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;
@@ -992,6 +2037,42 @@ export 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.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.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
@@ -1015,11 +2096,40 @@ export declare interface DocxTextRunInfo {
     fontSize: number;
     /** CSS `font` shorthand used for canvas drawing (e.g. `"bold 16px Arial"`). */
     font: string;
-}
-
-export declare class DocxViewer {
+    /** 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;
+}
+
+export 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
@@ -1032,20 +2142,56 @@ export 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;
@@ -1055,6 +2201,91 @@ export 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.
      *
@@ -1066,7 +2297,34 @@ export 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;
+    /** 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.
+     */
+    private _hyperlinkHandler;
 }
 
 export declare interface DocxViewerOptions extends RenderPageOptions, LoadOptions {
@@ -1078,10 +2336,53 @@ export declare interface DocxViewerOptions extends RenderPageOptions, LoadOption
     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;
     /** 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 §17.8.3.3-.6 — one embedded font-style slot from
+ *  `word/fontTable.xml`, resolved to its obfuscated part path + fontKey. */
+export 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';
+
 export declare interface FieldRun {
     /** "page" | "numPages" | "other" */
     fieldType: string;
@@ -1100,6 +2401,51 @@ export 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;
+}
+
+/**
+ * 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.
+ */
+export 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}. */
+export 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;
 }
 
 /**
@@ -1158,6 +2504,49 @@ export declare interface HeadersFooters {
     even: HeaderFooter | 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`).
+ */
+export declare type HyperlinkTarget = {
+    kind: 'external';
+    url: string;
+} | {
+    kind: 'internal';
+    ref: string;
+    slideIndex?: number;
+};
+
 export declare interface ImageRun {
     /**
      * Embedded zip path of the raster blip (e.g. `word/media/image1.png`) — the
@@ -1215,6 +2604,19 @@ export 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"
@@ -1264,6 +2666,18 @@ export declare interface ImageRun {
     anchorYRelativeFrom?: string | null;
 }
 
+declare interface LegendManualLayout {
+    /** `"edge"` = `x`/`y` are fractions from top-left of chart space;
+     *  `"factor"` = fractions offset from the default position. */
+    xMode: string;
+    yMode: string;
+    /** Fractions of chart space width/height. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
 /** DrawingML line-end (arrow head). ECMA-376 §20.1.8.3 CT_LineEndProperties.
  *  Maps 1:1 to core's `ArrowEnd`. */
 export declare interface LineEnd {
@@ -1275,6 +2689,24 @@ export 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. */
+export 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;
+}
+
 export declare interface LineSpacing {
     value: number;
     rule: 'auto' | 'exact' | 'atLeast';
@@ -1326,6 +2758,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.
      *
@@ -1370,6 +2831,23 @@ declare interface LoadOptions_2 {
     math?: MathRenderer;
 }
 
+/**
+ * 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';
@@ -1392,6 +2870,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 '('). */
@@ -1449,7 +2952,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';
@@ -1492,6 +3011,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 {
@@ -1556,6 +3084,114 @@ export declare interface NumberingInfo {
     picBulletHeightPt?: number;
 }
 
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function openExternalHyperlink(url: string, allowed?: readonly string[], win?: Pick<Window, 'open'> | undefined): 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. */
+export 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/…). */
+export 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`). */
+export declare interface PageNumType {
+    start?: number;
+    fmt?: string;
+}
+
 export declare interface ParaBorderEdge {
     style: string;
     color: string | null;
@@ -1599,6 +3235,22 @@ export declare type PathCmd = {
     cmd: 'close';
 };
 
+/** 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. */
+export 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;
+}
+
 export declare interface RenderPageOptions {
     /** Canvas CSS width in px; height is auto-computed from page aspect ratio.
      *  Applies per CALL — pages of different physical widths (per-section pgSz,
@@ -1608,7 +3260,10 @@ export 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;
@@ -1617,12 +3272,27 @@ export 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. */
+export declare type RenderPageToBitmapOptions = WireRenderPageOptions & {
+    onTextRun?: (run: DocxTextRunInfo) => void;
+};
 
 export declare interface RubyAnnotation {
     text: string;
@@ -1639,6 +3309,50 @@ export declare interface RunRevision {
     date?: string;
 }
 
+/**
+ * A secondary value axis (combo charts). Mirrors the primary value-axis
+ * properties but lives in its own object so the flat primary-axis fields stay
+ * untouched. Parsed from the right-hand `<c:valAx>` (`axPos="r"`,
+ * `<c:crosses val="max">`).
+ */
+declare interface SecondaryValueAxis {
+    /** `<c:scaling><c:min val>`. null = derive from the series data. */
+    min: number | null;
+    /** `<c:scaling><c:max val>`. null = derive from the series data. */
+    max: number | null;
+    /** `<c:title>` plain text. null = no title. */
+    title: string | null;
+    /** `<c:delete val="1"/>` — hide labels/ticks entirely. */
+    hidden: boolean;
+    /** `<c:numFmt formatCode>` for tick labels. */
+    formatCode?: string | null;
+    /** `<c:txPr>…<a:solidFill>` tick-label color (hex without '#'). */
+    fontColor?: string | null;
+    /** `<c:txPr>` tick-label font size (hpt). */
+    fontSizeHpt?: number | null;
+    /** `<c:spPr><a:ln><a:solidFill>` axis-line color (hex without '#'). */
+    lineColor?: string | null;
+    /** `<c:spPr><a:ln w>` axis-line width in EMU. */
+    lineWidthEmu?: number | null;
+    /** `<c:spPr><a:ln><a:noFill>` — hide just the axis rule. */
+    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. */
+    titleFontBold?: boolean | null;
+    /** `<c:title>` run-prop color (hex without '#'). */
+    titleFontColor?: string | null;
+}
+
 /** ECMA-376 §17.6.13 `<w:pgSz>` + §17.6.11 `<w:pgMar>` — a section's page
  *  geometry: page size + margins + header/footer distances (pt). Mirrors the Rust
  *  `SectionGeom`. Carried on a {@link BodyElement} `sectionBreak` arm (`geom`) so a
@@ -1683,6 +3397,17 @@ export 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
@@ -1701,6 +3426,23 @@ export 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 ShapeFill = {
@@ -1793,6 +3535,15 @@ export declare interface ShapeRun {
     wrapSide?: string | null;
     /** Text rendered INSIDE the shape's bounding box (`<wps:txbx><w:txbxContent>`). */
     textBlocks?: ShapeText[];
+    /** 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
@@ -1805,6 +3556,16 @@ export declare interface ShapeRun {
     textInsetT?: number;
     textInsetR?: number;
     textInsetB?: number;
+    /** 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;
 }
 
 export declare interface ShapeText {
@@ -1940,7 +3701,107 @@ export declare interface TblpPr {
     tblpYSpec?: 'inline' | 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 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. */
+export 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;
+}
+
 /** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
 export declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
 
+/**
+ * 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 { }