html2canvas-pro 2.0.3 → 2.1.0

package/src/core/origin-checker.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 class OriginChecker {
+    private readonly link: HTMLAnchorElement;
+    private readonly origin: string;
+
+    constructor(window: Window) {
+        if (!window || !window.document) {
+            throw new Error('Valid window object required for OriginChecker');
+        }
+
+        if (!window.location || !window.location.href) {
+            throw new Error('Window object must have valid location');
+        }
+
+        this.link = window.document.createElement('a');
+        this.origin = this.getOrigin(window.location.href);
+    }
+
+    /**
+     * 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 {
+        this.link.href = url;
+        // IE9 hack: accessing href twice to ensure it's properly parsed
+        this.link.href = this.link.href;
+        return this.link.protocol + this.link.hostname + this.link.port;
+    }
+
+    /**
+     * 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 {
+        return this.getOrigin(src) === this.origin;
+    }
+
+    /**
+     * Get the current context origin
+     *
+     * @returns The origin of the context window
+     */
+    getContextOrigin(): string {
+        return this.origin;
+    }
+}

package/src/core/performance-monitor.ts

@@ -0,0 +1,241 @@
+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 class PerformanceMonitor {
+    private readonly activeMetrics: Map<string, PerformanceMetric> = new Map();
+    private readonly completedMetrics: PerformanceMetric[] = [];
+    private readonly enabled: boolean;
+    private readonly getTime: () => number;
+
+    constructor(
+        private readonly context: Context | null,
+        enabled: boolean = true
+    ) {
+        this.enabled = enabled;
+
+        // Fallback for environments without performance.now()
+        this.getTime =
+            typeof performance !== 'undefined' && typeof performance.now === 'function'
+                ? () => performance.now()
+                : () => Date.now();
+    }
+
+    /**
+     * 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 {
+        if (!this.enabled) {
+            return;
+        }
+
+        if (this.activeMetrics.has(name)) {
+            this.context?.logger.warn(`Performance metric '${name}' already started. Overwriting.`);
+        }
+
+        this.activeMetrics.set(name, {
+            name,
+            startTime: this.getTime(),
+            metadata
+        });
+    }
+
+    /**
+     * 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 {
+        if (!this.enabled) {
+            return undefined;
+        }
+
+        const metric = this.activeMetrics.get(name);
+
+        if (!metric) {
+            this.context?.logger.warn(`Performance metric '${name}' not found. Was start() called?`);
+            return undefined;
+        }
+
+        metric.endTime = this.getTime();
+        metric.duration = metric.endTime - metric.startTime;
+
+        this.completedMetrics.push(metric);
+        this.activeMetrics.delete(name);
+
+        this.context?.logger.debug(`⏱️  ${name}: ${metric.duration.toFixed(2)}ms`, metric.metadata);
+
+        return metric;
+    }
+
+    /**
+     * 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 {
+        this.start(name, metadata);
+        try {
+            const result = fn();
+            this.end(name);
+            return result;
+        } catch (error) {
+            this.end(name);
+            throw error;
+        }
+    }
+
+    /**
+     * 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
+     */
+    async measureAsync<T>(name: string, fn: () => Promise<T>, metadata?: Record<string, any>): Promise<T> {
+        this.start(name, metadata);
+        try {
+            const result = await fn();
+            this.end(name);
+            return result;
+        } catch (error) {
+            this.end(name);
+            throw error;
+        }
+    }
+
+    /**
+     * Get all completed metrics
+     *
+     * @returns Array of completed performance metrics
+     */
+    getMetrics(): PerformanceMetric[] {
+        return [...this.completedMetrics];
+    }
+
+    /**
+     * Get a specific metric by name
+     *
+     * @param name - Metric name
+     * @returns The metric, or undefined if not found
+     */
+    getMetric(name: string): PerformanceMetric | undefined {
+        return this.completedMetrics.find((m) => m.name === name);
+    }
+
+    /**
+     * Get performance summary
+     *
+     * @returns Aggregated performance data
+     */
+    getSummary(): PerformanceSummary {
+        const totalDuration = this.completedMetrics.reduce((sum, metric) => sum + (metric.duration || 0), 0);
+
+        const breakdown = this.completedMetrics.map((metric) => ({
+            name: metric.name,
+            duration: metric.duration || 0,
+            percentage: totalDuration > 0 ? (((metric.duration || 0) / totalDuration) * 100).toFixed(1) + '%' : '0%'
+        }));
+
+        return {
+            totalDuration,
+            metrics: this.getMetrics(),
+            breakdown
+        };
+    }
+
+    /**
+     * Log performance summary to console
+     */
+    logSummary(): void {
+        if (!this.enabled || this.completedMetrics.length === 0 || !this.context) {
+            return;
+        }
+
+        const summary = this.getSummary();
+
+        this.context.logger.info(`\n📊 Performance Summary (Total: ${summary.totalDuration.toFixed(2)}ms):`);
+
+        summary.breakdown
+            .sort((a, b) => b.duration - a.duration)
+            .forEach((item) => {
+                this.context!.logger.info(
+                    `  ${item.name.padEnd(20)} ${item.duration.toFixed(2).padStart(8)}ms  ${item.percentage.padStart(6)}`
+                );
+            });
+    }
+
+    /**
+     * Clear all metrics
+     */
+    clear(): void {
+        this.activeMetrics.clear();
+        this.completedMetrics.splice(0);
+    }
+
+    /**
+     * Check if monitoring is enabled
+     */
+    isEnabled(): boolean {
+        return this.enabled;
+    }
+
+    /**
+     * Get active (uncompleted) metrics
+     * Useful for debugging leaked measurements
+     */
+    getActiveMetrics(): string[] {
+        return Array.from(this.activeMetrics.keys());
+    }
+}

