html2canvas-pro 2.0.3 → 2.1.0

package/package.json

@@ -5,7 +5,13 @@
   "main": "dist/html2canvas-pro.js",
   "module": "dist/html2canvas-pro.esm.js",
   "typings": "dist/types/index.d.ts",
-  "browser": "dist/html2canvas-pro.js",
+  "browser": "dist/html2canvas-pro.esm.js",
+  "sideEffects": false,
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE"
+  ],
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -14,7 +20,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.0.3",
+  "version": "2.1.0",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -44,17 +50,16 @@
     "@types/express": "^5.0.6",
     "@types/filenamify-url": "^2.0.1",
     "@types/glob": "^9.0.0",
-    "@types/jest": "^29.5.12",
-    "@types/jest-image-snapshot": "^6.4.0",
     "@types/karma": "^6.3.0",
-    "@types/mkdirp": "^2.0.0",
     "@types/mocha": "^10.0.7",
     "@types/node": "^25.0.3",
     "@types/platform": "^1.3.4",
+    "@types/pngjs": "^6.0.5",
     "@types/promise-polyfill": "^6.0.3",
     "@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",
     "base64-arraybuffer": "1.0.2",
     "body-parser": "^2.2.1",
@@ -71,11 +76,9 @@
     "filenamify-url": "4.0.0",
     "glob": "^13.0.0",
     "husky": "^9.1.7",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^30.2.0",
-    "jest-image-snapshot": "^6.4.0",
     "jquery": "^3.5.1",
     "js-polyfills": "^0.1.42",
+    "jsdom": "^29.1.1",
     "karma": "^6.3.2",
     "karma-chrome-launcher": "^3.1.0",
     "karma-edge-launcher": "^0.4.2",
@@ -84,11 +87,12 @@
     "karma-junit-reporter": "^2.0.1",
     "karma-mocha": "^2.0.1",
     "karma-safarinative-launcher": "^1.1.0",
-    "karma-sauce-launcher": "^4.3.6",
     "lint-staged": "^16.2.7",
     "mocha": "^11.7.5",
     "node-simctl": "^8.1.2",
+    "pixelmatch": "^7.2.0",
     "platform": "^1.3.6",
+    "pngjs": "^7.0.0",
     "prettier": "^3.3.3",
     "puppeteer": "^24.34.0",
     "replace-in-file": "^8.4.0",
@@ -98,47 +102,51 @@
     "serve-index": "^1.9.1",
     "slash": "5.1.0",
     "standard-version": "^9.5.0",
-    "ts-jest": "^29.1.5",
     "ts-node": "^10.9.2",
     "tsx": "^4.22.3",
+    "typedoc": "^0.28.19",
     "typescript": "^5.5.4",
     "uglify-js": "^3.13.10",
-    "vitepress": "^1.3.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.2.6",
     "yargs": "^18.0.0"
   },
