@zumer/snapdom 1.9.12-dev.4 → 1.9.14

package/README.md

@@ -38,12 +38,12 @@ It captures any HTML element as a scalable SVG image, preserving styles, fonts,
 * ⚡ Ultra fast, no dependencies
 * 📦 100% based on standard Web APIs
 * Support same-origin `ìframe`
-* Support CSS counter() and counters()
+* Support CSS counter() and CSS counters()
 * Support `...` line-clamp
 
 ## Demo
 
-[https://zumerlab.github.io/snapdom/](https://zumerlab.github.io/snapdom/)
+[https://snapdom.dev](https://snapdom.dev)
 
 
 ## Table of Contents
@@ -69,8 +69,10 @@ It captures any HTML element as a scalable SVG image, preserving styles, fonts,
     - [iconFonts](#iconfonts)
     - [excludeFonts](#excludefonts)
   - [Filtering nodes: `exclude` vs `filter`](#filtering-nodes-exclude-vs-filter)
-  - [preCache() – Optional helper](#precache--optional-helper)
+  - [straighten](#straighten)
+  - [noShadows](#no-shadows)
   - [Cache control](#cache-control)
+- [preCache](#precache--optional-helper)
 - [Limitations](#limitations)
 - [⚡ Performance Benchmarks (Chromium)](#performance-benchmarks)
   - [Simple elements](#simple-elements)
@@ -163,7 +165,8 @@ Returns an object with reusable export methods:
 {
   url: string;
   toRaw(): string;
-  toImg(): Promise<HTMLImageElement>;
+  toImg(): Promise<HTMLImageElement>; // deprecated 
+  toSvg(): Promise<HTMLImageElement>;
   toCanvas(): Promise<HTMLCanvasElement>;
   toBlob(options?): Promise<Blob>;
   toPng(options?): Promise<HTMLImageElement>;
@@ -177,7 +180,8 @@ Returns an object with reusable export methods:
 
 | Method                         | Description                       |
 | ------------------------------ | --------------------------------- |
-| `snapdom.toImg(el, options?)`  | Returns an `HTMLImageElement`     |
+| `snapdom.toImg(el, options?)`  | Returns an SVG `HTMLImageElement` (deprecated) |
+| `snapdom.toSvg(el, options?)`  | Returns an SVG `HTMLImageElement` |
 | `snapdom.toCanvas(el, options?)` | Returns a `Canvas`               |
 | `snapdom.toBlob(el, options?)` | Returns an SVG or raster `Blob`   |
 | `snapdom.toPng(el, options?)`  | Returns a PNG image               |
@@ -191,13 +195,14 @@ Returns an object with reusable export methods:
 
 All capture methods accept an `options` object:
 
+
 | Option            | Type     | Default  | Description                                     |
 | ----------------- | -------- | -------- | ----------------------------------------------- |
 | `fast`            | boolean  | `true`   | Skips small idle delays for faster results      |
 | `embedFonts`      | boolean  | `false`  | Inlines non-icon fonts (icon fonts always on)   |
 | `localFonts`      | array    | `[]`     | Local fonts `{ family, src, weight?, style? }`  |
 | `iconFonts`       | string\|RegExp\|Array | `[]` | Extra icon font matchers                      |
-| `excludeFonts`    | object  | `{}`     | Exclude font families/domains/subsets during embedding |
+| `excludeFonts`    | object   | `{}`     | Exclude families/domains/subsets during embedding |
 | `scale`           | number   | `1`      | Output scale multiplier                         |
 | `dpr`             | number   | `devicePixelRatio` | Device pixel ratio                     |
 | `width`           | number   | -        | Output width                                    |
@@ -207,12 +212,14 @@ All capture methods accept an `options` object:
 | `useProxy`        | string   | `''`     | Proxy base for CORS fallbacks                   |
 | `type`            | string   | `svg`    | Default Blob type (`svg`\|`png`\|`jpg`\|`webp`) |
 | `exclude`         | string[] | -        | CSS selectors to exclude                        |
-| `excludeMode`     | string   | 'hide' | Controls how `exclude` works with nodes    |
+| `excludeMode`     | `"hide"`\|`"remove"` | `"hide"` | How `exclude` is applied                  |
 | `filter`          | function | -        | Custom predicate `(el) => boolean`              |
-| `filterMode`      | string   | 'hide' | Controls how `filter` works with nodes    |
-| `cache`           | string   | `"soft"` | Control internal caches: `disabled`, `soft`, `auto`, `full` |
-| `placeholders`           | boolean   | `true`  | Show placeholders for images and cross-origin iframes |
-| `fallbackURL` | 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}`) |
+| `filterMode`      | `"hide"`\|`"remove"` | `"hide"` | How `filter` is applied                   |
+| `cache`           | string   | `"soft"` | `disabled` \| `soft` \| `auto` \| `full`        |
+| `placeholders`    | boolean  | `true`   | Show placeholders for images/CORS iframes       |
+| `fallbackURL`     | string \| function  | - | Fallback image for `<img>` load failure |
+| `straighten`      | boolean  | `false`  | Straightens the root: removes `translate/rotate` but preserves `scale/skew`, producing a flat, reusable capture |
+| `noShadows`       | boolean  | `false`  | Do not expand the root’s bounding box for shadows/blur/outline, and strip those visual effects from the cloned root |
 
 ### Fallback image on `<img>` load failure
 
@@ -220,18 +227,18 @@ Provide a default image for failed `<img>` loads. You can pass a fixed URL or a
 
 ```js
 // 1) Fixed URL fallback
-await snapdom.toImg(element, {
+await snapdom.toSvg(element, {
   fallbackURL: '/images/fallback.png'
 });
 
 // 2) Dynamic placeholder via callback
-await snapdom.toImg(element, {
+await snapdom.toSvg(element, {
   fallbackURL: ({ width: 300, height: 150 }) =>
     `https://placehold.co/${width}x${height}`
 });
 
 // 3) With proxy (if your fallback host has no CORS)
-await snapdom.toImg(element, {
+await snapdom.toSvg(element, {
   fallbackURL: ({ width = 300, height = 150 }) =>
     `https://dummyimage.com/${width}x${height}/cccccc/666.png&text=img`,
   useProxy: 'https://proxy.corsfix.com/?'
@@ -307,7 +314,7 @@ await snapdom.toPng(el, {
 - Matching is case-insensitive for `families`. Hosts are matched by substring against the resolved URL.
 
 
-### Filtering nodes: `exclude` vs `filter`
+#### Filtering nodes: `exclude` vs `filter`
 
 * `exclude`: remove by **selector**.
 * `excludeMode`: `hide` applies `visibility:hidden` CSS rule on excluded nodes and the layout remains as the original. `remove` do not clone excluded nodes at all.
@@ -336,22 +343,30 @@ await snapdom.toPng(el, {
   exclude: ['.cookie-banner', '.tooltip', '[data-test="debug"]']
 });
 ```
-### `preCache()` – Optional helper
 
-Preloads external resources to avoid first-capture stalls (helpful for big/complex trees).
+### Straighten 
 
-```js
-import { preCache } from '@zumer/snapdom';
+When capturing rotated or translated elements, you may want to **straighten** the root so the snapshot can be reused in another layout without inheriting those transforms.
 
-await preCache({
-  root: document.body,
-  embedFonts: true,
-  localFonts: [{ family: 'Inter', src: '/fonts/Inter.woff2', weight: 400 }],
-  useProxy: 'https://proxy.corsfix.com/?'
-});
+- **`straighten: true`**  
+  Straightens the cloned root: **removes `translate` and `rotate`** but **keeps `scale/skew`** to preserve proportions.  
+  The output is **flat, upright, and ready** to embed elsewhere.
+
+
+### noShadows
+- **`noShadows: true`**  
+  Prevents expanding the bounding box for shadows, blur, or outline on the root, and also strips `box-shadow`, `text-shadow`, `filter: blur()/drop-shadow()`, and `outline` from the cloned root.  
+
+> 💡 **Tip:** Using both (`straighten` + `noShadows`) produces a strict, minimal bounding box with no visual bleed.
+
+**Example**
+
+```js
+// Straighten and remove shadow bleed
+await snapdom.toSvg(el, { straighten: true, noShadows: true });
 ```
 
-### Cache control
+## Cache control
 
 SnapDOM maintains internal caches for images, backgrounds, resources, styles, and fonts.
 You can control how they are cleared between captures using the `cache` option:
@@ -376,6 +391,21 @@ await snapdom.toPng(el, { cache: 'full' });
 await snapdom.toPng(el, { cache: 'disabled' });
 ```
 
+## `preCache()` – Optional helper
+
+Preloads external resources to avoid first-capture stalls (helpful for big/complex trees).
+
+```js
+import { preCache } from '@zumer/snapdom';
+
+await preCache({
+  root: document.body,
+  embedFonts: true,
+  localFonts: [{ family: 'Inter', src: '/fonts/Inter.woff2', weight: 400 }],
+  useProxy: 'https://proxy.corsfix.com/?'
+});
+```
+
 ## Limitations
 
 * External images should be CORS-accessible (use `useProxy` option for handling CORS denied)
@@ -490,6 +520,7 @@ For detailed contribution guidelines, please see [CONTRIBUTING](https://github.c
 <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/K1ender" title="K1ender"><img src="https://avatars.githubusercontent.com/u/146767945?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="K1ender"/></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>
 <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>
@@ -512,7 +543,7 @@ For detailed contribution guidelines, please see [CONTRIBUTING](https://github.c
 
 ## Sponsors
 
-Special thanks to [@megaphonecolin](https://github.com/megaphonecolin) for supporting this project!
+Special thanks to [@megaphonecolin](https://github.com/megaphonecolin), [@sdraper69](https://github.com/sdraper69), [@reynaldichernando](https://github.com/reynaldichernando) and [@gamma-app](https://github.com/gamma-app), for supporting this project!
 
 If you'd like to support this project too, you can [become a sponsor](https://github.com/sponsors/tinchox5).