html2canvas-pro 2.4.5 → 2.5.1

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

@@ -0,0 +1,36 @@
+/**
+ * Mask Renderer
+ *
+ * Paints CSS mask-image layers into a mask surface (alpha mask) which the
+ * caller composites onto the element surface via `destination-in`.
+ *
+ * Value grammars are shared with background-image (position/size/repeat), so
+ * the layer maths mirrors the background renderer but works in the local
+ * coordinate space of the mask positioning area (default: border box) and
+ * 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`).
+ */
+import { ICSSImage } from '../../css/types/image';
+import { LengthPercentage } from '../../css/types/length-percentage';
+import { BACKGROUND_REPEAT } from '../../css/property-descriptors/background-repeat';
+import { BackgroundSizeInfo } from '../../css/property-descriptors/background-size';
+export interface MaskLayerStyles {
+    maskPosition: LengthPercentage[][];
+    maskRepeat: BACKGROUND_REPEAT[];
+    maskSize: BackgroundSizeInfo[][];
+}
+export interface MaskArea {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export type MaskImageSource = HTMLImageElement | HTMLCanvasElement;
+/**
+ * Paint every mask layer into `ctx` (expected to already be scaled to device
+ * pixels and translated so the page origin maps correctly).
+ */
+export declare const paintMaskLayers: (ctx: CanvasRenderingContext2D, layers: ICSSImage[], styles: MaskLayerStyles, area: MaskArea, matchImage: (url: string) => Promise<MaskImageSource | undefined>) => Promise<void>;

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

@@ -0,0 +1,56 @@
+/**
+ * Text Clip Renderer
+ *
+ * Implements `background-clip: text` — paints the element's background
+ * (color + images) to an offscreen canvas and clips it to the text glyph
+ * shapes with destination-in compositing, then composites the result back
+ * onto the main canvas.
+ *
+ * Extracted from CanvasRenderer to keep paint orchestration separate from
+ * this self-contained compositing algorithm.
+ *
+ * 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';
+import { Context } from '../../core/context';
+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;
+    /**
+     * 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 renderShadowSilhouettes;
+    private getTextStrokeLineJoin;
+}

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

@@ -35,6 +35,13 @@ export declare class TextRenderer {
     private readonly ctx;
     private readonly options;
     private readonly decorationRenderer;
+    /**
+     * Baseline ascent per font string. Consecutive text nodes overwhelmingly
+     * share a font, and each measureBaseline call issues a canvas measureText,
+     * so repeated fonts are memoised (bounded; cleared if the working set
+     * exceeds the cap).
+     */
+    private readonly baselineCache;
     /**
      * Per-render glyph width cache. Keyed by glyph + font string,
      * avoids redundant `measureText` calls when letter-spacing is non-zero.
@@ -90,6 +97,13 @@ export declare class TextRenderer {
      * Public method used by list rendering
      */
     createFontStyle(styles: CSSParsedDeclaration): string[];
+    /**
+     * -webkit-text-fill-color overrides the fill colour while leaving
+     * decorations and strokes on `color` (e.g. the classic transparent-fill
+     * gradient text). Falls back to `color` when the computed value could not
+     * be resolved (currentcolor).
+     */
+    private resolveFillColor;
     /**
      * Render text with -webkit-line-clamp truncation.
      * Groups text bounds by their Y position into visual lines, then renders
@@ -101,5 +115,13 @@ export declare class TextRenderer {
      * Returns true if ellipsis was applied (caller should skip normal rendering).
      */
     private renderEllipsisText;
+    private measureBaselineCached;
     renderTextNode(text: TextContainer, styles: CSSParsedDeclaration, containerBounds?: Bounds): Promise<void>;
+    /**
+     * Draw text-emphasis marks over (or under) each grapheme cluster.
+     *
+     * Vertical writing modes are skipped in the current scope: marks would
+     * need to sit beside vertical glyph runs rather than above them.
+     */
+    private renderTextEmphasis;
 }

package/dist/types/render/stacking-context.d.ts

@@ -20,11 +20,14 @@ export declare class ElementPaint {
     readonly effects: IElementEffect[];
     readonly curves: BoundCurves;
     listValue?: string;
+    /** Memoised getEffects results for the plain (surfaceRoot-less) render path. */
+    private plainEffectsCache;
     constructor(container: ElementContainer, parent: ElementPaint | null);
     getEffects(target: EffectTarget, surfaceRoot?: ElementPaint): IElementEffect[];
+    private computeEffects;
 }
 /** @internal – exported for testing only. */