+  "dependencies": {
+    "css-line-break": "^2.1.0",
+    "text-segmentation": "^1.0.3"
+  },
+  "lint-staged": {
+    "{src,tests}/**/*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
   "scripts": {
-    "prebuild": "rimraf dist/ && rimraf build/ && mkdirp dist && mkdirp build",
-    "build": "tsc --module commonjs && npx tsx --tsconfig tsconfig.json ./node_modules/.bin/rollup -c rollup.config.ts && npm run build:create-reftest-list && npx tsx --tsconfig tests/tsconfig.json ./node_modules/.bin/rollup -c tests/rollup.config.ts && npm run build:minify",
-    "build:testrunner": "npx tsx --tsconfig tests/tsconfig.json ./node_modules/.bin/rollup -c tests/rollup.config.ts",
+    "prebuild": "rimraf dist/ && rimraf build/ && mkdir -p dist && mkdir -p build",
+    "build": "tsc --module commonjs -p tsconfig.build.json && rollup --configPlugin typescript -c rollup.config.ts && pnpm build:create-reftest-list && rollup --configPlugin typescript -c tests/rollup.config.ts && pnpm build:minify",
+    "build:testrunner": "rollup --configPlugin typescript -c tests/rollup.config.ts",
     "build:minify": "uglifyjs --compress --comments /^!/ -o dist/html2canvas-pro.min.js --mangle -- dist/html2canvas-pro.js",
-    "build:reftest-result-list": "npx tsx scripts/create-reftest-result-list.ts",
-    "build:create-reftest-list": "npx tsx scripts/create-reftest-list.ts tests/reftests/ignore.txt build/reftests.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",
     "format": "prettier --write \"{src,tests,scripts}/**/*.ts\"",
     "lint": "eslint src/**/*.ts --max-warnings 0",
-    "test": "npm run lint && npm run unittest && npm run karma",
-    "unittest": "jest",
-    "reftests-diff": "mkdirp tmp/snapshots && jest --roots=tests --testMatch=**/reftest-diff.ts",
+    "test": "pnpm lint && pnpm unittest && pnpm karma",
+    "unittest": "vitest run",
+    "unittest:coverage": "vitest run --coverage",
+    "bench:css-parse": "tsx scripts/benchmarks/css-parse.bench.ts",
+    "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": "rollup -c rollup.config.ts -w",
-    "watch:unittest": "mocha --require tsx/register --watch-extensions ts -w src/**/__tests__/*.ts",
-    "start": "npx tsx tests/server --port=8080 --cors=8081",
+    "watch": "rollup --configPlugin typescript -c rollup.config.ts -w",
+    "watch:unittest": "vitest",
+    "start": "tsx tests/server --port=8080 --cors=8081",
     "commitlint": "commitlint --config .commitlintrc.json -e -V",
     "tag": "sh scripts/create-tag.sh",
-    "prepare": "if [ \"$SKIP_PREPARE\" != \"true\" ]; then husky install; fi",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  },
-  "dependencies": {
-    "css-line-break": "^2.1.0",
-    "text-segmentation": "^1.0.3"
-  },
-  "lint-staged": {
-    "{src,tests}/**/*.ts": [
-      "prettier --write",
-      "eslint --fix"
-    ]
+    "docs:preview": "vitepress preview docs",
+    "docs:api": "typedoc",
+    "docs:api:watch": "typedoc --watch"
   }
-}
+}

package/src/__tests__/index.ts

@@ -0,0 +1,99 @@
+import html2canvas from '../index';
+
+import { CanvasRenderer } from '../render/canvas/canvas-renderer';
+import { DocumentCloner } from '../dom/document-cloner';
+import { COLORS } from '../css/types/color';
+
+vi.mock('../core/logger');
+vi.mock('../css/layout/bounds');
+vi.mock('../dom/document-cloner');
+vi.mock('../dom/node-parser', () => {
+    return {
+        isBodyElement: () => false,
+        isHTMLElement: () => false,
+        parseTree: vi.fn().mockImplementation(() => {
+            return { styles: {}, restoreTree: vi.fn() };
+        })
+    };
+});
+
+vi.mock('../render/stacking-context');
+vi.mock('../render/canvas/canvas-renderer');
+
+describe('html2canvas', () => {
+    const element = {
+        ownerDocument: {
+            defaultView: {
+                document: {
+                    createElement: () => ({ href: '' })
+                },
+                location: { href: 'http://localhost/' },
+                pageXOffset: 12,
+                pageYOffset: 34,
+                innerWidth: 800,
+                innerHeight: 600
+            }
+        }
+    } as unknown as HTMLElement;
+
+    it('should render with an element', async () => {
+        DocumentCloner.destroy = vi.fn().mockReturnValue(true);
+        await html2canvas(element);
+        expect(CanvasRenderer).toHaveBeenLastCalledWith(
+            expect.objectContaining({
+                cache: expect.any(Object),
+                logger: expect.any(Object),
+                windowBounds: expect.objectContaining({ left: 12, top: 34 })
+            }),
+            expect.objectContaining({
+                backgroundColor: 0xffffffff,
+                scale: 1,
+                height: 50,
+                width: 200,
+                x: 0,
+                y: 0,
+                canvas: undefined
+            })
+        );
+        expect(DocumentCloner.destroy).toBeCalled();
+    });
+
+    it('should have transparent background with backgroundColor: null', async () => {
+        await html2canvas(element, { backgroundColor: null });
+        expect(CanvasRenderer).toHaveBeenLastCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                backgroundColor: COLORS.TRANSPARENT
+            })
+        );
+    });
+
+    it('should use existing canvas when given as option', async () => {
+        const canvas = {} as HTMLCanvasElement;
+        await html2canvas(element, { canvas });
+        expect(CanvasRenderer).toHaveBeenLastCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                canvas
+            })
+        );
+    });
+
+    it('should not remove cloned window when removeContainer: false', async () => {
+        DocumentCloner.destroy = vi.fn();
+        await html2canvas(element, { removeContainer: false });
+        expect(CanvasRenderer).toHaveBeenLastCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                backgroundColor: 0xffffffff,
+                scale: 1,
+                height: 50,
+                width: 200,
+                x: 0,
+                y: 0,
+                canvas: undefined
+            })
+        );
+        expect(DocumentCloner.destroy).not.toBeCalled();
+    });
+});

