@zumer/snapdom 2.18.0 → 2.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom",
-  "version": "2.18.0",
+  "version": "2.22.0",
   "description": "Fast, modern alternative to html2canvas — captures HTML elements to images (PNG, JPG, SVG, WebP) with exceptional speed and accuracy.",
   "type": "module",
   "main": "./dist/snapdom.js",
@@ -33,13 +33,15 @@
     "compile": "node esbuild.config.mjs",
     "lint": "eslint src __tests__ --ext .js",
     "lint:fix": "eslint src __tests__ --ext .js --fix",
-    "test": "npm run lint:fix && npx vitest run --browser.headless --reporter=verbose",
+    "test:types": "tsc --noEmit",
+    "test": "npm run lint:fix && npm run test:types && npx vitest run --browser.headless --reporter=verbose",
     "test:firefox": "BROWSER=firefox npx vitest run --browser.headless --reporter=verbose",
     "test:webkit": "BROWSER=webkit npx vitest run --browser.headless --reporter=verbose",
-    "test:full": "npm run lint:fix && BROWSER=all npx vitest run --browser.headless --reporter=verbose",
+    "test:full": "npm run lint:fix && npm run test:types && BROWSER=all npx vitest run --browser.headless --reporter=verbose",
     "report:cross": "node scripts/cross-report.mjs",
     "test:coverage": "npx vitest run --browser.headless --coverage",
     "test:benchmark": "npx vitest bench --browser.headless --watch=false",
+    "site": "npm run compile && node scripts/serve-site.mjs",
     "bump:dry": "npx @zumerbox/bump -d",
     "bump": "npx @zumerbox/bump && npx @zumerbox/changelog",
     "build": "npm run compile && npm pack",
@@ -90,7 +92,8 @@
     "esbuild": "^0.28.1",
     "eslint": "^9.36.0",
     "globals": "^16.4.0",
-    "playwright": "^1.52.0"
+    "playwright": "^1.52.0",
+    "typescript": "^7.0.2"
   },
   "overrides": {
     "vite": "^6"

package/types/snapdom.d.ts

@@ -82,14 +82,46 @@ export interface SnapdomOptions {
   /** How to apply `filter` ("hide" or "remove"). Default "hide". */
   filterMode?: "hide" | "remove";
 
-  /** outerTransforms the root: remove translate/rotate, keep scale/skew. */
+  /**
+   * Layout reconciliation: mount the styled clone in-document once, compare every node's
+   * box against the live DOM and pin only diverging sizes. Measurement over heuristics.
+   * Opt-in (adds one in-document layout of the clone). Default false.
+   */
+  reconcile?: boolean;
+
+  /**
+   * Memoizes repeated captures of this element: a scoped MutationObserver marks it dirty on
+   * external change, and an unchanged repeat capture returns the cached result without
+   * re-running the pipeline. Opt-in — costs a persistent observer per element. Without it,
+   * snapdom warns once (console.warn) if the same element is captured 3+ times within 2s.
+   * Default false.
+   */
+  burst?: boolean;
+
+  /**
+   * With `burst: true`, forces a fresh capture on this call for changes the automatic
+   * MutationObserver tracking can't see: canvas pixel draws, programmatic CSSOM edits
+   * (stylesheet.insertRule/deleteRule, cssRule.style.* on a rule rather than an element).
+   * Ignored without `burst: true`. Default false.
+   */
+  invalidate?: boolean;
+
+  /** outerTransforms the root: remove translate/rotate, keep scale/skew. Default true. */
   outerTransforms?: boolean;
   /**
-   * Do not expand root bbox for shadows/blur/outline; also strip shadows/outline
-   * from the cloned root to get a tight capture box.
+   * Expand root bbox for shadows/blur/outline instead of stripping them from the
+   * cloned root. Default false (root shadows/outline are stripped, blur bleed is
+   * still included).
    */
   outerShadows?: boolean;
 
+  /**
+   * Capture only a region instead of the full element: `'viewport'` (what the user
+   * currently sees) or a page-coordinate rect. Offscreen subtrees are pruned before
+   * styling/inlining, so this is faster than a full capture. Default null (no clip).
+   */
+  clip?: "viewport" | { x: number; y: number; width: number; height: number } | null;
+
   /**
    * Downsample inlined raster images to their visible resolution (display box × scale × dpr),
    * preserving the source codec (lossless PNG stays lossless). On by default; pass `false`
@@ -224,6 +256,16 @@ export interface SnapdomPlugin {
    */
   defineExports?(context: CaptureContext): ExportMap | Promise<ExportMap>;
 
+  /**
+   * Per-node hook, called for every element while the clone is built (after exclude/filter,
+   * before built-in iframe/canvas/video/audio handling). First plugin returning a value wins:
+   * - Node → used as the finished clone for that node (mapped to source, box styles applied)
+   * - null → skip the node entirely
+   * - undefined → continue with the normal pipeline
+   * Runs on every node: keep checks cheap.
+   */
+  resolveNode?(node: Element, context: CaptureContext): Node | null | undefined | Promise<Node | null | undefined>;
+
   /** Runs ONCE after the FIRST successful export of this capture (good for cleanup). */
   afterSnap?(context: CaptureContext): void | Promise<void>;
 }
@@ -358,12 +400,6 @@ export declare namespace snapdom {
     options?: SnapdomOptions
   ): Promise<HTMLImageElement>;
 
-  function toJpeg(
-    element: Element,
-    options?: SnapdomOptions
-  ): Promise<HTMLImageElement>;
-
-  /** Alias for `toJpeg`. */
   function toJpg(
     element: Element,
     options?: SnapdomOptions