@silurus/ooxml 0.71.0 → 0.72.0

package/dist/types/index.d.ts

@@ -61,11 +61,18 @@ declare interface BlipBullet {
     /** MIME type of the blip at {@link BlipBullet.imagePath} (e.g. `image/png`). */
     mimeType: string;
     /**
-     * `<a:buSzPct val>` (ECMA-376 §21.1.2.4.3) as a percentage of the text size
+     * `<a:buSzPct val>` (ECMA-376 §21.1.2.4.9) as a percentage of the text size
      * (100 = same size). `null` when no explicit `<a:buSzPct>` is present, in
      * which case the renderer uses the spec default of 100%.
      */
     sizePct: number | null;
+    /**
+     * `<a:buSzPts val>` (ECMA-376 §21.1.2.4.10) — an ABSOLUTE marker size in
+     * points, independent of the text size. Mutually exclusive with {@link
+     * BlipBullet.sizePct} (both are the one `EG_TextBulletSize` choice). Omitted
+     * when no explicit `<a:buSzPts>` is present; when present it takes precedence.
+     */
+    sizePts?: number;
 }
 
 declare type BodyElement = {
@@ -114,6 +121,14 @@ declare type BodyElement = {
      *  separately from `geom` because a section may inherit its geometry yet
      *  still restart / re-format its page numbers. */
     pageNumType?: PageNumType | null;
+    /** ECMA-376 §17.6.20 `<w:textDirection w:val>` — this ENDING section's
+     *  flow direction (TRANSITIONAL ST_TextDirection, same enum and semantics
+     *  as {@link SectionProps.textDirection}), so a vertical (tbRl/btLr)
+     *  non-final section can coexist with a horizontal final section (issue
+     *  #1000). Absent ⇒ horizontal ("lrTb" is collapsed by the parser).
+     *  Carried separately from `geom` (like `pageNumType`) because a section
+     *  may inherit its page geometry yet still set its own flow direction. */
+    textDirection?: string | null;
 };
 
 declare interface Border {
@@ -145,17 +160,23 @@ declare interface BorderSpec {
 /**
  * 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).
+ * Every box is positioned as a PERCENTAGE of `cssWidth`/`cssHeight`, and the
+ * container's own size is left untouched (`width:100%;height:100%` from the
+ * caller), so the highlights track the canvas's ACTUAL rendered box even when a
+ * consumer scales the canvas down with external CSS — mirroring
+ * {@link buildDocxTextLayer}.
+ *
+ * @param layer    the overlay div (cleared here; sized `100%` by the caller).
  * @param runs     the page's runs (same array the page was rendered/text-layered from).
  * @param matches  the page's matches (run-slices + active flag).
- * @param canvasCssWidth  the rendered canvas's CSS width (e.g. `"700px"`).
- * @param canvasCssHeight the rendered canvas's CSS height.
+ * @param cssWidth  the page's intended CSS width (px, number) — the x-axis % denominator.
+ * @param cssHeight the page's intended CSS height (px, number) — the y-axis % denominator.
  * @param measureForFont  returns a width-measurer primed with a run's `font`
  *                        (the viewer closes over a canvas 2d context). Kept as a
  *                        factory so the font is set once per run, not per glyph.
  * @param colors   optional colour overrides.
  */
-declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], canvasCssWidth: string, canvasCssHeight: string, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
+declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
 
 /**
  * Build the transparent text-selection overlay for a rendered docx page: one
@@ -168,11 +189,21 @@ declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRu
  * 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).
+ * Every span is positioned as a PERCENTAGE of `cssWidth`/`cssHeight` (the page's
+ * intended CSS-px box), never literal px, and the container's own width/height are
+ * left untouched (the caller sizes it `width:100%;height:100%`). This lets the
+ * overlay track the canvas's ACTUAL rendered box even when a consumer scales the
+ * canvas down with external CSS (`width:100%!important; height:auto`): the
+ * `display:inline-block` wrapper shrinks with the canvas, the `100%` container
+ * follows, and every `%`-placed span scales with it, so nothing overflows the
+ * wrapper into an ancestor's scroll area.
+ *
+ * @param layer            the overlay div (sized `width:100%;height:100%` by the caller).
  * @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 cssWidth         the page's intended CSS width (px, number) — the %
+ *                         denominator for the x axis.
+ * @param cssHeight        the page's intended CSS height (px, number) — the %
+ *                         denominator for the y axis.
  * @param onHyperlinkClick IX1 — invoked when a run carrying a resolved
  *                         {@link HyperlinkTarget} is clicked. A hyperlink run's
  *                         span keeps its transparent glyphs (the visible link
@@ -192,18 +223,23 @@ declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRu
  *                         a 縦中横 span keeps the bare rotate (no regression for
  *                         callers that do not thread a measurer).
  */
-declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
+declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], cssWidth: number, cssHeight: number, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
 
 /**
  * Populate a highlight overlay layer with a box per matched run-slice, grouped
  * by shape frame (with the shape's rotation) so each box lands on the drawn
  * glyphs.
  *
- * @param layer     the overlay div (cleared + re-sized here).
+ * All coordinates are PERCENTAGES of `cssWidth`/`cssHeight`, and the container's
+ * own size is left untouched (`width:100%;height:100%` from the caller), so the
+ * highlights track the canvas's ACTUAL rendered box even when a consumer scales
+ * the canvas down with external CSS — mirroring {@link buildPptxTextLayer}.
+ *
+ * @param layer     the overlay div (cleared here; sized `100%` by the caller).
  * @param runs      the slide's runs (same array the slide was rendered from).
  * @param matches   the slide's matches (run-slices + active flag).
- * @param cssWidth  rendered canvas CSS width (px, number).
- * @param cssHeight rendered canvas CSS height (px, number).
+ * @param cssWidth  the slide's intended CSS width (px, number) — the % denominator.
+ * @param cssHeight the slide's intended CSS height (px, number) — the % denominator.
  * @param measureForFont returns a width-measurer primed with a run's font.
  * @param colors    optional colour overrides.
  */
@@ -228,16 +264,32 @@ declare function buildPptxHighlightLayer(layer: HTMLDivElement, runs: PptxTextRu
  * (no hyperlink) is byte-identical to before. A JS click handler is used rather
  * than an `<a href>` so the URL never bypasses the viewer's sanitisation.
  *
- * @param layer     the overlay div.
+ * The overlay's coordinates are all PERCENTAGES of `cssWidth`/`cssHeight` (the
+ * slide's intended CSS-px box), never literal px, and the container's own
+ * `width`/`height` are left untouched (the caller sizes it `width:100%;
+ * height:100%` so it fills the wrapper). This lets the overlay track the canvas's
+ * ACTUAL rendered box even when a consumer scales the canvas down with external
+ * CSS (e.g. `width:100%!important;height:auto`): the wrapper (and therefore the
+ * `100%` container) shrinks with the canvas, and every `%`-placed child scales
+ * with it, so nothing overflows the wrapper into an ancestor's scroll area.
+ *
+ * @param layer     the overlay div (sized `width:100%;height:100%` by the caller).
  * @param runs      per-run + per-shape geometry from `renderSlide({ onTextRun })`.
- * @param cssWidth  the rendered canvas's CSS width (px, number).
- * @param cssHeight the rendered canvas's CSS height (px, number).
+ * @param cssWidth  the slide's intended CSS width (px, number) — the % denominator.
+ * @param cssHeight the slide's intended CSS height (px, number) — the % denominator.
  * @param onHyperlinkClick called with the run's resolved {@link HyperlinkTarget}
  *                         when a hyperlink span is clicked. Omit to leave links
  *                         non-interactive (spans stay plain, selectable text).
  */
 declare function buildPptxTextLayer(layer: HTMLDivElement, runs: PptxTextRunInfo[], cssWidth: number, cssHeight: number, onHyperlinkClick?: (target: HyperlinkTarget) => void): void;
 
+/**
+ * A paragraph's bullet marker. For `char`, the marker size is EITHER `sizePct`
+ * (a percentage of the run size — ECMA-376 §21.1.2.4.9 `<a:buSzPct>`) OR `sizePts`
+ * (an absolute size in points — §21.1.2.4.10 `<a:buSzPts>`), never both: they are
+ * the one `EG_TextBulletSize` xsd:choice. `sizePts` is optional (absent when no
+ * `<a:buSzPts>` was declared); when present it takes precedence over `sizePct`.
+ */
 declare type Bullet = {
     type: 'none';
 } | {
@@ -247,11 +299,13 @@ declare type Bullet = {
     char: string;
     color: string | null;
     sizePct: number | null;
+    sizePts?: number;
     fontFamily: string | null;
 } | {
     type: 'autoNum';
     numType: string;
     startAt: number | null;
+    color: string | null;
 };
 
 /**
@@ -678,6 +732,14 @@ declare interface ChartModel {
     title: string | null;
     categories: string[];
     series: ChartSeries[];
+    /**
+     * §21.2.2.227 `<c:varyColors val="1"/>` on a SINGLE-series bar/column chart:
+     * color each data point (bar) from the theme/palette sequence and list one
+     * legend entry per point, matching Office. Set by the shared parser ONLY for
+     * that non-pie, single-series case (pie/doughnut already vary by point via
+     * `chartType` + `dataPointColors`); absent/false otherwise.
+     */
+    varyColors?: boolean | null;
     /** Show data labels on bars / points / slices. */
     showDataLabels: boolean;
     /** Explicit Y-axis minimum (OOXML `<c:valAx><c:min>`). */
@@ -1056,8 +1118,9 @@ declare interface ChartModel {
  *  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`. */
+ *  inline box of that size; an anchored chart (§20.4.2.3) is painted via
+ *  `registerAnchorFloats` when it wraps text, or by `renderAnchorImages` for
+ *  wrapNone/no-wrap anchors — all paths use `renderChart`. */
 declare interface ChartRun {
     chart: ChartModel;
     widthPt: number;
@@ -1069,6 +1132,39 @@ declare interface ChartRun {
     anchorYPt?: number;
     anchorXFromMargin?: boolean;
     anchorYFromPara?: boolean;
+    /**
+     * Wrap mode for anchored charts (ECMA-376 §20.4.2.16/.17):
+     *   "square" | "topAndBottom" | "none" | "tight" | "through"
+     * Inline charts and undetermined cases leave this undefined. The renderer
+     * treats "tight" and "through" as "square", matching anchored images.
+     */
+    wrapMode?: string;
+    /** Padding top (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distTop?: number;
+    /** Padding bottom (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distBottom?: number;
+    /** Padding left (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distLeft?: number;
+    /** Padding right (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distRight?: number;
+    /** wrapText attribute: "bothSides" | "left" | "right" | "largest". */
+    wrapSide?: string;
+    /**
+     * ECMA-376 §20.4.2.3 `wp:anchor/@allowOverlap`. The parser omits this
+     * field when true, so renderers must read it as `allowOverlap ?? true`.
+     */
+    allowOverlap?: boolean;
+    /** ECMA-376 §20.4.3.1 wp:align horizontal: "left" | "center" | "right" |
+     *  "inside" | "outside". */
+    anchorXAlign?: string | null;
+    /** Vertical equivalent of anchorXAlign: "top" | "center" | "bottom". */
+    anchorYAlign?: string | null;
+    /**
+     * ECMA-376 §20.4.3.2 `<wp:positionH/@relativeFrom>` / §20.4.3.5
+     * `<wp:positionV/@relativeFrom>` — the raw anchor placement containers.
+     */
+    anchorXRelativeFrom?: string | null;
+    anchorYRelativeFrom?: string | null;
 }
 
 declare interface ChartSeries {
@@ -1393,12 +1489,20 @@ declare interface DocParagraph {
     shading?: string | null;
     /** Force a page break before this paragraph (w:pageBreakBefore) */
     pageBreakBefore?: boolean;
-    /** Suppress spacing between adjacent same-style paragraphs (w:contextualSpacing) */
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — between adjacent SAME-style
+     *  paragraphs, a toggling paragraph drops its OWN contribution to the
+     *  collapsed inter-paragraph gap (per-side, Word-adjudicated — issue #1015;
+     *  see the renderer's `contextualSpacingAdjust`). */
     contextualSpacing?: boolean;
     /** Keep paragraph on same page as the next paragraph (w:keepNext) */
     keepNext?: boolean;
     /** Keep all lines of this paragraph on the same page (w:keepLines) */
     keepLines?: boolean;
+    /** ECMA-376 §17.3.1.29 + §17.3.2.41 — the paragraph MARK's resolved `w:vanish`
+     *  (hidden text). An inkless paragraph whose mark is vanished collapses to zero
+     *  height in the normal/print view (hidden-text off), the same way the parser
+     *  strips hidden runs; the paginator drops it whole. Absent = mark is visible. */
+    markVanish?: boolean;
     /** Widow/orphan control (w:widowControl). ECMA-376 default is true. */
     widowControl?: boolean;
     /** Paragraph borders (w:pBdr) */
@@ -1410,6 +1514,17 @@ declare interface DocParagraph {
     /** Default font family resolved from the style chain. Used to size empty
      *  paragraphs (no runs) with the intended font's line metrics. */
     defaultFontFamily?: string | null;
+    /** Default East Asian font family resolved from the style chain. Empty /
+     *  anchor-only paragraph marks in East Asian documents use this axis for line
+     *  metrics instead of the ASCII fallback. */
+    defaultFontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.3.1.29 — the paragraph MARK run's resolved `w:color` (direct
+     *  pPr/rPr → pStyle chain → docDefaults; hex 6 without `#`, lowercased; an
+     *  explicit `auto` surfaces as absent, §17.3.2.6). Word formats a numbering
+     *  marker with the level rPr (§17.9.24) layered over the mark's run
+     *  properties, so the renderer uses this as the marker-color fallback when
+     *  {@link NumberingInfo.color} is absent. */
+    paragraphMarkColor?: string | null;
     /**
      * ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left paragraph. `true` = RTL,
      * `false` = explicitly LTR, absent = unspecified (inherit). The renderer uses
@@ -1487,6 +1602,17 @@ declare interface DocSettings {
      *  tab stops generated after all custom stops. `undefined` ⇒ the renderer
      *  uses the spec default of 720 twips (36pt). */
     defaultTabStop?: number;
+    /** §17.15.1.18 `w:characterSpacingControl@w:val` — East Asian punctuation /
+     *  character-spacing control. */
+    characterSpacingControl?: string;
+    /** §17.15.3.1 `w:compat/w:useFELayout` — Far East layout compatibility. */
+    useFeLayout?: boolean;
+    /** §17.15.3.1 `w:compat/w:balanceSingleByteDoubleByteWidth` — balance
+     *  single-byte and double-byte widths for East Asian layout. */
+    balanceSingleByteDoubleByteWidth?: boolean;
+    /** §17.15.3.1 `w:compat/w:adjustLineHeightInTable` — apply the section
+     *  document-grid line pitch to text in table cells. */
+    adjustLineHeightInTable?: boolean;
 }
 
 declare interface DocTable {
@@ -1568,6 +1694,9 @@ declare interface DocTableRow {
      *  lower bound; "exact" = fixed clip. */
     rowHeightRule: 'auto' | 'atLeast' | 'exact' | string;
     isHeader: boolean;
+    /** ECMA-376 §17.4.6 `<w:cantSplit>` — when true, the row must not be split
+     *  across page boundaries. Omitted/false rows may split at page boundaries. */
+    cantSplit?: boolean;
 }
 
 export declare namespace docx {
@@ -1829,6 +1958,16 @@ declare interface DocxDocumentModel {
      * entry is absent or classified as "auto".
      */
     fontFamilyClasses?: Record<string, string>;
+    /**
+     * ECMA-376 §17.8.3.29 — per-font pitch from `word/fontTable.xml`
+     * (`<w:pitch>`, ST_Pitch §17.18.66): font name → "fixed" | "variable" |
+     * "default". Present only for fonts that declare `<w:pitch>`. The renderer
+     * pairs this with {@link fontFamilyClasses}: a `family="modern"` face is
+     * treated as monospace ONLY when its pitch is "fixed"; "variable" /
+     * "default" / absent fall through to name-pattern / CJK-sans classification
+     * (§17.8.3.10 `family` classifies the design, not the pitch — issue #855).
+     */
+    fontFamilyPitches?: Record<string, string>;
     /** ECMA-376 §17.8.3.3-.6 — embedded fonts from `word/fontTable.xml`, resolved
      *  to their `.odttf` part paths + fontKey. The viewer de-obfuscates (§17.8.1)
      *  and registers each as a FontFace before pagination so text measures/draws
@@ -2131,6 +2270,12 @@ declare class DocxScrollViewer implements ZoomableViewer {
      * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and scrolls there
      * with {@link scrollToPage}. An anchor naming no known bookmark is a safe no-op
      * rather than a scroll to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
      */
     private _hyperlinkHandler;
     /** A width-measurer primed with a run's `font` — used ONLY to clamp a §17.3.2.10
@@ -2139,6 +2284,10 @@ declare class DocxScrollViewer implements ZoomableViewer {
      *  unavailable so the caller still gets a callable (the overlay then sees scale
      *  1 and leaves the span un-clamped). */
     private _measureForFont;
+    /** A canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path,
+     *  falling back to the backing-store size when unset; tolerates the `px` suffix. */
+    private _canvasCssPx;
     /** Route an async render failure to `onError`, or `console.error` when none is
      *  set (so failures are never fully silent), and never after teardown. */
     private _reportRenderError;
@@ -2435,6 +2584,13 @@ declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTex
      *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
      *  internal → jump to the page whose text contains the bookmark (best-effort). */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  but are inert, like plain text. */
+    enableHyperlinks?: boolean;
     /** Error callback. When set, `load()` invokes it and resolves (otherwise the
      *  error is rethrown — shared viewer error contract). It ALSO fires for async
      *  per-slot render failures (both main `renderPage` and worker
@@ -2533,12 +2689,22 @@ declare interface DocxTextRun {
     /** ECMA-376 §17.3.2.20 `<w:lang w:bidi>` — complex-script (RTL) language tag,
      *  lower-cased (e.g. "ar-sa", "ae-ar"). Drives Word's AN digit ordering. */
     langBidi?: string;
+    /** ECMA-376 §17.3.2.34 `<w:snapToGrid>` — false opts this run out of the
+     *  section character grid; absent inherits participation. */
+    snapToGrid?: boolean;
     /** ECMA-376 §17.3.2.35 `<w:spacing w:val>` — character-spacing adjustment in
      *  POINTS (signed): the extra pitch added after each character before the next
      *  is rendered. The renderer feeds it to `ctx.letterSpacing` on BOTH the
      *  measure and paint passes so line breaking / pagination stay consistent.
      *  Absent ⇒ no extra pitch. */
     charSpacing?: number;
+    /** ECMA-376 §17.3.2.14 `<w:fitText>` — manual run-width target in TWIPS
+     *  (`w:val`, 1/20 pt) plus the optional `w:id` that links consecutive runs
+     *  into one region. The arbitrary-precision XSD integer id is serialized as a
+     *  string; numeric synthetic inputs remain supported for layout tests and
+     *  direct model construction. An id-less run is always standalone. */
+    fitTextVal?: number;
+    fitTextId?: string | number;
     /** ECMA-376 §17.3.2.43 `<w:w w:val>` — horizontal text scale as a FRACTION of
      *  normal character width (0.67 = 67%, 2.0 = 200%). Stretches each glyph's
      *  width, not the gap between glyphs. Absent ⇒ 100%. */
@@ -2592,6 +2758,9 @@ declare interface DocxTextRunInfo {
     fontSize: number;
     /** CSS `font` shorthand used for canvas drawing (e.g. `"bold 16px Arial"`). */
     font: string;
+    /** Uniform per-code-point pitch in CSS px used to draw a horizontal run.
+     *  Absent when the pitch is zero or the run uses vertical / 縦中横 paint. */
+    letterSpacingPx?: number;
     /** ECMA-376 §17.6.20 (tbRl) — when the page is vertical the canvas is the
      *  physical landscape page rotated +90° at paint, so this run's `x`/`y` are the
      *  PHYSICAL top-left the overlay span must sit at, and `transform` is the CSS
@@ -2801,6 +2970,11 @@ declare class DocxViewer implements ZoomableViewer {
     /** Draw the find-highlight boxes for the current page from its runs. Clears
      *  the overlay when there is no active find. */
     private _buildHighlightLayer;
+    /** The canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path
+     *  (which mirror the render's logical size), falling back to the backing-store
+     *  dimensions when unset. Parsing tolerates the trailing `px`. */
+    private _canvasCssPx;
     /** A width-measurer primed with `font`, backed by a private 1×1 canvas so it
      *  never disturbs the visible canvas's context state. */
     private _measureForFont;
@@ -2819,6 +2993,12 @@ declare class DocxViewer implements ZoomableViewer {
      * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and jumps there
      * with {@link goToPage}. An anchor naming no known bookmark is a safe no-op
      * rather than a jump to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
      */
     private _hyperlinkHandler;
 }
@@ -2848,6 +3028,15 @@ declare interface DocxViewerOptions extends RenderPageOptions, LoadOptions_4 {
      *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
      *  internal → jump to the page whose text contains the bookmark (best-effort). */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  (their colour/underline are painted on the canvas) but are inert, like plain
+     *  text. Set it to disable clickable links entirely — e.g. in a preview where
+     *  navigation must not leave the current view. */
+    enableHyperlinks?: boolean;
     /** Called on parse or render errors. */
     onError?: (err: Error) => void;
 }
@@ -3245,6 +3434,14 @@ declare interface ImageFill {
     tile?: TileInfo;
     /** `a:blip > a:alphaModFix@amt` as a fraction (0.0–1.0). Absent = opaque. */
     alpha?: number;
+    /**
+     * ECMA-376 §20.1.8.23 `<a:duotone>` recolour, resolved to its two endpoint
+     * colours (through the slide theme). Absent ⇒ no duotone. When present the
+     * renderer maps the blip's luminance ramp between the two colours (core
+     * `applyDuotone`) — the same recolour a `<p:pic>` duotone applies, wired onto
+     * the picture-FILL path (§20.1.8.14) by issue #889.
+     */
+    duotone?: Duotone;
 }
 
 declare interface ImageRun {
@@ -3846,6 +4043,19 @@ declare interface NumberingInfo {
      *  this family. Absent ⇒ the renderer falls back to
      *  {@link NumberingInfo.fontFamily}. */
     fontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.9.24 — the numbering level rPr's `w:color` (hex 6 without
+     *  `#`, lowercased). Colors the marker glyph only, never the paragraph's
+     *  runs. Absent ⇒ the renderer falls back to
+     *  {@link DocParagraph.paragraphMarkColor} (§17.3.1.29 — Word layers the
+     *  level rPr over the paragraph mark's run properties) and finally to its
+     *  default ink. An explicit `w:val="auto"` is absent here + {@link colorAuto}. */
+    color?: string | null;
+    /** ECMA-376 §17.3.2.6 / ST_HexColorAuto (§17.18.39) — true when the level
+     *  rPr carries an EXPLICIT `w:color w:val="auto"`. Auto names no concrete
+     *  color but is not "unset": it breaks the paragraph-mark fallback, so the
+     *  marker draws the automatic (default) ink instead of
+     *  {@link DocParagraph.paragraphMarkColor}. */
+    colorAuto?: boolean;
     /** ECMA-376 §17.9.9/§17.9.20 — when the level uses a `<w:lvlPicBulletId>`,
      *  the marker is this image (zip path, e.g. `word/media/image1.gif`), drawn in
      *  place of {@link NumberingInfo.text}. Absent ⇒ ordinary text/glyph marker. */
@@ -4043,6 +4253,14 @@ declare interface Paragraph_2 extends Paragraph {
      * emits an effective boolean.
      */
     eaLnBrk: boolean;
+    /**
+     * `<a:pPr defTabSz>` (ECMA-376 §21.1.2.2.7) — the default tab-stop interval in
+     * EMU. When a `\t` has no reachable explicit `a:tabLst` stop, it advances to
+     * the next multiple of this grid (issue #1006). Absent ⇒ the renderer uses the
+     * PowerPoint universal default of 914400 EMU (1 inch). Omitted from JSON when
+     * the parser found no explicit value.
+     */
+    defTabSz?: number;
 }
 
 declare interface ParagraphBorders {
@@ -5007,6 +5225,15 @@ declare class PptxScrollViewer implements ZoomableViewer {
      * to the target slide via {@link scrollToSlide} once the action resolves to a
      * slide index (a jump resolving to no reachable slide is a safe no-op).
      */
+    /**
+     * IX1 — the click handler passed to the text-layer overlay, or `undefined` when
+     * `enableHyperlinks` is `false`. This is the single gate that disables hyperlink
+     * interactivity: {@link buildPptxTextLayer} renders link runs exactly like plain
+     * runs when no handler is supplied, so no hit region, cursor, tooltip, listener,
+     * or navigation is wired (a custom `onHyperlinkClick` is suppressed too). When
+     * enabled, the returned handler dispatches through {@link _onHyperlinkClick}.
+     */
+    private _hyperlinkHandler;
     private _onHyperlinkClick;
     /** Populate an internal {@link HyperlinkTarget}'s `slideIndex` from its `ref`
      *  via the engine's stamped part names. Relative `hlinkshowjump` verbs are
@@ -5173,6 +5400,13 @@ declare interface PptxScrollViewerOptions extends Omit<RenderSlideOptions, 'onTe
      * instead and takes NO default action.
      */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: the overlay's link
+     *  spans are non-interactive, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal slide jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  but are inert, like plain text. */
+    enableHyperlinks?: boolean;
 }
 
 /** Information about a rendered text segment for building a transparent selection overlay. */
@@ -5412,6 +5646,15 @@ declare class PptxViewer implements ZoomableViewer {
     /** Rebuild the highlight overlay for the current slide from cached runs. */
     private _redrawHighlights;
     private _buildTextLayer;
+    /**
+     * IX1 — the click handler passed to the text-layer overlay, or `undefined` when
+     * `enableHyperlinks` is `false`. This is the single gate that disables hyperlink
+     * interactivity: {@link buildPptxTextLayer} renders link runs exactly like plain
+     * runs when no handler is supplied, so no hit region, cursor, tooltip, listener,
+     * or navigation is wired (a custom `onHyperlinkClick` is suppressed too). When
+     * enabled, the returned handler dispatches through {@link _onHyperlinkClick}.
+     */
+    private _hyperlinkHandler;
     /**
      * IX1/IX-nav hyperlink click dispatch. An internal target is first *enriched*
      * with its resolved 0-based `slideIndex` (via
@@ -5508,6 +5751,14 @@ declare interface PptxViewerOptions extends RenderOptions, LoadOptions {
      * viewer calls this instead and takes NO default action.
      */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: the overlay's link
+     *  spans are non-interactive, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal slide jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  (theme `hlink` colour + underline are painted on the canvas) but are inert,
+     *  like plain text. */
+    enableHyperlinks?: boolean;
 }
 
 declare interface Presentation {
@@ -5794,6 +6045,10 @@ declare interface RubyAnnotation {
     text: string;
     /** Annotation font size in pt. Word stores this as half-points in `<w:hps>`. */
     fontSizePt: number;
+    /** Distance “between the phonetic guide base text and the phonetic guide
+     *  text” in pt. Word stores this as half-points in `<w:hpsRaise>`
+     *  (ECMA-376 §17.3.3.12). */
+    hpsRaisePt?: number;
 }
 
 declare interface Run {
@@ -6067,6 +6322,14 @@ declare interface ShapeElement {
     /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
      *  rendered in Phase A. */
     sp3d?: Sp3d;
+    /** `<p:nvSpPr><p:cNvPr @id>` — DrawingML cNvPr id. Present for file-authored
+     *  shapes (the attribute is schema-required); absent on parser-synthesized
+     *  shapes such as the SmartArt data-model fallback. */
+    id?: string;
+    /** `<p:nvSpPr><p:cNvPr @name>` — author-visible shape name (e.g. "Title 1").
+     *  The SmartArt data-model fallback synthesizes `name: "SmartArt"` with no
+     *  {@link ShapeElement.id} (see smartart-fallback-contrast.ts). */
+    name?: string;
     /** Shape-level hyperlink target resolved from `<p:cNvPr><a:hlinkClick @r:id>`
      *  via slide _rels (ECMA-376 §21.1.2.3.5). For an external link this is the
      *  URL; for an internal slide jump it is the resolved internal part name.
@@ -6216,7 +6479,7 @@ declare interface ShapeRun {
     groupHeightPt?: number | null;
     /** Draw behind text when true (wp:anchor behindDoc="1"). */
     behindDoc?: boolean;
-    /** Document-order index within a group; lower values render first. */
+    /** ECMA-376 §20.4.2.3 `wp:anchor/@relativeHeight`: lower values render first. */
     zOrder: number;
     /** Normalized [0,1] custom-geometry sub-paths. Empty when `presetGeometry`
      *  is set; the renderer chooses between buildCustomPath and buildShapePath. */
@@ -6224,8 +6487,10 @@ declare interface ShapeRun {
     /** OOXML <a:prstGeom prst> name (e.g. "rect", "ellipse", "rtTriangle").
      *  When set the renderer calls core's buildShapePath with `adjValues`. */
     presetGeometry?: string | null;
-    /** Up to four <a:gd name="adj{n}"> values from prstGeom/avLst (0–100000). */
-    adjValues?: number[];
+    /** <a:gd name="adj{n}"> values from prstGeom/avLst in adj1..adj8 order.
+     *  `null` preserves omitted named guides so the preset engine can use the
+     *  geometry's default for that index. */
+    adjValues?: Array<number | null>;
     fill: ShapeFill | null;
     stroke: string | null;
     strokeWidth?: number;
@@ -6275,6 +6540,14 @@ declare interface ShapeRun {
     textInsetT?: number;
     textInsetR?: number;
     textInsetB?: number;
+    /** ECMA-376 §20.1.10.83 ST_TextVerticalType — the text-body flow direction from
+     *  `<wps:bodyPr vert>` / `<a:bodyPr vert>`. Recognised vertical values:
+     *  "vert" (all glyphs 90° CW, chars T→B, lines R→L), "vert270" (all glyphs 270°
+     *  CW = 90° CCW, chars B→T, lines L→R), and "eaVert" (East-Asian upright: CJK
+     *  stands upright, non-EA rotated 90°, chars T→B, lines R→L). "horz"/absent ⇒
+     *  horizontal (unchanged). Unrecognised values ("mongolianVert", "wordArtVert",
+     *  …) fall back to horizontal until implemented. */
+    textVert?: string | null;
     /** ECMA-376 Part 4 §19.1.2.23 `<v:textpath>` — WordArt text laid on the
      *  shape path (a text watermark). When set the renderer draws this string,
      *  scaled to fill the box (`fitshape`), rotated by {@link ShapeRun.rotation},
@@ -6330,6 +6603,8 @@ declare interface ShapeText_2 {
      *  (image blocks / legacy single-format paragraphs). Absent for image-only
      *  paragraphs. */
     runs?: ShapeTextRun_2[];
+    /** ECMA-376 §17.9 paragraph numbering for text-box paragraphs. */
+    numbering?: NumberingInfo | null;
     alignment: string;
     /** ECMA-376 §17.3.1.33 `<w:spacing w:before>` of this text-box paragraph, in
      *  pt — reserved ABOVE the paragraph inside the box. Absent/0 ⇒ no offset. */
@@ -6367,6 +6642,19 @@ declare interface ShapeText_2 {
      *  base direction for the UAX#9 reordering pass (the body renderer reads the
      *  identical field). */
     bidi?: boolean;
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — resolved through the style
+     *  chain in the parser. When set, this text-box paragraph drops its OWN
+     *  contribution to the collapsed gap against an ADJACENT paragraph that
+     *  shares its {@link ShapeText.styleId} (per-side, Word-adjudicated — issue
+     *  #1015; identical to {@link DocParagraph.contextualSpacing} via the
+     *  renderer's `contextualSpacingAdjust`). Absent ⇒ no suppression. */
+    contextualSpacing?: boolean;
+    /** Resolved paragraph style id of this text-box paragraph — the explicit
+     *  `<w:pStyle>`, else the document default paragraph style, else "Normal" (the
+     *  same stable id {@link DocParagraph.styleId} carries). Paired with
+     *  {@link ShapeText.contextualSpacing} to group adjacent same-style paragraphs
+     *  for §17.3.1.9. */
+    styleId?: string | null;
     /** Zip path of an inline image inside this text-box paragraph
      *  (`<w:drawing><wp:inline><a:blip r:embed>`), e.g. `word/media/image1.emf`.
      *  Absent for a text-only paragraph. */
@@ -6438,6 +6726,8 @@ declare interface ShapeTextRun_2 {
     fontFamilyEastAsia?: string | null;
     bold?: boolean;
     italic?: boolean;
+    /** ECMA-376 §17.3.3.25 ruby annotation (furigana) for text-box runs. */
+    ruby?: RubyAnnotation | null;
 }
 
 declare interface SharedString {
@@ -6766,7 +7056,10 @@ declare interface TableRow {
 }
 
 declare interface TabStop {
-    /** Position in EMU from the left edge of the text area (after lIns) */
+    /** Position in EMU from the LEADING text-inset edge of the text area —
+     *  logical, not physical (ECMA-376 §21.1.2.1): the left edge (after lIns)
+     *  in an LTR paragraph, the right edge (before rIns) in an RTL
+     *  (`<a:pPr rtl="1">`) paragraph. */
     pos: number;
     /** Alignment: "l" | "r" | "ctr" | "dec" */
     algn: string;
@@ -7803,7 +8096,13 @@ declare class XlsxViewer implements ZoomableViewer {
      *  match the renderer's `hyperlinkMap` exactly (`${hl.row}:${hl.col}`). */
     private buildHyperlinkMap;
     /** IX1 — the hyperlink at a cell, or null. `getCellAt` returns 1-based
-     *  {row,col}, matching the parser/renderer keying. */
+     *  {row,col}, matching the parser/renderer keying.
+     *
+     *  Returns null unconditionally when `enableHyperlinks` is `false`: this is the
+     *  single gate that disables hyperlink interactivity. Both consumers — the
+     *  pointermove pointer-cursor affordance and the click dispatch
+     *  ({@link dispatchHyperlink}) — funnel through this hit-test, so a null result
+     *  means no cursor change, no default navigation, and no `onHyperlinkClick`. */
     private hyperlinkAtCell;
     /**
      * IX1 — dispatch a click on a hyperlinked cell. Builds a
@@ -7990,6 +8289,13 @@ declare interface XlsxViewerOptions extends LoadOptions_2 {
      * default handler's job, so a blocked scheme still reaches a custom callback).
      */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the cell hit-test reports no hyperlink under any cell, so hyperlink
+     *  interactivity is disabled entirely: no pointer cursor over a link, no default
+     *  navigation (external new-tab / internal sheet jump), and `onHyperlinkClick`
+     *  is never called. Hyperlinked cells still render exactly as authored but are
+     *  inert. */
+    enableHyperlinks?: boolean;
     /**
      * Color of the cell-selection highlight. A single CSS color drives both the
      * selection rectangle's border (drawn in this color) and its fill (the same
@@ -8135,6 +8441,14 @@ declare class XlsxWorkbook {
      * validation-list expansion use). Returns `''` before the workbook is loaded.
      */
     cellText(ws: Worksheet, cell: Cell): string;
+    /**
+     * Render a sheet viewport into `target`. Note: `opts.fetchImage` is ignored
+     * here — image bytes always come from this workbook's own archive through its
+     * stable per-instance loader, whose closure identity keys the shared decoded
+     * caches, the render-pass lease, and {@link destroy}'s cache drops. Callers
+     * needing a custom byte source should use the standalone
+     * `renderWorksheetViewport` orchestrator directly.
+     */
     renderViewport(target: HTMLCanvasElement | OffscreenCanvas, sheetIndex: number, viewport: ViewportRange, opts?: RenderViewportOptions): Promise<void>;
     /**
      * Render a sheet viewport and return it as an ImageBitmap (both modes; in