html2canvas-pro 2.2.4 → 2.3.0

package/dist/types/css/syntax/token-types.d.ts

@@ -0,0 +1,72 @@
+export declare const enum TokenType {
+    STRING_TOKEN = 0,
+    BAD_STRING_TOKEN = 1,
+    LEFT_PARENTHESIS_TOKEN = 2,
+    RIGHT_PARENTHESIS_TOKEN = 3,
+    COMMA_TOKEN = 4,
+    HASH_TOKEN = 5,
+    DELIM_TOKEN = 6,
+    AT_KEYWORD_TOKEN = 7,
+    PREFIX_MATCH_TOKEN = 8,
+    DASH_MATCH_TOKEN = 9,
+    INCLUDE_MATCH_TOKEN = 10,
+    LEFT_CURLY_BRACKET_TOKEN = 11,
+    RIGHT_CURLY_BRACKET_TOKEN = 12,
+    SUFFIX_MATCH_TOKEN = 13,
+    SUBSTRING_MATCH_TOKEN = 14,
+    DIMENSION_TOKEN = 15,
+    PERCENTAGE_TOKEN = 16,
+    NUMBER_TOKEN = 17,
+    FUNCTION = 18,
+    FUNCTION_TOKEN = 19,
+    IDENT_TOKEN = 20,
+    COLUMN_TOKEN = 21,
+    URL_TOKEN = 22,
+    BAD_URL_TOKEN = 23,
+    CDC_TOKEN = 24,
+    CDO_TOKEN = 25,
+    COLON_TOKEN = 26,
+    SEMICOLON_TOKEN = 27,
+    LEFT_SQUARE_BRACKET_TOKEN = 28,
+    RIGHT_SQUARE_BRACKET_TOKEN = 29,
+    UNICODE_RANGE_TOKEN = 30,
+    WHITESPACE_TOKEN = 31,
+    EOF_TOKEN = 32
+}
+interface IToken {
+    type: TokenType;
+}
+export interface Token extends IToken {
+    type: TokenType.BAD_URL_TOKEN | TokenType.BAD_STRING_TOKEN | TokenType.LEFT_PARENTHESIS_TOKEN | TokenType.RIGHT_PARENTHESIS_TOKEN | TokenType.COMMA_TOKEN | TokenType.SUBSTRING_MATCH_TOKEN | TokenType.PREFIX_MATCH_TOKEN | TokenType.SUFFIX_MATCH_TOKEN | TokenType.COLON_TOKEN | TokenType.SEMICOLON_TOKEN | TokenType.LEFT_SQUARE_BRACKET_TOKEN | TokenType.RIGHT_SQUARE_BRACKET_TOKEN | TokenType.LEFT_CURLY_BRACKET_TOKEN | TokenType.RIGHT_CURLY_BRACKET_TOKEN | TokenType.DASH_MATCH_TOKEN | TokenType.INCLUDE_MATCH_TOKEN | TokenType.COLUMN_TOKEN | TokenType.WHITESPACE_TOKEN | TokenType.CDC_TOKEN | TokenType.CDO_TOKEN | TokenType.EOF_TOKEN;
+}
+export interface StringValueToken extends IToken {
+    type: TokenType.STRING_TOKEN | TokenType.DELIM_TOKEN | TokenType.FUNCTION_TOKEN | TokenType.IDENT_TOKEN | TokenType.URL_TOKEN | TokenType.AT_KEYWORD_TOKEN;
+    value: string;
+}
+export interface HashToken extends IToken {
+    type: TokenType.HASH_TOKEN;
+    flags: number;
+    value: string;
+}
+export interface NumberValueToken extends IToken {
+    type: TokenType.PERCENTAGE_TOKEN | TokenType.NUMBER_TOKEN;
+    flags: number;
+    number: number;
+}
+export interface DimensionToken extends IToken {
+    type: TokenType.DIMENSION_TOKEN;
+    flags: number;
+    unit: string;
+    number: number;
+}
+export interface UnicodeRangeToken extends IToken {
+    type: TokenType.UNICODE_RANGE_TOKEN;
+    start: number;
+    end: number;
+}
+export type CSSToken = Token | StringValueToken | NumberValueToken | DimensionToken | UnicodeRangeToken | HashToken;
+export declare const FLAG_UNRESTRICTED: number;
+export declare const FLAG_ID: number;
+export declare const FLAG_INTEGER: number;
+export declare const FLAG_NUMBER: number;
+export {};

