html2canvas-pro 2.6.0 → 2.6.2

package/dist/types/core/performance-monitor.d.ts

@@ -1,4 +1,4 @@
-import { Context } from './context';
+import { Logger } from './logger';
 /**
  * Performance Metric
  *
@@ -33,7 +33,8 @@ export interface PerformanceSummary {
  *
  * Usage:
  * ```typescript
- * const monitor = new PerformanceMonitor(context);
+ * // Standalone (logs disabled) or with the render pipeline's context.
+ * const monitor = new PerformanceMonitor(null);
  *
  * monitor.start('clone');
  * await cloneDocument();
@@ -43,12 +44,12 @@ export interface PerformanceSummary {
  * ```
  */
 export declare class PerformanceMonitor {
-    private readonly context;
+    private readonly logger;
     private readonly activeMetrics;
     private readonly completedMetrics;
     private readonly enabled;
     private readonly getTime;
-    constructor(context: Context | null, enabled?: boolean);
+    constructor(logger: Logger | null, enabled?: boolean);
     /**
      * Start measuring a performance metric
      *

package/dist/types/css/index.d.ts

@@ -74,6 +74,8 @@ import { boxDecorationBreak } from './property-descriptors/box-decoration-break'
 import { type AccentColor } from './property-descriptors/accent-color';
 import { type WebkitTextFillColor } from './property-descriptors/webkit-text-fill-color';
 import { type ISOLATION } from './property-descriptors/isolation';
+import { type WILL_CHANGE } from './property-descriptors/will-change';
+import { type CONTAIN } from './property-descriptors/contain';
 import { type OUTLINE_STYLE, type OutlineColor } from './property-descriptors/outline';
 import { type FilterValue } from './property-descriptors/filter';
 import { type MaskImage, type MaskPosition, type MaskRepeat, type MaskSize } from './property-descriptors/mask';
@@ -173,6 +175,8 @@ export declare class CSSParsedDeclaration {
     accentColor: AccentColor;
     webkitTextFillColor: WebkitTextFillColor;
     isolation: ISOLATION;
+    willChange: WILL_CHANGE;
+    contain: CONTAIN;
     outlineColor: OutlineColor;
     outlineStyle: OUTLINE_STYLE;
     outlineWidth: number;

package/dist/types/css/property-descriptors/contain.d.ts

@@ -0,0 +1,7 @@
+import { IPropertyIdentValueDescriptor } from '../property-descriptor';
+export declare const enum CONTAIN {
+    NONE = 0,
+    /** `paint`, `layout`, `strict`, `content` or `size paint`-style combos. */
+    PAINT_ISOLATION = 1
+}
+export declare const contain: IPropertyIdentValueDescriptor<CONTAIN>;

package/dist/types/css/property-descriptors/will-change.d.ts

@@ -0,0 +1,7 @@
+import { IPropertyListDescriptor } from '../property-descriptor';
+export declare const enum WILL_CHANGE {
+    AUTO = 0,
+    /** Any paint-affecting hint: the element creates a stacking context. */
+    STACKING = 1
+}
+export declare const willChange: IPropertyListDescriptor<WILL_CHANGE>;

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/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/canvas-renderer.d.ts