package/src/config.ts

@@ -0,0 +1,107 @@
+import { Cache } from './core/cache-storage';
+
+/**
+ * Configuration options for Html2Canvas
+ *
+ * This class manages global configuration without using module-level static variables.
+ * Each html2canvas invocation can have its own configuration instance.
+ */
+export interface ConfigOptions {
+    /**
+     * Window object to use for DOM operations
+     */
+    window?: Window;
+
+    /**
+     * CSP nonce for inline styles
+     * See: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+     */
+    cspNonce?: string;
+
+    /**
+     * Cache instance to reuse across multiple calls
+     * Useful for avoiding redundant image loads
+     */
+    cache?: Cache;
+}
+
+/**
+ * Html2Canvas Configuration
+ *
+ * Manages configuration state for html2canvas rendering.
+ * Eliminates the need for global static variables.
+ */
+export class Html2CanvasConfig {
+    readonly window: Window;
+    readonly cspNonce?: string;
+    readonly cache?: Cache;
+
+    constructor(options: ConfigOptions = {}) {
+        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: HTMLElement, options: Partial<ConfigOptions> = {}): Html2CanvasConfig {
+        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: Partial<ConfigOptions> = {}): Html2CanvasConfig {
+        return new Html2CanvasConfig({
+            window: options.window || this.window,
+            cspNonce: options.cspNonce ?? this.cspNonce,
+            cache: options.cache ?? this.cache
+        });
+    }
+}
+
+/**
+ * Default global configuration (for backward compatibility)
+ * @deprecated Use Html2CanvasConfig instances instead
+ */
+let _defaultConfig: Html2CanvasConfig | null = null;
+
+/**
+ * Set default configuration
+ * @deprecated Pass configuration directly to html2canvas instead
+ */
+export function setDefaultConfig(config: Html2CanvasConfig): void {
+    console.warn('[html2canvas-pro] setDefaultConfig is deprecated. Pass configuration to html2canvas directly.');
+    _defaultConfig = config;
+}
+
+/**
+ * Get default configuration
+ * @deprecated Pass configuration directly to html2canvas instead
+ */
+export function getDefaultConfig(): Html2CanvasConfig | null {
+    return _defaultConfig;
+}

package/src/core/__mocks__/cache-storage.ts

@@ -0,0 +1 @@
+export class CacheStorage {}

package/src/core/__mocks__/context.ts

@@ -0,0 +1,19 @@
+import { logger, Logger } from './logger';
+
+export class Context {
+    readonly logger: Logger = logger;
+
+    readonly _cache: { [key: string]: Promise<any> } = {};
+
+    readonly cache: any;
+
+    constructor() {
+        this.cache = {
+            addImage: vi.fn().mockImplementation((src: string): Promise<void> => {
+                const result = Promise.resolve();
+                this._cache[src] = result;
+                return result;
+            })
+        };
+    }
+}