package/dist/types/css/syntax/tokenizer.d.ts

@@ -1,75 +1,9 @@
-export declare const enum TokenType {
-    STRING_TOKEN = 0,
-    BAD_STRING_TOKEN = 1,
-    LEFT_PARENTHESIS_TOKEN = 2,
-    RIGHT_PARENTHESIS_TOKEN = 3,
-    COMMA_TOKEN = 4,
-    HASH_TOKEN = 5,
-    DELIM_TOKEN = 6,
-    AT_KEYWORD_TOKEN = 7,
-    PREFIX_MATCH_TOKEN = 8,
-    DASH_MATCH_TOKEN = 9,
-    INCLUDE_MATCH_TOKEN = 10,
-    LEFT_CURLY_BRACKET_TOKEN = 11,
-    RIGHT_CURLY_BRACKET_TOKEN = 12,
-    SUFFIX_MATCH_TOKEN = 13,
-    SUBSTRING_MATCH_TOKEN = 14,
-    DIMENSION_TOKEN = 15,
-    PERCENTAGE_TOKEN = 16,
-    NUMBER_TOKEN = 17,
-    FUNCTION = 18,
-    FUNCTION_TOKEN = 19,
-    IDENT_TOKEN = 20,
-    COLUMN_TOKEN = 21,
-    URL_TOKEN = 22,
-    BAD_URL_TOKEN = 23,
-    CDC_TOKEN = 24,
-    CDO_TOKEN = 25,
-    COLON_TOKEN = 26,
-    SEMICOLON_TOKEN = 27,
-    LEFT_SQUARE_BRACKET_TOKEN = 28,
-    RIGHT_SQUARE_BRACKET_TOKEN = 29,
-    UNICODE_RANGE_TOKEN = 30,
-    WHITESPACE_TOKEN = 31,
-    EOF_TOKEN = 32
-}
-interface IToken {
-    type: TokenType;
-}
-export interface Token extends IToken {
-    type: TokenType.BAD_URL_TOKEN | TokenType.BAD_STRING_TOKEN | TokenType.LEFT_PARENTHESIS_TOKEN | TokenType.RIGHT_PARENTHESIS_TOKEN | TokenType.COMMA_TOKEN | TokenType.SUBSTRING_MATCH_TOKEN | TokenType.PREFIX_MATCH_TOKEN | TokenType.SUFFIX_MATCH_TOKEN | TokenType.COLON_TOKEN | TokenType.SEMICOLON_TOKEN | TokenType.LEFT_SQUARE_BRACKET_TOKEN | TokenType.RIGHT_SQUARE_BRACKET_TOKEN | TokenType.LEFT_CURLY_BRACKET_TOKEN | TokenType.RIGHT_CURLY_BRACKET_TOKEN | TokenType.DASH_MATCH_TOKEN | TokenType.INCLUDE_MATCH_TOKEN | TokenType.COLUMN_TOKEN | TokenType.WHITESPACE_TOKEN | TokenType.CDC_TOKEN | TokenType.CDO_TOKEN | TokenType.EOF_TOKEN;
-}
-export interface StringValueToken extends IToken {
-    type: TokenType.STRING_TOKEN | TokenType.DELIM_TOKEN | TokenType.FUNCTION_TOKEN | TokenType.IDENT_TOKEN | TokenType.URL_TOKEN | TokenType.AT_KEYWORD_TOKEN;
-    value: string;
-}
-export interface HashToken extends IToken {
-    type: TokenType.HASH_TOKEN;
-    flags: number;
-    value: string;
-}
-export interface NumberValueToken extends IToken {
-    type: TokenType.PERCENTAGE_TOKEN | TokenType.NUMBER_TOKEN;
-    flags: number;
-    number: number;
-}
-export interface DimensionToken extends IToken {
-    type: TokenType.DIMENSION_TOKEN;
-    flags: number;
-    unit: string;
-    number: number;
-}
-export interface UnicodeRangeToken extends IToken {
-    type: TokenType.UNICODE_RANGE_TOKEN;
-    start: number;
-    end: number;
-}
-export type CSSToken = Token | StringValueToken | NumberValueToken | DimensionToken | UnicodeRangeToken | HashToken;
-export declare const FLAG_UNRESTRICTED: number;
-export declare const FLAG_ID: number;
-export declare const FLAG_INTEGER: number;
-export declare const FLAG_NUMBER: number;
-export declare const EOF_TOKEN: Token;
+import type { CSSToken } from './token-types';
+export { TokenType } from './token-types';
+export type { Token, StringValueToken, HashToken, NumberValueToken, DimensionToken, UnicodeRangeToken, CSSToken } from './token-types';
+export { FLAG_UNRESTRICTED, FLAG_ID, FLAG_INTEGER, FLAG_NUMBER } from './token-types';
+export { isDigit, isHex, isWhiteSpace, isNameCodePoint, isValidEscape, isIdentifierStart, isNameStartCodePoint, isNumberStart } from './token-constants';
+export { COMMA_TOKEN, COLON_TOKEN, SEMICOLON_TOKEN, LEFT_PARENTHESIS_TOKEN, RIGHT_PARENTHESIS_TOKEN, LEFT_CURLY_BRACKET_TOKEN, RIGHT_CURLY_BRACKET_TOKEN, LEFT_SQUARE_BRACKET_TOKEN, RIGHT_SQUARE_BRACKET_TOKEN, WHITESPACE_TOKEN, EOF_TOKEN, BAD_URL_TOKEN, BAD_STRING_TOKEN, CDC_TOKEN, CDO_TOKEN, PREFIX_MATCH_TOKEN, SUFFIX_MATCH_TOKEN, SUBSTRING_MATCH_TOKEN, DASH_MATCH_TOKEN, INCLUDE_MATCH_TOKEN, COLUMN_TOKEN } from './token-singletons';
 export declare class Tokenizer {
     private static _pool;
     private static readonly MAX_POOL_SIZE;
@@ -96,4 +30,3 @@ export declare class Tokenizer {
     private consumeEscapedCodePoint;
     private consumeName;
 }
-export {};

package/dist/types/css/types/length-percentage.d.ts

@@ -1,12 +1,53 @@
-import { DimensionToken, NumberValueToken } from '../syntax/tokenizer';
+import { DimensionToken, NumberValueToken, TokenType } from '../syntax/tokenizer';
 import { CSSValue, CSSFunction } from '../syntax/parser';
+/**
+ * Internal token representing a calc() expression that has both a percentage
+ * component and a pixel offset. Created at parse time and resolved at render
+ * time once the container size is known.
+ *
+ * Extends NumberValueToken so it is structurally assignable wherever
+ * LengthPercentage (DimensionToken | NumberValueToken) is expected,
+ * avoiding widespread type changes.
+ */
+export interface CalcWithPercentage extends NumberValueToken {
+    type: TokenType.NUMBER_TOKEN;
+    /** The percentage coefficient (extracted from the calc expression). */
+    _calcPercentage: number;
+    /** The pixel offset (extracted from the calc expression). */
+    _calcPixelOffset: number;
+}
 export type LengthPercentage = DimensionToken | NumberValueToken;
 export type LengthPercentageTuple = [LengthPercentage] | [LengthPercentage, LengthPercentage];
 export declare const isLengthPercentage: (token: CSSValue) => token is LengthPercentage;
+/**
+ * Check if a token is a CalcWithPercentage deferred token.
+ * Accepts CSSValue (structural duck-type check) for use in type guards.
+ */
+export declare const isCalcWithPercentage: (token: CSSValue) => token is CalcWithPercentage;
 /**
  * Check if a token is a calc() function
  */
 export declare const isCalcFunction: (token: CSSValue) => token is CSSFunction;
+/**
+ * Parse a calc() token and produce a LengthPercentage.
+ *
+ * Uses two-point evaluation to extract the percentage coefficient and pixel
+ * offset from a calc() expression so it can be resolved later at render time
+ * when the container size is known.
+ *
+ *   evaluate(0)   → pixelOffset
+ *   evaluate(100) → percentage + pixelOffset   →  percentage = evaluate(100) - pixelOffset
+ *
+ * If the expression has no percentage component, returns a plain NUMBER_TOKEN
+ * for backwards compatibility.
+ */
+export declare const parseCalcForLengthPercentage: (calcToken: CSSFunction) => LengthPercentage | null;
+/**
+ * Convenience helper for parsing an optional calc() or length-percentage value.
+ * Used by property descriptors that accept both calc() and regular length-percentage tokens.
+ * Returns null if the value is neither a calc() function nor a length-percentage token.
+ */
+export declare const parseOptionalCalcOrLength: (value: CSSValue) => LengthPercentage | null;
 /**
  * Evaluate a calc() expression and convert to LengthPercentage token
  * Supports basic arithmetic: +, -, *, /

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

@@ -49,4 +49,9 @@ declare enum PseudoElementType {
     AFTER = 1
 }
 export declare const copyCSSStyles: <T extends HTMLElement | SVGElement>(style: CSSStyleDeclaration, target: T) => T;
+/**
+ * Serialise a document type declaration to an HTML string.
+ * @internal – exported for testing only, not part of the public API.
+ */
+export declare const serializeDoctype: (doctype?: DocumentType | null) => string;
 export {};

package/dist/types/dom/node-parser.d.ts

@@ -1,5 +1,3 @@
 import { ElementContainer } from './element-container';
 import { Context } from '../core/context';
-import { isBodyElement, isCanvasElement, isCustomElement, isElementNode, isHTMLElement, isHTMLElementNode, isIFrameElement, isImageElement, isInputElement, isLIElement, isOLElement, isScriptElement, isSelectElement, isSlotElement, isStyleElement, isSVGElement, isSVGElementNode, isTextareaElement, isTextNode, isVideoElement } from './node-type-guards';
-export { isBodyElement, isCanvasElement, isCustomElement, isElementNode, isHTMLElement, isHTMLElementNode, isIFrameElement, isImageElement, isInputElement, isLIElement, isOLElement, isScriptElement, isSelectElement, isSlotElement, isStyleElement, isSVGElement, isSVGElementNode, isTextareaElement, isTextNode, isVideoElement };
 export declare const parseTree: (context: Context, element: HTMLElement) => ElementContainer;

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

@@ -38,12 +38,8 @@ export declare class BackgroundRenderer {
      * CanvasPatterns are tied to the rendering context and must not be
      * shared across different render passes. This cache lives for the
      * duration of one html2canvas() call.
-     *
-     * Also reused for linear-gradient and repeating-linear-gradient
-     * pattern canvases to avoid redundant offscreen canvas allocation.
      */
     private readonly patternCache;
-    private static readonly PATTERN_CACHE_MAX;
     constructor(deps: BackgroundRendererDependencies);
     /**
      * Render background images for a container
@@ -95,10 +91,4 @@ export declare class BackgroundRenderer {
      * @param paths - Array of path points
      */
     private path;
-    /**
-     * LRU-aware get: returns value and promotes the entry to end of Map.
-     */
-    private lruGet;
-    /** LRU-aware set for CanvasPattern caches. Evicts oldest entry on overflow. */
-    private lruSet;
 }

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

@@ -6,6 +6,8 @@
  * - Transform effects (matrix transformations)
  * - Clip effects (overflow / border-radius clipping via Path[])
  * - Clip-path effects (CSS clip-path shapes: inset, circle, ellipse, polygon, path)
+ * - Blend effects (mix-blend-mode)
+ * - Filter effects (CSS filter functions)
  */
 import { IElementEffect } from '../effects';
 import { Path } from '../path';
@@ -26,40 +28,63 @@ export interface EffectsPathCallback {
  *
  * Manages rendering effects stack including opacity, transforms, and clipping.
  * Extracted from CanvasRenderer to improve code organization and maintainability.
+ *
+ * ## Save/restore optimisation
+ *
+ * Canvas `save()` / `restore()` snapshot and restore the entire canvas state
+ * (transform matrix, clip region, compositing mode, filter, shadow, …) which
+ * is relatively expensive. The old implementation called `save()` / `restore()`
+ * for every single effect unconditionally.
+ *
+ * This implementation does a **batch pre-scan** before applying effects:
+ *
+ * | Effect type        | Modifies             | Reversible?   | Needs save? |
+ * |--------------------|----------------------|---------------|-------------|
+ * | TransformEffect     | transform matrix     | ❌ irreversible | **YES**     |
+ * | ClipEffect         | clip region          | ❌ cumulative   | **YES**     |
+ * | ClipPathEffect     | clip region          | ❌ cumulative   | **YES**     |
+ * | OpacityEffect      | globalAlpha          | ✅ scalar       | NO          |
+ * | BlendEffect        | globalCompositeOp    | ✅ scalar       | NO          |
+ * | FilterEffect       | filter + shadow      | ✅ string+vec   | NO          |
+ *
+ * When the batch contains *only* lightweight effects (opacity / blend / filter)
+ * we skip `save()` entirely and manually reset properties on pop.
+ *
+ * When the batch contains at least one heavyweight effect (transform / clip /
+ * clip-path) we call `save()` **once** before the first heavyweight effect and
+ * `restore()` **once** when that effect is popped.
  */
 export declare class EffectsRenderer {
     private readonly ctx;
     private readonly pathCallback;
     private readonly activeEffects;
+    /** Whether a canvas state save was performed for the current batch. */
+    private didSave;
+    /** Index (0-based, from start of activeEffects array) of the last
+     *  heavyweight effect in the batch — the one whose pop triggers
+     *  restore(). Set to -1 when no save was performed. */
+    private saveAtDepth;
     constructor(deps: EffectsRendererDependencies, pathCallback: EffectsPathCallback);
     /**
-     * Apply multiple effects
-     * Clears existing effects and applies new ones
-     *
-     * @param effects - Array of effects to apply
+     * Apply multiple effects.
+     * Clears existing effects and applies new ones.
      */
     applyEffects(effects: IElementEffect[]): void;
     /**
-     * Apply a single effect
-     *
-     * @param effect - Effect to apply
+     * Apply a single effect (called internally by applyEffects).
      */
-    applyEffect(effect: IElementEffect): void;
+    private applyEffect;
     /**
-     * Remove the most recent effect
-     * Restores the canvas state before the effect was applied
+     * Remove the most recent effect.
+     * Restores canvas state if needed.
      */
-    popEffect(): void;
+    private popEffect;
     /**
-     * Get the current number of active effects
-     *
-     * @returns Number of active effects
+     * Get the current number of active effects.
      */
     getActiveEffectCount(): number;
     /**
-     * Check if there are any active effects
-     *
-     * @returns True if there are active effects
+     * Check if there are any active effects.
      */
     hasActiveEffects(): boolean;
 }

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

@@ -37,7 +37,19 @@ export declare class TextRenderer {
     private readonly ctx;
     private readonly options;
     private readonly decorationRenderer;
+    /**
+     * Per-render glyph width cache. Keyed by glyph + font string,
+     * avoids redundant `measureText` calls when letter-spacing is non-zero.
+     * Cleared at the start of each renderTextNode call.
+     */
+    private glyphWidthCache;
     constructor(deps: TextRendererDependencies);
+    /**
+     * Returns the cached width for a glyph+font pair, measuring via
+     * measureText if not yet cached. Only used when letterSpacing !== 0
+     * (the `canRenderWholeText` fast path handles the zero-spacing case).
+     */
+    private cachedMeasureText;
     /**
      * Iterate grapheme clusters one-by-one, applying correct letter-spacing and
      * per-script baseline for each character.

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

@@ -1,6 +1,8 @@
 import { ElementContainer } from '../dom/element-container';
 import { BoundCurves } from './bound-curves';
-import { EffectTarget, IElementEffect } from './effects';
+import { ClipPathEffect, EffectTarget, IElementEffect } from './effects';
+import { Bounds } from '../css/layout/bounds';
+import { ClipPathValue, ShapeRadius } from '../css/property-descriptors/clip-path';
 export declare class StackingContext {
     element: ElementPaint;
     negativeZIndex: StackingContext[];
@@ -21,4 +23,27 @@ export declare class ElementPaint {
     constructor(container: ElementContainer, parent: ElementPaint | null);
     getEffects(target: EffectTarget): IElementEffect[];
 }
+/** @internal – exported for testing only. */
+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()`.
+ *
+ * @param r       - The ShapeRadius (keyword or length-percentage).
+ * @param center  - Absolute center coordinate on this axis (cx or cy).
+ * @param start   - Absolute start of the reference box on this axis.
+ * @param end     - Absolute end of the reference box on this axis.
+ * @param dimRef  - Reference dimension for resolving a length-percentage value.
+ * @internal – exported for testing only.
+ */
+export declare const resolveAxisRadius: (r: ShapeRadius, center: number, start: number, end: number, dimRef: number) => number;
+/**
+ * Convert a parsed ClipPathValue + element bounds into a ClipPathEffect whose
+ * `applyClip` callback draws the clip shape directly onto the canvas context.
+ *
+ * All coordinates are computed in page-absolute space at construction time so
+ * the callback itself is allocation-free and executes synchronously.
+ * @internal – exported for testing only.
+ */
+export declare const buildClipPathEffect: (clipPath: ClipPathValue, bounds: Bounds) => ClipPathEffect | null;
 export declare const parseStackingContexts: (container: ElementContainer) => StackingContext;

package/package.json

@@ -2,7 +2,7 @@
   "name": "html2canvas-pro",
   "description": "Screenshots with JavaScript. Next generation!",
   "type": "module",
-  "main": "dist/html2canvas-pro.js",
+  "main": "dist/html2canvas-pro.cjs",
   "module": "dist/html2canvas-pro.esm.js",
   "typings": "dist/types/index.d.ts",
   "browser": "dist/html2canvas-pro.esm.js",
@@ -15,11 +15,11 @@
     ".": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/html2canvas-pro.esm.js",
-      "require": "./dist/html2canvas-pro.js",
+      "require": "./dist/html2canvas-pro.cjs",
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.2.4",
+  "version": "2.3.0",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -87,14 +87,13 @@
     "puppeteer": "^24.34.0",
     "replace-in-file": "^8.4.0",
     "rimraf": "^6.0.1",
-    "rolldown": "^1.1.2",
+    "rolldown": "^1.2.0",
     "serve-index": "^1.9.1",
     "slash": "5.1.0",
     "ts-node": "^10.9.2",
     "tsx": "^4.22.3",
     "typedoc": "^0.28.19",
     "typescript": "^5.5.4",
-    "uglify-js": "^3.13.10",
     "vitepress": "^1.6.4",
     "vitest": "^3.2.6",
     "yargs": "^18.0.0"
@@ -111,9 +110,8 @@
   },
   "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 && pnpm build:minify",
+    "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",
     "build:testrunner": "rolldown -c tests/rolldown.testrunner.config.ts",
-    "build:minify": "uglifyjs --compress --comments /^!/ -o dist/html2canvas-pro.min.js --mangle -- dist/html2canvas-pro.js",
     "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",