@silurus/ooxml 0.74.6 → 0.75.0

package/README.md

@@ -285,8 +285,8 @@ 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.
+headless engines (`mode`, `useGoogleFonts`, `resourceLimits`, the deprecated
+`maxZipEntryBytes` alias, `math`, `dpr`) are accepted too.
 
 ### Markdown export
 
@@ -878,7 +878,7 @@ export const PptxViewerComponent = component$<{ src: string }>(({ src }) => {
 ## Companion packages
 
 - **[`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/node/`](packages/node/)** — the implementation behind the public Node-only `@silurus/ooxml/node` subpath. It exposes materializing `parsePptx` / `parseDocx` / `parseXlsx` / `parseXlsxAllSheets` helpers plus uniformly owned, bounded `openPptxPresentation`, `openDocxDocument`, and `openXlsxWorkbook` sessions, with no DOM or Web Worker dependency. Each `open*` call returns an explicit `close()`-able session; PPTX streams `slides()` and can render each yielded slide through the same bounded archive, DOCX completes format-required sequential pagination before streaming `pages()`, and XLSX parses its workbook index once before sequential `worksheetRows(sheetIndex)` streams reuse the retained archive. Useful for CI checks and headless rendering pipelines; canvas rendering accepts a user-supplied backend such as `skia-canvas` without making it a runtime dependency.
 - **[`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.
 
@@ -916,14 +916,113 @@ cd packages/xlsx/parser && wasm-pack build --target web && cp pkg/xlsx_parser_bg
 cd packages/pptx/parser && wasm-pack build --target web && cp pkg/pptx_parser_bg.wasm pkg/pptx_parser.js ../src/wasm/
 ```
 
+## Error handling
+
+Headless APIs (`DocxDocument`, `XlsxWorkbook`, and `PptxPresentation`) report
+load and render failures by rejecting the returned Promise. Viewer APIs also
+support an `onError(error)` callback, with an important delivery rule:
+
+- Without `onError`, a load/parse failure rejects `viewer.load()`.
+- With `onError`, that failure is delivered to the callback and
+  `viewer.load()` resolves. Do not treat resolution alone as proof that the
+  document rendered.
+- Later Viewer-managed render or media failures are delivered to `onError`, or
+  logged with `console.error` when the callback is omitted.
+
+Stable failures can be narrowed without parsing message strings:
+
+- `OoxmlError` — container failures. Its `code` is `encrypted`,
+  `invalid-password`, `unsupported-encryption`, `legacy-binary-format`, or
+  `not-ooxml`.
+- `OoxmlResourceLimitError` (`code === 'ooxml-resource-limit'`) — a measured
+  package or format resource crossed a configurable limit or hard ceiling.
+  `details.violation` contains the resource, metric, limit, observed value, and
+  usage snapshot.
+- `OoxmlDecodedImageLimitError`
+  (`code === 'ooxml-decoded-image-limit'`) — a raster crossed an image pixel or
+  active decoded-byte ceiling. Its `metric`, `limit`, and `observed` properties
+  are stable.
+- An otherwise ordinary `Error` may carry `code === 'parser-crashed'` for a
+  recognized WASM trap. This does not mean “OOM”: panic, allocation failure,
+  stack overflow, and other traps can be indistinguishable at the current WASM
+  boundary.
+
+All other configuration, fetch, parser, renderer, worker, and media failures
+remain `Error`, `TypeError`, or `RangeError` values without a stable code. Their
+messages are diagnostic text, not a programmatic API.
+
+```ts
+import {
+  DocxViewer,
+  OoxmlDecodedImageLimitError,
+  OoxmlError,
+  OoxmlResourceLimitError,
+} from '@silurus/ooxml/docx';
+
+const viewer = new DocxViewer(canvas, {
+  onError(error) {
+    if (error instanceof OoxmlResourceLimitError) {
+      const { limit, observed } = error.details.violation;
+      showTooLargeMessage({ limit, observed });
+    } else if (error instanceof OoxmlDecodedImageLimitError) {
+      showImageTooLargeMessage(error);
+    } else if (error instanceof OoxmlError) {
+      handleContainerError(error.code);
+    } else {
+      reportUnexpectedError(error);
+    }
+  },
+});
+
+await viewer.load(file);
+```
+
 ## Security & Privacy
 
 - **Canvas-only rendering.** Documents are decoded and drawn to an `HTMLCanvasElement`. No script, link, form, or other active content from the source file is executed or injected into the DOM.
-- **ZIP decompression cap.** Each entry in the source archive is limited to 512 MiB of uncompressed output by default to block zip-bomb DoS. Override per viewer with `maxZipEntryBytes` (bytes) — raise it for legitimate decks with large embedded media, lower it to tighten the budget for untrusted input:
+- **Bounded OOXML package expansion.** DOCX, XLSX, and PPTX use the same resource policy. By default, one archive entry may inflate to at most 128 MiB and the distinct entries visited during one package session may inflate to at most 256 MiB. Override either budget with a plain `resourceLimits` object on a viewer or `load(...)` call:
+  ```ts
+  new XlsxViewer(container, {
+    resourceLimits: {
+      maxArchiveEntryBytes: 64 * 1024 * 1024,
+      maxTotalInflatedBytes: 192 * 1024 * 1024,
+    },
+  });
+  ```
+  `maxArchiveEntryBytes` applies to every XML, text, image, media, and other package part that the parser reads. `maxTotalInflatedBytes` counts the largest amount actually read from each distinct part during the lifetime of the loaded package; reading the same part again does not consume that budget twice. Set an individual field to `null` to disable that configurable budget. Internal hard safety ceilings still apply, so disabling a budget does not make arbitrary archives acceptable. Values other than `null` must be positive safe-integer byte counts.
+
+  A violation rejects with `OoxmlResourceLimitError` (`code === 'ooxml-resource-limit'`). Its structured `details.violation` reports the resource, metric, limit, observed value, usage snapshot, and part name when a particular part caused the failure. The deprecated `maxZipEntryBytes` option remains as a compatibility alias for `resourceLimits.maxArchiveEntryBytes`, but is scheduled for removal in a future breaking release; new code should use `resourceLimits`.
+
+  Applications can collect the same data as a machine-readable `OoxmlResourceMetrics` report without enabling console output. This is useful for choosing limits from representative files in the application's own domain:
+  ```ts
+  new DocxViewer(canvas, {
+    onResourceMetrics(metrics) {
+      // Send only under your application's own consent/privacy policy.
+      analytics.record('ooxml-resource-usage', metrics);
+    },
+  });
+  ```
+  After resource options validate, the callback also runs for failed document loads, for which no document/viewer engine is returned. It is not awaited; callback exceptions and rejected promises are ignored and never change the load result. On a successful load, every DOCX/XLSX/PPTX engine and Viewer also exposes `await getResourceMetrics()`; unlike the one-shot callback, this probes the archive owner and returns a fresh snapshot after lazy sheet, slide, image, font, or media access. A failed or unresponsive probe rejects within a bounded timeout rather than presenting stale counters as current. Collection for that getter is always active—`debug` controls only console presentation. The library itself does not transmit or persist the report.
+
+  For interactive inspection, pass `debug: true`. The same report is formatted as one compact, Ratatui-inspired console card with the compressed source size, largest observed inflated entry, distinct inflated total, entry count, configured limits, and timing checkpoints:
   ```ts
-  new PptxViewer(canvas, { maxZipEntryBytes: 64 * 1024 * 1024 }); // 64 MiB
+  new DocxViewer(canvas, {
+    debug: true,
+    resourceLimits: {
+      maxArchiveEntryBytes: 128 * 1024 * 1024,
+      maxTotalInflatedBytes: 256 * 1024 * 1024,
+    },
+  });
   ```
-  Supported uniformly by `DocxViewer`, `PptxViewer`, and `XlsxViewer`. Zero / negative values fall back to the default.
+  Browser DevTools receive typography-only `%c` styling (a fixed-width font stack, fixed size and line height, disabled ligatures, zero letter spacing, and preserved whitespace) so Unicode borders and gauges stay aligned. The library does not set foreground or background colors. Node and Worker consoles receive the same card as one plain argument without CSS or ANSI escapes.
+
+  The report is content-free by construction: it does not include source URLs, filenames, package paths, document text, passwords, or raw error messages. It still contains document-derived sizes, counts, and timings, so applications remain responsible for consent, retention, and telemetry policy. The initial browser callback covers the underlying document/workbook/presentation factory and does not wait for a Viewer's first canvas paint; use `getResourceMetrics()` for the latest observed package counters. Bounded Node sessions accept both `onResourceMetrics` and `debug`. DOCX/PPTX report successful terminal metrics when their one-pass stream completes or the session is explicitly closed; XLSX reports success when the reusable workbook session is explicitly closed. Open-time and session-operation failures report immediately.
+
+  Image decoding has separate, non-configurable browser safety ceilings shared by all three formats: at most 32 megapixels (128 MiB RGBA) for one raster, 128 MiB of decoded raster ownership per document cache or live render pass, and two simultaneous decodes per document. Crossing a measurable image ceiling rejects with `OoxmlDecodedImageLimitError` (`code === 'ooxml-decoded-image-limit'`) instead of silently omitting the image. These are hard implementation guards rather than public tuning knobs because browser/GPU overhead is not portable enough for an application-supplied byte value to mean the same thing across devices.
+
+  The package counters and raster-image guards are deterministic admission limits, not exact JavaScript/WASM process-memory accounting. XML trees, document models, canvas backing stores, browser decoder overhead, renderer state, and browser-managed SVG/vector parse or decoded storage can still require several times the measured input. SVG has no portable decoded-byte measure or explicit browser release primitive; the library count-bounds its cache and revokes owned object URLs, but cannot charge it as RGBA bytes. The defaults therefore reduce risk but cannot promise that an OOM is impossible on every device. Running parse and render work in `mode: 'worker'` can contain many failures away from the main UI thread, but a Worker is not a separate operating-system process or a strict memory sandbox.
+
+  A measured limit crossing is reported as `OoxmlResourceLimitError`. A residual WASM failure that reaches a recognized trap-shaped boundary is reported conservatively as `parser-crashed`, not `parser-oom`: with the current aborting Rust/WASM boundary, panic, allocation failure, explicit `unreachable`, and stack overflow can lose their distinct causes and converge on the same generic runtime error. Inferring OOM from an exception class or message would misclassify some parser defects as large-file failures. Reliable OOM classification would require preserving a structured cause before the trap across every relevant allocation path; it cannot be recovered from the generic trap afterward. The WebAssembly JavaScript embedding also permits implementation-defined stack/OOM failures, including an indistinguishable plain `Error` or process termination, so converting and poisoning every engine-level failure cannot be guaranteed.
 - **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).
 - **Encrypted OOXML ([MS-OFFCRYPTO] Agile Encryption).** Password-protected `.docx` / `.xlsx` / `.pptx` files are OLE2/CFB containers, not ZIPs. Pass `password` to `load(...)` and the file is decrypted **client-side** via WebCrypto — no bytes and no password leave the browser: