@silurus/ooxml 0.85.1 → 0.85.2

package/README.md

@@ -1052,16 +1052,17 @@ try {
 
   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 uses a separate adaptive resource policy shared by all three formats. Target-resizable rasters—browser-decodable formats and TIFF when its optional codec is configured—keep their native decode while the complete visible paint fits the default 128 MiB decoded budget and the per-surface ceilings, preserving established output. When native ownership would cross either boundary, the renderer decodes those rasters at the current canvas/DPR requirement instead of retaining source pixels the paint cannot show. If even those display targets exceed the aggregate budget, it applies one uniform quality reduction across them; a later zoom requests a sharper cache variant. Image-bearing paints for the same loaded document are serialized so overlapping paints cannot each consume the full budget, while the admitted paint still runs up to two decodes concurrently. Formats or sources that cannot be decoder-resized remain on their format-specific path under the hard surface ceilings. Applications with a known environment can override the aggregate budget on Viewer or per-render options:
+  Image decoding uses a separate adaptive resource policy shared by all three formats. Ordinary browser-decodable rasters are assigned a geometry-weighted share of the default 128 MiB decoded budget before source extraction. Each source can then flow directly from extraction to decode: it keeps native resolution when it fits its share and otherwise uses up to a 2x canvas/DPR grid when that share has headroom, avoiding visibly soft 1x intermediates for small placed artwork. If the complete set of display grids itself exceeds the budget, adaptive mode reduces them by one uniform quality ratio. This avoids an all-paint inspection barrier without making display-sized downsampling the default. Natural-size consumers, pixel effects that require the authored grid, and formats that cannot be decoder-resized remain on their guarded format-specific paths under the hard surface ceilings. Image-bearing paints for the same loaded document are serialized so overlapping paints cannot each consume the full budget, while the admitted paint still runs up to two decodes concurrently. Applications with a known environment can override the aggregate budget on Viewer or per-render options:
   ```ts
   new PptxViewer(canvas, {
     imageResources: {
       decodedByteBudget: 256 * 1024 * 1024,
       strategy: 'adaptive', // or 'strict' to reject instead of reducing quality
+      resolution: 'native-if-fit', // or 'display' to minimize retained pixels
     },
   });
   ```
-  `decodedByteBudget` accepts a positive safe integer from 4 bytes through 512 MiB. This configures planned and retained decoded RGBA ownership; it does not measure browser decoder intermediates or disable the encoded-source, per-axis, or per-surface hard safety ceilings. A strict aggregate crossing or any hard-ceiling crossing rejects with `OoxmlDecodedImageLimitError` (`code === 'ooxml-decoded-image-limit'`) instead of silently omitting the image.
+  `resolution` defaults to `'native-if-fit'`. Use `'display'` when minimizing retained raster pixels is more important than preserving source-resolution sampling. `decodedByteBudget` accepts a positive safe integer from 4 bytes through 512 MiB. This configures planned and retained decoded RGBA ownership; it does not measure browser decoder intermediates or disable the encoded-source, per-axis, or per-surface hard safety ceilings. A strict aggregate crossing or any hard-ceiling crossing rejects with `OoxmlDecodedImageLimitError` (`code === 'ooxml-decoded-image-limit'`) instead of silently omitting the image.
 
   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.