@silurus/ooxml 0.56.0 → 0.58.0

package/dist/types/index.d.ts

@@ -32,6 +32,19 @@ declare interface AutoResizeOptions {
     pauseWhenHidden?: boolean;
 }
 
+/**
+ * `<a:bevel>` — ECMA-376 §20.1.5.3 (`CT_Bevel`). Lengths in EMU; `w`/`h`
+ * default to 76200 EMU and `prst` to "circle".
+ */
+declare interface Bevel3d {
+    /** Bevel width in EMU. */
+    w: number;
+    /** Bevel height in EMU. */
+    h: number;
+    /** Bevel preset name (`ST_BevelPresetType`). */
+    prst: string;
+}
+
 declare type BodyElement = {
     type: 'paragraph';
 } & DocParagraph | {
@@ -83,6 +96,21 @@ declare type Bullet = {
     startAt: number | null;
 };
 
+/**
+ * `<a:camera>` — ECMA-376 §20.1.5.5 (`CT_Camera`). `prst` selects one of the
+ * 62 preset cameras (§20.1.10.47); `fov`/`zoom`/`rot` optionally override it.
+ */
+declare interface Camera3d {
+    /** Preset camera name (`ST_PresetCameraType`), e.g. "perspectiveRelaxed". */
+    prst: string;
+    /** Field-of-view override in degrees. Omitted = preset default. */
+    fov?: number;
+    /** Zoom factor as a unit ratio (1.0 = 100%). Omitted = 1.0. */
+    zoom?: number;
+    /** Camera rotation override. Omitted = preset base orientation. */
+    rot?: Rot3d;
+}
+
 declare interface Cell {
     col: number;
     row: number;
@@ -223,6 +251,8 @@ declare type CfRule = {
 } | {
     type: 'aboveAverage';
     aboveAverage: boolean;
+    equalAverage?: boolean;
+    stdDev?: number;
     dxfId: number | null;
     priority: number;
 } | {
@@ -305,7 +335,7 @@ declare interface ChartData {
      *  adapter tell "spec said noFill → transparent" from "no spPr → default". */
     hasChartSpPr?: boolean;
     /** `<c:legend><c:manualLayout>` fractions of chart space (§21.2.2.31). */
-    legendManualLayout?: LegendManualLayout | null;
+    legendManualLayout?: LegendManualLayout_2 | null;
     /** `<c:catAx><c:delete val="1"/>` — hide the category axis (§21.2.2.40). */
     catAxisHidden?: boolean;
     /** `<c:valAx><c:delete val="1"/>` — hide the value axis (§21.2.2.40). */
@@ -512,6 +542,169 @@ declare interface ChartManualLayout {
     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: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;
+}
+
 declare interface ChartSeries {
     name: string;
     /** Hex without '#'. null = fall back to palette. */
@@ -626,6 +819,13 @@ declare interface ChartSeriesDataLabels {
     fontSizeHpt?: number;
 }
 
+/**
+ * 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' | string;
+
 declare interface ConditionalFormat {
     sqref: CellRange[];
     rules: CfRule[];
@@ -650,6 +850,28 @@ declare interface DataPointOverride {
     markerLine?: string;
 }
 
+/** One `<dataValidation>` rule (ECMA-376 §18.3.1.33). `type` is the constraint
+ *  class (`list` | `whole` | `decimal` | `date` | `time` | `textLength` |
+ *  `custom`); `operator` qualifies it (`between` | `notBetween` | `equal` | …).
+ *  `formula1` / `formula2` are the operands (for `list`, `formula1` is the
+ *  comma-separated literal list or a range/named reference). 1:1 with the Rust
+ *  `DataValidation` (serde camelCase). */
+declare interface DataValidation {
+    /** Affected cell ranges, verbatim from `@sqref` (space-separated A1 refs). */
+    sqref: string;
+    /** Constraint class. Absent means the spec default (`none`, no constraint). */
+    validationType?: string;
+    operator?: string;
+    formula1?: string;
+    formula2?: string;
+    /** `@allowBlank` — empty input is permitted. */
+    allowBlank?: boolean;
+    promptTitle?: string;
+    prompt?: string;
+    errorTitle?: string;
+    errorMessage?: string;
+}
+
 declare interface DefinedName {
     name: string;
     formula: string;
@@ -665,7 +887,12 @@ declare interface DocComment {
 
 declare interface DocNote {
     id: string;
-    text: string;
+    /** ECMA-376 §17.11.2 / §17.11.10 — the note's block-level content
+     *  (paragraphs / nested tables), parsed with the document's styles +
+     *  numbering. The leading run is the `<w:footnoteRef/>` auto-number marker
+     *  (carries a {@link DocxTextRun.noteRef}). Use {@link noteText} to extract
+     *  the plain-text body without the marker. */
+    content: BodyElement[];
 }
 
 declare interface DocParagraph {
@@ -707,10 +934,21 @@ declare interface DocParagraph {
     defaultFontFamily?: string | null;
     /**
      * ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left paragraph. `true` = RTL,
-     * `false` = explicitly LTR, absent = unspecified (inherit). Phase 0 of RTL
-     * support: recorded only; alignment/column-order resolution is deferred.
+     * `false` = explicitly LTR, absent = unspecified (inherit). The renderer uses
+     * this as the paragraph base direction: it seeds the UAX#9 reordering pass
+     * (`computeLineVisualOrder`), swaps the left/right indents, resolves the
+     * `w:jc` start/end edges (`resolveAlignEdge`), and lays out lines from the
+     * right.
      */
     bidi?: boolean;
+    /**
+     * ECMA-376 §17.3.1.32 `<w:snapToGrid>` — when `false`, this paragraph opts out
+     * of the section's document grid (`w:docGrid`): its lines use natural font
+     * metrics / the line-spacing multiplier directly instead of snapping to the
+     * grid pitch. `undefined` = inherit (default on). Set on Word's "Footnote
+     * Text" style, so footnote bodies use compact natural line height.
+     */
+    snapToGrid?: boolean;
 }
 
 declare interface DocRevision {
@@ -775,8 +1013,8 @@ declare interface DocTable {
     /**
      * ECMA-376 §17.4.1 `<w:bidiVisual>` — render columns in right-to-left
      * (visual) order. `true` = RTL columns, `false` = explicitly LTR, absent =
-     * unspecified. Phase 0 of RTL support: recorded only; column-order
-     * resolution is deferred.
+     * unspecified. When `true` the renderer mirrors the grid so logical column 0
+     * is placed rightmost, and flips per-cell left/right borders accordingly.
      */
     bidiVisual?: boolean;
 }
@@ -821,18 +1059,41 @@ export declare namespace docx {
         DocxViewerOptions,
         autoResize,
         AutoResizeOptions,
+        noteText,
         DocxDocumentModel,
+        DocSettings,
         SectionProps,
+        HeadersFooters,
+        HeaderFooter,
+        NumberingInfo,
         BodyElement,
         DocParagraph,
         DocRun,
         DocxTextRun,
+        FieldRun,
         ImageRun,
+        ShapeRun,
+        ShapeText_2 as ShapeText,
+        RubyAnnotation,
         RenderPageOptions,
         RunRevision,
         DocRevision,
         DocComment,
         DocNote,
+        NoteRef,
+        LineSpacing,
+        TabStop_2 as TabStop,
+        ParagraphBorders,
+        ParaBorderEdge,
+        DocTable,
+        DocTableRow,
+        DocTableCell,
+        CellElement,
+        TableBorders,
+        CellBorders,
+        BorderSpec,
+        PathCmd_3 as PathCmd,
+        GradientStop_2 as GradientStop,
         DocxTextRunInfo
     }
 }
@@ -848,6 +1109,29 @@ declare class DocxDocument {
     destroy(): void;
     get pageCount(): number;
     get document(): DocxDocumentModel;
+    /**
+     * ECMA-376 §17.13.4 — the document's comments (`word/comments.xml`), each with
+     * id / author / initials / date / plain-text body. Comments are a data-only
+     * API: they are NOT drawn on the page (Word renders them in a margin pane /
+     * balloons, which this viewer does not reproduce). Use this to build a review
+     * panel, export an annotation list, etc. Returns `[]` when the document has no
+     * comments part. The same data is also reachable via `document.comments`.
+     */
+    get comments(): DocComment[];
+    /**
+     * ECMA-376 §17.11.10 — the document's footnotes (`word/footnotes.xml`),
+     * excluding the reserved separator entries. Each note carries its `id` and
+     * block-level `content`; use {@link noteText} for the plain-text body. These
+     * ARE drawn at the bottom of the page that holds their reference; this getter
+     * additionally exposes them as data. Returns `[]` when absent.
+     */
+    get footnotes(): DocNote[];
+    /**
+     * ECMA-376 §17.11.4 — the document's endnotes (`word/endnotes.xml`). Same
+     * shape as {@link footnotes}; rendered at the end of the document. Returns
+     * `[]` when absent.
+     */
+    get endnotes(): DocNote[];
     private _getPages;
     renderPage(target: HTMLCanvasElement | OffscreenCanvas, pageIndex: number, opts?: RenderPageOptions): Promise<void>;
 }
@@ -918,8 +1202,10 @@ declare interface DocxTextRun {
      *  tracked changes appear inline. */
     revision?: RunRevision;
     /** ECMA-376 §17.3.2.30 `<w:rtl>` — complex-script / right-to-left run.
-     *  `true` = RTL, `false` = explicitly LTR, absent = unspecified.
-     *  Phase 0: recorded only; glyph-order resolution is deferred. */
+     *  `true` = RTL, `false` = explicitly LTR, absent = unspecified. The renderer
+     *  treats a `true` run as RTL for the UAX#9 pass (it forces complex-script
+     *  shaping and marks the segment so `computeLineVisualOrder` reorders it), and
+     *  draws the slice with `ctx.direction = 'rtl'` so Canvas mirrors the glyphs. */
     rtl?: boolean;
     /** ECMA-376 §17.3.2.7 `<w:cs/>` — complex-script run toggle: cs formatting
      *  applies to ALL characters of the run (§17.3.2.26). Distinct from
@@ -938,6 +1224,12 @@ 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.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
+     *  the raw `@w:id`; the renderer overrides the displayed glyph with the note's
+     *  sequential number. */
+    noteRef?: NoteRef;
 }
 
 /** Information about a rendered text segment for building a transparent selection overlay. */
@@ -1061,7 +1353,20 @@ declare interface FieldRun {
     highlight?: string | null;
 }
 
-declare type Fill = SolidFill | NoFill | GradientFill | PatternFill;
+declare type Fill = SolidFill | NoFill | GradientFill | PatternFill | ImageFill;
+
+/**
+ * ECMA-376 §20.1.8.30 (CT_RelativeRect) — the destination rectangle a stretched
+ * blip is mapped into, as edge insets relative to the fill region. Values are
+ * fractions (ST_Percentage / 100000); **negative values let the image bleed
+ * past the box (overscan)**. Absent edges default to 0.
+ */
+declare interface FillRect {
+    l?: number;
+    t?: number;
+    r?: number;
+    b?: number;
+}
 
 /** ECMA-376 §20.1.8.17 (CT_GlowEffect) — coloured halo with blur radius. */
 declare interface Glow {
@@ -1150,6 +1455,30 @@ declare interface ImageAnchor {
     dataUrl: string;
 }
 
+/**
+ * Image fill — ECMA-376 §20.1.8.14 (CT_BlipFillProperties). The embedded blip
+ * is resolved to a base64 data URL at parse time. Both fill-modes are modelled
+ * and mutually exclusive: `stretch` (§20.1.8.56) carries {@link ImageFill.fillRect};
+ * `tile` (§20.1.8.58) carries {@link ImageFill.tile}.
+ */
+declare interface ImageFill {
+    fillType: 'image';
+    /** `data:<mime>;base64,…` of the embedded blip. */
+    dataUrl: string;
+    /**
+     * `<a:stretch><a:fillRect>` insets. Absent → fills the whole box (or the
+     * fill is tiled — see {@link ImageFill.tile}).
+     */
+    fillRect?: FillRect;
+    /**
+     * `<a:tile>` descriptor. Present only when the blipFill is tiled; mutually
+     * exclusive with {@link ImageFill.fillRect}.
+     */
+    tile?: TileInfo;
+    /** `a:blip > a:alphaModFix@amt` as a fraction (0.0–1.0). Absent = opaque. */
+    alpha?: number;
+}
+
 declare interface ImageRun {
     dataUrl: string;
     widthPt: number;
@@ -1195,14 +1524,39 @@ declare interface ImageRun {
 }
 
 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;
 }
 
+declare interface LegendManualLayout_2 {
+    xMode: string;
+    yMode: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+/**
+ * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Drives the bevel-lip
+ * lighting (Phase B): `dir` selects the key-light octant.
+ */
+declare interface LightRig {
+    /** Light-rig preset (`ST_LightRigType`), e.g. "threePt". */
+    rig: string;
+    /** Light direction (`ST_LightRigDirection`): tl/t/tr/l/r/bl/b/br. */
+    dir: string;
+    /** Optional rotation override of the rig. */
+    rot?: Rot3d;
+}
+
 declare interface LineBreak {
     type: 'break';
 }
@@ -1449,6 +1803,20 @@ declare interface NoFill {
     fillType: 'none';
 }
 
+/** A footnote / endnote reference marker (ECMA-376 §17.11). */
+declare interface NoteRef {
+    /** "footnote" | "endnote" */
+    kind: 'footnote' | 'endnote' | string;
+    /** `@w:id` linking the marker to its note. Empty for the in-note
+     *  `<w:footnoteRef/>` placeholder (the renderer uses the enclosing note). */
+    id: string;
+}
+
+/** Flatten a footnote/endnote's content to its plain-text body, excluding the
+ *  auto-number reference marker. Convenience for data-only consumers
+ *  (the renderer draws {@link DocNote.content} directly). */
+declare function noteText(note: DocNote): string;
+
 declare interface NumberingInfo {
     numId: number;
     level: number;
@@ -1635,8 +2003,29 @@ declare interface PictureElement {
     flipV: boolean;
     /** Data URL, e.g. "data:image/png;base64,..." */
     dataUrl: string;
-    /** OOXML adj value (0–100000) for roundRect clip, null = plain rectangle */
-    clipAdjust: number | null;
+    /**
+     * Border line from `<p:pic><p:spPr><a:ln>` (ECMA-376 §20.1.2.2.24). A
+     * `p:pic`'s spPr is `CT_ShapeProperties` (§19.3.1.37), so a picture carries
+     * the same line model as a shape. `null` when there is no `<a:ln>` or it
+     * resolves to `<a:noFill/>` (border explicitly suppressed). The border is
+     * stroked along the picture's clip silhouette (roundRect / custGeom / rect).
+     */
+    stroke: Stroke | null;
+    /**
+     * `<p:spPr><a:prstGeom prst="…">` preset name (e.g. `"roundRect"`,
+     * `"ellipse"`). ECMA-376 §20.1.9.18: a picture's preset geometry is its clip
+     * silhouette and the path its border / contour hug. Undefined / omitted = a
+     * plain rectangle (`prst="rect"` or no prstGeom). When set, the renderer
+     * builds the silhouette via the shared preset-geometry engine (any of the 186
+     * presets). `custGeom` takes priority when both are present.
+     */
+    prstGeom?: string;
+    /**
+     * Adjust guides from the prstGeom `<a:avLst>` (1/1000-of-a-percent OOXML
+     * units), in `gd@name` declaration order (index 0 = adj/adj1, 1 = adj2, …).
+     * Omitted when avLst is empty — the preset's own declared defaults then apply.
+     */
+    prstAdjust?: number[];
     /**
      * ECMA-376 a:srcRect — source image crop as fractions (0..1) of the source
      * width/height. Omitted when the image is not cropped.
@@ -1657,6 +2046,27 @@ declare interface PictureElement {
      * trimmed to the laptop / device silhouette declared in the file.
      */
     custGeom?: PathCmd[][] | null;
+    /**
+     * Drop shadow from `spPr > effectLst > outerShdw`. A `p:pic`'s `spPr` is
+     * `CT_ShapeProperties` (ECMA-376 §19.3.1.37), so the same effects shapes
+     * carry apply to images. ECMA-376 §20.1.8.45 (CT_OuterShadowEffect).
+     */
+    shadow?: Shadow;
+    /** Inner (inset) shadow from effectLst > innerShdw. ECMA-376 §20.1.8.40. */
+    innerShadow?: Shadow;
+    /** Coloured glow halo from effectLst > glow. ECMA-376 §20.1.8.32. */
+    glow?: Glow;
+    /** Soft (feathered) edge from effectLst > softEdge. ECMA-376 §20.1.8.53. */
+    softEdge?: SoftEdge;
+    /** Mirrored reflection from effectLst > reflection. ECMA-376 §20.1.8.50. */
+    reflection?: Reflection;
+    /** `<a:scene3d>` 3D camera scene (ECMA-376 §20.1.5.5). A `p:pic`'s spPr is
+     *  `CT_ShapeProperties`, so 3D scenes apply to images. When non-identity the
+     *  renderer projects the picture through the camera homography (Phase A). */
+    scene3d?: Scene3d;
+    /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
+     *  rendered in Phase A. */
+    sp3d?: Sp3d;
 }
 
 export declare namespace pptx {
@@ -1670,25 +2080,65 @@ export declare namespace pptx {
         RenderOptions,
         PptxTextRunInfo,
         TextRunCallback,
+        PresentationHandle,
         autoResize,
         AutoResizeOptions,
         Presentation,
         Slide,
+        PptxComment,
         SlideElement,
         ShapeElement,
         PictureElement,
+        TableElement,
+        TableRow,
+        TableCell,
+        ChartElement,
+        MediaElement,
+        TextRect,
+        Scene3d,
+        Camera3d,
+        Rot3d,
+        LightRig,
+        Sp3d,
+        Bevel3d,
         Fill,
         SolidFill,
         NoFill,
+        GradientFill,
+        GradientStop,
+        ImageFill,
+        FillRect,
+        TileInfo,
         Stroke,
+        Shadow,
+        Glow,
+        SoftEdge,
+        Reflection,
+        PathCmd,
+        Bullet,
+        SpaceLine,
+        TabStop,
         TextBody,
         Paragraph,
         TextRun,
         TextRunData,
-        LineBreak
+        LineBreak,
+        ChartModel,
+        ChartSeries
     }
 }
 
+/** A single legacy slide comment (`<p:cm>` in `ppt/comments/commentN.xml`). */
+declare interface PptxComment {
+    /** Resolved author name from `ppt/commentAuthors.xml`. Absent when the
+     *  authors file is missing or the `authorId` is out of range. */
+    author?: string;
+    /** `<p:cm @dt>` — ISO-8601 timestamp the comment was authored. */
+    date?: string;
+    /** Plain-text comment body (`<p:text>`). */
+    text: string;
+}
+
 /**
  * Headless PPTX rendering engine.
  *
@@ -1726,6 +2176,26 @@ declare class PptxPresentation {
     get slideWidth(): number;
     /** Slide height in EMU. */
     get slideHeight(): number;
+    /**
+     * Speaker-notes text for a slide (`ppt/notesSlides/notesSlideN.xml`,
+     * ECMA-376 §13.3.5 — Notes Slide). Returns the notes-body text as a single
+     * string (paragraphs joined with `\n`), or `null` when the slide has no
+     * notes part. The notes are parsed at {@link load} time, so this is a
+     * synchronous lookup.
+     *
+     * `slideIndex` is 0-based. Unlike navigation methods it is *not* clamped:
+     * an out-of-range or non-integer index returns `null` rather than the notes
+     * of the nearest slide (so a tool iterating by index gets an honest "no
+     * notes" instead of a duplicated neighbour).
+     *
+     * @example
+     * const pres = await PptxPresentation.load(buffer);
+     * for (let i = 0; i < pres.slideCount; i++) {
+     *   const notes = pres.getNotes(i);
+     *   if (notes) console.log(`Slide ${i + 1} notes:`, notes);
+     * }
+     */
+    getNotes(slideIndex: number): string | null;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
     /**
@@ -1736,9 +2206,9 @@ declare class PptxPresentation {
     private _findMimeTypeForPath;
     /**
      * Render a slide and attach canvas-native playback controls for any
-     * embedded audio/video. Returns a disposable handle that owns the RAF loop,
-     * media elements, and object URLs. Unlike {@link renderSlide}, this method
-     * is stateful — always call `handle.dispose()` when leaving the slide.
+     * embedded audio/video. Returns a {@link PresentationHandle} that owns the
+     * RAF loop, media elements, and object URLs. Unlike {@link renderSlide}, this
+     * method is stateful — always call `handle.destroy()` when leaving the slide.
      */
     presentSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<PresentationHandle>;
     /** Terminate the worker and release all resources. */
@@ -1810,6 +2280,13 @@ declare class PptxViewer {
     prevSlide(): Promise<void>;
     get slideIndex(): number;
     get slideCount(): number;
+    /**
+     * Speaker-notes text for a slide (`ppt/notesSlides/notesSlideN.xml`,
+     * ECMA-376 §13.3.5). Passthrough to {@link PptxPresentation.getNotes}:
+     * 0-based index, returns `null` when the slide has no notes part, the index
+     * is out of range, or nothing is loaded yet.
+     */
+    getNotes(slideIndex: number): string | null;
     /** The underlying <canvas> element. */
     get canvasElement(): HTMLCanvasElement;
     private renderCurrentSlide;
@@ -1857,7 +2334,13 @@ declare interface Presentation {
 declare interface PresentationHandle {
     play(mediaPath?: string): void;
     pause(mediaPath?: string): void;
-    dispose(): void;
+    /**
+     * Stop the playback RAF loop, detach pointer listeners and release every
+     * media blob URL. Named `destroy()` to match the teardown method on the
+     * viewers/documents (`PptxViewer.destroy()`, `XlsxWorkbook.destroy()`, …)
+     * so the public API uses one consistent teardown verb.
+     */
+    destroy(): void;
 }
 
 /** ECMA-376 §20.1.8.27 (CT_ReflectionEffect) — mirrored copy below the
@@ -1980,6 +2463,35 @@ declare interface RenderViewportOptions {
     } | null;
 }
 
+/**
+ * Resolved allowed-value set for a list validation. Either concrete display
+ * `values` (inline list or expanded range), or — when the operand is a defined
+ * name / complex formula we cannot expand — the raw `formula` text so the panel
+ * can disclose it instead of showing nothing.
+ */
+declare type ResolvedList = {
+    kind: 'values';
+    values: string[];
+} | {
+    kind: 'formula';
+    formula: string;
+};
+
+/**
+ * 3D rotation in sphere coordinates — ECMA-376 §20.1.5.11 (`CT_SphereCoords`).
+ * Angles are in **degrees** (the XML carries 60000ths of a degree; the parser
+ * divides once). Per the spec, `lat`/`lon` are latitude/longitude and `rev` is
+ * the revolution about the resulting view axis.
+ */
+declare interface Rot3d {
+    /** Latitude — rotation about the horizontal (X) axis, degrees. */
+    lat: number;
+    /** Longitude — rotation about the vertical (Y) axis, degrees. */
+    lon: number;
+    /** Revolution — in-plane rotation about the view (Z) axis, degrees. */
+    rev: number;
+}
+
 declare interface Row {
     index: number;
     height: number | null;
@@ -2027,6 +2539,15 @@ declare interface RunRevision {
     date?: string;
 }
 
+/**
+ * `<a:scene3d>` — ECMA-376 §20.1.4.1.41 (`CT_Scene3D`). Camera + light rig for
+ * a shape's 3D scene.
+ */
+declare interface Scene3d {
+    camera: Camera3d;
+    lightRig?: LightRig;
+}
+
 declare interface SectionProps {
     pageWidth: number;
     pageHeight: number;
@@ -2139,6 +2660,13 @@ declare interface ShapeElement {
      *  same space as x/y/width/height). When present the renderer lays text out in
      *  this rectangle instead of the preset/ellipse-derived text rectangle. */
     textRect?: TextRect;
+    /** `<a:scene3d>` 3D camera scene (ECMA-376 §20.1.5.5). When the camera is
+     *  non-identity the renderer projects the shape through the camera
+     *  homography (Phase A). */
+    scene3d?: Scene3d;
+    /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
+     *  rendered in Phase A. */
+    sp3d?: Sp3d;
 }
 
 declare type ShapeFill = {
@@ -2154,6 +2682,11 @@ declare type ShapeFill = {
 declare type ShapeGeom = {
     type: 'preset';
     name: string;
+    /** Adjust handles from `<a:avLst><a:gd>` in `adj1..adj8` order
+     *  (ECMA-376 §19.5.31.3 / §20.1.9.5). `null` entries mean "use the
+     *  preset's declared default". Omitted entirely when the shape has no
+     *  `<a:avLst>`. Consumed by the shared `renderPresetShape` engine. */
+    adj?: (number | null)[];
 } | {
     type: 'custom';
     paths: PathInfo[];
@@ -2345,6 +2878,20 @@ declare interface Slide {
     slideNumber: number;
     background: Fill | null;
     elements: SlideElement[];
+    /**
+     * Speaker-notes pane text from `ppt/notesSlides/notesSlideN.xml`
+     * (ECMA-376 §13.3.5 — Notes Slide). The full notes-body text as a single
+     * string, paragraphs joined with `\n`. Absent (`undefined`) when the slide
+     * has no notes part. The renderer ignores this — it is surfaced for tools;
+     * read it via {@link PptxPresentation.getNotes}.
+     */
+    notes?: string;
+    /**
+     * Legacy slide comments (`ppt/comments/commentN.xml`, ECMA-376 §13.3.4).
+     * Modern Office 365 threaded comments are not parsed. Omitted from the JSON
+     * when the slide has no comments.
+     */
+    comments?: PptxComment[];
 }
 
 declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
@@ -2369,6 +2916,32 @@ declare interface SolidFill {
     color: string;
 }
 
+/**
+ * `<a:sp3d>` — ECMA-376 §20.1.5.12 (`CT_Shape3D`). Rendered in Phase B: bevelT/
+ * bevelB are shaded as a lit lip (distance-field + lightRig), extrusionH as a
+ * swept side wall, and contour as a flat outline approximation. Numeric fields
+ * are omitted from JSON when zero.
+ */
+declare interface Sp3d {
+    /** Z position of the front face in EMU (default 0). */
+    z?: number;
+    /** Extrusion (depth) height in EMU (default 0). */
+    extrusionH?: number;
+    /** Contour (outline) width in EMU (default 0). */
+    contourW?: number;
+    /** Contour colour (`<a:contourClr>`, ECMA-376 §20.1.5.12) as a hex string
+     *  (e.g. "969696"). Omitted when absent. The renderer draws a flat
+     *  approximation of the 3D contour edge (uniform-width outline, no bevel
+     *  shading) when both `contourW` and `contourClr` are present. */
+    contourClr?: string;
+    /** Preset surface material (`ST_PresetMaterialType`), default "warmMatte". */
+    prstMaterial: string;
+    /** Top bevel. */
+    bevelT?: Bevel3d;
+    /** Bottom bevel. */
+    bevelB?: Bevel3d;
+}
+
 declare type SpaceLine = {
     type: 'pct';
     val: number;
@@ -2513,13 +3086,29 @@ declare interface TableInfo {
     /** Accent color resolved by the parser from the built-in style name against
      *  the file's theme accents (e.g. `TableStyleLight18` → accent3). */
     accentColor: string;
+    /** `true` when `styleName` is defined in the file's `<tableStyles>` block,
+     *  i.e. a *custom* style (ECMA-376 §18.5.1.2). The renderer draws such tables
+     *  strictly from their declared element dxfs and must NOT apply the accent
+     *  approximation (banding / synthesized rules / header) reserved for built-in
+     *  style names whose definitions are absent from the file. */
+    isCustom?: boolean;
     /** Dxf index for the `wholeTable` element of a custom `<tableStyle>`
-     *  (ECMA-376 §18.8.40). When set, its border/fill apply to every cell of
+     *  (ECMA-376 §18.8.83). When set, its border/fill apply to every cell of
      *  the table as a base layer. Undefined for built-in style names. */
     wholeTableDxf?: number;
     /** Dxf index for the `headerRow` element of a custom `<tableStyle>` —
      *  provides header background, font color/weight, and vertical separators. */
     headerRowDxf?: number;
+    /** Dxf index for the `totalRow` element (ECMA-376 §18.18.93). */
+    totalRowDxf?: number;
+    /** Dxf index for the `firstColumn` element. */
+    firstColumnDxf?: number;
+    /** Dxf index for the `lastColumn` element. */
+    lastColumnDxf?: number;
+    /** Dxf index for `firstRowStripe` (band1 horizontal) — odd banded-row stripe. */
+    band1HorizontalDxf?: number;
+    /** Dxf index for `secondRowStripe` (band2 horizontal) — even banded-row stripe. */
+    band2HorizontalDxf?: number;
     /** Per-column DXF references (ECMA-376 §18.5.1.3 `tableColumn`). Index by
      *  `cellCol - range.left`. The renderer can use these to apply column-level
      *  overlays for named-style tables; for files where Excel pre-bakes the
@@ -2698,6 +3287,29 @@ declare interface TextRunData {
     outline?: TextOutline;
 }
 
+/**
+ * ECMA-376 §20.1.8.58 (CT_TileInfoProperties) — tiled blip-fill placement.
+ * The blip repeats at its native size (scaled by sx/sy) across the fill box.
+ * Mutually exclusive with {@link ImageFill.fillRect} (the `stretch` mode).
+ */
+declare interface TileInfo {
+    /** Horizontal offset of the first tile, in EMU (`tx`). Default 0. */
+    tx: number;
+    /** Vertical offset of the first tile, in EMU (`ty`). Default 0. */
+    ty: number;
+    /** Horizontal tile scale as a fraction (`sx` / 100000). Default 1.0. */
+    sx: number;
+    /** Vertical tile scale as a fraction (`sy` / 100000). Default 1.0. */
+    sy: number;
+    /** Mirror mode: `'none' | 'x' | 'y' | 'xy'` (`flip`). Default `'none'`. */
+    flip: string;
+    /**
+     * Anchor corner the tile grid registers against:
+     * `tl|t|tr|l|ctr|r|bl|b|br` (`algn`). Default `'tl'`.
+     */
+    algn: string;
+}
+
 declare interface ViewportRange {
     row: number;
     col: number;
@@ -2745,6 +3357,17 @@ declare interface Worksheet {
     /** A1-style cell refs of commented cells (ECMA-376 §18.7.3). Rendered as a
      *  small red triangle in each cell's top-right corner. */
     commentRefs?: string[];
+    /** Full-fidelity comment bodies (cell ref + author + plain text) for every
+     *  `<comment>` in `xl/commentsN.xml` (ECMA-376 §18.7). Parallel to
+     *  {@link commentRefs} (one entry per ref). Consume this to read the note
+     *  text; the renderer uses {@link commentRefs} for the red indicator and the
+     *  viewer surfaces these bodies in an Excel-style hover popup. */
+    comments?: XlsxComment[];
+    /** Data-validation rules on this sheet (ECMA-376 §18.3.1.32–33). Exposed for
+     *  tooling. The viewer draws a list-dropdown arrow on the active cell when the
+     *  selection intersects a `list`-type rule's `sqref` (display only — opening
+     *  the list / picking a value is out of scope for a viewer). */
+    dataValidations?: DataValidation[];
     /** Defined names in scope for this sheet (ECMA-376 §18.2.5). Used by
      *  conditional-formatting `expression` rules that call named ranges
      *  (e.g. `task_start`, `today`). */
@@ -2775,6 +3398,7 @@ export declare namespace xlsx {
         XlsxWorkbook,
         LoadOptions_3 as LoadOptions,
         XlsxViewer,
+        ResolvedList,
         XlsxViewerOptions,
         CellAddress,
         CellRange_2 as CellRange,
@@ -2798,7 +3422,45 @@ export declare namespace xlsx {
         ParsedWorkbook,
         ViewportRange,
         RenderViewportOptions,
-        XlsxTextRunInfo
+        XlsxTextRunInfo,
+        Run,
+        RunFont,
+        SharedString,
+        Dxf,
+        GradientFillSpec,
+        ConditionalFormat,
+        CfRule,
+        CfValue,
+        CfStop,
+        CfIcon,
+        DefinedName,
+        Hyperlink,
+        XlsxComment,
+        DataValidation,
+        TableInfo,
+        TableColumnInfo,
+        SlicerAnchor,
+        SlicerItem,
+        SparklineGroup,
+        Sparkline,
+        ImageAnchor,
+        ChartAnchor,
+        ShapeAnchor,
+        ShapeInfo,
+        ShapeGeom,
+        ShapeText,
+        ShapeParagraph,
+        ShapeTextRun,
+        PathInfo,
+        PathCmd_2 as PathCmd,
+        ChartData,
+        XlsxChartSeries,
+        SeriesDataLabels,
+        DataLabelOverride,
+        DataPointOverride,
+        ErrBars,
+        ManualLayout,
+        LegendManualLayout_2 as LegendManualLayout
     }
 }
 
@@ -2849,6 +3511,24 @@ declare interface XlsxChartSeries {
     errBars?: ErrBars[];
 }
 
+/** One cell comment. Sourced from the classic notes file `xl/commentsN.xml`
+ *  (ECMA-376 §18.7) when present, otherwise from the Office-365 threaded
+ *  comments part `xl/threadedComments/` (MS-XLSX schema
+ *  `…/spreadsheetml/2018/threadedcomments`, `personId` resolved via
+ *  `xl/persons/`). `text` is the joined plain text — every `<r><t>` run for
+ *  classic notes, every reply in the thread (newline-joined) for threaded
+ *  comments; rich-text formatting is dropped. 1:1 with the Rust `XlsxComment`
+ *  (serde camelCase). */
+declare interface XlsxComment {
+    /** A1-style cell reference (`@ref` on the comment element). */
+    cellRef: string;
+    /** Resolved author name — the `<authors>` entry (classic) or the `<person>`
+     *  `displayName` (threaded). Absent when unresolved. */
+    author?: string;
+    /** Concatenated plain text of every run / threaded reply. */
+    text: string;
+}
+
 /** Emitted once per cell that has text, with the cell's canvas-pixel bounds. */
 declare interface XlsxTextRunInfo {
     text: string;
@@ -2884,6 +3564,17 @@ declare class XlsxViewer {
     private currentWorksheet;
     private opts;
     private resizeObserver;
+    /**
+     * Start-anchored horizontal scroll position (the {@link effectiveScrollLeft}
+     * value last produced by a real user scroll or a programmatic reset), kept
+     * as the source of truth across container size changes. The native
+     * `scrollLeft` cannot serve that role for RTL sheets (ECMA-376 §18.3.1.87):
+     * it is the *inverse* of the start-anchored offset, and the browser clamps
+     * any assignment to 0 while the host is unlaid-out (`display:none` mount —
+     * e.g. a host revealed only after `load()` resolves), which would otherwise
+     * strand the view at the sheet's far end once the host gains its real size.
+     */
+    private effectiveH;
     private anchorCell;
     private activeCell;
     private selectionMode;
@@ -2891,6 +3582,32 @@ declare class XlsxViewer {
     private selectionOverlay;
     private keydownHandler;
     private pendingTap;
+    /** DOM overlay element that shows the hovered cell's comment. Lives in
+     *  canvasArea above the scrollHost; `pointer-events:none` so it never blocks
+     *  cell interaction. */
+    private commentPopup;
+    /** `"row:col"` → comment for the current sheet, rebuilt on every showSheet. */
+    private commentMap;
+    /** `"row:col"` of the cell whose popup is currently shown (or pending), so a
+     *  pointermove within the same cell doesn't restart the show timer. */
+    private commentPopupKey;
+    /** Pending show timer (see {@link COMMENT_POPUP_DELAY_MS}). */
+    private commentPopupTimer;
+    /** DOM overlay listing a list-validated cell's allowed values. Lives in
+     *  canvasArea above the scrollHost; unlike the comment popup this is a click
+     *  target (`pointer-events:auto`). Read-only: hovering an item highlights it
+     *  but selecting does NOT change the cell. */
+    private validationPanel;
+    /** `"row:col"` of the cell whose panel is currently open, or null. Lets a
+     *  re-click on the same arrow toggle the panel closed. */
+    private validationPanelKey;
+    /** Screen rect (canvasArea CSS px) of the dropdown arrow button last drawn by
+     *  {@link maybeDrawValidationDropdown}, so pointerdown can hit-test it. Null
+     *  when no arrow is currently visible. */
+    private validationArrowRect;
+    /** Document-level pointerdown listener that closes the panel on an outside
+     *  click; installed only while the panel is open. */
+    private validationOutsideHandler;
     constructor(container: HTMLElement, opts?: XlsxViewerOptions);
     /**
      * Load an XLSX from URL or ArrayBuffer and render the first sheet.
@@ -2937,6 +3654,11 @@ declare class XlsxViewer {
     /** Park the scrollbar at the sheet's natural start: scrollLeft=0 for LTR,
      *  the right end for RTL (so col A shows first). */
     private resetHorizontalScroll;
+    /** Re-derive the native scrollLeft from the tracked start-anchored
+     *  position after the scroll host's size changes. Only RTL needs this:
+     *  for LTR the native scrollLeft *is* start-anchored and the browser
+     *  already clamps it sensibly on resize. */
+    private reanchorHorizontalScroll;
     /** 0-based index of the currently displayed sheet. */
     get sheetIndex(): number;
     /** Total number of sheets in the loaded workbook. */
@@ -2960,6 +3682,14 @@ declare class XlsxViewer {
     private getCellRect;
     /** Returns the current selection, including mode. */
     get selection(): CellRange_2 | null;
+    /**
+     * Programmatically select a single cell by A1 reference (e.g. `"B2"`), as if
+     * the user had clicked it: updates the active/anchor cell, redraws the
+     * selection overlay (including any list-validation dropdown arrow), and fires
+     * `onSelectionChange`. A no-op for malformed refs. Closes any open validation
+     * panel, matching the click path.
+     */
+    select(ref: string): void;
     /**
      * Returns what the header area contains at the given client coordinates.
      * Returns null when the point is in the cell grid (not a header).
@@ -2968,6 +3698,49 @@ declare class XlsxViewer {
     /** Copy the selected cell range as tab-separated text to the clipboard. */
     private copySelection;
     private updateSelectionOverlay;
+    /** Draw the Excel list-validation dropdown button just outside the
+     *  bottom-right corner of the *active* cell when that cell is covered by a
+     *  `list` data-validation rule. Anchored to the single active cell (not the
+     *  whole range) to mirror Excel, which attaches the button to the active
+     *  cell of the selection. */
+    private maybeDrawValidationDropdown;
+    /** Toggle the dropdown panel for the active cell's list validation. Called
+     *  from pointerdown when the arrow rect is hit. Re-clicking the same arrow
+     *  closes it. */
+    private toggleValidationPanel;
+    /** Resolve the allowed values for `formula1` (relative to the current sheet)
+     *  and render them in the panel anchored below the active cell. Async because
+     *  cross-sheet range references may need a lazily-parsed worksheet. */
+    private openValidationPanel;
+    /** Build the panel's children. Uses textContent throughout (no HTML injection
+     *  from cell values). Items highlight on hover but are NOT selectable —
+     *  this is a read-only viewer, so clicking a value must not change the cell. */
+    private renderValidationPanel;
+    /** Position the (already-populated, visible-or-becoming-visible) panel below
+     *  the dropdown arrow / active cell using the pure geometry calculator. */
+    private positionValidationPanel;
+    /** Install a document-level pointerdown listener that closes the panel on a
+     *  click outside it (and outside the arrow, which toggles via its own path).
+     *  Removed by {@link hideValidationPanel}. */
+    private installValidationOutsideHandler;
+    /** Hide the panel and detach its outside-click listener. Called on re-click,
+     *  outside click, Esc, scroll, selection change, sheet switch and destroy. */
+    private hideValidationPanel;
+    /** Build the `"row:col"` → comment index for the given sheet. Parses each
+     *  `XlsxComment.cellRef` with the shared {@link parseA1}; later refs win on a
+     *  collision (Excel allows at most one note per cell, so this is moot in
+     *  practice). */
+    private buildCommentMap;
+    /** Show the popup for the comment on `cell` after the hover dwell, anchored to
+     *  the cell's current on-screen rect. No-op when the cell carries no comment.
+     *  Re-hovering the same cell does not restart the timer. */
+    private scheduleCommentPopup;
+    /** Immediately render the popup for `comment` anchored to `cell` (used by the
+     *  hover-dwell timer and by touch selection, which has no hover). */
+    private renderCommentPopup;
+    /** Hide the popup and cancel any pending show. Called on cell-out, scroll,
+     *  sheet switch and destroy. */
+    private hideCommentPopup;
     private applyPointerSelection;
     private setupSelectionEvents;
     private buildTabs;
@@ -3010,7 +3783,15 @@ declare interface XlsxViewerOptions {
     zoomMin?: number;
     zoomMax?: number;
     onReady?: (sheetNames: string[]) => void;
-    onSheetChange?: (index: number, name: string) => void;
+    /**
+     * Called when the active sheet changes, with the new sheet's zero-based
+     * `index` and the `total` number of sheets in the workbook. This mirrors the
+     * docx `onPageChange` and pptx `onSlideChange` contracts so all three viewers
+     * share one callback shape. To get the sheet *name*, look it up by index from
+     * `viewer.sheetNames[index]` (or the `sheetNames` array delivered to
+     * `onReady`).
+     */
+    onSheetChange?: (index: number, total: number) => void;
     onError?: (err: Error) => void;
     /** Called when the selected cell range changes. null means no selection. */
     onSelectionChange?: (selection: CellRange_2 | null) => void;
@@ -3061,6 +3842,22 @@ declare class XlsxWorkbook {
      *  `null` for sheets that declare no tab color. */
     get tabColors(): (string | null)[];
     getWorksheet(sheetIndex: number): Promise<Worksheet>;
+    /**
+     * Resolve a `list`-type data-validation `formula1` (ECMA-376 §18.3.1.32) into
+     * the set of allowed values to display, evaluated relative to `sheetIndex`
+     * (the sheet that owns the validation, used to resolve unqualified ranges):
+     *
+     * - Inline quoted list `"A,B,C"`        → the literal values.
+     * - Range ref `$B$2:$B$5`               → each non-empty cell's *display
+     *   string* (the same formatted text the grid shows, via {@link formatCellValue}),
+     *   walked row-major. `Sheet2!$A$1:$A$9` resolves against the named sheet
+     *   (lazily parsed via {@link getWorksheet}, hence async).
+     * - Named range / complex formula       → `{ kind: 'formula' }` carrying the
+     *   raw text so the caller can disclose it rather than blanking it.
+     *
+     * Read-only: this only reads cell values for display; it never writes.
+     */
+    resolveValidationList(sheetIndex: number, formula1: string | undefined): Promise<ResolvedList>;
     renderViewport(target: HTMLCanvasElement | OffscreenCanvas, sheetIndex: number, viewport: ViewportRange, opts?: RenderViewportOptions): Promise<void>;
     destroy(): void;
 }