@zumer/snapdom 1.9.10-dev.1 → 1.9.10-dev.2

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="http://zumerlab.github.io/snapdom">
-    <img src="https://raw.githubusercontent.com/zumerlab/snapdom/main/docs/assets/newhero.png" width="70%">
+    <img src="https://raw.githubusercontent.com/zumerlab/snapdom/main/docs/assets/newhero.png" width="80%">
   </a>
 </p>
 
@@ -164,6 +164,36 @@ All capture methods accept an `options` object:
 | `exclude`         | string[] | -        | CSS selectors to exclude                        |
 | `filter`          | function | -        | Custom predicate `(el) => boolean`              |
 | `cache`           | string   | `"soft"` | Control internal caches: `disabled`, `soft`, `auto`, `full` |
+| `defaultImageUrl` | string \| function  | -                  | Fallback image when an `<img>` fails. If a function is provided, it receives `{ width?, height?, src?, element }` and must return a URL (string or Promise<string>). Useful for placeholder services (e.g. `https://placehold.co/{width}x{height}`) |
+
+### Fallback image on `<img>` load failure
+
+Provide a default image for failed `<img>` loads. You can pass a fixed URL or a callback that receives measured dimensions and returns a URL (handy to generate dynamic placeholders).
+
+```js
+// 1) Fixed URL fallback
+await snapdom.toImg(element, {
+  defaultImageUrl: '/images/fallback.png'
+});
+
+// 2) Dynamic placeholder via callback
+await snapdom.toImg(element, {
+  defaultImageUrl: ({ width = 300, height = 150 }) =>
+    `https://placehold.co/${Math.round(width)}x${Math.round(height)}`
+});
+
+// 3) With proxy (if your fallback host has no CORS)
+await snapdom.toImg(element, {
+  defaultImageUrl: ({ width = 300, height = 150 }) =>
+    `https://dummyimage.com/${Math.round(width)}x${Math.round(height)}/cccccc/666.png&text=img`,
+  useProxy: 'https://corsproxy.io/?url='
+});
+```
+
+Notes:
+- If the fallback image also fails to load, snapDOM replaces the `<img>` with a placeholder block preserving width/height.
+- Width/height used by the callback are gathered from the original element (dataset, style/attrs, etc.) when available.
+
 
 ### Dimensions (`scale`, `width`, `height`)
 
@@ -280,7 +310,7 @@ You can control how they are cleared between captures using the `cache` option:
 
 | Mode        | Description                                                                 |
 | ----------- | --------------------------------------------------------------------------- |
-| `"disabled"`| No cache: clears absolutely everything on every capture                     |
+| `"disabled"`| No cache                   |
 | `"soft"`    | Clears session caches (`styleMap`, `nodeMap`, `styleCache`) _(default)_      |
 | `"auto"`    | Minimal cleanup: only clears transient maps                                 |
 | `"full"`    | Keeps all caches (nothing is cleared, maximum performance)                  |
@@ -301,7 +331,6 @@ await snapdom.toPng(el, { cache: 'disabled' });
 ## Limitations
 
 * External images should be CORS-accessible (use `useProxy` option for handling CORS denied)
-* Iframes are not supported
 * When WebP format is used on Safari, it will fallback to PNG rendering.
 * `@font-face` CSS rule is well supported, but if need to use JS `FontFace()`, see this workaround [`#43`](https://github.com/zumerlab/snapdom/issues/43)