@silurus/ooxml 0.57.0 → 0.59.0

package/README.md

@@ -30,7 +30,7 @@ pnpm add @silurus/ooxml
 
 > **Bundler note**: this package embeds `.wasm` files. With Vite add [`vite-plugin-wasm`](https://github.com/Menci/vite-plugin-wasm); with webpack use [`experiments.asyncWebAssembly`](https://webpack.js.org/configuration/experiments/).
 
-> **Bundle size note**: the package is ESM-only (`.mjs`). npm's *Unpacked Size* sums all four entry bundles, including the **opt-in** math engine (MathJax + STIX Two Math, ~3 MB). What actually lands in your app is much smaller — import only the format you need (e.g. `@silurus/ooxml/pptx`). The math engine is a **separate entry** (`@silurus/ooxml/math`): it is bundled **only if you import it and pass it to a viewer** (see [Rendering equations](#rendering-equations)). Viewers that never receive a `math` engine tree-shake the ~3 MB away entirely.
+> **Bundle size note**: the package is ESM-only (`.mjs`). npm's *Unpacked Size* sums all four entry bundles, including the **opt-in** math engine (MathJax + STIX Two Math, ~4 MB). What actually lands in your app is much smaller — import only the format you need (e.g. `@silurus/ooxml/pptx`). The math engine is a **separate entry** (`@silurus/ooxml/math`): it is bundled **only if you import it and pass it to a viewer** (see [Rendering equations](#rendering-equations)). Viewers that never receive a `math` engine tree-shake the ~4 MB away entirely.
 
 ---
 
@@ -63,9 +63,9 @@ pptx.nextSlide();
 
 OMML equations (`m:oMath` / `m:oMathPara`) in `.docx`, `.pptx` and `.xlsx` are rendered with
 [MathJax](https://www.mathjax.org/) + [STIX Two Math](https://github.com/stipub/stixfonts).
-That engine is ~3 MB, so it is **opt-in**: import the `math` engine from the separate
+That engine is ~4 MB, so it is **opt-in**: import the `math` engine from the separate
 `@silurus/ooxml/math` entry and pass it to the viewer. Pass it and equations render;
-omit it and the engine is referenced nowhere, so a bundler **tree-shakes the ~3 MB
+omit it and the engine is referenced nowhere, so a bundler **tree-shakes the ~4 MB
 away entirely** (equations are simply skipped). It is fully self-contained: no
 network, no cross-origin requests.
 
@@ -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>
@@ -420,9 +460,11 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Images (inline and anchored, with text wrap) | ✅ |
 | | Text boxes / drawing shapes | ✅ |
 | | WMF / EMF metafile images (legacy vector) | ❌ Not planned |
-| **Advanced** | Footnote / endnote reference markers | ✅ |
+| **Advanced** | Footnotes — reference markers + bottom-of-page bodies with separator rule, numbered (`w:footnoteReference` / `w:footnoteRef`, §17.11) | ✅ |
+| | Endnotes — reference markers + bodies at document end (`w:endnoteReference`, §17.11) | ✅ |
+| | `w:snapToGrid` opt-out of the document grid (§17.3.1.32) | ✅ |
 | | Track changes (`w:ins` / `w:del` — author-coloured underline / strikethrough) | ✅ |
-| | Comments / footnote bodies (parsed, not yet rendered inline) | ⚠️ |
+| | Comments — author / date / text via the document model (`doc.comments`, §17.13.4; not drawn on the page) | ✅ |
 | | Mail merge fields | ❌ Not planned |
 | **Interaction** | Text selection (transparent overlay, native copy) | ✅ |
 
@@ -456,7 +498,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | **Elements** | Images (`<xdr:twoCellAnchor>`) | ✅ |
 | | Drawing shapes / text boxes (`xdr:sp`, `xdr:txBody` — 186 preset geometries via the shared engine, with `avLst` adjust handles) | ✅ |
 | | Math equations in shapes (OMML `m:oMath` / `m:oMathPara` in `xdr:txBody`, incl. `a14:m` / `mc:AlternateContent`; rendered via MathJax — opt-in `@silurus/ooxml/math`) | ✅ |
-| | Charts (bar, line, area, radar, scatter / bubble) | ✅ |
+| | Charts (bar, line, area, pie, doughnut, radar, scatter / bubble) | ✅ |
 | | Chart markers (circle / square / diamond / triangle / x / plus / star / dot / dash, per-point `<c:dPt>` overrides) | ✅ |
 | | Chart data labels (`<c:dLbl>` per-point with CELLRANGE / VALUE / SERIESNAME / CATEGORYNAME field references, position `l`/`r`/`t`/`b`/`ctr`/`outEnd`) | ✅ |
 | | Chart error bars (`<c:errBars>` X/Y direction, `cust` / `fixedVal` / `stdErr` / `stdDev` / `percentage`, dashed/styled lines) | ✅ |
@@ -465,7 +507,8 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | **Advanced** | Conditional formatting (`cellIs`, `colorScale`, `dataBar`, `iconSet`, `top10`, `aboveAverage`) | ✅ |
 | | Slicers (static, Office 2010 extension) | ✅ |
 | | Pivot tables | ❌ Not planned |
-| | Data validation / comments | ❌ Not planned |
+| | Cell comments / notes (classic `xl/commentsN.xml` + Office-365 threaded comments — red triangle indicator + author / text via the worksheet model, shown in an Excel-style hover popup) | ✅ |
+| | Data validation (rules via the worksheet model; `list`-type dropdown arrow on the selected cell whose click opens a panel showing the allowed values — read-only) | ✅ |
 | **Interaction** | Cell selection (single / range / row / column / all) | ✅ |
 | | Excel-style row / column header highlight on selection | ✅ |
 | | Shift+click to extend, Ctrl+C to copy as TSV | ✅ |
@@ -484,7 +527,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Slide size (custom dimensions) | ✅ |
 | | Slide background (solid, gradient, image) | ✅ |
 | | Slide numbers | ✅ |
-| | Notes pages | ❌ |
+| | Speaker notes (plain text via `getNotes()`) | ✅ |
 | | Animations / transitions | ❌ Not planned |
 | **Element types** | Shapes (`sp`) | ✅ |
 | | Pictures (`pic`) | ✅ |
@@ -495,14 +538,13 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Charts (pie, doughnut) | ✅ |
 | | Charts (scatter — `scatterStyle` marker / line / smooth variants) | ✅ |
 | | Charts (bubble — `bubbleSize` per-point area scaling) | ✅ |
-| | SmartArt | ❌ |
-| | OLE objects | ❌ |
+| | SmartArt (renders the PowerPoint-saved drawing layout `dsp:drawing`; no native diagram layout engine) | ✅ |
+| | OLE embedded objects (`p:oleObj` — preview/icon rendering) | ❌ Not planned |
 | | Video / audio (poster + interactive playback) | ✅ |
 | | Ink / handwriting (`p:contentPart`, raster fallback) | ✅ |
-| **Shape geometry** | 130+ preset shapes (`prstGeom`) | ✅ |
+| **Shape geometry** | 186 preset shapes (`prstGeom` — incl. 3D presets cube / can / bevel / frame) | ✅ |
 | | Custom geometry (`custGeom`) on shapes and pictures (clipping) | ✅ |
 | | Rotation and flip (flipH / flipV) | ✅ |
-| | 3D preset shapes | ❌ |
 | **Fills** | Solid fill (`solidFill`) | ✅ |
 | | Linear / radial gradient (`gradFill`) | ✅ |
 | | No fill (`noFill`) | ✅ |
@@ -518,9 +560,10 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Inner shadow (`innerShdw`) | ✅ |
 | | Soft edge (`softEdge`) | ✅ |
 | | Reflection (`reflection`) | ✅ |
-| | 3D camera / perspective projection (`scene3d` camera + `rot`) on pictures | ✅ |
-| | 3D contour edge (`sp3d` `contourW` / `contourClr`) on pictures — flat approximation, no bevel shading | ⚠️ |
-| | Bevel / 3D extrusion (`sp3d` `bevelT` / `bevelB` / `extrusionH`) | ⚠️ parsed; rendering planned |
+| | 3D camera / perspective projection (`scene3d` camera + `rot`) on pictures and shapes — projected shape text is drawn but not selectable | ✅ |
+| | 3D contour edge (`sp3d` `contourW` / `contourClr`) — flat approximation | ⚠️ |
+| | Bevel shading (`sp3d` `bevelT` / `bevelB`) — distance-field lip lit by `lightRig`, `matte`/`plastic` materials | ✅ |
+| | 3D extrusion (`sp3d` `extrusionH` / `extrusionClr`) — swept side-wall approximation (visible only under a tilted camera) | ⚠️ |
 | **Text — characters** | Bold, italic, strikethrough (incl. `dblStrike`) | ✅ |
 | | Underline styles (`sng` / `dbl` / `dotted` / `dash` / `dashLong` / `dotDash` / `dotDotDash` / `wavy` / `wavyDbl` and `*Heavy` variants) | ✅ |
 | | Per-run underline colour (`uFill` / `uFillTx`) | ✅ |
@@ -569,7 +612,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 
 - **[`packages/markdown/`](packages/markdown/)** — `@silurus/ooxml-markdown` and the `ooxml-md` CLI convert `.pptx` / `.docx` / `.xlsx` to GitHub-flavoured markdown via the workspace WASM parsers. Same projection used by the MCP server (~21× smaller than the raw XML on the demo deck, ~8% bigger than a flat-text extractor). Includes a node20-based GitHub Action for bulk repo-wide conversion.
 - **[`packages/node/`](packages/node/)** — Node-side parsers (`@silurus/ooxml-node`) exposing `parsePptx` / `parseDocx` / `parseXlsx` / `parseXlsxAllSheets` against the workspace WASM artifacts, with no DOM or Web Worker dependency. Useful for CI checks, headless rendering pipelines, and CLI tools. Includes an `ooxml-thumbnail` CLI (pptx-only first pass; requires `skia-canvas`).
-- **[`packages/vscode-extension/`](packages/vscode-extension/)** — VS Code extension (`ooxml-viewer`) that registers `CustomEditorProvider`s for `.docx`, `.xlsx`, and `.pptx`, and (opt-in) auto-installs and registers the `ooxml-mcp-server` so AI coding agents in the same window (Copilot Agent mode, Claude, …) can read those files via dedicated tools.
+- **[`packages/vscode-extension/`](packages/vscode-extension/)** — VS Code extension (`ooxml-viewer`) that registers `CustomEditorProvider`s for `.docx`, `.xlsx`, and `.pptx`, and (opt-in) auto-installs and registers the `ooxml-mcp-server` so AI coding agents in the same window (Copilot Agent mode, Claude, …) can read those files via dedicated tools. The preview is offline by default; an opt-in `ooxmlViewer.useGoogleFonts` setting (off, and force-disabled in untrusted workspaces) surfaces the library's metric-compatible font substitution, widening the webview CSP to the Google Fonts CDN only while enabled.
 - **[`packages/mcp-server/`](packages/mcp-server/)** — Rust MCP server (`ooxml-mcp-server`) exposing the parsers as tools for AI agents (Claude, Copilot, Codex, etc.). Provides structured queries (`docx_get_structure`, `xlsx_get_cell_range`, `pptx_get_slide_structure`, …) so agents can inspect OOXML files without shelling out to `unzip`. Prebuilt binaries are attached to each [GitHub Release](https://github.com/yukiyokotani/office-open-xml-viewer/releases) for macOS / Linux / Windows; the VS Code extension downloads them on demand.
 
 ---
@@ -614,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