html2canvas-pro 2.5.0 → 2.5.2

package/dist/types/options.d.ts

@@ -7,6 +7,19 @@ import { Validator } from './core/validator';
  *
  * Combines clone, window, render, and context configuration into a single
  * options object. All properties are optional.
+ *
+ * The full surface is composed from these interfaces (each documented where
+ * it is declared):
+ * - {@link CloneOptions} — `ignoreElements`, `onclone`, `allowTaint`,
+ *   `iframeContainer` (src/dom/document-cloner.ts)
+ * - {@link WindowOptions} — `scrollX`, `scrollY`, `windowWidth`,
+ *   `windowHeight` (src/dom/document-cloner.ts)
+ * - {@link RenderOptions} — `scale`, `canvas`, `x`, `y`, `width`, `height`
+ *   (src/render/canvas/canvas-renderer.ts)
+ * - {@link ContextOptions} — `logging`, `cache`, `onError`, plus the
+ *   `ResourceOptions` it extends: `imageTimeout`, `useCORS`, `proxy`,
+ *   `customIsSameOrigin`, `maxCacheSize` (src/core/context.ts and
+ *   src/core/cache-storage.ts)
  */
 export type Options = CloneOptions & WindowOptions & RenderOptions & ContextOptions & {
     /** Background color for the resulting canvas. Use `null` for transparent. */
@@ -15,6 +28,14 @@ export type Options = CloneOptions & WindowOptions & RenderOptions & ContextOpti
     foreignObjectRendering: boolean;
     /** Whether to remove the cloned iframe after rendering. @default true */
     removeContainer?: boolean;
+    /**
+     * Normalize the cloned DOM before parsing: disable CSS animations and
+     * replace active transforms with identity values so element bounds are
+     * measured in layout space. Set to `false` to keep animation/transform
+     * state intact during capture.
+     * @default true
+     */
+    normalizeDom?: boolean;
     /** CSP nonce for inline style elements. */
     cspNonce?: string;
     /** Custom input validator. */
@@ -51,6 +72,9 @@ export type Options = CloneOptions & WindowOptions & RenderOptions & ContextOpti
     /**
      * Called when a resource fails to load (image, font, iframe, etc.).
      * The render continues — this is a notification hook, not an abort.
+     * Image/proxy load failures are reported exactly once, by the
+     * resource cache at load time; iframe content failures are reported
+     * by the iframe container.
      */
     onError?: (error: Error) => void;
     /**

package/dist/types/render/canvas/background-renderer.d.ts

@@ -85,6 +85,15 @@ export declare class BackgroundRenderer {
      * CSS `from <angle>`.
      */
     private renderConicGradient;
+    /**
+     * Render a repeating conic gradient background.
+     *
+     * Canvas conic gradient stops span the full 2π sweep as [0, 1], so the
+     * one-cycle stop list is stacked k·period + s for k = 0..cycles-1 over the
+     * whole sweep — the same periodic-stop stacking the repeating linear and
+     * radial renderers use along their gradient lines.
+     */
+    private renderRepeatingConicGradient;
     /**
      * Render a repeating pattern with offset
      *

package/dist/types/render/canvas/border-image-renderer.d.ts

@@ -64,4 +64,11 @@ export declare class BorderImageRenderer {
     renderBorderImage(bounds: Bounds, image: HTMLImageElement, slice: BorderImageSlice, repeat: BorderImageRepeat, borderTopWidth: number, borderRightWidth: number, borderBottomWidth: number, borderLeftWidth: number, outset?: BorderImageSides): void;
     private drawRegion;
     private drawRepeatedEdge;
+    /**
+     * Draw the center region of the border image, tiling each axis per its
+     * border-image-repeat keyword (stretch spans the whole axis, repeat
+     * tiles at source size with the overflow cropped, round scales the tile
+     * to divide the axis evenly).
+     */
+    private drawCenterRegion;
 }

package/dist/types/render/canvas/canvas-renderer.d.ts

