@silurus/ooxml 0.69.0 → 0.70.1

package/README.md

@@ -27,9 +27,23 @@ npm install @silurus/ooxml
 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, ~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.
+> **Bundler note**: the Rust parsers ship as real `.wasm` asset files next to the
+> JavaScript, referenced with the standard `new URL('…', import.meta.url)` form
+> and fetched (streaming-compiled) at load time. Vite, webpack 5, Rollup and
+> Parcel detect that reference and copy the asset automatically — no extra
+> WebAssembly plugin is required. esbuild and the Angular CLI (whose application
+> builder is esbuild-based) do **not** process that reference
+> ([esbuild#795](https://github.com/evanw/esbuild/issues/795)): copy the `.wasm`
+> into your served output yourself and point the viewer at it with the `wasmUrl`
+> load option — see the [Angular example](#framework-examples) for the two-step
+> setup. `wasmUrl` also serves the parser WASM from a CDN or any path you
+> control:
+>
+> ```typescript
+> new DocxViewer(canvas, { wasmUrl: 'https://cdn.example.com/docx_parser_bg.wasm' });
+> ```
+
+> **Bundle size note**: the package is ESM-only (`.mjs`). npm's *Unpacked Size* sums every entry bundle **and** the standalone MathJax + STIX Two Math asset (`mathjax-stix2.js`, ~3 MB) that ships in the tarball, so the reported figure is much larger than any single app build. What actually lands in your app is smaller on two counts: import only the format you need (e.g. `@silurus/ooxml/pptx`), and the math engine is a **separate entry** (`@silurus/ooxml/math`). Its main-thread chunk is a ~1 KB loader that references the ~3 MB engine asset as a **sibling file** (not an inline data URL): the engine is fetched **lazily, only when a document actually contains equations** — and only if you imported `@silurus/ooxml/math` and passed it to a viewer in the first place (see [Rendering equations](#rendering-equations)). Never import the `math` entry and the loader chunk never enters your graph at all.
 
 ---
 
@@ -62,11 +76,14 @@ 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 ~4 MB, so it is **opt-in**: import the `math` engine from the separate
+That engine is ~3 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 ~4 MB
-away entirely** (equations are simply skipped). It is fully self-contained: no
-network, no cross-origin requests.
+omit it and the engine is referenced nowhere, so a bundler leaves it out of your build
+entirely (equations are simply skipped). When you *do* pass it, the ~3 MB engine ships
+as a **standalone asset file** next to the bundle rather than an inline data URL, and is
+fetched **on demand — only the first time a document actually contains an equation**, so
+equation-free documents never pay for it. It is fully self-contained: served from your own
+origin, no cross-origin requests.
 
 ```typescript
 import { DocxViewer } from '@silurus/ooxml/docx';
@@ -125,6 +142,97 @@ Notes:
   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.
 
+### Continuous scroll viewers
+
+`DocxScrollViewer` and `PptxScrollViewer` render the whole document as one
+vertically-scrolling, PDF-reader-style surface instead of a single page/slide at
+a time. Unlike `DocxViewer` / `PptxViewer` (which take a `<canvas>`), the scroll
+viewers take a **container** `<div>` — they own the scroll host, virtualize the
+page/slide list (only the visible window plus a small overscan is mounted), and
+recycle canvases as you scroll.
+
+```typescript
+import { DocxScrollViewer } from '@silurus/ooxml/docx';
+
+const container = document.getElementById('docx-scroll') as HTMLElement;
+const viewer = new DocxScrollViewer(container);
+await viewer.load('/document.docx');
+// viewer.scrollToPage(3);
+// viewer.pageCount, viewer.topVisiblePage
+```
+
+```typescript
+import { PptxScrollViewer } from '@silurus/ooxml/pptx';
+
+const container = document.getElementById('pptx-scroll') as HTMLElement;
+const viewer = new PptxScrollViewer(container);
+await viewer.load('/deck.pptx');
+// viewer.scrollToSlide(2);
+// viewer.slideCount, viewer.topVisibleSlide
+```
+
+The container must have a bounded height (e.g. `height: 100vh` or a flex child)
+so the viewer can size its scroll host to it. Base zoom fits the first page/slide
+width to the container width and re-fits on resize; a `0`-width container defers
+layout until it has width. Call `destroy()` to tear down (a self-loaded engine is
+destroyed with it; an injected one is not — see below).
+
+**Desk appearance.** The viewer paints each page/slide on its own white canvas
+with a soft drop shadow, over a transparent "desk". Style the desk and the sheet
+gaps without any wrapper CSS:
+
+```typescript
+const viewer = new DocxScrollViewer(container, {
+  background: '#f3f4f6',            // the desk behind / between pages
+  gap: 24,                          // vertical gap between pages
+  paddingTop: 32,                   // desk padding above the first page
+  pageShadow: '0 0 0 1px #c8ccd0',  // crisp 1px "border" look (box-shadow never shifts layout)
+  // pageShadow: false,             // flat pages, no shadow
+});
+```
+
+`paddingBottom`, `paddingLeft` and `paddingRight` each default to `gap`, so the
+sheet sits inside a uniform desk margin; pass `0` for a flush edge.
+
+**Zoom.** `Ctrl`/`⌘` + mouse-wheel (and trackpad pinch) zooms the surface;
+bare-wheel still scrolls natively. Zoom is flicker-free — a rapid gesture shows a
+CSS preview and settles into a crisp re-render when it pauses. Bounds are the
+absolute scale factors `zoomMin` / `zoomMax` (default `0.1` / `4`), and
+`setScale(scale)` sets it programmatically. Pass `enableZoom: false` to disable.
+
+**Text selection** (main mode only). Pass `enableTextSelection: true` to overlay
+a transparent, selectable text layer per page/slide for native copy. In
+`mode: 'worker'` the overlay stays empty (the per-run geometry cannot cross the
+worker boundary) and the viewer logs one warning — use the default `mode: 'main'`
+for selectable text.
+
+**Master–detail / shared engine.** Inject an already-loaded headless engine so a
+paged viewer and a scroll viewer (or several panes) share **one** parse. When you
+inject, `load()` is unsupported (the engine is already loaded), the engine's own
+`mode` wins, and `destroy()` leaves the injected engine intact — the caller owns
+its lifecycle:
+
+```typescript
+import { DocxDocument, DocxScrollViewer } from '@silurus/ooxml/docx';
+
+const doc = await DocxDocument.load('/document.docx'); // parse once
+const scroll = new DocxScrollViewer(container, { document: doc });
+// ...also drive a thumbnail grid, a paged view, etc. from the same `doc`.
+scroll.destroy(); // the injected `doc` is NOT destroyed — you own it
+doc.destroy();    // release it yourself when every pane is gone
+```
+
+`PptxScrollViewer` takes the same shape with `{ presentation: pres }`
+(`await PptxPresentation.load(...)`).
+
+Both viewers also expose `relayout()` (force a re-fit when the container resizes
+in a way a `ResizeObserver` cannot see — e.g. a late web-font load),
+`onVisiblePageChange` / `onVisibleSlideChange` (fires when the top-most visible
+page/slide changes), and `onError` (async per-page render failures are routed
+here instead of crashing the scroll loop). The parse/render knobs from the
+headless engines (`mode`, `useGoogleFonts`, `maxZipEntryBytes`, `math`, `dpr`)
+are accepted too.
+
 ---
 
 <details>
@@ -200,7 +308,7 @@ All three formats follow the same shape: the worker parses the `.docx` / `.xlsx`
 <summary><strong>React 19</strong></summary>
 
 ```tsx
-// React 19.1 — vite-plugin-wasm required in vite.config.ts
+// React 19.1 — Vite copies the parser .wasm asset automatically; no extra plugin needed.
 import { useEffect, useRef, useState } from 'react';
 import { PptxViewer } from '@silurus/ooxml/pptx';
 
@@ -272,6 +380,28 @@ onMounted(async () => {
 <details>
 <summary><strong>Angular 19</strong></summary>
 
+The Angular CLI's esbuild-based builder does not process the `new URL('…', import.meta.url)`
+asset reference the parsers use ([angular-cli#22388](https://github.com/angular/angular-cli/issues/22388)),
+so the `.wasm` never reaches the build output — and under `ng serve` the dependency
+optimizer additionally rewrites the reference into its own cache path. **Both steps
+below are required** (the asset copy alone fixes only production builds; `ng serve`
+still 404s without `wasmUrl`):
+
+```jsonc
+// angular.json — copy the parser WASM into the served root
+// (restart `ng serve` after editing this file)
+"architect": {
+  "build": {
+    "options": {
+      "assets": [
+        { "glob": "*_parser_bg.wasm", "input": "node_modules/@silurus/ooxml/dist", "output": "/" },
+        { "glob": "**/*", "input": "public" }
+      ]
+    }
+  }
+}
+```
+
 ```typescript
 // Angular 19 — standalone component with signal-based state
 import {
@@ -300,6 +430,7 @@ export class PptxViewerComponent implements AfterViewInit {
 
   ngAfterViewInit(): void {
     this.viewer = new PptxViewer(this.canvasEl().nativeElement, {
+      wasmUrl: '/pptx_parser_bg.wasm',
       onSlideChange: (i, t) => { this.current.set(i); this.total.set(t); },
     });
     this.viewer.load('/deck.pptx');
@@ -310,7 +441,10 @@ export class PptxViewerComponent implements AfterViewInit {
 }
 ```
 
-> Add `"allowSyntheticDefaultImports": true` and configure `@angular-builders/custom-webpack` (or use `esbuild` builder) with WASM support in your Angular workspace.
+> The `*_parser_bg.wasm` glob copies all three parsers; narrow it to
+> `pptx_parser_bg.wasm` if you only use one format. If you deploy under a
+> non-root `base href`, adjust `wasmUrl` so it resolves under your base (a
+> relative `wasmUrl` is resolved against the document URL).
 
 </details>
 
@@ -459,7 +593,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Math equations (OMML `m:oMath` / `m:oMathPara`, rendered via MathJax — opt-in `@silurus/ooxml/math`) | ✅ |
 | | Images (inline and anchored, with text wrap) | ✅ |
 | | SVG images (`asvg:svgBlip` MS-2016 extension — vector drawn from the embedded `.svg`, raster fallback) | ✅ |
-| | Text boxes / drawing shapes (`wps:txbx`, `a:prstGeom` — 186 preset geometries via the shared engine; connector arrow heads `headEnd` / `tailEnd` (§20.1.8.3) and `prstDash` dash patterns (§20.1.8.48)) | ✅ |
+| | Text boxes / drawing shapes (`wps:txbx`, `a:prstGeom` — 186 preset geometries via the shared engine; connector arrow heads `headEnd` / `tailEnd` (§20.1.8.3) and `prstDash` dash patterns (§20.1.8.48)). Text-box paragraphs run through the **same line-layout engine as body text**, so kinsoku 行頭/行末禁則 (§17.15.1.58–60), UAX#9 bidi (`w:bidi`, §17.3.1.6), justification (§17.18.44) and tab stops (§17.3.1.37) all apply inside a box | ✅ |
 | | WMF metafile images (legacy vector, incl. inside text boxes) — rasterized via a built-in player (window mapping, pens/brushes, poly/rect); true EMF detected but not yet rendered | ✅ |
 | **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) | ✅ |
@@ -468,6 +602,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | 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) | ✅ |
+| | Continuous scroll viewer (`DocxScrollViewer` — virtualized page list, desk background / shadow, Ctrl/⌘+wheel zoom, engine injection) | ✅ |
 
 ---
 
@@ -612,6 +747,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 | | Font scheme (`+mj-lt`, `+mn-lt`) | ✅ |
 | | lumMod / lumOff / alpha transforms | ✅ |
 | **Interaction** | Text selection (transparent overlay, native copy) | ✅ |
+| | Continuous scroll viewer (`PptxScrollViewer` — virtualized slide list, desk background / shadow, Ctrl/⌘+wheel zoom, engine injection) | ✅ |
 
 ---