html2canvas-pro 2.5.4 → 2.6.1

package/dist/types/core/validator.d.ts

@@ -22,7 +22,8 @@ export interface ValidatorConfig {
      */
     allowedProxyDomains?: string[];
     /**
-     * Allow localhost/127.0.0.1 as proxy URL. Only set for development or test (e.g. Karma reftests).
+     * Allow localhost/127.0.0.1 as proxy URL. Only set for development or test
+     * (e.g. the Playwright reftest runner, which proxies through localhost).
      * @default false
      */
     allowLocalhostProxy?: boolean;
@@ -81,6 +82,13 @@ export declare class Validator {
      * @returns Validation result
      */
     validateCspNonce(nonce: string): ValidationResult;
+    /**
+     * Validate the backgroundColor option
+     *
+     * @param backgroundColor - CSS color string or null (transparent)
+     * @returns Validation result
+     */
+    validateBackgroundColor(backgroundColor: unknown): ValidationResult;
     /**
      * Validate image timeout
      *

package/dist/types/dom/document-cloner.d.ts

@@ -42,6 +42,13 @@ export declare class DocumentCloner {
      * the other stylesheet-cloning paths.
      */
     private appendDocumentAdoptedStyles;
+    /**
+     * Add the rules that hide the source ::before / ::after (the clone draws
+     * them as surrogate elements) to the clone's <head>. Inside <body> the
+     * <style> would be one of its children, and `body > :first-child`,
+     * `:nth-child()` and sibling selectors would match the wrong elements.
+     */
+    private appendPseudoHideStyles;
     toIFrame(ownerDocument: Document, windowSize: Bounds): Promise<HTMLIFrameElement>;
     createElementClone<T extends HTMLElement | SVGElement>(node: T): HTMLElement | SVGElement;
     createCustomElementClone(originalNode: HTMLElement, clonedNode: HTMLElement): HTMLElement;

package/dist/types/dom/element-container.d.ts

@@ -2,6 +2,7 @@ import { CSSParsedDeclaration } from '../css/index';
 import { TextContainer } from './text-container';
 import { Bounds } from '../css/layout/bounds';
 import { Context } from '../core/context';
+import { FilterReferences } from './filter-reference';
 export interface ElementContainerOptions {
     normalizeDom?: boolean;
 }
@@ -17,6 +18,11 @@ export declare class ElementContainer {
      * bounds to leave a matching gap (issue #227).
      */
     readonly legendBounds?: Bounds;
+    /**
+     * Same-document `filter: url(#id)` references, resolved while the cloned
+     * DOM is available. The surface compositor renders them in an SVG pass.
+     */
+    readonly filterReferences?: FilterReferences;
     createsStackingContext: boolean;
     createsRealStackingContext: boolean;
     isListOwner: boolean;

package/dist/types/dom/filter-reference.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CSS `filter: url(#id)` references for the surface compositor.
+ *
+ * The referenced <filter> is resolved while the cloned DOM is still available
+ * and copied into a detached, self-contained form: its region is converted to
+ * user space around the element's border box, and presentation properties a
+ * stylesheet may set are inlined. The copy is later serialized into an SVG
+ * image together with the composited surface, so it must not depend on the
+ * document it came from.
+ */
+export interface FilterRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FilterReference {
+    /** Detached copy with a userSpaceOnUse region relative to the border box. */
+    readonly element: SVGFilterElement;
+    readonly region: FilterRegion;
+    /** How far (CSS px) the filter region reaches beyond the border box. */
+    readonly outset: number;
+}
+export type FilterReferences = ReadonlyMap<string, FilterReference>;
+/** The `#id` of a same-document url() body (`"#id"`, `'#id'` or `#id`), or null. */
+export declare const parseFilterReference: (body: string) => string | null;
+/**
+ * Resolve every same-document url() reference of a computed filter value.
+ * References that cannot be expressed in the serialized SVG are left out, so
+ * the compositor rejects the chain and the subtree keeps the legacy renderer.
+ */
+export declare function resolveFilterReferences(element: Element, filter: string | null, box: {
+    width: number;
+    height: number;
+}): FilterReferences | undefined;

package/dist/types/dom/iframe-mount.d.ts

@@ -64,7 +64,7 @@ export declare const createIFrameContainer: (ownerDocument: Document, bounds: Bo
  */
 export declare const stylesheetsReady: (documentClone: Document, logger?: {
     warn: (msg: string) => void;
-}, signal?: AbortSignal) => Promise<void>;
+}, signal?: AbortSignal, timeoutMs?: number) => Promise<void>;
 /**
  * Serialise a document type declaration to an HTML string.
  * @internal – exported for testing only, not part of the public API.

package/dist/types/dom/pseudo-content.d.ts

@@ -15,9 +15,9 @@ export declare enum PseudoElementType {
 }
 /**
  * Inject the stylesheet that hides pseudo-element surrogate containers.
- * Called on the cloned <body> so the surrogates themselves never render.
+ * Added to the cloned <head> so the surrogates themselves never render.
  */
-export declare const createPseudoHideStyles: (body: HTMLElement, cspNonce?: string) => void;
+export declare const createPseudoHideStyles: (parent: Element, cspNonce?: string) => void;
 /**
  * Resolves computed `content` of ::before/::after into surrogate DOM nodes.
  *

package/dist/types/render/canvas/filter-surface.d.ts

@@ -1,12 +1,14 @@
+import { FilterReferences } from '../../dom/filter-reference';
 export declare class FilterSurfaceError extends Error {
 }
 export declare const releaseSurface: (canvas: HTMLCanvasElement) => void;
 /**
  * A parsed CSS filter chain. Functions keep their declaration order — CSS
  * applies them left to right, and the native canvas backend reproduces that
- * order exactly. Chains containing functions the backends cannot express
- * (url() references, unknown functions) fail parsing and stay on the legacy
- * renderer, where ctx.filter receives the full string natively.
+ * order exactly. Same-document url() references are kept as their own step
+ * and rendered by an SVG pass. Chains containing functions the backends
+ * cannot express (external url() references, unknown functions) fail parsing
+ * and stay on the legacy renderer, where ctx.filter receives the full string.
  */
 export type FilterFunction = {
     kind: 'blur';
@@ -21,6 +23,9 @@ export type FilterFunction = {
     kind: 'unitless';
     name: UnitlessFilterName;
     value: number;
+} | {
+    kind: 'url';
+    ref: string;
 };
 export type UnitlessFilterName = 'brightness' | 'contrast' | 'grayscale' | 'hue-rotate' | 'invert' | 'opacity' | 'saturate' | 'sepia';
 export interface ParsedFilter {
@@ -36,8 +41,18 @@ export declare const nativeFilterString: (filter: ParsedFilter, scale: number) =
 /**
  * Outset (in CSS pixels) a surface must grow so blur/shadow spillover is not
  * cropped. Unitless functions never spread beyond the bounds. Consecutive
- * blurs compound, so their radii sum.
+ * blurs compound, so their radii sum. A url() reference can paint up to its
+ * filter region, which may extend beyond the border box.
  */
-export declare function filterOutset(filter: ParsedFilter): number;
+export declare function filterOutset(filter: ParsedFilter, references?: FilterReferences): number;
 export declare function supportsNativeFilters(owner?: Document): boolean;
-export declare function renderFilterSurface(source: HTMLCanvasElement, filter: ParsedFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;
+/** Where url() references resolve, and the border box origin inside the surface (CSS px). */
+export interface FilterSurfaceReferences {
+    references?: FilterReferences;
+    origin: {
+        x: number;
+        y: number;
+    };
+}
+export declare function renderFilterSurface(source: HTMLCanvasElement, filter: ParsedFilter, opacity: number, scale: number, signal?: AbortSignal, references?: FilterSurfaceReferences): Promise<HTMLCanvasElement>;
+export declare function renderSvgFilterSurface(source: HTMLCanvasElement, filter: ParsedFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.5.4",
+  "version": "2.6.1",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -39,10 +39,10 @@
     "url": "https://github.com/yorickshan/html2canvas-pro"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.2.3",
-    "@commitlint/config-conventional": "^21.2.3",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
     "@types/express": "^5.0.6",
-    "@types/node": "^26.6.5",
+    "@types/node": "^24.0.0",
     "@types/pngjs": "^6.0.5",
     "@types/serve-index": "^1.9.4",
     "@typescript-eslint/eslint-plugin": "^8.71.2",
@@ -50,7 +50,7 @@
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^5.0.4",
     "axios": "^1.20.0",
-    "body-parser": "^2.3.0",
+    "body-parser": "^2.4.0",
     "conventional-changelog": "^8.1.3",
     "conventional-changelog-conventionalcommits": "^10.4.1",
     "cors": "^2.8.6",
@@ -58,10 +58,10 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
     "express": "^5.3.0",
-    "express-rate-limit": "^8.7.1",
+    "express-rate-limit": "^8.7.2",
     "glob": "^13.0.6",
     "husky": "^9.1.7",
-    "jsdom": "^30.1.2",
+    "jsdom": "^30.1.3",
     "lint-staged": "^17.6.0",
     "pixelmatch": "^8.0.0",
     "playwright": "1.64.0",
@@ -91,8 +91,9 @@
     "build:reftest-result-list": "tsx scripts/create-reftest-result-list.ts",
     "build:create-reftest-list": "tsx scripts/create-reftest-list.ts tests/reftests/ignore.txt build/reftests.js",
     "release": "sh scripts/version-upgrade.sh",
-    "format": "prettier --write \"{src,tests,scripts}/**/*.ts\"",
-    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"scripts/**/*.mjs\" --max-warnings 0",
+    "format": "prettier --write \"{src,tests,scripts,examples}/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"scripts/**/*.mjs\" \"examples/**/*.ts\" --max-warnings 0",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
     "test": "pnpm lint && pnpm unittest && pnpm reftests:pw",
     "unittest": "vitest run",
     "unittest:coverage": "vitest run --coverage",