@zumer/snapdom 1.7.1 → 1.9.3

package/README.md

@@ -7,7 +7,25 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@zumer/snapdom"><img src="https://img.shields.io/github/package-json/v/zumerlab/snapdom"></a>
+ <a href="https://www.npmjs.com/package/@zumer/snapdom">
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@zumer/snapdom?style=flat-square&label=Version">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/graphs/contributors">
+    <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/zumerlab/snapdom?style=flat-square&label=Contributors">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/stargazers">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/zumerlab/snapdom?style=flat-square&label=Stars">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/network/members">
+    <img alt="GitHub forks" src="https://img.shields.io/github/forks/zumerlab/snapdom?style=flat-square&label=Forks">
+  </a>
+  <a href="https://github.com/sponsors/tinchox5">
+    <img alt="Sponsor tinchox5" src="https://img.shields.io/github/sponsors/tinchox5?style=flat-square&label=Sponsor">
+  </a>
+
+  <a href="https://github.com/zumerlab/snapdom/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/zumerlab/snapdom?style=flat-square">
+  </a>
 </p>
 
 **snapDOM** is a fast and accurate DOM-to-image capture tool built for **Zumly**, a zoom-based view transition framework.
@@ -128,28 +146,60 @@ All capture methods accept an `options` object:
 | `fast`            | boolean  | `true`   | Skips idle delay for faster results        |
 | `embedFonts`      | boolean  | `false`  | Inlines fonts (icon fonts always embedded) |
 | `scale`           | number   | `1`      | Output scale multiplier                    |
+| `width`           | number   | -        | Output specific width size                 |
+| `height`          | number   | -        | Output specific height size                |
 | `backgroundColor` | string   | `"#fff"` | Fallback color for JPG/WebP                |
 | `quality`         | number   | `1`      | Quality for JPG/WebP (0 to 1)              |
-| `crossOrigin`     | function | -        | Function to determine CORS mode per image URL |
+| `useProxy`     | string | ''        | Specify a proxy for handling CORS images as fallback|
+
+### Setting custom dimensions with width and height options
+
+Use the `width` and `height` options to generate an image with specific dimensions.
+
+**Examples:**
+
+**1. Fixed width (proportional height)**
+Sets a specific width while maintaining the aspect ratio. Height adjusts proportionally.
+
+```js
+const result = await snapdom(element, {
+  width: 400 // Outputs a 400px-wide image with auto-scaled height
+});
+```
+
+**2. Fixed height (proportional width)**
+Sets a specific height while maintaining the aspect ratio. Width adjusts proportionally.
+
+```js
+const result = await snapdom(element, {
+  height: 200 // Outputs a 200px-tall image with auto-scaled width
+});
+```
+
+**3. Fixed width and height (may distort image)**
+Forces exact dimensions, potentially distorting the image if the aspect ratio differs.
+
+```js
+const result = await snapdom(element, {
+  width: 800,  // Outputs an 800px × 200px image (may stretch/squish content)
+  height: 200  
+});
+```
+
+**Note:** If `scale` is different from  1, it takes priority over width and height.
+Example: `{ scale: 3, width: 500 }` ignores width and scales the image 3x instead.
+
 
 ### Cross-Origin Images
 
-By default, snapDOM loads images with `crossOrigin="anonymous"`. You can customize this behavior using the `crossOrigin` option:
+By default, snapDOM loads images with `crossOrigin="anonymous"` or `crossOrigin="use-credentials"`. In case fails to get the images, `useProxy` can be used to deal with CORS images:
 
 ```js
 const result = await snapdom(element, {
-  crossOrigin: (url) => {
-    // Use credentials for same-origin images
-    if (url.startsWith(window.location.origin)) {
-      return "use-credentials";
-    }
-    // Use anonymous for cross-origin images
-    return "anonymous";
-  }
+  useProxy: 'your/proxy/' //Example: 'https://corsproxy.io/?url=' or 'https://api.allorigins.win/raw?url='
 });
 ```
 
-This is useful when your images require authentication or when dealing with credentialed requests.
 
 ### Download options
 
@@ -184,13 +234,13 @@ import { snapdom, preCache } from './snapdom.mjs';
 
 * `embedFonts` *(boolean, default: true)* — Inlines non-icon fonts during preload.
 * `reset` *(boolean, default: false)* — Clears all existing internal caches.
-* `crossOrigin` *(function)* — Function to determine CORS mode per image URL during preload.
+* `useProxy` *(string)* — Proxy for handling CORS images as fallback.
 
 
 ## Features
 
 * Captures **shadow DOM** and Web Components
-* Supports `::before` and `::after` pseudo-elements
+* Supports `::before`, `::after` and `::first-letter` pseudo-elements
 * Inlines background images and fonts
 * Handles **Font Awesome**, **Material Icons**, and more
 * `data-capture="exclude"` to ignore an element
@@ -198,30 +248,58 @@ import { snapdom, preCache } from './snapdom.mjs';
 
 ## Limitations
 
-* External images must be CORS-accessible (use `crossOrigin` option for credentialed requests)
+* External images shloud 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)
 
-## Benchmarks
 
-`snapDOM` is not only highly accurate — it’s **extremely fast**.
+## ⚡ Performance Benchmarks
 