@@ -50,11 +50,26 @@ export declare class CanvasRenderer {
     constructor(context: Context, options: RenderConfigurations, surfaceRoot?: ElementPaint | undefined, surfaceBudget?: SurfaceBudget);
     renderStack(stack: StackingContext): Promise<void>;
     private canComposite;
+    /**
+     * Root-to-element transform accumulated from the ancestor chain's
+     * TransformEffects (including zoom), stopping at the surface root. The
+     * element's own TransformEffect is intentionally excluded: inside the
+     * offscreen surface it is still applied by the normal effects pass, and
+     * at composition time it is filtered from the recomposed effect list.
+     */
+    private ancestorTransform;
     private renderCompositedStack;
     /**
      * Composite an alpha mask onto a finished element surface: all mask
      * layers are painted additively into a mask surface, then kept pixels are
      * selected with destination-in.
+     *
+     * Coordinate spaces: the source surface paints in LAYOUT space (the
+     * ancestor TransformEffects stay active on the main canvas and transform
+     * the draw-back), so the mask must be painted in layout space too —
+     * anchored to the element's border box (containerBounds) — riding ONLY
+     * the element's own transform effects, which apply inside the surface
+     * rather than at draw-back.
      */
     private applyMask;
     /**

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/dist/types/render/matrix.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 2D affine matrix utilities for the composited-surface render path.
+ *
+ * Matrices use the canvas `transform(a, b, c, d, e, f)` column-vector
+ * convention:
+ *
+ *     | a c e |       | x' |   | a·x + c·y + e |
+ *     | b d f |  ×    | y' | = | b·x + d·y + f |
+ *     | 0 0 1 |       |  1 |   |       1       |
+ *
+ * `TransformEffect` carries the same tuple order, so effects and bounds can
+ * share these helpers. Composition follows the canvas post-multiply rule:
+ * `multiplyMatrix(ancestor, own)` equals `ancestor` followed by `own`.
+ */
+import { Bounds } from '../css/layout/bounds';
+import type { Matrix } from '../css/property-descriptors/transform';
+export declare const IDENTITY_MATRIX: Matrix;
+export declare const isIdentityMatrix: (m: Matrix) => boolean;
+/**
+ * Compose two transforms: the result applies `a` first, then `b`
+ * (canvas post-multiply, matching successive `ctx.transform` calls).
+ */
+export declare const multiplyMatrix: (a: Matrix, b: Matrix) => Matrix;
+/** Apply a matrix to a point, returning the mapped [x, y]. */
+export declare const applyMatrixToPoint: (m: Matrix, x: number, y: number) => [number, number];
+/**
+ * Map a layout-space Bounds through the matrix and return the axis-aligned
+ * bounding box of the four transformed corners. Non-uniform scales and
+ * rotations grow the box; this is intentionally conservative.
+ */
+export declare const transformBoundsToAabb: (m: Matrix, bounds: Bounds) => Bounds;
+/**
+ * Invert an affine matrix. Returns null for singular matrices
+ * (zero-scale transforms have no meaningful inverse).
+ */
+export declare const invertMatrix: (m: Matrix) => Matrix | null;
+/**
+ * Map a visual-space viewport back into the layout space of `m`'s inputs.
+ * Used where a crop window (visual coordinates) must select content measured
+ * in layout coordinates: the conservative answer is the AABB of the inverse
+ * viewport corners.
+ */
+export declare const inverseTransformBoundsToAabb: (m: Matrix, bounds: Bounds) => Bounds | null;

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.6.0",
+  "version": "2.6.2",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -39,44 +39,44 @@
     "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": "^24.0.0",
+    "@types/node": "^24.19.2",
     "@types/pngjs": "^6.0.5",
     "@types/serve-index": "^1.9.4",
-    "@typescript-eslint/eslint-plugin": "^8.71.2",
-    "@typescript-eslint/parser": "^8.71.2",
+    "@typescript-eslint/eslint-plugin": "^8.72.1",
+    "@typescript-eslint/parser": "^8.72.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "^5.0.4",
-    "axios": "^1.20.0",
-    "body-parser": "^2.3.0",
+    "@vitest/coverage-v8": "^5.1.0",
+    "axios": "^1.21.0",
+    "body-parser": "^2.4.0",
     "conventional-changelog": "^8.1.3",
     "conventional-changelog-conventionalcommits": "^10.4.1",
     "cors": "^2.8.6",
-    "eslint": "^10.12.0",
+    "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-prettier": "^5.5.7",
     "express": "^5.3.0",
-    "express-rate-limit": "^8.7.1",
+    "express-rate-limit": "^8.7.3",
     "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",
     "pngjs": "^7.0.0",
     "prettier": "^3.9.10",
-    "rimraf": "^6.1.3",
-    "rolldown": "^1.2.13",
+    "rimraf": "^6.1.4",
+    "rolldown": "^1.2.16",
     "serve-index": "^1.9.2",
     "slash": "5.1.0",
     "tsx": "^4.23.15",
     "typedoc": "^0.28.20",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vite": "^8.3.4",
-    "vitepress": "^2.0.0-alpha.20",
-    "vitest": "^5.0.4",
+    "vite": "^8.3.5",
+    "vitepress": "2.0.0-alpha.21",
+    "vitest": "^5.1.0",
     "yargs": "^18.2.0"
   },
   "lint-staged": {
@@ -99,7 +99,7 @@
     "unittest:coverage": "vitest run --coverage",
     "bench:css-parse": "tsx scripts/benchmarks/css-parse.bench.ts",
     "bench:render": "node scripts/benchmarks/render.bench.mjs",
-    "reftests-diff": "mkdir -p tmp/snapshots && vitest run --config vitest.reftest.config.ts",
+    "reftests-diff": "vitest run --config vitest.reftest.config.ts",
     "watch": "rolldown -w",
     "watch:unittest": "vitest",
     "start": "tsx tests/server --port=8080 --cors=8081",