package/src/core/render-element.ts

@@ -0,0 +1,272 @@
+import { Bounds, parseBounds, parseDocumentSize } from '../css/layout/bounds';
+import { COLORS, parseColor } from '../css/types/color';
+import { isTransparent } from '../css/types/color-utilities';
+import { CloneConfigurations, DocumentCloner } from '../dom/document-cloner';
+import { isBodyElement, isHTMLElement, parseTree } from '../dom/node-parser';
+import { ElementContainer } from '../dom/element-container';
+import { CanvasRenderer, RenderConfigurations } from '../render/canvas/canvas-renderer';
+import { ForeignObjectRenderer } from '../render/canvas/foreignobject-renderer';
+import { Context } from './context';
+import { Html2CanvasConfig } from '../config';
+import { createDefaultValidator } from './validator';
+import { PerformanceMonitor } from './performance-monitor';
+import type { Options } from '../options';
+
+const coerceNumberOptions = (opts: Partial<Options>): void => {
+    const numKeys: (keyof Options)[] = [
+        'scale',
+        'width',
+        'height',
+        'imageTimeout',
+        'x',
+        'y',
+        'windowWidth',
+        'windowHeight',
+        'scrollX',
+        'scrollY'
+    ];
+    numKeys.forEach((key) => {
+        const v = opts[key];
+        if (v !== undefined && v !== null && typeof v !== 'number') {
+            const n = Number(v);
+            if (!Number.isNaN(n)) {
+                (opts as Record<string, unknown>)[key] = n;
+            }
+        }
+    });
+};
+
+export const renderElement = async (
+    element: HTMLElement,
+    opts: Partial<Options>,
+    config: Html2CanvasConfig
+): Promise<HTMLCanvasElement> => {
+    coerceNumberOptions(opts);
+
+    // Input validation (unless explicitly skipped)
+    if (!opts.skipValidation) {
+        const validator = opts.validator || createDefaultValidator();
+
+        const elementValidation = validator.validateElement(element);
+        if (!elementValidation.valid) {
+            throw new Error(elementValidation.error);
+        }
+
+        const optionsValidation = validator.validateOptions(opts);
+        if (!optionsValidation.valid) {
+            throw new Error(`Invalid options: ${optionsValidation.error}`);
+        }
+    }
+
+    if (!element || typeof element !== 'object') {
+        throw new Error('Invalid element provided as first argument');
+    }
+    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`);
+    }
+
+    const resourceOptions = {
+        allowTaint: opts.allowTaint ?? false,
+        imageTimeout: opts.imageTimeout ?? 15000,
+        proxy: opts.proxy,
+        useCORS: opts.useCORS ?? false,
+        customIsSameOrigin: opts.customIsSameOrigin
+    };
+
+    const contextOptions = {
+        logging: opts.logging ?? true,
+        cache: opts.cache ?? config.cache,
+        ...resourceOptions
+    };
+
+    const DEFAULT_WINDOW_WIDTH = 800;
+    const DEFAULT_WINDOW_HEIGHT = 600;
+    const DEFAULT_SCROLL = 0;
+    const win = defaultView as Window & {
+        innerWidth?: number;
+        innerHeight?: number;
+        pageXOffset?: number;
+        pageYOffset?: number;
+    };
+    const windowOptions = {
+        windowWidth: opts.windowWidth ?? win.innerWidth ?? DEFAULT_WINDOW_WIDTH,
+        windowHeight: opts.windowHeight ?? win.innerHeight ?? DEFAULT_WINDOW_HEIGHT,
+        scrollX: opts.scrollX ?? win.pageXOffset ?? DEFAULT_SCROLL,
+        scrollY: opts.scrollY ?? win.pageYOffset ?? DEFAULT_SCROLL
+    };
+
+    const windowBounds = new Bounds(
+        windowOptions.scrollX,
+        windowOptions.scrollY,
+        windowOptions.windowWidth,
+        windowOptions.windowHeight
+    );
+
+    const context = new Context(contextOptions, windowBounds, config);
+
+    const performanceMonitoring = opts.enablePerformanceMonitoring ?? opts.logging ?? false;
+    const perfMonitor = new PerformanceMonitor(context, performanceMonitoring);
+
+    perfMonitor.start('total', {
+        width: windowOptions.windowWidth,
+        height: windowOptions.windowHeight
+    });
+
+    const signal = opts.signal;
+
+    if (signal?.aborted) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    const foreignObjectRendering = opts.foreignObjectRendering ?? false;
+
+    const cloneOptions: CloneConfigurations = {
+        allowTaint: opts.allowTaint ?? false,
+        onclone: opts.onclone,
+        ignoreElements: opts.ignoreElements,
+        iframeContainer: opts.iframeContainer,
+        inlineImages: foreignObjectRendering,
+        copyStyles: foreignObjectRendering,
+        cspNonce: opts.cspNonce ?? config.cspNonce
+    };
+
+    context.logger.debug(
+        `Starting document clone with size ${windowBounds.width}x${
+            windowBounds.height
+        } scrolled to ${-windowBounds.left},${-windowBounds.top}`
+    );
+
+    perfMonitor.start('clone');
+    const documentCloner = new DocumentCloner(context, element, cloneOptions);
+    const clonedElement = documentCloner.clonedReferenceElement;
+    if (!clonedElement) {
+        throw new Error('Unable to find element in cloned iframe');
+    }
+
+    const container = await documentCloner.toIFrame(ownerDocument, windowBounds);
+    perfMonitor.end('clone');
+
+    if (signal?.aborted) {
+        if (opts.removeContainer ?? true) {
+            DocumentCloner.destroy(container);
+        }
+        throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    const { width, height, left, top } =
+        isBodyElement(clonedElement) || isHTMLElement(clonedElement)
+            ? parseDocumentSize(clonedElement.ownerDocument)
+            : parseBounds(context, clonedElement);
+
+    const backgroundColor = parseBackgroundColor(context, clonedElement, opts.backgroundColor);
+
+    const renderOptions: RenderConfigurations = {
+        canvas: opts.canvas,
+        backgroundColor,
+        signal,
+        scale: opts.scale ?? defaultView.devicePixelRatio ?? 1,
+        x: (opts.x ?? 0) + left,
+        y: (opts.y ?? 0) + top,
+        width: opts.width ?? Math.ceil(width),
+        height: opts.height ?? Math.ceil(height),
+        imageSmoothing: opts.imageSmoothing,
+        imageSmoothingQuality: opts.imageSmoothingQuality
+    };
+
+    let canvas;
+
+    let root: ElementContainer | undefined;
+
+    try {
+        if (foreignObjectRendering) {
+            context.logger.debug(`Document cloned, using foreign object rendering`);
+            perfMonitor.start('render-foreignobject');
+            const renderer = new ForeignObjectRenderer(context, renderOptions);
+            canvas = await renderer.render(clonedElement);
+            perfMonitor.end('render-foreignobject');
+        } else {
+            context.logger.debug(
+                `Document cloned, element located at ${left},${top} with size ${width}x${height} using computed rendering`
+            );
+
+            context.logger.debug(`Starting DOM parsing`);
+            perfMonitor.start('parse');
+            if (signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            root = parseTree(context, clonedElement);
+            perfMonitor.end('parse');
+
+            if (backgroundColor === root.styles.backgroundColor) {
+                root.styles.backgroundColor = COLORS.TRANSPARENT;
+            }
+
+            context.logger.debug(
+                `Starting renderer for element at ${renderOptions.x},${renderOptions.y} with size ${renderOptions.width}x${renderOptions.height}`
+            );
+
+            perfMonitor.start('render');
+            if (signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            const renderer = new CanvasRenderer(context, renderOptions);
+            canvas = await renderer.render(root);
+            perfMonitor.end('render');
+        }
+
+        perfMonitor.start('cleanup');
+        if (opts.removeContainer ?? true) {
+            if (!DocumentCloner.destroy(container)) {
+                context.logger.error(`Cannot detach cloned iframe as it is not in the DOM anymore`);
+            }
+        }
+        perfMonitor.end('cleanup');
+
+        perfMonitor.end('total');
+        context.logger.debug(`Finished rendering`);
+
+        if (performanceMonitoring) {
+            perfMonitor.logSummary();
+        }
+
+        return canvas;
+    } finally {
+        if (root) {
+            root.restoreTree();
+        }
+    }
+};
+
+const parseBackgroundColor = (context: Context, element: HTMLElement, backgroundColorOverride?: string | null) => {
+    const ownerDocument = element.ownerDocument;
+    // http://www.w3.org/TR/css3-background/#special-backgrounds
+    const documentBackgroundColor = ownerDocument.documentElement
+        ? parseColor(context, getComputedStyle(ownerDocument.documentElement).backgroundColor as string)
+        : COLORS.TRANSPARENT;
+    const bodyBackgroundColor = ownerDocument.body
+        ? parseColor(context, getComputedStyle(ownerDocument.body).backgroundColor as string)
+        : COLORS.TRANSPARENT;
+
+    const defaultBackgroundColor =
+        typeof backgroundColorOverride === 'string'
+            ? parseColor(context, backgroundColorOverride)
+            : backgroundColorOverride === null
+              ? COLORS.TRANSPARENT
+              : 0xffffffff;
+
+    return element === ownerDocument.documentElement
+        ? isTransparent(documentBackgroundColor)
+            ? isTransparent(bodyBackgroundColor)
+                ? defaultBackgroundColor
+                : bodyBackgroundColor
+            : documentBackgroundColor
+        : defaultBackgroundColor;
+};

package/src/core/util.ts

@@ -0,0 +1 @@
+export const SMALL_IMAGE = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';