+Snapdom has received **major performance improvements** since version `v1.8.0`. Below are benchmark results comparing:
 
-Latest benchmarks show significant performance improvements against other libraries:
+* 🔷 **Snapdom (current)**
+* 🔸 **Snapdom v1.8.0**
+* 🟥 `html2canvas`
+* 🟨 `modern-screenshot`
 
-| Scenario                         | vs. `modern-screenshot` | vs. `html2canvas` |
-| -------------------------------- | :---------------------: | :---------------: |
-| Small element (200×100)          |       6.46× faster      |   32.27× faster   |
-| Modal size (400×300)             |       7.28× faster      |   32.66× faster   |
-| Page view (1200×800)             |      13.17× faster      |   35.29× faster   |
-| Large scroll area (2000×1500)    |      38.23× faster      |   68.85× faster   |
-| Very large element (4000×2000)   |      93.31× faster      |   133.12× faster  |
-| Complex small element (200×100)  |       3.97× faster      |   15.23× faster   |
-| Complex modal (400×300)          |       2.32× faster      |    5.33× faster   |
-| Complex page (1200×800)          |       1.62× faster      |    1.65× faster   |
-| Complex large scroll (2000×1500) |       1.66× faster      |    1.24× faster   |
-| Complex very large (4000×2000)   |       1.52× faster      |    1.28× faster   |
+Each benchmark shows the **fastest observed time** (lower is better), measured in **milliseconds (ms)**.
+
+---
+
+### Simple elements
+
+| Scenario                 | Snapdom (current) | Snapdom v1.8.0 | html2canvas | modern-screenshot |
+| ------------------------ | ----------------- | -------------- | ----------- | ----------------- |
+| Small (200×100)          | **0.4 ms**        | 1.2 ms         | 70.3 ms     | 11.9 ms           |
+| Modal (400×300)          | **0.4 ms**        | 1.1 ms         | 68.8 ms     | 14.1 ms           |
+| Page View (1200×800)     | **0.4 ms**        | 1.0 ms         | 100.5 ms    | 34.2 ms           |
+| Large Scroll (2000×1500) | **0.4 ms**        | 1.0 ms         | 153.1 ms    | 77.8 ms           |
+| Very Large (4000×2000)   | **0.4 ms**        | 1.0 ms         | 278.9 ms    | 194.7 ms          |
+
+---
+
+### Complex elements
+
+| Scenario                 | Snapdom (current) | Snapdom v1.8.0 | html2canvas | modern-screenshot |
+| ------------------------ | ----------------- | -------------- | ----------- | ----------------- |
+| Small (200×100)          | **1.1 ms**        | 3.2 ms         | 72.5 ms     | 16.1 ms           |
+| Modal (400×300)          | **4.5 ms**        | 14.0 ms        | 90.1 ms     | 34.6 ms           |
+| Page View (1200×800)     | **32.9 ms**       | 113.6 ms       | 196.1 ms    | 181.1 ms          |
+| Large Scroll (2000×1500) | **133.9 ms**      | 387.4 ms       | 446.6 ms    | 635.9 ms          |
+| Very Large (4000×2000)   | **364.0 ms**      | 1,200.4 ms     | 1,275.4 ms  | 1,685.6 ms        |
+
+---
+
+### Summary
+
+* Snapdom (current) is consistently **2×–4× faster** than `v1.8.0`
+* Up to **500× faster** than `html2canvas`
+* Also significantly faster than `modern-screenshot`, especially for large DOMs
+
+<sub>All benchmarks were run in Chromium using Vitest.<br>
+Tests were performed on a 2018 MacBook Air.<br>
+⚠️ Performance can be even better on more modern hardware.</sub>
 
 
 ### Run the benchmarks
@@ -237,11 +315,53 @@ npm run test:benchmark
 
 They execute in **headless Chromium** using real DOM nodes.
 
+## Development
+
+To contribute or build snapDOM locally:
+
+```sh
+# Clone the repository
+git clone https://github.com/zumerlab/snapdom.git
+cd snapdom
+
+# Install dependencies
+npm install
+
+# Compile the library (ESM, CJS, and minified versions)
+npm run compile
+
+# Run tests
+npm test
+
+# Run Benchmarks
+npm run test:benchmark
+```
+
+The main entry point is in `src/`, and output bundles are generated in the `dist/` folder.
+
+For detailed contribution guidelines, please see [CONTRIBUTING](https://github.com/zumerlab/snapdom/blob/main/CONTRIBUTING.md).
+
+
 ## Contributors 🙌
 
-<a href="https://github.com/zumerlab/snapdom/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=zumerlab/snapdom" />
-</a>
+<!-- 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/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/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/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/elliots" title="elliots"><img src="https://avatars.githubusercontent.com/u/622455?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="elliots"/></a>
+<a href="https://github.com/jswhisperer" title="jswhisperer"><img src="https://avatars.githubusercontent.com/u/1177690?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="jswhisperer"/></a>
+<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/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>
+</p>
+<!-- CONTRIBUTORS:END -->
+
+## 💖 Sponsors
+
+Special thanks to [@megaphonecolin](https://github.com/megaphonecolin) for supporting this project!  
+
+If you'd like to support this project too, you can [become a sponsor](https://github.com/sponsors/tinchox5).
 
 ## License