@silurus/ooxml 0.58.0 → 0.59.0

package/dist/types/docx.d.ts

@@ -151,6 +151,7 @@ export declare type DocRun = {
     nodes: MathNode[];
     display: boolean;
     fontSize: number;
+    jc?: string;
 };
 
 export declare interface DocSettings {
@@ -164,6 +165,10 @@ export 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;
 }
 
 export declare interface DocTable {
@@ -228,7 +233,9 @@ export declare interface DocTableRow {
 
 export declare class DocxDocument {
     private _document;
+    private _meta;
     private _pages;
+    private _mode;
     private _worker;
     private _bridge;
     private constructor();
@@ -236,6 +243,10 @@ export 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
@@ -262,6 +273,16 @@ export declare class DocxDocument {
     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>;
 }
 
 export declare interface DocxDocumentModel {
@@ -384,6 +405,12 @@ export 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.
@@ -520,6 +547,14 @@ export declare interface LoadOptions 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';
 }
 
 /**
@@ -919,4 +954,7 @@ export declare interface TabStop {
     leader: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
 }
 
+/** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
+export declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
+
 export { }

package/dist/types/index.d.ts

@@ -976,6 +976,7 @@ declare type DocRun = {
     nodes: MathNode[];
     display: boolean;
     fontSize: number;
+    jc?: string;
 };
 
 declare interface DocSettings {
@@ -989,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 {
@@ -1055,6 +1060,7 @@ export declare namespace docx {
     export {
         DocxDocument,
         LoadOptions_4 as LoadOptions,
+        WireRenderPageOptions,
         DocxViewer,
         DocxViewerOptions,
         autoResize,
@@ -1100,7 +1106,9 @@ export declare namespace docx {
 
 declare class DocxDocument {
     private _document;
+    private _meta;
     private _pages;
+    private _mode;
     private _worker;
     private _bridge;
     private constructor();
@@ -1108,6 +1116,10 @@ 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
@@ -1134,6 +1146,16 @@ declare class DocxDocument {
     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 {
@@ -1256,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.
@@ -1571,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
@@ -1615,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
@@ -1629,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 {
@@ -2076,6 +2129,7 @@ export declare namespace pptx {
         PptxPresentation,
         LoadOptions,
         RenderSlideOptions,
+        RenderSlideToBitmapOptions,
         renderSlide,
         RenderOptions,
         PptxTextRunInfo,
@@ -2157,7 +2211,9 @@ declare interface PptxComment {
 declare class PptxPresentation {
     private readonly _worker;
     private readonly _bridge;
+    private _mode;
     private _presentation;
+    private _meta;
     private _mediaCache;
     private _workerReady;
     private _workerReadyCallbacks;
@@ -2197,7 +2253,17 @@ declare class PptxPresentation {
      */
     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.
@@ -2265,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.
@@ -2431,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;
@@ -2443,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).
@@ -3317,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[];
 }
@@ -3397,6 +3485,7 @@ export declare namespace xlsx {
     export {
         XlsxWorkbook,
         LoadOptions_3 as LoadOptions,
+        WireRenderViewportOptions,
         XlsxViewer,
         ResolvedList,
         XlsxViewerOptions,
@@ -3563,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}
@@ -3817,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 {
@@ -3824,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;
@@ -3832,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>;
@@ -3859,6 +3964,21 @@ declare class XlsxWorkbook {
      */
     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;
 }
 

package/dist/types/pptx.d.ts

@@ -604,9 +604,16 @@ export declare interface LineBreak {
     type: 'break';
 }
 
-/** Options for {@link PptxPresentation.load}. The shared load-options type
- *  from `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`). */
-export declare type LoadOptions = LoadOptions_2;
+/** Options for {@link PptxPresentation.load}. */
+export 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
@@ -980,7 +987,9 @@ export declare interface PptxComment {
 export declare class PptxPresentation {
     private readonly _worker;
     private readonly _bridge;
+    private _mode;
     private _presentation;
+    private _meta;
     private _mediaCache;
     private _workerReady;
     private _workerReadyCallbacks;
@@ -1020,7 +1029,17 @@ export declare class PptxPresentation {
      */
     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.
@@ -1088,6 +1107,12 @@ export 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.
@@ -1233,6 +1258,15 @@ export declare interface RenderSlideOptions {
     skipMediaControls?: boolean;
 }
 
+/** Options for {@link PptxPresentation.renderSlideToBitmap}. */
+export 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 */
+}
+
 /**
  * 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

package/dist/types/xlsx.d.ts

@@ -456,9 +456,19 @@ export declare interface LegendManualLayout {
     h: number;
 }
 
-/** Options for {@link XlsxWorkbook.load}. The shared load-options type from
- *  `@silurus/ooxml-core` (`useGoogleFonts`, `maxZipEntryBytes`). */
-export declare type LoadOptions = 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. */
+export declare interface LoadOptions 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';
+}
 
 /**
  * Common load-time options shared by the docx / pptx / xlsx
@@ -714,8 +724,8 @@ export 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).
@@ -1044,6 +1054,10 @@ export declare interface ViewportRange {
     cols: number;
 }
 
+/** Serializable subset of RenderViewportOptions: drop the callback and the
+ *  image cache (the worker owns its own). */
+export declare type WireRenderViewportOptions = Omit<RenderViewportOptions, 'onTextRun' | 'loadedImages'>;
+
 export declare interface Workbook {
     sheets: SheetMeta[];
 }
@@ -1219,6 +1233,12 @@ export 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}
@@ -1473,6 +1493,15 @@ export 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';
 }
 
 export declare class XlsxWorkbook {
@@ -1480,7 +1509,7 @@ export 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;
@@ -1488,6 +1517,7 @@ export 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): Promise<XlsxWorkbook>;
@@ -1515,6 +1545,21 @@ export declare class XlsxWorkbook {
      */
     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;
 }