In short
Worker rendering across DOCX, XLSX and PPTX was introduced in v0.59.0. v0.80.0 closes its remaining built-in renderer gaps: equations, 3-D charts and Region Maps now use the same math, threeD and regionMap options in main-thread and worker modes.
Main-thread mode remains the default. No migration is required for existing applications.
- Use main mode for smaller documents, the smallest worker download, the lowest single-frame overhead or custom renderer objects.
- Use worker mode when larger or more complex documents make scrolling, navigation or other application UI less responsive.
- The built-in math, 3-D chart and Region Map renderers now use the same injection options in both modes.
- Selection, find, navigation and viewer interactions retain the same public APIs.
Choose the mode that fits your app
In main mode, parsing already runs in a Worker, while layout and Canvas rendering run on the main thread. It is the best default for ordinary previews, smaller files and applications that prioritize the smallest download and lowest per-frame transfer overhead.
In worker mode, parsing, layout and Canvas rendering run in a Web Worker. Choose it when rendering a larger document competes with scrolling, navigation, animation or other UI work in your application. Viewer controls and interactions remain available in both modes.
A DOCX document that needs browser-only OpenType vertical-glyph selection automatically uses main mode for correct text shaping. Read the loaded document's mode when your integration needs to observe that fallback.
Worker mode requires Worker and OffscreenCanvas support. It improves responsiveness rather than guaranteeing faster total rendering time, and it is not a separate process or a memory-safety boundary.
Use the same options in either mode
Pass math, threeD and regionMap exactly as in main-thread mode. The library recognizes its built-in renderers and reconstructs them inside the worker without exposing worker protocol objects through the public renderer contracts.
Custom renderer objects remain a main-mode feature because arbitrary JavaScript objects cannot be transferred into a Worker. Use the built-in math, threeD and regionMap exports when those capabilities are required in worker mode.
Render an XLSX Viewer off the main thread
import { XlsxViewer } from '@silurus/ooxml/xlsx';
import { math } from '@silurus/ooxml/math';
import { threeD } from '@silurus/ooxml/three-d';
import { regionMap } from '@silurus/ooxml/region-map';
const viewer = new XlsxViewer(container, {
mode: 'worker',
math,
threeD,
regionMap,
});
await viewer.load(source);Trade-offs to consider
Worker mode downloads a larger self-contained worker asset and transfers a rendered bitmap for each frame. Main mode has less worker code to download and avoids that frame transfer, but heavy layout or paint can occupy the UI thread.
Both modes keep Viewer navigation, zoom, virtualized scrolling, selection, find, hyperlinks, equations, 3-D charts and Region Maps available. PowerPoint media controls and other DOM overlays continue to be presented by the Viewer in either mode.
Technical note
JavaScript renderer functions cannot cross the structured-clone boundary. Instead of exposing a second worker-specific API, v0.80 keeps the public math, threeD and regionMap objects as ordinary renderer contracts and records the built-in module identity privately. The worker reconstructs only those recognized built-ins, so application code uses the same options while transport details stay out of the public types.
Production packaging was the less obvious part. A consumer bundler can treat a published Worker as an opaque asset: copying the entry file while leaving its split chunks behind, or rebasing a MathJax URL against the consumer output directory. The published render worker is therefore self-contained, while browser-resolved external asset URLs are handed across explicitly. Tests cover both the raw package output and a fresh Vite consumer rebundle.
Math output also needed one drawing contract in both realms. Equations are rasterized through the same Canvas path in Window and Worker contexts on a size-bounded surface. A 256 px/em source is reduced in two stages and cached at 64 px/em for cleaner 100% display without turning ordinary document text into vector geometry.
Finally, the worker path is compared against main mode in the same browser for public DOCX, XLSX and PPTX examples, equations, 3-D charts and Region Maps. The exercised frames are pixel-identical; CI retains a small tolerance only for browser text rasterization differences across environments.