zumerlab
diff --git a/‎README.md‎
Lines changed: 230 additions & 1 deletion b/‎README.md‎
Lines changed: 230 additions & 1 deletion
@@ -76,6 +76,13 @@ It captures any HTML element as a scalable SVG image, preserving styles, fonts,
  - [noShadows](#no-shadows)
  - [Cache control](#cache-control)
 - [preCache](#precache--optional-helper)
+- [Plugins (BETA)](#plugins-beta)
+ - [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)
 - [Limitations](#limitations)
 - [⚡ Performance Benchmarks (Chromium)](#performance-benchmarks)
  - [Simple elements](#simple-elements)
@@ -409,6 +416,229 @@ await preCache({
 });
 ```
 
+## 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.
+
+### 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
+
+| Hook                           | Purpose                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `beforeSnap(context)`          | Before any clone/style work. Ideal for adjusting global capture options.             |
+| `beforeClone(context)`         | Before DOM cloning. Can modify live DOM (use carefully).                             |
+| `afterClone(context)`          | After the element subtree has been cloned. Safe to modify styles in the cloned tree. |
+| `beforeRender(context)`        | Right before SVG/dataURL serialization.                                              |
+| `afterRender(context)`         | After serialization (you can inspect `context.svgString` or `context.dataURL`).      |
+| `beforeExport(context)`        | Before each export call (`toPng`, `toSvg`, etc.).                                    |
+| `afterExport(context, result)` | After each export call — can transform the returned result.                          |
+| `afterSnap(context)`           | Runs **once**, after the **first export** finishes. Perfect for cleanup.             |
+| `defineExports(context)`       | Returns a map of **custom exporters**, e.g. `{ pdf: async (ctx, opts) => Blob }`.    |
+
+> 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`, `straighten`, `noShadows`, `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`.
+
+
 ## Limitations
 
 * External images should be CORS-accessible (use `useProxy` option for handling CORS denied)
@@ -431,7 +661,6 @@ Values are **average capture time (ms)** → lower is better.
 | 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