@@ -71,7 +71,6 @@ export declare class CanvasRenderer {
     renderReplacedElement(container: ReplacedElementContainer, curves: BoundCurves, image: HTMLImageElement | HTMLCanvasElement): void;
     renderNodeContent(paint: ElementPaint): Promise<void>;
     renderStackContent(stack: StackingContext): Promise<void>;
-    mask(paths: Path[]): void;
     path(paths: Path[]): void;
     formatPath(paths: Path[]): void;
     private renderSurfaceBoxShadow;
@@ -81,10 +80,18 @@ export declare class CanvasRenderer {
      * offset outwards. Outlines paint atop content and do not affect layout.
      */
     private renderOutline;
+    /**
+     * Rasterise a gradient border-image-source across the border image area.
+     * CSS allows any <image> as the border-image source; gradients are painted
+     * over the whole border-image box and then sliced by the regular 9-slice
+     * pipeline, matching browser behaviour for `border-image: linear-gradient()`.
+     * Returns null when the gradient could not be painted.
+     */
+    private rasterizeGradientSource;
     /**
      * Filter the already-painted content beneath the element's border box and
-     * paint the result back, approximating CSS backdrop-filter for the
-     * blur/drop-shadow subset supported by parseSimpleFilter.
+     * paint the result back, approximating CSS backdrop-filter for the chain
+     * subset the filter surface backends support.
      */
     private renderBackdropFilter;
     render(element: ElementContainer): Promise<HTMLCanvasElement>;

package/dist/types/render/canvas/effects-renderer.d.ts

@@ -16,6 +16,13 @@ import { Path } from '../path';
  */
 export interface EffectsRendererDependencies {
     ctx: CanvasRenderingContext2D;
+    /**
+     * Device-pixel ratio of the bound context. Canvas shadow metrics
+     * (offset/blur) live in device space, unaffected by the context
+     * transform, so drop-shadow() blur must be scaled like the offsets.
+     * Defaults to 1.
+     */
+    scale?: number;
 }
 /**
  * Path callback for clip effects
@@ -57,6 +64,7 @@ export interface EffectsPathCallback {
 export declare class EffectsRenderer {
     private readonly ctx;
     private readonly pathCallback;
+    private readonly scale;
     private readonly activeEffects;
     /** Whether a canvas state save was performed for the current batch. */
     private didSave;

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

@@ -1,17 +1,43 @@
 export declare class FilterSurfaceError extends Error {
 }
 export declare const releaseSurface: (canvas: HTMLCanvasElement) => void;
-export interface SimpleFilter {
+/**
+ * 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.
+ */
+export type FilterFunction = {
+    kind: 'blur';
+    value: number;
+} | {
+    kind: 'drop-shadow';
+    x: number;
+    y: number;
     blur: number;
-    shadow?: {
-        x: number;
-        y: number;
-        blur: number;
-        color: string;
-    };
+    color: string;
+} | {
+    kind: 'unitless';
+    name: UnitlessFilterName;
+    value: number;
+};
+export type UnitlessFilterName = 'brightness' | 'contrast' | 'grayscale' | 'hue-rotate' | 'invert' | 'opacity' | 'saturate' | 'sepia';
+export interface ParsedFilter {
+    functions: FilterFunction[];
 }
-export declare function parseSimpleFilter(value: string | null): SimpleFilter | null;
-export declare function filterOutset(filter: SimpleFilter): number;
+export declare function parseFilterChain(value: string | null): ParsedFilter | null;
+/**
+ * Render the chain as a canvas ctx.filter string, scaling all device-space
+ * lengths (blur radii, shadow offsets) by the capture scale. Unitless
+ * functions and hue angles are scale-invariant.
+ */
+export declare const nativeFilterString: (filter: ParsedFilter, scale: number) => string;
+/**
+ * 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.
+ */
+export declare function filterOutset(filter: ParsedFilter): number;
 export declare function supportsNativeFilters(owner?: Document): boolean;
-export declare function renderFilterSurface(source: HTMLCanvasElement, filter: SimpleFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;
-export declare function renderSvgFilterSurface(source: HTMLCanvasElement, { blur, shadow }: SimpleFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;
+export declare function renderFilterSurface(source: HTMLCanvasElement, filter: ParsedFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;

package/dist/types/render/canvas/gradient-rasterizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared gradient rasterisation primitives.
+ *
+ * Canvas 2D has no repeating gradients and no native elliptical radial
+ * gradients, so every gradient painter (background, mask, border-image) needs
+ * the same two building blocks:
+ *
+ * 1. periodic stop stacking — the one-cycle stop list re-added k·period + s
+ *    for k = 0..cycles-1, clamped to the [0, 1] gradient range;
+ * 2. ellipse rasterisation — a circle of radius rx scaled vertically by
+ *    ry / rx, painted on a 2rx × 2ry offscreen canvas.
+ *
+ * Centralising them keeps the subtle invariants in one place:
+ * - stop positions are normalised against rx (the canvas gradient radius),
+ *   NOT the diameter — normalising against the diameter halves every
+ *   absolute-px stop;
+ * - the fill must cover the pre-scale circle (fillRect of the rx*2 square),
+ *   not the post-scale ellipse box — a user-space (2rx × 2ry) rect shrinks
+ *   vertically under the y-scale and clips the ellipse whenever ry < rx;
+ * - outside the ending shape a radial gradient continues with its last
+ *   colour, which callers must paint across the full area first.
+ */
+import { UnprocessedGradientColorStop, GradientColorStop } from '../../css/types/image';
+export interface StringColorStop {
+    stop: number;
+    color: string;
+}
+/**
+ * Stack the one-cycle stop list periodically across [0, 1]. Returns null for
+ * a degenerate period (all stops clamped to one point) — CSS renders the
+ * last colour across the whole area in that case, and callers should paint
+ * the last colour instead of stacking.
+ */
+export declare const stackRepeatingStops: (processed: GradientColorStop[]) => StringColorStop[] | null;
+/** Map parsed stops to string-colour stops clamped into the canvas [0, 1] range. */
+export declare const toCanvasStops: (processed: GradientColorStop[]) => StringColorStop[];
+export interface RasterizedRadialGradient {
+    /** 2rx × 2ry device-pixel canvas holding the gradient ellipse. */
+    canvas: HTMLCanvasElement;
+    /** Colour beyond the ending shape (the last stop's colour). */
+    lastColor: string;
+    rx: number;
+    ry: number;
+}
+/**
+ * Rasterise a radial gradient's ending-shape ellipse to an offscreen canvas.
+ *
+ * The ellipse is a circle of radius rx scaled vertically by ry / rx around
+ * the canvas centre, so the offscreen canvas is the ellipse's full 2rx × 2ry
+ * bounding box and callers draw it at (centre - rx, centre - ry). Handles the
+ * repeating variant by stacking stops across the [0, 1] gradient range.
+ */
+export declare const rasterizeRadialGradient: (ownerDocument: Document, rx: number, ry: number, stops: UnprocessedGradientColorStop[], repeating?: boolean) => RasterizedRadialGradient | null;

package/dist/types/render/canvas/mask-renderer.d.ts

@@ -10,8 +10,11 @@
  * always fills the whole area — a mask surface is about alpha coverage, not
  * about what is visible underneath.
  *
- * Limitations (v1): repeating gradients render their base cycle; mask-mode is
- * alpha-only; layers composite with source-over (≈ the default `add`).
+ * Gradient layers share the rasterisation primitives of the background
+ * renderer (gradient-rasterizer.ts): repeating gradients stack their stop
+ * cycles, and the area beyond a radial gradient's ending shape keeps the
+ * last stop's colour. Limitations (v1): mask-mode is alpha-only; layers
+ * composite with source-over (≈ the spec-default `add`).
  */
 import { ICSSImage } from '../../css/types/image';
 import { LengthPercentage } from '../../css/types/length-percentage';

package/dist/types/render/canvas/text-clip-renderer.d.ts

@@ -9,8 +9,15 @@
  * Extracted from CanvasRenderer to keep paint orchestration separate from
  * this self-contained compositing algorithm.
  *
- * The offscreen canvas uses CSS-pixel dimensions (not device-pixel) because the
- * background renderer handles scaling internally via BackgroundRenderer options.
+ * The offscreen and mask canvases are backed at device-pixel resolution
+ * (bounds × scale) with their contexts scaled to CSS pixels, so the
+ * composite back onto the main canvas maps 1:1 onto the backing store and
+ * stays sharp at devicePixelRatio > 1.
+ *
+ * Matching browser paint order for clipped text:
+ * - text shadows render *beneath* the clipped background (silhouettes in
+ *   the shadow colour), they are not part of the clip region;
+ * - -webkit-text-stroke is part of the clip region (fill ∪ stroke band).
  */
 import { ElementPaint } from '../stacking-context';
 import { CSSParsedDeclaration } from '../../css';
@@ -19,18 +26,30 @@ export interface TextClipRendererDependencies {
     /** Main canvas context the clipped background is composited onto. */
     ctx: CanvasRenderingContext2D;
     context: Context;
+    /** Device-pixel ratio shared with the main renderer. */
+    scale: number;
     /** Font builder shared with the text renderer so both use identical fonts. */
     createFontStyle: (styles: CSSParsedDeclaration) => string[];
 }
 export declare class TextClipRenderer {
     private readonly ctx;
     private readonly context;
+    private readonly scale;
     private readonly createFontStyle;
     constructor(deps: TextClipRendererDependencies);
     render(paint: ElementPaint): Promise<void>;
+    private createLayer;
+    private createGlyphLayer;
+    /**
+     * Draw one text bound onto a glyph layer, splitting into per-glyph draws
+     * when letter-spacing is in effect so the layout matches the main text
+     * renderer. Vertical writing modes fall back to a single draw call.
+     */
+    private drawGlyphs;
     /**
-     * Render text glyphs one-by-one as a mask, applying letter-spacing between characters.
-     * This ensures the mask matches how the text renderer lays out the characters.
+     * Paint the text-shadow silhouettes for every glyph, one canvas per
+     * shadow, returned front-to-back (the last shadow sits deepest). Returns
+     * null when the element has no text shadows.
      */
-    private renderTextMaskWithLetterSpacing;
+    private renderShadowSilhouettes;
 }

package/dist/types/render/canvas/text-renderer.d.ts

@@ -25,6 +25,7 @@ export interface TextRendererDependencies {
     };
 }
 export declare const hasCJKCharacters: (text: string) => boolean;
+export declare const getTextStrokeLineJoin: () => CanvasLineJoin;
 /**
  * Text Renderer
  *

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.5.0",
+  "version": "2.5.2",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -31,7 +31,7 @@
     "screenshot"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=24.0.0"
   },
   "homepage": "https://yorickshan.github.io/html2canvas-pro/",
   "repository": {
@@ -41,27 +41,18 @@
   "devDependencies": {
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@types/chai": "^5.2.3",
     "@types/express": "^5.0.6",
-    "@types/karma": "^6.3.9",
-    "@types/mocha": "^10.0.10",
     "@types/node": "^26.6.3",
-    "@types/platform": "^1.3.6",
     "@types/pngjs": "^6.0.5",
     "@types/serve-index": "^1.9.4",
     "@typescript-eslint/eslint-plugin": "^8.70.1",
     "@typescript-eslint/parser": "^8.70.1",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^5.0.2",
-    "appium-ios-simulator": "^8.2.8",
-    "base64-arraybuffer": "1.0.2",
     "body-parser": "^2.3.0",
-    "chai": "6.2.2",
-    "change-case": "^5.4.4",
     "conventional-changelog": "^8.1.3",
     "conventional-changelog-conventionalcommits": "^10.4.0",
     "cors": "^2.8.6",
-    "cz-conventional-changelog": "^3.3.0",
     "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
@@ -70,23 +61,11 @@
     "glob": "^13.0.6",
     "husky": "^9.1.7",
     "jsdom": "^30.1.1",
-    "karma": "^6.4.4",
-    "karma-chrome-launcher": "^3.2.0",
-    "karma-edge-launcher": "^0.4.2",
-    "karma-firefox-launcher": "^2.1.3",
-    "karma-ie-launcher": "^1.0.0",
-    "karma-junit-reporter": "^2.0.1",
-    "karma-mocha": "^2.0.1",
-    "karma-safarinative-launcher": "^1.1.0",
     "lint-staged": "^17.6.0",
-    "mocha": "^12.0.2",
-    "node-simctl": "^8.2.9",
     "pixelmatch": "^7.2.0",
-    "platform": "^1.3.6",
     "playwright": "1.63.0",
     "pngjs": "^7.0.0",
     "prettier": "^3.9.9",
-    "puppeteer": "^25.12.0",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.11",
     "serve-index": "^1.9.2",
@@ -99,10 +78,7 @@
     "vitest": "^5.0.2",
     "yargs": "^18.2.0"
   },
-  "dependencies": {
-    "css-line-break": "^2.1.0",
-    "text-segmentation": "^1.0.3"
-  },
+  "dependencies": {},
   "lint-staged": {
     "{src,tests}/**/*.ts": [
       "prettier --write",
@@ -111,20 +87,19 @@
   },
   "scripts": {
     "prebuild": "rimraf dist/ && rimraf build/ && mkdir -p dist && mkdir -p build",
-    "build": "tsc -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && rolldown -c tests/rolldown.testrunner.config.ts && node scripts/bundle-filter-surface.mjs",
+    "build": "tsc -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && node scripts/bundle-filter-surface.mjs",
     "build:testrunner": "rolldown -c tests/rolldown.testrunner.config.ts",
     "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 --max-warnings 0",
-    "test": "pnpm lint && pnpm unittest && pnpm karma",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"scripts/**/*.mjs\" --max-warnings 0",
+    "test": "pnpm lint && pnpm unittest && pnpm reftests:pw",
     "unittest": "vitest run",
     "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",
-    "prekarma": "node scripts/ensure-karma-prereqs.mjs",
-    "karma": "tsx tests/karma",
     "watch": "rolldown -w",
     "watch:unittest": "vitest",
     "start": "tsx tests/server --port=8080 --cors=8081",
@@ -133,6 +108,9 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:api": "typedoc",
-    "docs:api:watch": "typedoc --watch"
+    "docs:api:watch": "typedoc --watch",
+    "reftests:pw": "tsx tests/reftests-playwright.ts",
+    "reftests": "pnpm reftests:pw",
+    "prebrowser": "node scripts/ensure-browser-prereqs.mjs"
   }
 }

package/dist/types/render/font-metrics.d.ts

@@ -1,11 +0,0 @@
-export interface FontMetric {
-    baseline: number;
-    middle: number;
-}
-export declare class FontMetrics {
-    private readonly _data;
-    private readonly _document;
-    constructor(document: Document);
-    private parseMetrics;
-    getMetrics(fontFamily: string, fontSize: string): FontMetric;
-}

package/dist/types/render/renderer-interface.d.ts

@@ -1,28 +0,0 @@
-/**
- * Base interface for all specialized renderers.
- * Each renderer is responsible for rendering a specific aspect of an element.
- *
- * @internal This interface is a structural contract; prefer using concrete
- *           renderer classes (BackgroundRenderer, BorderRenderer, etc.)
- *           directly rather than relying on the generic IRenderer shape.
- */
-export interface IRenderer {
-    render(...args: unknown[]): void | Promise<void>;
-}
-/**
- * Common dependencies required by renderers.
- * RenderConfigurations from canvas-renderer.ts provides a concrete type.
- */
-export interface RendererDependencies {
-    ctx: CanvasRenderingContext2D;
-    scale: number;
-    options: Record<string, unknown>;
-}
-/**
- * Performance tracking for renderers.
- */
-export interface RenderMetrics {
-    renderCount: number;
-    totalTime: number;
-    averageTime: number;
-}