-export declare const hasOverflowClip: (styles: ElementContainer["styles"]) => boolean;
+export declare const hasOverflowClip: (styles: ElementContainer['styles']) => boolean;
 /**
  * Resolve a `closest-side` or `farthest-side` shape-radius keyword to pixels
  * for a single axis. Used by both `circle()` (per-axis) and `ellipse()`.

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.4.5",
+  "version": "2.5.1",
   "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": {
@@ -39,66 +39,65 @@
     "url": "https://github.com/yorickshan/html2canvas-pro"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.3.0",
-    "@commitlint/config-conventional": "^20.2.0",
+    "@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.0",
-    "@types/mocha": "^10.0.7",
-    "@types/node": "^25.0.3",
-    "@types/platform": "^1.3.4",
+    "@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.50.0",
-    "@typescript-eslint/parser": "^8.50.0",
-    "@vitest/coverage-v8": "^3.2.6",
-    "appium-ios-simulator": "^8.0.9",
+    "@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.2.1",
+    "body-parser": "^2.3.0",
     "chai": "6.2.2",
     "change-case": "^5.4.4",
-    "conventional-changelog": "^7.2.1",
-    "conventional-changelog-conventionalcommits": "^9.3.1",
-    "cors": "^2.8.5",
+    "conventional-changelog": "^8.1.3",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
+    "cors": "^2.8.6",
     "cz-conventional-changelog": "^3.3.0",
-    "eslint": "^9.13.0",
+    "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.6",
     "express": "^5.2.1",
     "filenamify-url": "4.0.0",
-    "glob": "^13.0.0",
-    "html2canvas-pro-baseline": "npm:html2canvas-pro@2.4.3",
+    "glob": "^13.0.6",
     "husky": "^9.1.7",
-    "jsdom": "^29.1.1",
-    "karma": "^6.3.2",
-    "karma-chrome-launcher": "^3.1.0",
+    "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.0",
+    "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": "^16.2.7",
-    "mocha": "^11.7.5",
-    "node-simctl": "^8.1.2",
+    "lint-staged": "^17.6.0",
+    "mocha": "^12.0.2",
+    "node-simctl": "^8.2.9",
     "pixelmatch": "^7.2.0",
     "platform": "^1.3.6",
-    "playwright": "1.60.0",
+    "playwright": "1.63.0",
     "pngjs": "^7.0.0",
-    "prettier": "^3.3.3",
-    "puppeteer": "^24.34.0",
-    "replace-in-file": "^8.4.0",
-    "rimraf": "^6.0.1",
-    "rolldown": "^1.2.0",
-    "serve-index": "^1.9.1",
+    "prettier": "^3.9.9",
+    "puppeteer": "^25.12.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.11",
+    "serve-index": "^1.9.2",
     "slash": "5.1.0",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.22.3",
-    "typedoc": "^0.28.19",
-    "typescript": "^5.5.4",
+    "tsx": "^4.23.15",
+    "typedoc": "^0.28.20",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.3.1",
     "vitepress": "^1.6.4",
-    "vitest": "^3.2.6",
-    "yargs": "^18.0.0"
+    "vitest": "^5.0.2",
+    "yargs": "^18.2.0"
   },
   "dependencies": {
     "css-line-break": "^2.1.0",
@@ -112,13 +111,13 @@
   },
   "scripts": {
     "prebuild": "rimraf dist/ && rimraf build/ && mkdir -p dist && mkdir -p build",
-    "build": "tsc --module commonjs -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && rolldown -c tests/rolldown.testrunner.config.ts && node scripts/copy-filter-baseline.mjs",
+    "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: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",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"scripts/**/*.mjs\" --max-warnings 0",
     "test": "pnpm lint && pnpm unittest && pnpm karma",
     "unittest": "vitest run",
     "unittest:coverage": "vitest run --coverage",

package/dist/lib/config.js

