html2canvas-pro 1.6.6 → 2.0.0

package/dist/types/core/cache-storage.d.ts

@@ -1,9 +1,26 @@
 import { Context } from './context';
+/**
+ * CacheStorage (Deprecated static methods)
+ *
+ * @deprecated The static methods of CacheStorage are deprecated.
+ * Use OriginChecker class instead for instance-based origin checking.
+ *
+ * For backward compatibility, these methods remain but should not be used in new code.
+ */
 export declare class CacheStorage {
     private static _link?;
     private static _origin;
+    /**
+     * @deprecated Use OriginChecker.getOrigin() instead
+     */
     static getOrigin(url: string): string;
+    /**
+     * @deprecated Use OriginChecker.isSameOrigin() instead
+     */
     static isSameOrigin(src: string): boolean;
+    /**
+     * @deprecated No longer needed. OriginChecker is created per Context.
+     */
     static setContext(window: Window): void;
 }
 export interface ResourceOptions {
@@ -12,14 +29,38 @@ export interface ResourceOptions {
     allowTaint: boolean;
     proxy?: string;
     customIsSameOrigin?: (this: void, src: string, oldFn: (src: string) => boolean) => boolean | Promise<boolean>;
+    maxCacheSize?: number;
 }
 export declare class Cache {
     private readonly context;
     private readonly _options;
     private readonly _cache;
+    private readonly maxSize;
+    private readonly _pendingOperations;
     constructor(context: Context, _options: ResourceOptions);
     addImage(src: string): Promise<void>;
-    match(src: string): Promise<any>;
+    private _addImageInternal;
+    match(src: string): Promise<any> | undefined;
+    /**
+     * Set a value in cache with LRU eviction
+     */
+    private set;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Get cache size
+     */
+    size(): number;
+    /**
+     * Get max cache size
+     */
+    getMaxSize(): number;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
     private loadImage;
     private has;
     keys(): Promise<string[]>;

package/dist/types/core/context.d.ts

@@ -1,6 +1,8 @@
 import { Logger } from './logger';
 import { Cache, ResourceOptions } from './cache-storage';
 import { Bounds } from '../css/layout/bounds';
+import { OriginChecker } from './origin-checker';
+import { Html2CanvasConfig } from '../config';
 export type ContextOptions = {
     logging: boolean;
     cache?: Cache;
@@ -10,6 +12,8 @@ export declare class Context {
     private readonly instanceName;
     readonly logger: Logger;
     readonly cache: Cache;
+    readonly originChecker: OriginChecker;
+    readonly config: Html2CanvasConfig;
     private static instanceCount;
-    constructor(options: ContextOptions, windowBounds: Bounds);
+    constructor(options: ContextOptions, windowBounds: Bounds, config: Html2CanvasConfig);
 }

package/dist/types/core/origin-checker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Origin Checker
+ *
+ * Provides origin checking functionality without global static state.
+ * Each instance maintains its own anchor element and origin reference.
+ *
+ * Replaces the static methods in CacheStorage with instance-based approach.
+ */
+export declare class OriginChecker {
+    private readonly link;
+    private readonly origin;
+    constructor(window: Window);
+    /**
+     * Get the origin (protocol + hostname + port) of a URL
+     *
+     * @param url - URL to parse
+     * @returns Origin string (e.g., "https://example.com:8080")
+     */
+    getOrigin(url: string): string;
+    /**
+     * Check if a URL is from the same origin as the context
+     *
+     * @param src - URL to check
+     * @returns true if same origin, false otherwise
+     */
+    isSameOrigin(src: string): boolean;
+    /**
+     * Get the current context origin
+     *
+     * @returns The origin of the context window
+     */
+    getContextOrigin(): string;
+}

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

@@ -0,0 +1,131 @@
+import { Context } from './context';
+/**
+ * Performance Metric
+ *
+ * Represents a single performance measurement
+ */
+export interface PerformanceMetric {
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Performance Summary
+ *
+ * Aggregated performance data
+ */
+export interface PerformanceSummary {
+    totalDuration: number;
+    metrics: PerformanceMetric[];
+    breakdown: Array<{
+        name: string;
+        duration: number;
+        percentage: string;
+    }>;
+}
+/**
+ * Performance Monitor
+ *
+ * Tracks performance metrics throughout the rendering pipeline.
+ * Provides insights into where time is spent during rendering.
+ *
+ * Usage:
+ * ```typescript
+ * const monitor = new PerformanceMonitor(context);
+ *
+ * monitor.start('clone');
+ * await cloneDocument();
+ * monitor.end('clone');
+ *
+ * const summary = monitor.getSummary();
+ * ```
+ */
+export declare class PerformanceMonitor {
+    private readonly context;
+    private readonly activeMetrics;
+    private readonly completedMetrics;
+    private readonly enabled;
+    private readonly getTime;
+    constructor(context: Context | null, enabled?: boolean);
+    /**
+     * Start measuring a performance metric
+     *
+     * @param name - Unique name for this metric
+     * @param metadata - Optional metadata to attach
+     */
+    start(name: string, metadata?: Record<string, any>): void;
+    /**
+     * End measuring a performance metric
+     *
+     * @param name - Name of the metric to end
+     * @returns The completed metric, or undefined if not found
+     */
+    end(name: string): PerformanceMetric | undefined;
+    /**
+     * Measure a synchronous function
+     *
+     * @param name - Name for this measurement
+     * @param fn - Function to measure
+     * @param metadata - Optional metadata
+     * @returns The function's return value
+     */
+    measure<T>(name: string, fn: () => T, metadata?: Record<string, any>): T;
+    /**
+     * Measure an asynchronous function
+     *
+     * @param name - Name for this measurement
+     * @param fn - Async function to measure
+     * @param metadata - Optional metadata
+     * @returns Promise resolving to the function's return value
+     */
+    measureAsync<T>(name: string, fn: () => Promise<T>, metadata?: Record<string, any>): Promise<T>;
+    /**
+     * Get all completed metrics
+     *
+     * @returns Array of completed performance metrics
+     */
+    getMetrics(): PerformanceMetric[];
+    /**
+     * Get a specific metric by name
+     *
+     * @param name - Metric name
+     * @returns The metric, or undefined if not found
+     */
+    getMetric(name: string): PerformanceMetric | undefined;
+    /**
+     * Get performance summary
+     *
+     * @returns Aggregated performance data
+     */
+    getSummary(): PerformanceSummary;
+    /**
+     * Log performance summary to console
+     */
+    logSummary(): void;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Check if monitoring is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get active (uncompleted) metrics
+     * Useful for debugging leaked measurements
+     */
+    getActiveMetrics(): string[];
+}
+/**
+ * Create a no-op performance monitor for production
+ * Has minimal overhead when disabled
+ */
+export declare class NoOpPerformanceMonitor extends PerformanceMonitor {
+    constructor();
+    start(): void;
+    end(): undefined;
+    measure<T>(_name: string, fn: () => T): T;
+    measureAsync<T>(_name: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/types/core/validator.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Input Validator
+ *
+ * Provides validation and sanitization for user inputs to prevent security vulnerabilities
+ * including SSRF, XSS, and injection attacks.
+ */
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    sanitized?: any;
+    /**
+     * Indicates if runtime validation is recommended
+     * (e.g., for proxy URLs to prevent DNS rebinding attacks)
+     */
+    requiresRuntimeCheck?: boolean;
+}
+/**
+ * Validator configuration
+ */
+export interface ValidatorConfig {
+    /**
+     * Allowed proxy domains for SSRF prevention
+     * If empty, no domain restrictions
+     */
+    allowedProxyDomains?: string[];
+    /**
+     * Allow localhost/127.0.0.1 as proxy URL. Only set for development or test (e.g. Karma reftests).
+     * @default false
+     */
+    allowLocalhostProxy?: boolean;
+    /**
+     * Maximum allowed image timeout in milliseconds
+     */
+    maxImageTimeout?: number;
+    /**
+     * Whether to allow data URLs
+     */
+    allowDataUrls?: boolean;
+    /**
+     * Custom validation function
+     */
+    customValidator?: (value: any, type: string) => ValidationResult;
+}
+/**
+ * Input Validator
+ *
+ * Validates and sanitizes user inputs for security and correctness.
+ */
+export declare class Validator {
+    private readonly config;
+    constructor(config?: ValidatorConfig);
+    /**
+     * Validate a URL
+     *
+     * @param url - URL to validate
+     * @param context - Context for validation (e.g., 'proxy', 'image')
+     * @returns Validation result
+     */
+    validateUrl(url: string, context?: 'proxy' | 'image' | 'general'): ValidationResult;
+    /**
+     * Check if a hostname is a private IP address
+     */
+    private isPrivateIP;
+    /**
+     * Check if an IPv6 address is private or special
+     * Handles compressed IPv6 addresses (e.g., ::1, fc00::1)
+     */
+    private isPrivateIPv6;
+    /**
+     * Expand compressed IPv6 address to full form
+     * e.g., "::1" -> "0000:0000:0000:0000:0000:0000:0000:0001"
+     */
+    private expandIPv6;
+    /**
+     * Fallback prefix matching for IPv6 when expansion fails
+     */
+    private isPrivateIPv6Prefix;
+    /**
+     * Validate CSP nonce
+     *
+     * @param nonce - CSP nonce to validate
+     * @returns Validation result
+     */
+    validateCspNonce(nonce: string): ValidationResult;
+    /**
+     * Validate image timeout
+     *
+     * @param timeout - Timeout in milliseconds
+     * @returns Validation result
+     */
+    validateImageTimeout(timeout: number): ValidationResult;
+    /**
+     * Validate window dimensions
+     *
+     * @param width - Window width
+     * @param height - Window height
+     * @returns Validation result
+     */
+    validateDimensions(width: number, height: number): ValidationResult;
+    /**
+     * Validate scale factor
+     *
+     * @param scale - Scale factor
+     * @returns Validation result
+     */
+    validateScale(scale: number): ValidationResult;
+    /**
+     * Validate HTML element
+     *
+     * @param element - Element to validate
+     * @returns Validation result
+     */
+    validateElement(element: any): ValidationResult;
+    /**
+     * Validate entire options object
+     *
+     * @param options - Options to validate
+     * @returns Validation result with all errors
+     */
+    validateOptions(options: any): ValidationResult;
+}
+/**
+ * Create a default validator instance
+ */
+export declare function createDefaultValidator(config?: ValidatorConfig): Validator;
+/**
+ * Create a strict validator with security-focused settings
+ */
+export declare function createStrictValidator(allowedProxyDomains: string[]): Validator;

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

@@ -51,6 +51,7 @@ import { webkitLineClamp } from './property-descriptors/webkit-line-clamp';
 import { Context } from '../core/context';
 import { objectFit } from './property-descriptors/object-fit';
 import { textOverflow } from './property-descriptors/text-overflow';
+import { imageRendering } from './property-descriptors/image-rendering';
 export declare class CSSParsedDeclaration {
     animationDuration: ReturnType<typeof duration.parse>;
     backgroundClip: ReturnType<typeof backgroundClip.parse>;
@@ -125,6 +126,7 @@ export declare class CSSParsedDeclaration {
     wordBreak: ReturnType<typeof wordBreak.parse>;
     zIndex: ReturnType<typeof zIndex.parse>;
     objectFit: ReturnType<typeof objectFit.parse>;
+    imageRendering: ReturnType<typeof imageRendering.parse>;
     constructor(context: Context, declaration: CSSStyleDeclaration);
     isVisible(): boolean;
     isTransparent(): boolean;

package/dist/types/css/property-descriptors/__tests__/image-rendering-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/css/property-descriptors/__tests__/image-rendering-performance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/css/property-descriptors/__tests__/image-rendering.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/css/property-descriptors/image-rendering.d.ts

@@ -0,0 +1,8 @@
+import { IPropertyIdentValueDescriptor } from '../IPropertyDescriptor';
+export declare enum IMAGE_RENDERING {
+    AUTO = 0,
+    CRISP_EDGES = 1,
+    PIXELATED = 2,
+    SMOOTH = 3
+}
+export declare const imageRendering: IPropertyIdentValueDescriptor<IMAGE_RENDERING>;

package/dist/types/css/types/color-math.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Color mathematics utilities
+ * Extracted to break circular dependency between srgb.ts and color-utilities.ts
+ */
+/**
+ * Clamp a value between min and max
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Multiply two 3x3 matrices
+ */
+export declare const multiplyMatrices: (A: number[], B: number[]) => [number, number, number];

package/dist/types/css/types/color-utilities.d.ts

@@ -1,13 +1,13 @@
 import { Context } from '../../core/context';
 import { CSSValue } from '../syntax/parser';
+import { clamp, multiplyMatrices } from './color-math';
 type Color = number;
 export declare const isTransparent: (color: Color) => boolean;
 export declare const asString: (color: Color) => string;
 export declare const pack: (r: number, g: number, b: number, a: number) => Color;
 export declare const getTokenColorValue: (token: CSSValue, i: number) => number;
 export declare const isRelativeTransform: (tokens: CSSValue[]) => boolean;
-export declare const clamp: (value: number, min: number, max: number) => number;
-export declare const multiplyMatrices: (A: number[], B: number[]) => [number, number, number];
+export { clamp, multiplyMatrices };
 export declare const packSrgb: (args: number[]) => number;
 export declare const packSrgbLinear: ([r, g, b, a]: [number, number, number, number]) => number;
 export declare const packXYZ: (args: number[]) => number;
@@ -105,4 +105,3 @@ export declare const convertXyz: (args: number[]) => number;
  * @param args
  */
 export declare const convertXyz50: (args: number[]) => number;
-export {};

package/dist/types/dom/__tests__/dom-normalizer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/dom/__tests__/element-container.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -34,6 +34,52 @@ export declare class DocumentCloner {
     createCanvasClone(canvas: HTMLCanvasElement): HTMLImageElement | HTMLCanvasElement;
     createVideoClone(video: HTMLVideoElement): HTMLCanvasElement;
     appendChildNode(clone: HTMLElement | SVGElement, child: Node, copyStyles: boolean): void;
+    /**
+     * Check if a child node should be cloned based on filtering rules
+     * Filters out: scripts, ignored elements, and optionally styles
+     */
+    private shouldCloneChild;
+    /**
+     * Check if a style element should be cloned based on copyStyles option
+     */
+    private shouldCloneStyleElement;
+    /**
+     * Safely append a cloned child to a target, applying all filtering rules
+     */
+    private safeAppendClonedChild;
+    /**
+     * Clone assigned nodes from a slot element to the target
+     */
+    private cloneAssignedNodes;
+    /**
+     * Clone fallback content from a slot element when no nodes are assigned
+     */
+    private cloneSlotFallbackContent;
+    /**
+     * Handle cloning of a slot element, including assigned nodes or fallback content
+     */
+    private cloneSlotElement;
+    /**
+     * Clone shadow DOM children to the target shadow root
+     */
+    private cloneShadowDOMChildren;
+    /**
+     * Clone light DOM children to the target element
+     */
+    private cloneLightDOMChildren;
+    /**
+     * Clone slot element as light DOM when shadow root creation failed
+     */
+    private cloneSlotElementAsLightDOM;
+    /**
+     * Clone shadow DOM content as light DOM when shadow root creation failed
+     * This is a fallback mechanism to ensure content is not lost
+     */
+    private cloneShadowDOMAsLightDOM;
+    /**
+     * Clone child nodes from source element to clone element
+     * Handles shadow DOM, slots, and light DOM appropriately
+     */
     cloneChildNodes(node: Element, clone: HTMLElement | SVGElement, copyStyles: boolean): void;
     cloneNode(node: Node, copyStyles: boolean): Node;
     resolvePseudoContent(node: Element, clone: Element, style: CSSStyleDeclaration, pseudoElt: PseudoElementType): HTMLElement | void;

package/dist/types/dom/dom-normalizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DOM Normalizer
+ * Handles DOM side effects that need to happen before rendering
+ * Extracted from ElementContainer to follow SRP
+ */
+import { CSSParsedDeclaration } from '../css';
+/**
+ * Stored original styles for restoration
+ */
+export interface OriginalStyles {
+    animationDuration?: string;
+    transform?: string;
+    rotate?: string;
+}
+/**
+ * Normalize element styles for accurate rendering
+ * This includes disabling animations and resetting transforms
+ */
+export declare class DOMNormalizer {
+    /**
+     * Normalize a single element and return original styles
+     *
+     * @param element - Element to normalize
+     * @param styles - Parsed CSS styles
+     * @returns Original styles map for restoration
+     */
+    static normalizeElement(element: Element, styles: CSSParsedDeclaration): OriginalStyles;
+    /**
+     * Normalize element and its descendants recursively
+     *
+     * @param element - Element to normalize
+     * @param styles - Parsed CSS styles
+     * @returns Original styles map for restoration
+     */
+    static normalizeTree(element: Element, styles: CSSParsedDeclaration): OriginalStyles;
+    /**
+     * Restore element styles after rendering
+     *
+     * @param element - Element to restore
+     * @param originalStyles - Original styles to restore
+     */
+    static restoreElement(element: Element, originalStyles: OriginalStyles): void;
+}

package/dist/types/dom/element-container.d.ts

@@ -8,6 +8,13 @@ export declare const enum FLAGS {
     IS_LIST_OWNER = 8,
     DEBUG_RENDER = 16
 }
+export interface ElementContainerOptions {
+    /**
+     * Whether to normalize DOM (disable animations, reset transforms)
+     * Default: true for backward compatibility
+     */
+    normalizeDom?: boolean;
+}
 export declare class ElementContainer {
     protected readonly context: Context;
     readonly styles: CSSParsedDeclaration;
@@ -15,5 +22,17 @@ export declare class ElementContainer {
     readonly elements: ElementContainer[];
     bounds: Bounds;
     flags: number;
-    constructor(context: Context, element: Element);
+    private originalStyles?;
+    private originalElement?;
+    constructor(context: Context, element: Element, options?: ElementContainerOptions);
+    /**
+     * Restore original element styles (if normalized)
+     * Call this after rendering is complete to clean up DOM state
+     */
+    restore(): void;
+    /**
+     * Recursively restore all elements in the tree
+     * Call this on the root container after rendering is complete
+     */
+    restoreTree(): void;
 }

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

@@ -1,12 +1,8 @@
 import { ElementContainer } from './element-container';
 import { Context } from '../core/context';
+import { isElementNode, isTextNode, isSVGElementNode, isHTMLElementNode, isLIElement, isOLElement, isCustomElement } from './node-type-guards';
+export { isElementNode, isTextNode, isSVGElementNode, isHTMLElementNode, isLIElement, isOLElement, isCustomElement };
 export declare const parseTree: (context: Context, element: HTMLElement) => ElementContainer;
-export declare const isTextNode: (node: Node) => node is Text;
-export declare const isElementNode: (node: Node) => node is Element;
-export declare const isHTMLElementNode: (node: Node) => node is HTMLElement;
-export declare const isSVGElementNode: (element: Element) => element is SVGElement;
-export declare const isLIElement: (node: Element) => node is HTMLLIElement;
-export declare const isOLElement: (node: Element) => node is HTMLOListElement;
 export declare const isInputElement: (node: Element) => node is HTMLInputElement;
 export declare const isHTMLElement: (node: Element) => node is HTMLHtmlElement;
 export declare const isSVGElement: (node: Element) => node is SVGSVGElement;
@@ -20,4 +16,3 @@ export declare const isScriptElement: (node: Element) => node is HTMLScriptEleme
 export declare const isTextareaElement: (node: Element) => node is HTMLTextAreaElement;
 export declare const isSelectElement: (node: Element) => node is HTMLSelectElement;
 export declare const isSlotElement: (node: Element) => node is HTMLSlotElement;
-export declare const isCustomElement: (node: Element) => node is HTMLElement;

package/dist/types/dom/node-type-guards.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DOM Node Type Guards
+ * Extracted to break circular dependencies
+ */
+/**
+ * Check if node is an Element
+ */
+export declare const isElementNode: (node: Node) => node is Element;
+/**
+ * Check if node is a Text node
+ */
+export declare const isTextNode: (node: Node) => node is Text;
+/**
+ * Check if element is an SVG element
+ */
+export declare const isSVGElementNode: (element: Element) => element is SVGElement;
+/**
+ * Check if node is an HTML element
+ */
+export declare const isHTMLElementNode: (node: Node) => node is HTMLElement;
+/**
+ * Check if node is an LI element
+ */
+export declare const isLIElement: (node: Element) => node is HTMLLIElement;
+/**
+ * Check if node is an OL element
+ */
+export declare const isOLElement: (node: Element) => node is HTMLOListElement;
+/**
+ * Check if element is a custom element
+ * Custom elements must have a hyphen and cannot be SVG elements
+ */
+export declare const isCustomElement: (element: Element) => element is HTMLElement;

package/dist/types/dom/replaced-elements/iframe-element-container.d.ts

@@ -1,11 +1,14 @@
 import { ElementContainer } from '../element-container';
 import { Color } from '../../css/types/color';
 import { Context } from '../../core/context';
+type ParseTreeFunction = (context: Context, node: Node) => ElementContainer;
 export declare class IFrameElementContainer extends ElementContainer {
     src: string;
     width: number;
     height: number;
     tree?: ElementContainer;
     backgroundColor: Color;
-    constructor(context: Context, iframe: HTMLIFrameElement);
+    private parseTreeFn?;
+    constructor(context: Context, iframe: HTMLIFrameElement, parseTreeFn?: ParseTreeFunction);
 }
+export {};