package/{dist/lib/core/__mocks__/features.js → src/core/__mocks__/features.ts}

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEATURES = void 0;
-exports.FEATURES = {
+export const FEATURES = {
     SUPPORT_RANGE_BOUNDS: true,
     SUPPORT_SVG_DRAWING: true,
     SUPPORT_FOREIGNOBJECT_DRAWING: true,
@@ -9,4 +6,3 @@ exports.FEATURES = {
     SUPPORT_RESPONSE_TYPE: true,
     SUPPORT_CORS_XHR: true
 };
-//# sourceMappingURL=features.js.map

package/src/core/__mocks__/logger.ts

@@ -0,0 +1,17 @@
+export class Logger {
+    debug(): void {}
+
+    static create(): void {}
+
+    static destroy(): void {}
+
+    static getInstance(): Logger {
+        return logger;
+    }
+
+    info(): void {}
+
+    error(): void {}
+}
+
+export const logger = new Logger();

package/{dist/lib/core/__tests__/cache-storage.test.js → src/core/__tests__/cache-storage.test.ts}

@@ -1,20 +1,20 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const assert_1 = require("assert");
-const cache_storage_1 = require("../cache-storage");
-const context_1 = require("../context");
-const bounds_1 = require("../../css/layout/bounds");
-const config_1 = require("../../config");
+import { strictEqual, ok, deepStrictEqual } from 'assert';
+import { Cache, ResourceOptions } from '../cache-storage';
+import { Context } from '../context';
+import { Bounds } from '../../css/layout/bounds';
+import { Html2CanvasConfig } from '../../config';
+
 describe('Cache LRU', () => {
-    let context;
-    let cache;
+    let context: Context;
+    let cache: Cache;
+
     beforeEach(() => {
         const mockWindow = {
             document: {
-                createElement: (_name) => {
+                createElement: (_name: string) => {
                     let _href = '';
                     return {
-                        set href(value) {
+                        set href(value: string) {
                             _href = value;
                         },
                         get href() {
@@ -33,34 +33,46 @@ describe('Cache LRU', () => {
                 }
             },
             location: { href: 'http://localhost/' }
-        };
-        const config = new config_1.Html2CanvasConfig({ window: mockWindow });
-        context = new context_1.Context({
-            logging: false,
-            imageTimeout: 15000,
-            useCORS: false,
-            allowTaint: false
-        }, new bounds_1.Bounds(0, 0, 800, 600), config);
-        const options = {
+        } as unknown as Window;
+
+        const config = new Html2CanvasConfig({ window: mockWindow });
+        context = new Context(
+            {
+                logging: false,
+                imageTimeout: 15000,
+                useCORS: false,
+                allowTaint: false
+            },
+            new Bounds(0, 0, 800, 600),
+            config
+        );
+
+        const options: ResourceOptions = {
             imageTimeout: 15000,
             useCORS: false,
             allowTaint: false,
             maxCacheSize: 3 // Small size for testing
         };
-        cache = new cache_storage_1.Cache(context, options);
+
+        cache = new Cache(context, options);
     });
+
     it('should enforce maximum cache size', () => {
-        (0, assert_1.strictEqual)(cache.getMaxSize(), 3);
-        (0, assert_1.strictEqual)(cache.size(), 0);
+        strictEqual(cache.getMaxSize(), 3);
+        strictEqual(cache.size(), 0);
     });
+
     it('should add images to cache', () => {
         const blob1 = 'blob:http://localhost/image1';
         const blob2 = 'blob:http://localhost/image2';
+
         cache.addImage(blob1);
-        (0, assert_1.strictEqual)(cache.size(), 1);
+        strictEqual(cache.size(), 1);
+
         cache.addImage(blob2);
-        (0, assert_1.strictEqual)(cache.size(), 2);
+        strictEqual(cache.size(), 2);
     });
+
     it('should not exceed max cache size', () => {
         const blobs = [
             'blob:http://localhost/image1',
@@ -68,91 +80,126 @@ describe('Cache LRU', () => {
             'blob:http://localhost/image3',
             'blob:http://localhost/image4' // This should trigger eviction
         ];
+
         blobs.forEach((blob) => cache.addImage(blob));
+
         // Should not exceed max size (3)
-        (0, assert_1.strictEqual)(cache.size(), 3);
+        strictEqual(cache.size(), 3);
     });
+
     it('should evict least recently used entry when full', async () => {
         const blob1 = 'blob:http://localhost/image1';
         const blob2 = 'blob:http://localhost/image2';
         const blob3 = 'blob:http://localhost/image3';
         const blob4 = 'blob:http://localhost/image4';
+
         // Add 3 images (fill cache)
         cache.addImage(blob1);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.addImage(blob2);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.addImage(blob3);
         await new Promise((resolve) => setTimeout(resolve, 10));
-        (0, assert_1.strictEqual)(cache.size(), 3);
+
+        strictEqual(cache.size(), 3);
+
         // Access blob2 and blob3 (update their access time)
         cache.match(blob2);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.match(blob3);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         // Add blob4 - should evict blob1 (oldest, never accessed)
         cache.addImage(blob4);
-        (0, assert_1.strictEqual)(cache.size(), 3);
+
+        strictEqual(cache.size(), 3);
+
         // blob1 should be evicted
-        (0, assert_1.strictEqual)(cache.match(blob1), undefined);
+        strictEqual(cache.match(blob1), undefined);
+
         // blob2, blob3, blob4 should exist
-        (0, assert_1.ok)(cache.match(blob2) !== undefined);
-        (0, assert_1.ok)(cache.match(blob3) !== undefined);
-        (0, assert_1.ok)(cache.match(blob4) !== undefined);
+        ok(cache.match(blob2) !== undefined);
+        ok(cache.match(blob3) !== undefined);
+        ok(cache.match(blob4) !== undefined);
     });
+
     it('should update access time on repeated access', async () => {
         const blob1 = 'blob:http://localhost/image1';
         const blob2 = 'blob:http://localhost/image2';
         const blob3 = 'blob:http://localhost/image3';
+
         cache.addImage(blob1);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.addImage(blob2);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.addImage(blob3);
-        (0, assert_1.strictEqual)(cache.size(), 3);
+        strictEqual(cache.size(), 3);
+
         // Access blob1 multiple times (update access time)
         cache.match(blob1);
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         cache.addImage(blob1); // Should update access time
         await new Promise((resolve) => setTimeout(resolve, 10));
+
         // Add 4th image - should evict blob2 (oldest unaccessed)
         const blob4 = 'blob:http://localhost/image4';
         cache.addImage(blob4);
-        (0, assert_1.strictEqual)(cache.size(), 3);
-        (0, assert_1.strictEqual)(cache.match(blob2), undefined); // Evicted
-        (0, assert_1.ok)(cache.match(blob1) !== undefined); // Still exists
+
+        strictEqual(cache.size(), 3);
+        strictEqual(cache.match(blob2), undefined); // Evicted
+        ok(cache.match(blob1) !== undefined); // Still exists
     });
+
     it('should clear all cache entries', () => {
         cache.addImage('blob:http://localhost/image1');
         cache.addImage('blob:http://localhost/image2');
-        (0, assert_1.strictEqual)(cache.size(), 2);
+        strictEqual(cache.size(), 2);
+
         cache.clear();
-        (0, assert_1.strictEqual)(cache.size(), 0);
+        strictEqual(cache.size(), 0);
     });
+
+    it('should return cache keys', async () => {
+        const blob1 = 'blob:http://localhost/image1';
+        const blob2 = 'blob:http://localhost/image2';
+
+        cache.addImage(blob1);
+        cache.addImage(blob2);
+
+        deepStrictEqual(await cache.keys(), [blob1, blob2]);
+    });
+
     it('should throw error for invalid max size', () => {
-        const options = {
+        const options: ResourceOptions = {
             imageTimeout: 15000,
             useCORS: false,
             allowTaint: false,
             maxCacheSize: 0 // Invalid
         };
+
         try {
-            new cache_storage_1.Cache(context, options);
-            (0, assert_1.ok)(false, 'Should have thrown error');
-        }
-        catch (error) {
-            (0, assert_1.ok)(error.message.includes('at least 1'));
+            new Cache(context, options);
+            ok(false, 'Should have thrown error');
+        } catch (error: any) {
+            ok(error.message.includes('at least 1'));
         }
     });
+
     it('should use default max size if not specified', () => {
-        const options = {
+        const options: ResourceOptions = {
             imageTimeout: 15000,
             useCORS: false,
             allowTaint: false
             // maxCacheSize not specified
         };
-        const cacheWithDefault = new cache_storage_1.Cache(context, options);
-        (0, assert_1.strictEqual)(cacheWithDefault.getMaxSize(), 100); // Default
+
+        const cacheWithDefault = new Cache(context, options);
+        strictEqual(cacheWithDefault.getMaxSize(), 100); // Default
     });
 });
-//# sourceMappingURL=cache-storage.test.js.map