@zumer/snapdom 3.0.0-beta.1 → 3.0.1-dev.0

package/README.md

@@ -42,7 +42,7 @@ Export images and canvas with the core. Use plugins for self-contained HTML, pag
 
 [Documentation and demos](https://snapdom.dev/) · [Technical features](FEATURES.md) · [Official plugins](packages/plugins/README.md) · [简体中文](README_CN.md)
 
-This checkout documents **v3**. The migration guide below compares it with 2.24.16, the last v2 release.
+This checkout documents **v3.x.x**. The migration guide below compares it with **v2.x.x**. The [v2 source](https://github.com/zumerlab/snapdom/tree/v2) and [v2 documentation](https://snapdom.dev/v2/) remain available.
 
 ## What you can build
 
@@ -84,13 +84,13 @@ The result keeps that capture even if the source element later changes. Call `sn
 Install the core and, when you need them, the official plugins; use matching major versions:
 
 ```sh
-npm i @zumer/snapdom @zumer/snapdom-plugins
+npm i @zumer/snapdom@latest @zumer/snapdom-plugins@latest
 ```
 
 Or load it in a browser:
 
 ```html
-<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.js"></script>
+<script src="https://unpkg.com/@zumer/snapdom@latest/dist/snapdom.js"></script>
 <script>
   snapdom.toPng(document.querySelector('#card')).then(image => {
     document.body.appendChild(image);
@@ -101,11 +101,11 @@ Or load it in a browser:
 As an ES module from a CDN:
 
 ```js
-import { snapdom } from 'https://esm.sh/@zumer/snapdom';
-import { htmlExport } from 'https://esm.sh/@zumer/snapdom-plugins/html-export';
+import { snapdom } from 'https://esm.sh/@zumer/snapdom@latest';
+import { htmlExport } from 'https://esm.sh/@zumer/snapdom-plugins@latest/html-export';
 ```
 
-`https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs` serves the same module. Pin package versions in production.
+`https://unpkg.com/@zumer/snapdom@latest/dist/snapdom.mjs` serves the same module. These examples load the latest published core and plugins.
 
 To run the docs site against a local build of this checkout instead:
 
@@ -171,6 +171,7 @@ const result = await snapdom(card, {
 | `captureSelection` | `false` | Include the user's text selection |
 | `canvas` | Unset | Reuse an existing canvas |
 | `invalidate` | `false` | Refresh after changes such as programmatic CSSOM edits |
+| `fast` | `true` | `false` keeps the page responsive during long captures |
 
 [All options](https://snapdom.dev/docs/options/) include shadows, transforms, fonts, CORS, fallbacks and layout reconciliation.
 
@@ -236,7 +237,7 @@ The second engine is experimental: it still needs a compatible browser with its
 
 ## Migrating from v2
 
-The main capture pattern remains `snapdom(element, options)`. This guide compares v3 with **v2.24.16**; review these changes before upgrading:
+The main capture pattern remains `snapdom(element, options)`. This guide compares v3 with **v2.x.x**; review these changes before upgrading:
 
 | In v2 | In v3 | What to change |
 | --- | --- | --- |
@@ -244,13 +245,14 @@ The main capture pattern remains `snapdom(element, options)`. This guide compare
 | Raster width/height could be multiplied by `scale` | Width/height win over scale | Pass the final size: `width: 400` instead of `width: 200, scale: 2` |
 | `burst` opted into repeat memoization | Eligible captures memoize automatically; `burst` is no longer documented or supported | Remove `burst` (the engine still reads it for internal use, do not rely on it) and use `invalidate: true` for one fresh capture after unobservable changes such as `sheet.insertRule()` |
 | `preCache` prepared resources | Removed; `preCapture()` learns capture intent | Remove `preCache`; `preCapture()` is not a drop-in rename |
-| `fast` selected an optimization path | Removed | Delete the option |
+| `fast: false` cloned through idle callbacks | `fast: false` pauses about every frame, at nearly the same total time | Keep `fast: false` |
 | `filter` / `filterMode` and `exclude` / `excludeMode` could be used together | Both controls and their independent modes remain supported; `exclude` also accepts predicates | Keep existing rules and modes; use the additional predicate form only when useful |
 | `cache: 'auto'` or `'full'` | Both map to `'soft'` | Usually omit it; `'disabled'` / `false` is for debugging |
 | `compress` controlled embedded image downsampling | Image optimization is automatic; `compress` is no longer documented or supported | Remove `compress`; the engine still reads it for internal use, do not rely on it |
 | `resolvePicturePlaceholders` / `pictureResolver` configured lazy-image preparation | Responsive/lazy image resolution happens on the clone; these options are no longer documented or supported | Remove the options and handle custom loading/timeouts in your app before capture; the engine still reads `resolvePicturePlaceholders` for internal use, do not rely on it |
 | Some visible input values were redacted | Core masks passwords only | Add `redactInputs()` for other fields |
 | `afterExport` returns became the next hook's payload, not the caller's result | Returns are ignored; hooks receive the same export payload | Stop chaining through return values; use `defineExports` to produce a different output |
+| Plugins v2.x.x exposed `@zumer/snapdom-plugins/html-in-canvas` | That subpath is removed | Use the experimental core `engine: 'html-in-canvas'` with a compatible custom build; the default build uses SVG |
 | TypeScript exported `PluginExportFacade` | The named type is removed; `ctx.exports` still provides core exporters | Infer it in `defineExports`, or use `NonNullable<CaptureContext['exports']>` |
 
 ### Use filter and exclude together
@@ -309,6 +311,7 @@ For a useful comparison, use the same scene, output format, scale and DPR. Compa
 
 ## Documentation
 
+- [Archived v2 documentation](https://snapdom.dev/v2/) and [v2 source](https://github.com/zumerlab/snapdom/tree/v2)
 - [API](https://snapdom.dev/docs/api/) and [options](https://snapdom.dev/docs/options/)
 - [Framework guides](https://snapdom.dev/guides/) and [how-to examples](https://snapdom.dev/how-to/)
 - [Official plugins](packages/plugins/README.md), [plugin specification](PLUGIN_SPEC.md) and [contributing plugins](CONTRIBUTING_PLUGINS.md)
@@ -336,6 +339,7 @@ npm run test:pack
 <!-- CONTRIBUTORS:START -->
 <p>
 <a href="https://github.com/tinchox5" title="tinchox5"><img src="https://avatars.githubusercontent.com/u/11557901?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="tinchox5"/></a>
+<a href="https://github.com/claude" title="claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="claude"/></a>
 <a href="https://github.com/pdufour" title="pdufour"><img src="https://avatars.githubusercontent.com/u/1239145?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="pdufour"/></a>
 <a href="https://github.com/FlavioLimaMindera" title="FlavioLimaMindera"><img src="https://avatars.githubusercontent.com/u/96424442?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="FlavioLimaMindera"/></a>
 <a href="https://github.com/Jarvis2018" title="Jarvis2018"><img src="https://avatars.githubusercontent.com/u/36788851?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="Jarvis2018"/></a>
@@ -351,7 +355,6 @@ npm run test:pack
 <a href="https://github.com/av01d" title="av01d"><img src="https://avatars.githubusercontent.com/u/6247646?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="av01d"/></a>
 <a href="https://github.com/CHOYSEN" title="CHOYSEN"><img src="https://avatars.githubusercontent.com/u/25995358?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="CHOYSEN"/></a>
 <a href="https://github.com/pedrocateexte" title="pedrocateexte"><img src="https://avatars.githubusercontent.com/u/207524750?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="pedrocateexte"/></a>
-<a href="https://github.com/claude" title="claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="claude"/></a>
 <a href="https://github.com/domialex" title="domialex"><img src="https://avatars.githubusercontent.com/u/4694217?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="domialex"/></a>
 <a href="https://github.com/stypr" title="stypr"><img src="https://avatars.githubusercontent.com/u/6625978?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="stypr"/></a>
 <a href="https://github.com/mon-jai" title="mon-jai"><img src="https://avatars.githubusercontent.com/u/91261297?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="mon-jai"/></a>