@silurus/ooxml 0.58.0 → 0.59.0

package/README.md

@@ -86,6 +86,46 @@ per-render argument. (Excel stores "Insert > Equation" as OMML inside the shared
 DrawingML `<xdr:txBody>` grammar, so `XlsxViewer` renders equations embedded in
 shapes / text boxes the same way.)
 
+### Off-main-thread rendering
+
+By default the headless engines parse in a worker but render on the main thread.
+Pass `mode: 'worker'` to `.load()` to parse **and** render entirely inside a Web
+Worker — the main thread only paints the returned `ImageBitmap` via a
+`bitmaprenderer` context, keeping it free for scrolling and input. It requires
+`Worker` + `OffscreenCanvas`.
+
+```typescript
+import { PptxPresentation } from '@silurus/ooxml/pptx';
+
+// Render entirely inside a Web Worker — the main thread only paints bitmaps.
+const pres = await PptxPresentation.load('/deck.pptx', { mode: 'worker' });
+const canvas = document.getElementById('pptx-canvas') as HTMLCanvasElement;
+const bitmap = await pres.renderSlideToBitmap(0, { width: 960, dpr: window.devicePixelRatio });
+const ctx = canvas.getContext('bitmaprenderer') as ImageBitmapRenderingContext;
+ctx.transferFromImageBitmap(bitmap); // consumes the bitmap
+```
+
+The `*ToBitmap` method exists on all three engines —
+`PptxPresentation.renderSlideToBitmap(slideIndex, opts)`,
+`DocxDocument.renderPageToBitmap(pageIndex, opts)`, and
+`XlsxWorkbook.renderViewportToBitmap(sheetIndex, viewport, opts)` (the xlsx
+variant **requires** `opts.width` and `opts.height`, since a worker has no DOM
+element to measure). They work in **both** modes — in main mode they render to
+an internal `OffscreenCanvas` — so you can write mode-agnostic code.
+
+Notes:
+
+- The returned `ImageBitmap` is owned by the caller: `transferFromImageBitmap`
+  consumes it, or call `bitmap.close()` when done.
+- The canvas-target methods (`renderSlide(canvas)`, `renderPage(canvas)`,
+  `renderViewport(canvas)`) are unavailable in worker mode — use the `*ToBitmap`
+  variants instead.
+- OMML equations require `mode: 'main'`; in worker mode they are skipped (with a
+  console warning).
+- Trade-off: worker mode keeps the main thread responsive, but each frame is
+  transferred back as an `ImageBitmap`, so a single render can be marginally
+  slower than `mode: 'main'`. Choose it for non-blocking UI, not raw speed.
+
 ---
 
 <details>
@@ -617,7 +657,7 @@ cd packages/pptx/parser && wasm-pack build --target web && cp pkg/pptx_parser_bg
   new PptxViewer(canvas, { maxZipEntryBytes: 64 * 1024 * 1024 }); // 64 MiB
   ```
   Supported uniformly by `DocxViewer`, `PptxViewer`, and `XlsxViewer`. Zero / negative values fall back to the default.
-- **No network by default.** The library does not send telemetry or analytics, and does not contact third-party services unless you ask it to. In particular, theme webfonts (and Office font metric substitutes for XLSX) are **not** loaded from Google Fonts unless you pass `useGoogleFonts: true` to the relevant `Viewer` / `load(...)` options — supported uniformly by `DocxViewer`, `PptxViewer`, and `XlsxViewer`. Enabling that option causes the end-user's browser to send an HTTP request (IP and User-Agent) to `fonts.googleapis.com`, which may have GDPR implications for your application — consider self-hosting the required fonts via `@font-face` instead.
+- **No network by default.** The library does not send telemetry or analytics, and does not contact third-party services unless you ask it to. In particular, theme webfonts, Office font metric substitutes (Carlito/Caladea), and the script fallback fonts are **not** loaded from Google Fonts unless you pass `useGoogleFonts: true` to the relevant `Viewer` / `load(...)` options — supported uniformly by `DocxViewer`, `PptxViewer`, and `XlsxViewer`. When enabled, fonts for non-Latin scripts are supplied on demand from Noto families so text does not fall back to tofu: Arabic (Noto Naskh/Sans Arabic), CJK (Noto Sans/Serif KR · SC · TC · JP, picked per document language so shared Han glyphs take the right shapes), Cyrillic (Noto Sans/Serif), Hebrew (Noto Sans/Serif Hebrew, RTL), Thai (Noto Sans Thai) and Devanagari (Noto Sans Devanagari). No font binaries ship in the bundle. Enabling this option causes the end-user's browser to send an HTTP request (IP and User-Agent) to `fonts.googleapis.com`, which may have GDPR implications for your application — consider self-hosting the required fonts via `@font-face` instead.
 - **XML parsing.** Uses `roxmltree`, which does not resolve external entities (XXE-safe by default).
 
 ## License