@zumer/snapdom 2.16.0 → 2.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom",
-  "version": "2.16.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,9 +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 && 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",
@@ -82,10 +88,14 @@
     "@eslint/js": "^9.36.0",
     "@vitest/browser": "^3.1.2",
     "@vitest/coverage-v8": "^3.1.2",
-    "@zumer/snapdiff": "^0.1.1",
+    "@zumer/snapdiff": "^0.2.2",
     "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

@@ -1,11 +1,11 @@
 /**
  * snapDOM – ultra-fast DOM-to-image capture
- * TypeScript definitions (v1.9.14)
+ * TypeScript definitions (v2.16)
  *
  * Notes:
  * - Style compression is internal (no public option).
  * - Icon fonts are always embedded; `embedFonts` controls non-icon fonts only.
- * - This file preserves backward compatibility with earlier 1.9.x defs.
+ * - This file preserves backward compatibility with earlier defs.
  */
 
 /* =========================
@@ -27,6 +27,8 @@ export interface LocalFont {
   src: string;            // URL or data: URL
   weight?: string | number;
   style?: string;
+  /** font-stretch as a percentage (e.g. 100). Default 100. */
+  stretchPct?: number;
 }
 
 export interface ExcludeFonts {
@@ -54,9 +56,9 @@ export interface SnapdomOptions {
   /** Target height of the export (keeps aspect if only one dimension is provided). */
   height?: number;
 
-  /** Background fallback color (used esp. for JPEG). Default "#fff". */
+  /** Background fallback color. Default: `"#ffffff"` for JPEG/WebP, `null` (transparent) otherwise. */
   backgroundColor?: string;
-  /** Quality for JPEG/WebP (0..1). Default 1. */
+  /** Quality for JPEG/WebP (0..1). Default 0.92. */
   quality?: number;
   /** Output format for capture/export helpers. Default "png". */
   format?: BlobType;
@@ -80,18 +82,50 @@ 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). Opt-in; off by default — output is
-   * byte-identical to omitting it.
+   * preserving the source codec (lossless PNG stays lossless). On by default; pass `false`
+   * to embed images verbatim.
    */
   compress?: boolean;
 
@@ -103,6 +137,23 @@ export interface SnapdomOptions {
   iconFonts?: IconFontMatcher | IconFontMatcher[];
   /** Skip specific non-icon fonts (by family/domain/subset). */
   excludeFonts?: ExcludeFonts;
+  /** Extra domains allowed for cross-origin font stylesheet fetches (e.g. self-hosted CDNs). */
+  fontStylesheetDomains?: string[];
+
+  /**
+   * Skip style properties when snapshotting computed styles (e.g. `/^--/` to exclude
+   * CSS variables on pages with thousands of custom props).
+   */
+  excludeStyleProps?: RegExp | ((prop: string) => boolean);
+
+  /** Safari warmup iterations for WebKit #219770 (1..3). Default 3. */
+  safariWarmupAttempts?: number;
+
+  /** Verbose diagnostics via console.warn. Default false. */
+  debug?: boolean;
+
+  /** Default filename (without extension) for download(). Default "snapDOM". */
+  filename?: string;
 
   /**
    * Fallback image when <img> fails to load.
@@ -205,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>;
 }
@@ -245,6 +306,12 @@ export interface CaptureResult {
   /** Canonical data URL of the SVG snapshot (when available). */
   url: string;
 
+  /** Returns the raw SVG data URL (same as `url`). */
+  toRaw(): string;
+
+  /** Run any registered export by name (core or plugin), e.g. `to("png")`. */
+  to(type: string, options?: any): Promise<any>;
+
   /**
    * @deprecated Use `toSvg()` for an <img> that renders the SVG snapshot.
    * Historical alias kept for compatibility.
@@ -301,6 +368,12 @@ export declare namespace snapdom {
 
   /** Shortcut helpers that run a one-off capture+export. */
 
+  /** Returns the raw SVG data URL of a one-off capture. */
+  function toRaw(
+    element: Element,
+    options?: SnapdomOptions
+  ): Promise<string>;
+
   /** @deprecated Returns an SVG <img>; prefer `toSvg`. */
   function toImg(
     element: Element,
@@ -327,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