@@ -1,49 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Html2CanvasConfig = void 0;
-/**
- * Html2Canvas Configuration
- *
- * Manages configuration state for html2canvas rendering.
- * Eliminates the need for global static variables.
- */
-class Html2CanvasConfig {
-    constructor(options = {}) {
-        const resolvedWindow = options.window || (typeof window !== 'undefined' ? window : undefined);
-        if (!resolvedWindow) {
-            throw new Error('Window object is required but not available');
-        }
-        this.window = resolvedWindow;
-        this.cspNonce = options.cspNonce;
-        this.cache = options.cache;
-    }
-    /**
-     * Create configuration from an element
-     * Extracts window from element's owner document
-     */
-    static fromElement(element, options = {}) {
-        const ownerDocument = element.ownerDocument;
-        if (!ownerDocument) {
-            throw new Error('Element is not attached to a document');
-        }
-        const defaultView = ownerDocument.defaultView;
-        if (!defaultView) {
-            throw new Error('Document is not attached to a window');
-        }
-        return new Html2CanvasConfig({
-            window: defaultView,
-            ...options
-        });
-    }
-    /**
-     * Clone configuration with override options
-     */
-    clone(options = {}) {
-        return new Html2CanvasConfig({
-            window: options.window || this.window,
-            cspNonce: options.cspNonce ?? this.cspNonce,
-            cache: options.cache ?? this.cache
-        });
-    }
-}
-exports.Html2CanvasConfig = Html2CanvasConfig;

package/dist/lib/core/abort-helper.js

@@ -1,20 +0,0 @@
-"use strict";
-/**
- * AbortSignal helper utilities.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.throwIfAborted = void 0;
-/**
- * Throw a DOMException if the given AbortSignal is already aborted.
- * Used at checkpoints throughout the rendering pipeline to support
- * cancellable renders.
- *
- * @param signal - The AbortSignal to check. If undefined or not aborted, this is a no-op.
- * @throws {DOMException} With name 'AbortError' if the signal has been aborted.
- */
-const throwIfAborted = (signal) => {
-    if (signal?.aborted) {
-        throw new DOMException('The operation was aborted.', 'AbortError');
-    }
-};
-exports.throwIfAborted = throwIfAborted;

package/dist/lib/core/background-parser.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseBackgroundColor = void 0;
-const color_1 = require("../css/types/color");
-const color_utilities_1 = require("../css/types/color-utilities");
-/**
- * Resolve the background colour for the rendered canvas, following CSS
- * background propagation rules:
- *
- * 1. If the target element is `<html>`, inherit the first opaque ancestor
- *    (doc → body → fallback).
- * 2. Otherwise use the user-supplied backgroundColor, or opaque white.
- *
- * @param context               - Current rendering context.
- * @param element               - The root element being rendered.
- * @param backgroundColorOverride - User-supplied override (string | null).
- * @returns A resolved colour value suitable for filling the canvas.
- */
-const parseBackgroundColor = (context, element, backgroundColorOverride) => {
-    const ownerDocument = element.ownerDocument;
-    // http://www.w3.org/TR/css3-background/#special-backgrounds
-    const documentBackgroundColor = ownerDocument.documentElement
-        ? (0, color_1.parseColor)(context, getComputedStyle(ownerDocument.documentElement).backgroundColor)
-        : color_1.COLORS.TRANSPARENT;
-    const bodyBackgroundColor = ownerDocument.body
-        ? (0, color_1.parseColor)(context, getComputedStyle(ownerDocument.body).backgroundColor)
-        : color_1.COLORS.TRANSPARENT;
-    const defaultBackgroundColor = typeof backgroundColorOverride === 'string'
-        ? (0, color_1.parseColor)(context, backgroundColorOverride)
-        : backgroundColorOverride === null
-            ? color_1.COLORS.TRANSPARENT
-            : 0xffffffff;
-    return element === ownerDocument.documentElement
-        ? (0, color_utilities_1.isTransparent)(documentBackgroundColor)
-            ? (0, color_utilities_1.isTransparent)(bodyBackgroundColor)
-                ? defaultBackgroundColor
-                : bodyBackgroundColor
-            : documentBackgroundColor
-        : defaultBackgroundColor;
-};
-exports.parseBackgroundColor = parseBackgroundColor;

package/dist/lib/core/bitwise.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.contains = void 0;
-const contains = (bit, value) => (bit & value) !== 0;
-exports.contains = contains;