@zumer/snapdom 2.15.0-dev.1 → 2.16.0-colin.0

package/README.md

@@ -1,11 +1,14 @@
 <p align="center">
-  <a href="http://zumerlab.github.io/snapdom">
+  <a href="https://snapdom.dev">
     <img src="https://raw.githubusercontent.com/zumerlab/snapdom/main/docs/assets/newhero.png" width="80%">
   </a>
 </p>
 
 <p align="center">
- <a href="https://www.npmjs.com/package/@zumer/snapdom">
+ <a href="https://snapdom.dev">
+    <img alt="Website" src="https://img.shields.io/badge/Website-snapdom.dev-2ea44f?style=flat-square">
+  </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://www.npmjs.com/package/@zumer/snapdom">
@@ -36,16 +39,15 @@
 **SnapDOM** is a next-generation **DOM Capture Engine** — the fast, modern alternative to **html2canvas**, **dom-to-image**, and **html-to-image**.  
 It converts any DOM subtree into a self-contained representation that can be exported to SVG, PNG, JPG, WebP, Canvas, Blob, or **any custom format** through plugins — ultra-fast, modular, extensible, and dependency-free.
 
-* Full DOM capture
-* Embedded styles, pseudo-elements, and fonts
-* Export to SVG, PNG, JPG, WebP, `canvas`, or Blob
-* ⚡ Ultra fast, no dependencies
-* 100% based on standard Web APIs
-* Support same-origin `ìframe`
-* Support CSS counter() and CSS counters()
-* Support `...` line-clamp
+> 📖 **[Documentation, guides & live demos → snapdom.dev](https://snapdom.dev)**
+
+## Features
+
+Full DOM capture with embedded styles, pseudo-elements and fonts; export to SVG, PNG, JPG, WebP, `canvas` or Blob — ultra fast, dependency-free, and 100% based on standard Web APIs.
 
-## Demo
+👉 **See the complete technical feature list in [FEATURES.md](FEATURES.md).**
+
+## Website & Live Demos
 
 [https://snapdom.dev](https://snapdom.dev)
 
@@ -72,95 +74,23 @@ await result.download({ format: 'jpg', filename: 'card.jpg' });
 
 ---
 
-## Capture Flow
-
-SnapDOM transforms your DOM element through these stages:
-
-```
-DOM Element
-    ↓
-Clone
-    ↓
-Styles & Pseudo
-    ↓
-Images & Backgrounds
-    ↓
-Fonts
-    ↓
-SVG foreignObject
-    ↓
-data:image/svg+xml
-    ↓
-toPng / toSvg / toBlob / download
-```
-
-| Stage | What happens |
-|-------|--------------|
-| **Clone** | Deep clone with styles, Shadow DOM, iframes. Exclude/filter nodes. |
-| **Styles & Pseudo** | Inline `::before`/`::after` as elements, resolve `counter()`/`counters()`. |
-| **Images & Backgrounds** | Fetch and inline external images/backgrounds as data URLs. |
-| **Fonts** | Embed `@font-face` (optional) and icon fonts. |
-| **SVG** | Wrap clone in `<foreignObject>`, serialize to `data:image/svg+xml`. |
-| **Export** | Convert SVG to PNG/JPG/WebP/Blob or trigger download. |
-
-Plugin hooks: `beforeSnap` → `beforeClone` → `afterClone` → `beforeRender` → `afterRender` → `beforeExport` → `afterExport`.
-
-
 ## Table of Contents
 
 - [Quick Start](#quick-start)
-- [Capture Flow](#capture-flow)
+- [Features](#features)
+- [Website & Live Demos](#website--live-demos)
 - [Installation](#installation)
-  - [NPM / Yarn (stable)](#npm--yarn-stable)
-  - [NPM / Yarn (dev builds)](#npm--yarn-dev-builds)
-  - [CDN (stable)](#cdn-stable)
-  - [CDN (dev builds)](#cdn-dev-builds)
-- [Build Outputs](#build-outputs--tree-shaking)
+- [Build Outputs](#build-outputs)
 - [Usage](#usage)
-  - [Reusable capture](#reusable-capture)
-  - [One-step shortcuts](#one-step-shortcuts)
-- [API](#api)
-  - [snapdom(el, options?)](#snapdomel-options)
-  - [Shortcut methods](#shortcut-methods)
-- [Options](#options)
-  - [debug](#debug)
-  - [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)
-  - [outerTransforms](#outerTransforms)
-  - [outerShadows](#no-shadows)
-  - [Cache control](#cache-control)
-- [preCache](#precache--optional-helper)
-- [Plugins (BETA)](#plugins-beta)
-  - [Official Plugins](#official-plugins)
-  - [Community Plugins](#community-plugins)
-  - [Build a Plugin in 5 Minutes](#build-a-plugin-in-5-minutes)
-  - [Registering Plugins](#registering-plugins)
-  - [Plugin Lifecycle Hooks](#plugin-lifecycle-hooks)
-  - [Context Object](#context-object)
-  - [Custom Exports via Plugins](#custom-exports-via-plugins)
-  - [Example: Overlay Filter Plugin](#example-overlay-filter-plugin)
-  - [Full Plugin Template](#full-plugin-template)
+- [Documentation](#documentation) — full API, Options, Plugins & Cache reference on [snapdom.dev/docs](https://snapdom.dev/docs/)
 - [Limitations](#limitations)
-- [⚡ Performance Benchmarks (Chromium)](#performance-benchmarks)
-  - [Simple elements](#simple-elements)
-  - [Complex elements](#complex-elements)
-  - [Run the benchmarks](#run-the-benchmarks)
-- [Roadmap](#roadmap)
+- [Performance Benchmarks](#performance-benchmarks)
 - [Development](#development)
-- [Contributors 🙌](#contributors)
-- [💖 Sponsors](#sponsors)
-- [Star History](#star-history)
+- [Contributors](#contributors)
+- [Sponsors](#sponsors)
+- [Show your support](#show-your-support)
 - [License](#license)
 
-
-
 ## Installation
 
 ### NPM / Yarn (stable)
@@ -261,579 +191,61 @@ const blob = await snapdom.toBlob(el);
 document.body.appendChild(png);
 ```
 
-## API
+## Documentation
 
-### `snapdom(el, options?)`
+The full reference lives on **[snapdom.dev/docs](https://snapdom.dev/docs/)** — kept there so it stays in sync and searchable:
 
-Returns an object with reusable export methods:
+- **[API reference](https://snapdom.dev/docs/api/)** — the `snapdom()` reusable object, shortcut methods, and exporter-specific options.
+- **[Options](https://snapdom.dev/docs/options/)** — every capture option (`scale`, `dpr`, `embedFonts`, `useProxy`, `exclude`/`filter`, `compress`, `outerTransforms`, `outerShadows`, `cache`…) explained with examples.
+- **[Plugins](https://snapdom.dev/docs/plugins/)** — build, register and ship custom plugins and export formats. Browse community plugins on the [plugins page](https://snapdom.dev/plugins.html).
+- **[Cache & preCache](https://snapdom.dev/docs/cache/)** — control caching between captures and preload resources.
 
-```js
-{
-  url: string;
-  toRaw(): string;
-  toImg(): Promise<HTMLImageElement>; // deprecated 
-  toSvg(): Promise<HTMLImageElement>;
-  toCanvas(): Promise<HTMLCanvasElement>;
-  toBlob(options?): Promise<Blob>;
-  toPng(options?): Promise<HTMLImageElement>;
-  toJpg(options?): Promise<HTMLImageElement>;
-  toWebp(options?): Promise<HTMLImageElement>;
-  download(options?): Promise<void>;
-}
-```
+### API at a glance
 
-### Shortcut methods
+`snapdom(el, options?)` returns a reusable object (`toPng`, `toSvg`, `toCanvas`, `toBlob`, `toJpg`, `toWebp`, `download`, `url`). For single exports, use the shortcuts:
 
-| Method                         | Description                       |
+| Method | Description |
 | ------------------------------ | --------------------------------- |
-| `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.toCanvas(el, options?)` | Returns a `Canvas`              |
 | `snapdom.toBlob(el, options?)` | Returns an SVG or raster `Blob`   |
 | `snapdom.toPng(el, options?)`  | Returns a PNG image               |
 | `snapdom.toJpg(el, options?)`  | Returns a JPG image               |
 | `snapdom.toWebp(el, options?)` | Returns a WebP image              |
-| `snapdom.download(el, options?)` | Triggers a download              |
-
-### Exporter-specific options
+| `snapdom.download(el, options?)` | Triggers a download             |
 
-Some exporters accept a small set of **export-only options** in addition to the global capture options.
+### Options at a glance
 
-#### `download()` 
+All options are optional and can be passed to `snapdom(el, options)` or any shortcut method.
 
 | Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `filename` | `string` | `snapdom` | Download name. |
-| `format` | `"png" \| "jpeg" \| "jpg" \| "webp" \| "svg"` | `"png"` | Output format for the downloaded file. |
-
-**Example:**
-
-```js
-await result.download({
-  format: 'jpg',
-  quality: 0.92,
-  filename: 'my-capture'
-});
-```
-
-#### `toBlob()`
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `type` | `"svg" \| "png" \| "jpeg" \| "jpg" \| "webp"` | `"svg"` | Blob type to generate. |
-
-**Example:**
-
-```js
-const blob = await result.toBlob({ type: 'jpeg', quality: 0.92 });
-```
-
-## Options
-
-All capture methods accept an `options` object:
-
-
-| Option            | Type     | Default  | Description                                     |
-| ----------------- | -------- | -------- | ----------------------------------------------- |
-| `debug`           | boolean  | `false`  | When `true`, logs suppressed errors to `console.warn` for troubleshooting |
-| `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 families/domains/subsets during embedding |
-| `scale`           | number   | `1`      | Output scale multiplier                         |
-| `dpr`             | number   | `devicePixelRatio` | Device pixel ratio                     |
-| `width`           | number   | -        | Output width                                    |
-| `height`          | number   | -        | Output height                                   |
-| `backgroundColor` | string   | `"#fff"` | Fallback color for JPG/WebP                     |
-| `quality`         | number   | `1`      | Quality for JPG/WebP (0 to 1)                   |
-| `useProxy`        | string   | `''`     | Proxy base for CORS fallbacks                   |
-| `exclude`         | string[] | -        | CSS selectors to exclude                        |
-| `excludeMode`     | `"hide"`\|`"remove"` | `"hide"` | How `exclude` is applied                  |
-| `filter`          | function | -        | Custom predicate `(el) => boolean`              |
-| `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 |
-| `outerTransforms`      | boolean  | `true`  | When `false` removes `translate/rotate` but preserves `scale/skew`, producing a flat, reusable capture |
-| `outerShadows`       | boolean  | `false`  | Do not expand the root’s bounding box for shadows/blur/outline, and strip those visual effects from the cloned root |
-| `safariWarmupAttempts` | number   | `3`      | Safari only: iterations to prime font/decode (WebKit #219770). Use `1` if 3 causes lag |
-| `compress`        | boolean  | `true`   | Downsample inlined raster images to their visible resolution. Faster raster captures + smaller SVG output, fidelity-neutral. Set `false` to embed images verbatim |
-
-### debug
-
-When `debug: true`, SnapDOM logs normally suppressed errors to `console.warn` (with the `[snapdom]` prefix). Useful for troubleshooting capture issues (canvas failures, blob resolution, style stripping, etc.) without noisy output in production.
-
-```js
-await snapdom.toPng(el, { debug: true });
-```
-
-### compress
-
-Inlined raster images are embedded at their full natural resolution even when shown in a small box — pixels the output can never display, which only bloat the payload and slow rasterization. With `compress` (on by default) SnapDOM downsamples each oversized raster to (a touch below) the resolution actually visible (`display box × scale × dpr`), preserving aspect ratio and never upscaling. The source codec is kept (PNGs stay lossless), and because the image was already shown far smaller than its natural size the quality loss is imperceptible in practice. Images already at or below their visible size are left untouched. Covers `<img>` (incl. cloned canvas/video), non-repeating CSS `background-image`, and SVG `<image>`.
-
-The benefit depends on the export:
-
-- **Raster** (`toPng` / `toJpg` / `toCanvas` / `toBlob`): **much faster** — the browser decodes/composites small images instead of huge ones. Output size is essentially unchanged (the final bitmap is the same visible pixels).
-- **SVG** (`toSvg` / raw): **much smaller** output — the downsampled images are embedded in the SVG.
-
-It is a no-op for images already shown at (or below) their natural resolution, so the common case pays virtually nothing. Pass `compress: false` to embed images verbatim (e.g. if you intend to scale the SVG up later).
-
-```js
-// default: images downsampled to visible resolution
-await snapdom.toPng(el);
-
-// keep images at full resolution
-await snapdom.toPng(el, { compress: false });
-```
-
-### 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.toSvg(element, {
-  fallbackURL: '/images/fallback.png'
-});
-
-// 2) Dynamic placeholder via callback
-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.toSvg(element, {
-  fallbackURL: ({ width = 300, height = 150 }) =>
-    `https://dummyimage.com/${width}x${height}/cccccc/666.png&text=img`,
-  useProxy: 'https://proxy.corsfix.com/?'
-});
-```
-
-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`)
-
-* If `scale` is provided, it **takes precedence** over `width`/`height`.
-* If only `width` is provided, height scales proportionally (and vice versa).
-* Providing both `width` and `height` forces an exact size (may distort).
-
-### Cross-Origin Images & Fonts (`useProxy`)
-
-By default snapDOM tries `crossOrigin="anonymous"` (or `use-credentials` for same-origin). If an asset is CORS-blocked, you can set `useProxy` to a prefix URL that forwards the actual `src`:
-
-```js
-await snapdom.toPng(el, {
-  useProxy: 'https://proxy.corsfix.com/?' // Note: Any cors proxy could be used 'https://proxy.corsfix.com/?'
-});
-```
-
-
-* The proxy is only used as a **fallback**; same-origin and CORS-enabled assets skip it.
-
-### Fonts
-
-#### `embedFonts`
-When `true`, snapDOM embeds **non-icon** `@font-face` rules detected as used within the captured subtree. Icon fonts (Font Awesome, Material Icons, etc.) are embedded **always**.
-
-#### `localFonts`
-If you serve fonts yourself or have data URLs, you can declare them here to avoid extra CSS discovery:
-
-```js
-await snapdom.toPng(el, {
-  embedFonts: true,
-  localFonts: [
-    { family: 'Inter', src: '/fonts/Inter-Variable.woff2', weight: 400, style: 'normal' },
-    { family: 'Inter', src: '/fonts/Inter-Italic.woff2', style: 'italic' }
-  ]
-});
-```
-
-#### `iconFonts`
-Add custom icon families (names or regex matchers). Useful for private icon sets:
-
-```js
-await snapdom.toPng(el, {
-  iconFonts: ['MyIcons', /^(Remix|Feather) Icons?$/i]
-});
-```
-
-#### `excludeFonts`
-Skip specific non-icon fonts to speed up capture or avoid unnecessary downloads.
-
-```js
-await snapdom.toPng(el, {
-  embedFonts: true,
-  excludeFonts: {
-    families: ['Noto Serif', 'SomeHeavyFont'],     // skip by family name
-    domains: ['fonts.gstatic.com', 'cdn.example'], // skip by source host
-    subsets: ['cyrillic-ext']                      // skip by unicode-range subset tag
-  }
-});
-```
-*Notes*
-- `excludeFonts` only applies to **non-icon** fonts. Icon fonts are always embedded.
-- Matching is case-insensitive for `families`. Hosts are matched by substring against the resolved URL.
-
-
-#### 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.
-* `filter`: advanced predicate per element (return `false` to drop).
-* `filterMode`: `hide` applies `visibility:hidden` CSS rule on filtered nodes and the layout remains as the original. `remove` do not clone filtered nodes at all.
-
-**Example: filter out elements with `display:none`:**
-```js
-/**
- * Example filter: skip elements with display:none
- * @param {Element} el
- * @returns {boolean} true = keep, false = exclude
- */
-function filterHidden(el) {
-  const cs = window.getComputedStyle(el);
-  if (cs.display === 'none') return false;
-  return true;
-}
-
-await snapdom.toPng(document.body, { filter: filterHidden });
-```
-
-**Example with `exclude`:** remove banners or tooltips by selector
-```js
-await snapdom.toPng(el, {
-  exclude: ['.cookie-banner', '.tooltip', '[data-test="debug"]']
-});
-```
-
-### outerTransforms 
-
-When capturing rotated or translated elements, you may want use **outerTransforms: false** option if you want to eliminate those external transforms. So, the output is **flat, upright, and ready** to use elsewhere.
-
-- **`outerTransforms: true (default)`**  
-  **Keeps the original `transforms` and `rotate`**.  
-  
-
-### outerShadows
-- **`outerShadows: false (default)`**  
-  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 (`outerTransforms: false` + `outerShadows: false`) produces a strict, minimal bounding box with no visual bleed.
-
-**Example**
-
-```js
-// outerTransforms and remove shadow bleed
-await snapdom.toSvg(el, { outerTransforms: true, outerShadows: true });
-```
-
-## 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:
-
-| Mode        | Description                                                                 |
-| ----------- | --------------------------------------------------------------------------- |
-| `"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)                  |
-
-**Examples:**
-
-```js
-// Use minimal but fast cache
-await snapdom.toPng(el, { cache: 'auto' });
-
-// Keep everything in memory between captures
-await snapdom.toPng(el, { cache: 'full' });
-
-// Force a full cleanup on every capture
-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/?'
-});
-```
-
-## Plugins (BETA)
-
-SnapDOM includes a lightweight **plugin system** that allows you to extend or override behavior at any stage of the capture and export process — without touching the core library.
-
-A plugin is a simple object with a unique `name` and one or more lifecycle **hooks**.
-Hooks can be synchronous or `async`, and they receive a shared **`context`** object.
-
-### Official Plugins
-
-Install the official plugin package:
-
-```bash
-npm install @zumer/snapdom-plugins
-```
-
-```js
-import { filter } from '@zumer/snapdom-plugins/filter';
-import { timestampOverlay } from '@zumer/snapdom-plugins/timestamp-overlay';
-```
-
-| Plugin | Category | Description |
-|--------|----------|-------------|
-| `picture-resolver` | Capture | Resolves lazy-loaded `<picture>` placeholders. Detects base64 stubs and fetches the real image before capture. |
-| `timestamp-overlay` | Transform | Adds a configurable timestamp label on the captured clone. Supports multiple date formats and positions. |
-| `filter` | Transform | Applies CSS filter effects to captures. Ships with presets: `grayscale`, `sepia`, `blur`, `vintage`, `dramatic`. |
-| `replace-text` | Transform | Find-and-replace text in the captured clone. Supports strings and regex patterns. |
-| `color-tint` | Transform | Tints the entire capture to a specified color using an overlay with `mix-blend-mode`. |
-| `ascii-export` | Export | Adds a `toAscii()` method that converts captures to ASCII art. Configurable width, charset, and luminance. |
-| `pdf-image` | Export | Exports the capture as a PNG embedded in a downloadable PDF. Supports portrait and landscape orientations. |
-| `html-in-canvas` | Export | Uses the experimental WICG `drawElementImage` API for direct DOM-to-canvas rendering where supported. |
-| `prompt-export` | Export | LLM-friendly capture: adds a `toPrompt()` method that returns an annotated screenshot, structured element map with bounding boxes, and a pre-formatted text prompt. |
-
-### Community Plugins
-
-Community plugins are listed on the [Plugins page](https://zumerlab.github.io/snapdom/plugins.html). To submit your plugin, open a PR adding one line to `community-plugins.md`. See [CONTRIBUTING_PLUGINS.md](CONTRIBUTING_PLUGINS.md).
-
-### Build a Plugin in 5 Minutes
-
-SnapDOM's hook system gives you full control over every stage of the capture pipeline:
-
-1. **Clone the template** — `npx degit zumerlab/snapdom/packages/plugin-template my-plugin`
-2. **Write your hook logic** — `export function myPlugin() {}`
-3. **Get listed** — open a PR adding one line to `community-plugins.md`
-
-See [PLUGIN_SPEC.md](PLUGIN_SPEC.md) for the full specification and [CONTRIBUTING_PLUGINS.md](CONTRIBUTING_PLUGINS.md) for submission guidelines.
-
-### Registering Plugins
-
-**Global registration** (applies to all captures):
-
-```js
-import { snapdom } from '@zumer/snapdom';
-
-// You can register instances, factories, or [factory, options]
-snapdom.plugins(
-  myPluginInstance,
-  [myPluginFactory, { optionA: true }],
-  { plugin: anotherFactory, options: { level: 2 } }
-);
-```
-
-**Per-capture registration** (only for that specific call):
-
-```js
-const out = await snapdom(element, {
-  plugins: [
-    [overlayFilterPlugin, { color: 'rgba(0,0,0,0.25)' }],
-    [myFullPlugin, { providePdf: true }]
-  ]
-});
-```
-
-* **Execution order = registration order** (first registered, first executed).
-* **Per-capture plugins** run **before** global ones.
-* Duplicates are automatically skipped by `name`; a per-capture plugin with the same `name` overrides its global version.
-
-### Plugin Lifecycle Hooks
-
-Hooks run in capture order (see [Capture Flow](#capture-flow)):
-
-| Hook | Stage | Purpose |
-|------|-------|---------|
-| `beforeSnap` | Start | Adjust options before any work. |
-| `beforeClone` | Pre-clone | Before DOM clone (modify live DOM carefully). |
-| `afterClone` | Post-clone | Modify cloned tree safely (e.g. inject overlay). |
-| `beforeRender` | Pre-serialize | Right before SVG → data URL. |
-| `afterRender` | Post-serialize | Inspect `context.svgString` / `context.dataURL`. |
-| `beforeExport` | Per export | Before each `toPng`, `toSvg`, etc. |
-| `afterExport` | Per export | Transform returned result. |
-| `afterSnap` | Once | After first export; cleanup. |
-| `defineExports` | Setup | Add custom exporters (e.g. `toPdf`). |
-
-> Returned values from `afterExport` are chained to the next plugin (transform pipeline).
-
-### Context Object
-
-Every hook receives a single `context` object that contains normalized capture state:
-
-* **Input & options:**
-  `element`, `debug`, `fast`, `scale`, `dpr`, `width`, `height`, `backgroundColor`, `quality`, `useProxy`, `cache`, `outerTransforms`, `outerShadows`, `safariWarmupAttempts`, `compress`, `embedFonts`, `localFonts`, `iconFonts`, `excludeFonts`, `exclude`, `excludeMode`, `filter`, `filterMode`, `fallbackURL`.
-
-* **Intermediate values (depending on stage):**
-  `clone`, `classCSS`, `styleCache`, `fontsCSS`, `baseCSS`, `svgString`, `dataURL`.
-
-* **During export:**
-  `context.export = { type, options, url }`
-  where `type` is the exporter name (`"png"`, `"jpeg"`, `"svg"`, `"blob"`, etc.), and `url` is the serialized SVG base.
-
-> You may safely modify `context` (e.g., override `backgroundColor` or `quality`) — but do so early (`beforeSnap`) for global effects or in `beforeExport` for single-export changes.
-
-
-## Custom Exports via Plugins
-
-Plugins can add new exports using `defineExports(context)`.
-For each export key you return (e.g., `"pdf"`), SnapDOM automatically exposes a helper method named **`toPdf()`** on the capture result.
-
-**Register the plugin (global or per capture):**
-
-```js
-import { snapdom } from '@zumer/snapdom';
-
-// global
-snapdom.plugins(pdfExportPlugin());
-
-// or per capture
-const out = await snapdom(element, { plugins: [pdfExportPlugin()] });
-```
-
-**Call the custom export:**
-
-```js
-const out = await snapdom(document.querySelector('#report'));
-
-// because the plugin returns { pdf: async (ctx, opts) => ... }
-const pdfBlob = await out.toPdf({
-  // exporter-specific options (width, height, quality, filename, etc.)
-});
-```
-
-### Example: Overlay Filter Plugin
-
-Adds a translucent overlay or color filter **only** to the captured clone (not your live DOM).
-Useful for highlighting or dimming sections before export.
-
-```js
-/**
- * Ultra-simple overlay filter for SnapDOM (HTML-only).
- * Inserts a full-size <div> overlay on the cloned root.
- *
- * @param {{ color?: string; blur?: number }} [options]
- *   color: overlay color (rgba/hex/hsl). Default: 'rgba(0,0,0,0.25)'
- *   blur: optional blur in px (default: 0)
- */
-export function overlayFilterPlugin(options = {}) {
-  const color = options.color ?? 'rgba(0,0,0,0.25)';
-  const blur = Math.max(0, options.blur ?? 0);
-
-  return {
-    name: 'overlay-filter',
-
-    /**
-     * Add a full-coverage overlay to the cloned HTML root.
-     * @param {any} context
-     */
-    async afterClone(context) {
-      const root = context.clone;
-      if (!(root instanceof HTMLElement)) return; // HTML-only
-
-      // Ensure containing block so absolute overlay anchors to the root
-      if (getComputedStyle(root).position === 'static') {
-        root.style.position = 'relative';
-      }
-
-      const overlay = document.createElement('div');
-      overlay.style.position = 'absolute';
-      overlay.style.left = '0';
-      overlay.style.top = '0';
-      overlay.style.right = '0';
-      overlay.style.bottom = '0';
-      overlay.style.background = color;
-      overlay.style.pointerEvents = 'none';
-      if (blur) overlay.style.filter = `blur(${blur}px)`;
-
-      root.appendChild(overlay);
-    }
-  };
-}
-
-```
-
-**Usage:**
-
-```js
-import { snapdom } from '@zumer/snapdom';
-
-// Global registration
-snapdom.plugins([overlayFilterPlugin, { color: 'rgba(0,0,0,0.3)', blur: 2 }]);
-
-// Per-capture
-const out = await snapdom(document.querySelector('#card'), {
-  plugins: [[overlayFilterPlugin, { color: 'rgba(255,200,0,0.15)' }]]
-});
-
-const png = await out.toPng();
-document.body.appendChild(png);
-```
-
-> The overlay is injected **only in the cloned tree**, never in your live DOM, ensuring perfect fidelity and zero flicker.
-
-
-### Full Plugin Template
-
-Use this as a starting point for custom logic or exporters.
-
-```js
-export function myPlugin(options = {}) {
-  return {
-    /** Unique name used for de-duplication/overrides */
-    name: 'my-plugin',
-
-    /** Early adjustments before any clone/style work. */
-    async beforeSnap(context) {},
-
-    /** Before subtree cloning (use sparingly if touching the live DOM). */
-    async beforeClone(context) {},
-
-    /** After subtree cloning (safe to modify the cloned tree). */
-    async afterClone(context) {},
-
-    /** Right before serialization (SVG/dataURL). */
-    async beforeRender(context) {},
-
-    /** After serialization; inspect context.svgString/context.dataURL if needed. */
-    async afterRender(context) {},
-
-    /** Before EACH export call (toPng/toSvg/toBlob/...). */
-    async beforeExport(context) {},
-
-    /**
-     * After EACH export call.
-     * If you return a value, it becomes the result for the next plugin (chaining).
-     */
-    async afterExport(context, result) { return result; },
-
-    /**
-     * Define custom exporters (auto-added as helpers like out.toPdf()).
-     * Return a map { [key: string]: (ctx:any, opts:any) => Promise<any> }.
-     */
-    async defineExports(context) { return {}; },
-
-    /** Runs ONCE after the FIRST export finishes (cleanup). */
-    async afterSnap(context) {}
-  };
-}
-```
-
-**Quick recap:**
-
-* Plugins can modify capture behavior (`beforeSnap`, `afterClone`, etc.).
-* You can inject visuals or transformations safely into the cloned tree.
-* New exporters defined in `defineExports()` automatically become helpers like `out.toPdf()`.
-* All hooks can be asynchronous, run in order, and share the same `context`.
-
+| ------ | ---- | ------- | ----------- |
+| `scale` | `number` | `1` | Output scale multiplier |
+| `dpr` | `number` | `devicePixelRatio` | Pixel density of the rasterized output |
+| `width` / `height` | `number` | `null` | Target output size (keeps aspect ratio if only one is set) |
+| `backgroundColor` | `string` | `null` (`#ffffff` for JPEG/WebP) | Background fill |
+| `quality` | `number` | `0.92` | JPEG/WebP quality (0–1) |
+| `format` | `'png' \| 'jpeg' \| 'webp' \| 'svg'` | `'png'` | Format for `download()` |
+| `type` | `string` | `'svg'` | Blob type for `toBlob()` (`'png'`, `'jpeg'`…) |
+| `filename` | `string` | `'snapDOM'` | Download filename |
+| `embedFonts` | `boolean` | `false` | Inline `@font-face` so text renders with your real fonts |
+| `iconFonts` | `string \| RegExp \| array` | `[]` | Icon font families (always embedded) |
+| `localFonts` | `array` | `[]` | Explicit fonts: `{ family, src, weight?, style? }` |
+| `excludeFonts` | `object` | — | Skip fonts by family / domain / subset |
+| `exclude` | `string[]` | `[]` | CSS selectors to leave out of the capture |
+| `filter` | `(el) => boolean` | `null` | Keep-predicate (return `false` to drop a node) |
+| `excludeMode` / `filterMode` | `'hide' \| 'remove'` | `'hide'` | How excluded nodes are handled |
+| `clip` | `'viewport' \| {x, y, width, height}` | `null` | Capture only a region; offscreen content is pruned |
+| `compress` | `boolean` | `true` | Downsample inlined images to their visible resolution |
+| `useProxy` | `string` | `''` | CORS proxy prefix for cross-origin images |
+| `fallbackURL` | `string \| fn` | — | Fallback image for broken `<img>` |
+| `cache` | `'soft' \| 'auto' \| 'full' \| 'disabled'` | `'soft'` | Cache policy between captures |
+| `outerTransforms` | `boolean` | `true` | Keep root translate/rotate in the output |
+| `outerShadows` | `boolean` | `false` | Expand bounds to include root shadows/blur/outline |
+| `fast` | `boolean` | `true` | Skip idle delays for faster capture |
+| `plugins` | `array` | — | Per-capture plugins (override globals by name) |
+
+📖 **[Full API & every option, explained with examples → snapdom.dev/docs](https://snapdom.dev/docs/)**
 
 ## Limitations
 
@@ -881,35 +293,6 @@ npm run test:benchmark
 ```
 
 
-## Roadmap
-
-Planned improvements for future versions of SnapDOM:
-
-* [X] **Implement plugin system**
-  SnapDOM will support external plugins to extend or override internal behavior (e.g. custom node transformers, exporters, or filters).
-
-* [ ] **Refactor to modular architecture**
-  Internal logic will be split into smaller, focused modules to improve maintainability and code reuse.
-
-* [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)
-
-* [X] **Expose cache control**
-  Users will be able to manually clear image and font caches or configure their own caching strategies.
-
-* [X] **Auto font preloading**
-  Required fonts will be automatically detected and preloaded before capture, reducing the need for manual `preCache()` calls.
-
-* [X] **Document plugin development**
-  A full guide will be provided for creating and registering custom SnapDOM plugins.
-
-* [ ] **Make export utilities tree-shakeable**
-  Export functions like `toPng`, `toJpg`, `toBlob`, etc. will be restructured into independent modules to support tree shaking and minimal builds.
-
-Have ideas or feature requests?
-Feel free to share suggestions or feedback in [GitHub Discussions](https://github.com/zumerlab/snapdom/discussions).
-
-
 ## Development
 
 **Source layout:**
@@ -952,6 +335,7 @@ For detailed guidelines, see [CONTRIBUTING](https://github.com/zumerlab/snapdom/
 <a href="https://github.com/airamhr9" title="airamhr9"><img src="https://avatars.githubusercontent.com/u/57371081?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="airamhr9"/></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/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/mosuzi" title="mosuzi"><img src="https://avatars.githubusercontent.com/u/43341701?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="mosuzi"/></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>
@@ -967,9 +351,8 @@ For detailed guidelines, see [CONTRIBUTING](https://github.com/zumerlab/snapdom/
 <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/ZiuChen" title="ZiuChen"><img src="https://avatars.githubusercontent.com/u/64892985?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="ZiuChen"/></a>
+<a href="https://github.com/adajoy" title="adajoy"><img src="https://avatars.githubusercontent.com/u/26210079?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="adajoy"/></a>
 <a href="https://github.com/harshasiddartha" title="harshasiddartha"><img src="https://avatars.githubusercontent.com/u/147021873?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="harshasiddartha"/></a>
-<a href="https://github.com/karasHou" title="karasHou"><img src="https://avatars.githubusercontent.com/u/27048083?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="karasHou"/></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 -->
 
@@ -979,9 +362,34 @@ Special thanks to [@megaphonecolin](https://github.com/megaphonecolin), [@sdrape
 
 If you'd like to support this project too, you can [become a sponsor](https://github.com/sponsors/tinchox5).
 
-## Star History
+## Show your support
+
+If SnapDOM saved you time, a ⭐ on GitHub helps other developers find it — that's the whole ask.
+
+Shipping something built with SnapDOM? Add the badge to your README:
+
+[![Built with SnapDOM](https://img.shields.io/badge/built%20with-SnapDOM-blue)](https://snapdom.dev)
+
+```md
+[![Built with SnapDOM](https://img.shields.io/badge/built%20with-SnapDOM-blue)](https://snapdom.dev)
+```
+
+### Projects using SnapDOM
+
+SnapDOM runs in production across 290+ public repositories ([GitHub dependents graph](https://github.com/zumerlab/snapdom/network/dependents)). A few notable ones, each verified from its own `package.json`:
+
+- [LobeHub](https://github.com/lobehub/lobehub) — platform for operating AI agents
+- [Trilium Notes](https://github.com/TriliumNext/Trilium) — hierarchical personal knowledge base
+- [Sealos](https://github.com/labring/sealos) — AI-native cloud operating system
+- [Tencent tmagic-editor](https://github.com/Tencent/tmagic-editor) — low-code page editor
+- [Playroom](https://github.com/seek-oss/playroom) — JSX design tool by SEEK
+- [GPT-Vis](https://github.com/antvis/GPT-Vis) — AI-friendly data viz by Ant Group's AntV
+- [Rabby Wallet](https://github.com/RabbyHub/Rabby) — browser wallet for EVM chains
+- [uMap](https://github.com/umap-project/umap) — OpenStreetMap map builder
+- [ListenBrainz](https://github.com/metabrainz/listenbrainz-server) — music tracker by MetaBrainz
+- [SnapDIFF](https://zumerlab.com/snapdiff/) — in-browser visual regression testing *(by Zumerlab)*
 
-[![Star History Chart](https://api.star-history.com/svg?repos=zumerlab/snapdom&type=Date)](https://www.star-history.com/#zumerlab/snapdom&Date)
+See the full gallery at **[snapdom.dev/made-with](https://snapdom.dev/made-with/)**. Shipping SnapDOM? [Open a PR](https://github.com/zumerlab/snapdom/pulls) to add your project — real, verifiable projects only.
 
 ## License