@silurus/ooxml 0.57.0 → 0.59.0

package/dist/types/index.d.ts

@@ -251,6 +251,8 @@ declare type CfRule = {
 } | {
     type: 'aboveAverage';
     aboveAverage: boolean;
+    equalAverage?: boolean;
+    stdDev?: number;
     dxfId: number | null;
     priority: number;
 } | {
@@ -848,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;
@@ -863,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 {
@@ -905,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 {
@@ -936,6 +976,7 @@ declare type DocRun = {
     nodes: MathNode[];
     display: boolean;
     fontSize: number;
+    jc?: string;
 };
 
 declare interface DocSettings {
@@ -949,6 +990,10 @@ declare interface DocSettings {
     /** §17.15.1.59 `w:noLineBreaksAfter@w:val` — custom set of characters that
      *  cannot end a line (行末禁則). Replaces the default when present. */
     noLineBreaksAfter?: string;
+    /** §22.1.2.30 `m:mathPr/m:defJc@m:val` — document-wide default math
+     *  justification (ST_Jc math: left|right|center|centerGroup). `undefined`
+     *  ⇒ the renderer uses the spec default `centerGroup`. */
+    mathDefJc?: string;
 }
 
 declare interface DocTable {
@@ -973,8 +1018,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;
 }
@@ -1015,10 +1060,12 @@ export declare namespace docx {
     export {
         DocxDocument,
         LoadOptions_4 as LoadOptions,
+        WireRenderPageOptions,
         DocxViewer,
         DocxViewerOptions,
         autoResize,
         AutoResizeOptions,
+        noteText,
         DocxDocumentModel,
         DocSettings,
         SectionProps,
@@ -1039,6 +1086,7 @@ export declare namespace docx {
         DocRevision,
         DocComment,
         DocNote,
+        NoteRef,
         LineSpacing,
         TabStop_2 as TabStop,
         ParagraphBorders,
@@ -1058,7 +1106,9 @@ export declare namespace docx {
 
 declare class DocxDocument {
     private _document;
+    private _meta;
     private _pages;
+    private _mode;
     private _worker;
     private _bridge;
     private constructor();
@@ -1066,9 +1116,46 @@ declare class DocxDocument {
     private _parse;
     destroy(): void;
     get pageCount(): number;
+    /**
+     * The raw parsed document model. Available only in `mode: 'main'`; in
+     * `mode: 'worker'` the model stays in the worker and this throws.
+     */
     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>;
+    /**
+     * Render a page and return it as an ImageBitmap. Works in both modes; in
+     * worker mode the render runs entirely off the main thread. Paint with:
+     * `canvas.getContext('bitmaprenderer').transferFromImageBitmap(bitmap)`.
+     *
+     * 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.
+     */
+    renderPageToBitmap(pageIndex: number, opts?: WireRenderPageOptions): Promise<ImageBitmap>;
 }
 
 declare interface DocxDocumentModel {
@@ -1137,8 +1224,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
@@ -1157,6 +1246,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. */
@@ -1183,6 +1278,12 @@ declare class DocxViewer {
     private _wrapper;
     private _textLayer;
     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;
     constructor(canvas: HTMLCanvasElement, opts?: DocxViewerOptions);
     /**
      * Load a DOCX from URL or ArrayBuffer and render the first page.
@@ -1280,7 +1381,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 {
@@ -1369,6 +1483,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;
@@ -1435,8 +1573,8 @@ declare interface LegendManualLayout_2 {
 }
 
 /**
- * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Parsed for Phase B
- * (lighting/bevel shading); the Phase A camera renderer ignores it.
+ * `<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". */
@@ -1461,9 +1599,16 @@ declare interface LineSpacing {
     explicit?: boolean;
 }
 
-/** Options for {@link PptxPresentation.load}. The shared load-options type
- *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`). */
-declare type LoadOptions = LoadOptions_2;
+/** Options for {@link PptxPresentation.load}. */
+declare type LoadOptions = LoadOptions_2 & {
+    /**
+     * 'main' (default): parse in a worker, render on the main thread (current
+     * behaviour). 'worker': parse AND render inside the worker; use
+     * {@link PptxPresentation.renderSlideToBitmap} and paint the returned
+     * ImageBitmap via an `ImageBitmapRenderingContext`. Requires OffscreenCanvas.
+     */
+    mode?: 'main' | 'worker';
+};
 
 /**
  * Common load-time options shared by the docx / pptx / xlsx
@@ -1505,9 +1650,19 @@ declare interface LoadOptions_2 {
     math?: MathRenderer;
 }
 
-/** Options for {@link XlsxWorkbook.load}. The shared load-options type from
- *  `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`). */
-declare type LoadOptions_3 = LoadOptions_2;
+/** Options for {@link XlsxWorkbook.load}. Extends the shared load-options type
+ *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`, `math`)
+ *  with the worker-rendering mode. */
+declare interface LoadOptions_3 extends LoadOptions_2 {
+    /**
+     * 'main' (default): parse in a worker, render on the main thread (current
+     * behaviour). 'worker': parse AND render inside the worker; use
+     * {@link XlsxWorkbook.renderViewportToBitmap} and paint the returned
+     * ImageBitmap via an `ImageBitmapRenderingContext`. Requires OffscreenCanvas.
+     * The math engine is unavailable in this mode (equations are skipped).
+     */
+    mode?: 'main' | 'worker';
+}
 
 /** Options for {@link DocxDocument.load}. Extends the shared load-options type
  *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`) with the
@@ -1519,6 +1674,14 @@ declare interface LoadOptions_4 extends LoadOptions_2 {
      * omitted, equations are skipped and the ~3 MB engine never enters the bundle.
      */
     math?: MathRenderer;
+    /**
+     * 'main' (default): parse in a worker, render on the main thread (current
+     * behaviour). 'worker': parse, paginate AND render inside the worker; use
+     * {@link DocxDocument.renderPageToBitmap} and paint the returned ImageBitmap
+     * via an `ImageBitmapRenderingContext`. Requires OffscreenCanvas. The math
+     * engine is unavailable in this mode (equations are skipped).
+     */
+    mode?: 'main' | 'worker';
 }
 
 declare interface ManualLayout {
@@ -1693,6 +1856,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;
@@ -1952,6 +2129,7 @@ export declare namespace pptx {
         PptxPresentation,
         LoadOptions,
         RenderSlideOptions,
+        RenderSlideToBitmapOptions,
         renderSlide,
         RenderOptions,
         PptxTextRunInfo,
@@ -1961,6 +2139,7 @@ export declare namespace pptx {
         AutoResizeOptions,
         Presentation,
         Slide,
+        PptxComment,
         SlideElement,
         ShapeElement,
         PictureElement,
@@ -1981,6 +2160,9 @@ export declare namespace pptx {
         NoFill,
         GradientFill,
         GradientStop,
+        ImageFill,
+        FillRect,
+        TileInfo,
         Stroke,
         Shadow,
         Glow,
@@ -2000,6 +2182,17 @@ export declare namespace pptx {
     }
 }
 
+/** 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.
  *
@@ -2018,7 +2211,9 @@ export declare namespace pptx {
 declare class PptxPresentation {
     private readonly _worker;
     private readonly _bridge;
+    private _mode;
     private _presentation;
+    private _meta;
     private _mediaCache;
     private _workerReady;
     private _workerReadyCallbacks;
@@ -2037,8 +2232,38 @@ 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>;
+    renderSlide(canvas: HTMLCanvasElement | OffscreenCanvas, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
+    /**
+     * Render a slide and return it as an ImageBitmap. Works in both modes; in
+     * worker mode the entire render runs off the main thread. Paint with:
+     * `canvas.getContext('bitmaprenderer').transferFromImageBitmap(bitmap)`.
+     *
+     * 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.
+     */
+    renderSlideToBitmap(slideIndex: number, opts?: RenderSlideToBitmapOptions): Promise<ImageBitmap>;
     /**
      * Extract raw media bytes for a zip path referenced by {@link MediaElement}.
      * Results are cached by path for the lifetime of this instance.
@@ -2106,6 +2331,12 @@ declare class PptxViewer {
     private readonly opts;
     private currentSlide;
     private handle;
+    private readonly _mode;
+    /** The canvas's bitmaprenderer context, used only by the static worker-mode
+     *  render path. The media-playback path keeps a 2d context (via presentSlide),
+     *  so this is obtained only when worker mode renders without media playback. */
+    private _bitmapCtx;
+    private _warnedNoTextSelection;
     constructor(canvas: HTMLCanvasElement, opts?: PptxViewerOptions);
     /**
      * Load a PPTX from URL or ArrayBuffer and render the first slide.
@@ -2121,6 +2352,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;
@@ -2265,6 +2503,15 @@ declare interface RenderSlideOptions {
     skipMediaControls?: boolean;
 }
 
+/** Options for {@link PptxPresentation.renderSlideToBitmap}. */
+declare interface RenderSlideToBitmapOptions {
+    /** Slide width in CSS pixels. Defaults to 960. */
+    width?: number;
+    /** Device pixel ratio. Defaults to window.devicePixelRatio (workers have none). */
+    dpr?: number;
+    /* Excluded from this release type: skipMediaControls */
+}
+
 declare interface RenderViewportOptions {
     width?: number;
     height?: number;
@@ -2277,8 +2524,8 @@ declare interface RenderViewportOptions {
     freezeCols?: number;
     /** Scale factor applied to all cell/header dimensions (default 1). */
     cellScale?: number;
-    /** Pre-loaded Image elements keyed by their dataUrl (for ImageAnchor rendering). */
-    loadedImages?: Map<string, HTMLImageElement>;
+    /** Pre-decoded image sources keyed by their dataUrl (for ImageAnchor rendering). */
+    loadedImages?: Map<string, CanvasImageSource>;
     /** Called once per cell that contains text, with canvas-pixel position and cell address. */
     onTextRun?: (info: XlsxTextRunInfo) => void;
     /** Highlighted row range for selected row headers (1-indexed inclusive).
@@ -2297,6 +2544,20 @@ 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
@@ -2698,6 +2959,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;
@@ -2723,9 +2998,10 @@ declare interface SolidFill {
 }
 
 /**
- * `<a:sp3d>` — ECMA-376 §20.1.5.12 (`CT_Shape3D`). Parsed in full but **not
- * rendered in Phase A** (camera-only). bevel/contour/extrusion are Phase B.
- * Numeric fields are omitted from JSON when zero.
+ * `<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). */
@@ -3092,6 +3368,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;
@@ -3099,6 +3398,13 @@ declare interface ViewportRange {
     cols: number;
 }
 
+/** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
+declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
+
+/** Serializable subset of RenderViewportOptions: drop the callback and the
+ *  image cache (the worker owns its own). */
+declare type WireRenderViewportOptions = Omit<RenderViewportOptions, 'onTextRun' | 'loadedImages'>;
+
 declare interface Workbook {
     sheets: SheetMeta[];
 }
@@ -3139,6 +3445,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`). */
@@ -3168,7 +3485,9 @@ export declare namespace xlsx {
     export {
         XlsxWorkbook,
         LoadOptions_3 as LoadOptions,
+        WireRenderViewportOptions,
         XlsxViewer,
+        ResolvedList,
         XlsxViewerOptions,
         CellAddress,
         CellRange_2 as CellRange,
@@ -3205,6 +3524,8 @@ export declare namespace xlsx {
         CfIcon,
         DefinedName,
         Hyperlink,
+        XlsxComment,
+        DataValidation,
         TableInfo,
         TableColumnInfo,
         SlicerAnchor,
@@ -3279,6 +3600,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;
@@ -3313,6 +3652,12 @@ declare class XlsxViewer {
     private currentSheet;
     private currentWorksheet;
     private opts;
+    /** 'main' renders on this thread; 'worker' paints worker-produced bitmaps. */
+    private readonly _mode;
+    /** The canvas's bitmaprenderer context, used only in worker mode. A canvas
+     *  holds one context type for its lifetime, so this is obtained once and the
+     *  main-mode 2d render path is never used on the same canvas. */
+    private _bitmapCtx;
     private resizeObserver;
     /**
      * Start-anchored horizontal scroll position (the {@link effectiveScrollLeft}
@@ -3332,6 +3677,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.
@@ -3406,6 +3777,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).
@@ -3414,6 +3793,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;
@@ -3490,6 +3912,15 @@ declare interface XlsxViewerOptions {
      * dependency-injection contract as the docx/pptx viewers.
      */
     math?: MathRenderer;
+    /**
+     * `'main'` (default): parse in a worker, render on the main thread. `'worker'`:
+     * parse AND render entirely inside the worker and paint the returned
+     * ImageBitmap onto the viewer's canvas, so document rendering never blocks the
+     * UI thread. All interaction (scroll, sheet tabs, frozen panes, zoom, cell
+     * selection) is unchanged. Requires `Worker` + `OffscreenCanvas`. Equations
+     * require `'main'` (the math engine cannot cross the worker boundary).
+     */
+    mode?: 'main' | 'worker';
 }
 
 declare class XlsxWorkbook {
@@ -3497,7 +3928,7 @@ declare class XlsxWorkbook {
     private bridge;
     private parsedWorkbook;
     private sheetCache;
-    /** Cache of loaded images keyed by their data URL. Shared across sheets. */
+    /** Cache of decoded image bitmaps keyed by their data URL. Shared across sheets. */
     private imageCache;
     private rawData;
     private maxZipEntryBytes;
@@ -3505,6 +3936,7 @@ declare class XlsxWorkbook {
      *  `renderViewport` call reuses it — equations in shapes render when present,
      *  and are skipped (engine tree-shaken) when omitted. */
     private math;
+    private _mode;
     private constructor();
     /** Parse an XLSX from a URL or ArrayBuffer. */
     static load(source: string | ArrayBuffer, opts?: LoadOptions_3): Promise<XlsxWorkbook>;
@@ -3515,7 +3947,38 @@ 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>;
+    /**
+     * Render a sheet viewport and return it as an ImageBitmap (both modes; in
+     * worker mode the render runs entirely off the main thread). `opts.width` /
+     * `opts.height` are required: there is no DOM element to measure in a worker
+     * or on an OffscreenCanvas. Paint with
+     * `canvas.getContext('bitmaprenderer').transferFromImageBitmap(bitmap)`.
+     *
+     * 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.
+     */
+    renderViewportToBitmap(sheetIndex: number, viewport: ViewportRange, opts: WireRenderViewportOptions & {
+        width: number;
+        height: number;
+    }): Promise<ImageBitmap>;
     destroy(): void;
 }