@zumer/snapdom 1.9.10-dev.2 → 1.9.11

package/README.md

@@ -42,6 +42,46 @@ It captures any HTML element as a scalable SVG image, preserving styles, fonts,
 
 [https://zumerlab.github.io/snapdom/](https://zumerlab.github.io/snapdom/)
 
+
+## Table of Contents
+
+- [Installation](#installation)
+  - [NPM / Yarn](#npm--yarn)
+  - [CDN](#cdn)
+  - [Script tag (local)](#script-tag-local)
+  - [ES Module](#es-module)
+  - [Module via CDN](#module-via-cdn)
+- [Basic usage](#basic-usage)
+  - [Reusable capture](#reusable-capture)
+  - [One-step shortcuts](#one-step-shortcuts)
+- [API](#api)
+  - [snapdom(el, options?)](#snapdomel-options)
+  - [Shortcut methods](#shortcut-methods)
+- [Options](#options)
+  - [Fallback image on `<img>` load failure](#fallback-image-on-img-load-failure)
+  - [Dimensions (`scale`, `width`, `height`)](#dimensions-scale-width-height)
+  - [Cross-Origin Images & Fonts (`useProxy`)](#cross-origin-images--fonts-useproxy)
+  - [Fonts](#fonts)
+    - [embedFonts](#embedfonts)
+    - [localFonts](#localfonts)
+    - [iconFonts](#iconfonts)
+    - [excludeFonts](#excludefonts)
+  - [Filtering nodes: `exclude` vs `filter`](#filtering-nodes-exclude-vs-filter)
+  - [preCache() – Optional helper](#precache--optional-helper)
+  - [Cache control](#cache-control)
+- [Limitations](#limitations)
+- [⚡ Performance Benchmarks (Chromium)](#performance-benchmarks)
+  - [Simple elements](#simple-elements)
+  - [Complex elements](#complex-elements)
+  - [Run the benchmarks](#run-the-benchmarks)
+- [Roadmap](#roadmap)
+- [Development](#development)
+- [Contributors 🙌](#contributors)
+- [💖 Sponsors](#sponsors)
+- [Star History](#star-history)
+- [License](#license)
+
+
 ## Installation
 
 ### NPM / Yarn
@@ -335,50 +375,32 @@ await snapdom.toPng(el, { cache: 'disabled' });
 * `@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)
 
 
-## ⚡ Performance Benchmarks
-
-Snapdom has received **significant performance improvements** since version `v1.8.0`. The following benchmarks compare:
-
-* **Snapdom (current)**
-* **Snapdom v1.8.0**
-* `html2canvas`
-* `html-to-image`
+## Performance Benchmarks
 
+**Setup.** Vitest benchmarks on Chromium, repo tests. Hardware may affect results.
+Values are **average capture time (ms)** → lower is better.
 
 ### Simple elements
 
-| Scenario                 | Snapdom (current) | Snapdom v1.8.0 | html2canvas | html-to-image |
-| ------------------------ | ----------------- | -------------- | ----------- | ------------- |
-| Small (200×100)          | **0.4 ms**        | 1.2 ms         | 70.3 ms     | 3.6 ms        |
-| Modal (400×300)          | **0.4 ms**        | 1.1 ms         | 68.8 ms     | 3.6 ms        |
-| Page View (1200×800)     | **0.4 ms**        | 1.0 ms         | 100.5 ms    | 3.4 ms        |
-| Large Scroll (2000×1500) | **0.4 ms**        | 1.0 ms         | 153.1 ms    | 3.4 ms        |
-| Very Large (4000×2000)   | **0.4 ms**        | 1.0 ms         | 278.9 ms    | 4.3 ms        |
-
+| Scenario                 | SnapDOM v1.9.10 | SnapDOM v1.9.9 | html2canvas | html-to-image |
+| ------------------------ | --------------- | -------------- | ----------- | ------------- |
+| Small (200×100)          | **0.5 ms**      | 0.8 ms         | 67.7 ms     | 3.1 ms        |
+| Modal (400×300)          | **0.5 ms**      | 0.8 ms         | 75.5 ms     | 3.6 ms        |
+| Page View (1200×800)     | **0.5 ms**      | 0.8 ms         | 114.2 ms    | 3.3 ms        |
+| Large Scroll (2000×1500) | **0.5 ms**      | 0.8 ms         | 186.3 ms    | 3.2 ms        |
+| Very Large (4000×2000)   | **0.5 ms**      | 0.9 ms         | 425.9 ms    | 3.3 ms        |
 
+---
 
 ### Complex elements
 
-| Scenario                 | Snapdom (current) | Snapdom v1.8.0 | html2canvas | html-to-image |
-| ------------------------ | ----------------- | -------------- | ----------- | ------------- |
-| Small (200×100)          | **1.1 ms**        | 3.2 ms         | 76.0 ms     | 15.3 ms       |
-| Modal (400×300)          | **4.5 ms**        | 14.0 ms        | 133.2 ms    | 55.4 ms       |
-| Page View (1200×800)     | **32.9 ms**       | 113.6 ms       | 303.4 ms    | 369.1 ms      |
-| Large Scroll (2000×1500) | **133.9 ms**      | 387.4 ms       | 594.4 ms    | 1,163.0 ms    |
-| Very Large (4000×2000)   | **364.0 ms**      | 1,200.4 ms     | 1,380.8 ms  | 3,023.9 ms    |
-
-
-
-### Summary
-
-* Snapdom (current) is **2×–6× faster** than `v1.8.0`
-* Up to **150× faster** than `html2canvas`
-* Up to **8× faster** than `html-to-image` in large scenarios
-
-<sub>Benchmarks run in Chromium using Vitest.<br>
-Hardware: MacBook Air 2018.<br>
-⚠️ Performance may vary depending on device.</sub>
-
+| Scenario                 | SnapDOM v1.9.10 | SnapDOM v1.9.9 | html2canvas | html-to-image |
+| ------------------------ | --------------- | -------------- | ----------- | ------------- |
+| Small (200×100)          | **1.6 ms**      | 3.3 ms         | 68.0 ms     | 14.3 ms       |
+| Modal (400×300)          | **2.9 ms**      | 6.8 ms         | 87.5 ms     | 34.8 ms       |
+| Page View (1200×800)     | **17.5 ms**     | 50.2 ms        | 178.0 ms    | 429.0 ms      |
+| Large Scroll (2000×1500) | **54.0 ms**     | 201.8 ms       | 735.2 ms    | 984.2 ms      |
+| Very Large (4000×2000)   | **171.4 ms**    | 453.7 ms       | 1,800.4 ms  | 2,611.9 ms    |
 
 
 ### Run the benchmarks
@@ -404,10 +426,10 @@ Planned improvements for future versions of SnapDOM:
 * [X] **Decouple internal logic from global options**
   Functions will be redesigned to avoid relying directly on `options`. A centralized capture context will improve clarity, autonomy, and testability. See [`next` branch](https://github.com/zumerlab/snapdom/tree/main)
 
-* [ ] **Expose cache control**
+* [X] **Expose cache control**
   Users will be able to manually clear image and font caches or configure their own caching strategies.
 
-* [ ] **Auto font preloading**
+* [X] **Auto font preloading**
   Required fonts will be automatically detected and preloaded before capture, reducing the need for manual `preCache()` calls.
 
 * [ ] **Document plugin development**
@@ -453,11 +475,12 @@ The main entry point is in `src/`, and output bundles are generated in the `dist
 For detailed contribution guidelines, please see [CONTRIBUTING](https://github.com/zumerlab/snapdom/blob/main/CONTRIBUTING.md).
 
 
-## Contributors 🙌
+## Contributors
 
 <!-- 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/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>
 <a href="https://github.com/tarwin" title="tarwin"><img src="https://avatars.githubusercontent.com/u/646149?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="tarwin"/></a>
 <a href="https://github.com/17biubiu" title="17biubiu"><img src="https://avatars.githubusercontent.com/u/13295895?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="17biubiu"/></a>
 <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>
@@ -470,6 +493,7 @@ For detailed contribution guidelines, please see [CONTRIBUTING](https://github.c
 <a href="https://github.com/simon1uo" title="simon1uo"><img src="https://avatars.githubusercontent.com/u/60037549?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="simon1uo"/></a>
 <a href="https://github.com/titoBouzout" title="titoBouzout"><img src="https://avatars.githubusercontent.com/u/64156?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="titoBouzout"/></a>
 <a href="https://github.com/jhbae200" title="jhbae200"><img src="https://avatars.githubusercontent.com/u/20170610?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="jhbae200"/></a>
+<a href="https://github.com/xiaobai-web715" title="xiaobai-web715"><img src="https://avatars.githubusercontent.com/u/81091224?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="xiaobai-web715"/></a>
 <a href="https://github.com/miusuncle" title="miusuncle"><img src="https://avatars.githubusercontent.com/u/7549857?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="miusuncle"/></a>
 <a href="https://github.com/rbbydotdev" title="rbbydotdev"><img src="https://avatars.githubusercontent.com/u/101137670?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="rbbydotdev"/></a>
 <a href="https://github.com/zhanghaotian2018" title="zhanghaotian2018"><img src="https://avatars.githubusercontent.com/u/169218899?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="zhanghaotian2018"/></a>
@@ -478,7 +502,7 @@ For detailed contribution guidelines, please see [CONTRIBUTING](https://github.c
 </p>
 <!-- CONTRIBUTORS:END -->
 
-## 💖 Sponsors
+## Sponsors
 
 Special thanks to [@megaphonecolin](https://github.com/megaphonecolin) for supporting this project!
 

package/dist/snapdom.js

@@ -1,7 +1,7 @@
 
 /*
 * snapdom
-* v.1.9.10-dev.2
+* v.1.9.10
 * Author Juan Martin Muda
 * License MIT
 **/
@@ -721,22 +721,14 @@
     return Promise.all(childList.map((child) => {
       return new Promise((resolve) => {
         function deal() {
-          idle(
-            (deadline) => {
-              if (deadline instanceof IdleDeadline) {
-                if (deadline.timeRemaining()) {
-                  callback(child, resolve);
-                } else {
-                  deal();
-                }
-              } else {
-                callback(child, resolve);
-              }
-            },
-            {
-              fast
+          idle((deadline) => {
+            const hasIdleBudget = deadline && typeof deadline.timeRemaining === "function" ? deadline.timeRemaining() > 0 : true;
+            if (hasIdleBudget) {
+              callback(child, resolve);
+            } else {
+              deal();
             }
-          );
+          }, { fast });
         }
         deal();
       });
@@ -1843,7 +1835,7 @@
     }
     return used;
   }
-  function ensureFontsReady(families, warmupRepetitions = 1) {
+  function ensureFontsReady(families, warmupRepetitions = 2) {
     return __async(this, null, function* () {
       try {
         yield document.fonts.ready;
@@ -2375,17 +2367,40 @@
   function inlineBackgroundImages(_0, _1, _2) {
     return __async(this, arguments, function* (source, clone, styleCache, options = {}) {
       const queue = [[source, clone]];
-      const imageProps = [
+      const URL_PROPS = [
         "background-image",
+        // Mask shorthands & images (both standard and WebKit)
         "mask",
         "mask-image",
+        "-webkit-mask",
         "-webkit-mask-image",
+        // Mask sources (rare, but keep)
         "mask-source",
         "mask-box-image-source",
         "mask-border-source",
         "-webkit-mask-box-image-source",
+        // Border image
         "border-image",
-        "border-image-source",
+        "border-image-source"
+      ];
+      const MASK_LAYOUT_PROPS = [
+        "mask-position",
+        "mask-size",
+        "mask-repeat",
+        // WebKit variants
+        "-webkit-mask-position",
+        "-webkit-mask-size",
+        "-webkit-mask-repeat",
+        // Extra (optional but helpful across engines)
+        "mask-origin",
+        "mask-clip",
+        "-webkit-mask-origin",
+        "-webkit-mask-clip",
+        // Some engines expose X/Y position separately:
+        "-webkit-mask-position-x",
+        "-webkit-mask-position-y"
+      ];
+      const BORDER_AUX_PROPS = [
         "border-image-slice",
         "border-image-width",
         "border-image-outset",
@@ -2400,10 +2415,7 @@
           const bis = style.getPropertyValue("border-image-source");
           return bi && bi !== "none" || bis && bis !== "none";
         })();
-        for (const prop of imageProps) {
-          if (["border-image-slice", "border-image-width", "border-image-outset", "border-image-repeat"].includes(prop) && !hasBorderImage) {
-            continue;
-          }
+        for (const prop of URL_PROPS) {
           const val = style.getPropertyValue(prop);
           if (!val || val === "none") continue;
           const splits = splitBackgroundImage(val);
@@ -2414,6 +2426,18 @@
             cloneNode.style.setProperty(prop, inlined.join(", "));
           }
         }
+        for (const prop of MASK_LAYOUT_PROPS) {
+          const val = style.getPropertyValue(prop);
+          if (!val || val === "initial") continue;
+          cloneNode.style.setProperty(prop, val);
+        }
+        if (hasBorderImage) {
+          for (const prop of BORDER_AUX_PROPS) {
+            const val = style.getPropertyValue(prop);
+            if (!val || val === "initial") continue;
+            cloneNode.style.setProperty(prop, val);
+          }
+        }
         const sChildren = Array.from(srcNode.children);
         const cChildren = Array.from(cloneNode.children);
         for (let i = 0; i < Math.min(sChildren.length, cChildren.length); i++) {
@@ -2456,7 +2480,7 @@
               const families = new Set(
                 Array.from(required).map((k) => String(k).split("__")[0]).filter(Boolean)
               );
-              yield ensureFontsReady(families, 2);
+              yield ensureFontsReady(families, 5);
             }
             fontsCSS = yield embedCustomFonts({
               required,
@@ -2715,8 +2739,6 @@
 
   // src/core/context.js
   function normalizeCachePolicy(v) {
-    if (v === true) return "soft";
-    if (v === false) return "disabled";
     if (typeof v === "string") {
       const s = v.toLowerCase().trim();
       if (s === "disabled" || s === "full" || s === "auto" || s === "soft") return (
@@ -2886,9 +2908,7 @@
       if (context.iconFonts && context.iconFonts.length > 0) extendIconFonts(context.iconFonts);
       if (!context.snap) {
         context.snap = {
-          /** Delegates to this module’s PNG path (tu build devuelve <img>). */
           toPng: (el, opts) => snapdom.toPng(el, opts),
-          /** Útil si en algún flujo necesitás vector o <img> directo. */
           toImg: (el, opts) => snapdom.toImg(el, opts)
         };
       }
@@ -2896,12 +2916,18 @@
     });
   }
   snapdom.capture = (el, context, _token) => __async(null, null, function* () {
-    if (_token !== INTERNAL_TOKEN) {
-      throw new Error("[snapdom.capture] is internal. Use snapdom(...) instead.");
-    }
+    if (_token !== INTERNAL_TOKEN) throw new Error("[snapdom.capture] is internal. Use snapdom(...) instead.");
     const url = yield captureDOM(el, context);
     const ensureContext = (opts) => __spreadValues(__spreadValues({}, context), opts || {});
-    const withFormat = (format) => (opts) => rasterize(url, ensureContext(__spreadProps(__spreadValues({}, opts || {}), { format })));
+    const withFormat = (format) => (opts) => {
+      const next = ensureContext(__spreadProps(__spreadValues({}, opts || {}), { format }));
+      const wantsJpeg = format === "jpeg" || format === "jpg";
+      const noBg = next.backgroundColor == null || next.backgroundColor === "transparent";
+      if (wantsJpeg && noBg) {
+        next.backgroundColor = "#ffffff";
+      }
+      return rasterize(url, next);
+    };
     return {
       url,
       toRaw: () => url,