@zumer/snapdom 3.1.1 → 3.1.2-dev.1

package/README.md

@@ -175,6 +175,42 @@ const result = await snapdom(card, {
 
 [All options](https://snapdom.dev/docs/options/) include shadows, transforms, fonts, CORS, fallbacks and layout reconciliation.
 
+### Export a long page
+
+With the default SVG engine, PNG file exports automatically handle captures beyond the browser's canvas limits. Capture once, then download one full-resolution file or get its Blob:
+
+```js
+const capture = await snapdom(article);
+await capture.download({ format: 'png', scale: 2 });
+// Or upload/store the file yourself:
+const blob = await capture.toBlob({ format: 'png', scale: 2, dpr: 1 });
+```
+
+SnapDOM renders the frozen capture in windows and encodes them into one PNG. It preserves the requested dimensions, including shadows and padding, without allocating a canvas for the whole image. `download()` always uses DPR 1; `toBlob()` uses the capture's DPR unless you override it. Ordinary-sized exports use the native encoder.
+
+This requires `CompressionStream`; older browsers keep the existing downscale and warning. Very large files still take time and memory to encode, and the application opening them has its own image limits.
+
+### Export a long page in pieces
+
+`toCanvas()`, `toPng()` and JPEG/WebP exports still use a single canvas and scale down past SnapDOM's size guards (16,384px per side in Safari, 32,767px in Chrome/Firefox, plus an area limit). When you need separate canvases, use `crop`:
+
+```js
+const capture = await snapdom(article);
+const { contentX, contentY, w0, h0 } = capture.meta;
+const pieceHeight = 4000; // CSS px
+
+for (let y = 0; y < h0; y += pieceHeight) {
+  const canvas = await capture.toCanvas({
+    scale: 2,
+    dpr: 1,
+    crop: { x: contentX, y: contentY + y, width: w0, height: Math.min(pieceHeight, h0 - y) }
+  });
+  // save or upload this piece, then move on
+}
+```
+
+`crop` is a rectangle, not a switch. It is in the coordinates of `capture.meta`, and each call returns one canvas. The capture runs once; only the rasterization repeats. Keep `pieceHeight × scale × dpr` under the limit, and set `dpr` yourself, since it defaults to the device pixel ratio. [How tiling works](https://snapdom.dev/blog/huge-page-mosaic/).
+
 ### Export HTML or structured context
 
 Official plugins are published separately as `@zumer/snapdom-plugins` and must match the core major version; they declare a peer dependency on a v3 core. Their sources live in `packages/plugins/` in this checkout.
@@ -297,7 +333,7 @@ Capture-affecting plugins suspend memoization unless they declare `pure: true`.
 - SnapDOM needs a browser DOM. A server-side Node.js process needs a browser environment to run it.
 - Cross-origin images, fonts and stylesheets need readable resources or an appropriate proxy. `crossorigin` does not grant access unless the server also allows it. Cross-origin iframes use placeholders.
 - SVG output includes HTML inside `<foreignObject>`. It is suitable for browsers; support varies in other SVG viewers and document tools.
-- Output depends on browser rendering and canvas limits. Safari may fall back to PNG when WebP encoding is unavailable.
+- Output depends on browser rendering and image limits; for tall PNG files see [Export a long page](#export-a-long-page). Safari may fall back to PNG when WebP encoding is unavailable.
 - Canvas, video and other changing surfaces are captured fresh. JavaScript CSSOM edits are not observable automatically; use `invalidate: true` after them.
 - Core captures visible input values. Semantic plugins redact sensitive field values in their text/map output, but their attached image needs `redactInputs` or `exclude` if you want those pixels hidden too.