@ohos-ports/html2canvas-pro 0.0.0-stage → 2.3.2-beta.0

package/dist/lib/config.js

@@ -0,0 +1,49 @@
+"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

@@ -0,0 +1,20 @@
+"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

@@ -0,0 +1,41 @@
+"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

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

package/dist/lib/core/cache-storage.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+const features_1 = require("./features");
+class Cache {
+    constructor(context, _options) {
+        this.context = context;
+        this._options = _options;
+        this._cache = new Map();
+        this._pendingOperations = new Map();
+        /** When true, addImage() collects URLs without starting loads. */
+        this._deferMode = false;
+        /** URLs collected during defer mode, pending batch preload. */
+        this._collectedUrls = new Set();
+        // Default cache size: 100 items
+        this.maxSize = _options.maxCacheSize ?? 100;
+        if (this.maxSize < 1) {
+            throw new Error('Cache maxSize must be at least 1');
+        }
+        if (this.maxSize > 10000) {
+            this.context.logger.warn(`Cache maxSize ${this.maxSize} is very large and may cause memory issues. ` +
+                `Consider using a smaller value (recommended: 100-1000).`);
+        }
+    }
+    /**
+     * Enter defer mode: subsequent addImage() calls only collect URLs.
+     * Call preloadAll() to exit defer mode and batch-load all URLs.
+     */
+    startDefer() {
+        this._deferMode = true;
+    }
+    /**
+     * Exit defer mode and load all collected URLs in parallel, respecting
+     * an optional concurrency cap to avoid overwhelming the browser's network
+     * stack (default: 10 concurrent loads).
+     * After this call returns, all images are either loaded (cache hit) or
+     * failed (logged). Subsequent cache.match() calls return immediately.
+     *
+     * @param concurrency - Max concurrent image loads (1–100, default 10).
+     */
+    async preloadAll(concurrency = 10) {
+        this._deferMode = false;
+        const urls = Array.from(this._collectedUrls);
+        this._collectedUrls.clear();
+        if (urls.length === 0) {
+            return;
+        }
+        const limit = Math.max(1, Math.min(concurrency, 100));
+        this.context.logger.debug(`Preloading ${urls.length} image(s) with concurrency ${limit}`);
+        // Load in batches to respect the concurrency cap while maximising
+        // parallelism within each batch.
+        for (let i = 0; i < urls.length; i += limit) {
+            const batch = urls.slice(i, i + limit);
+            const operations = batch.map((url) => this._addImageWithPending(url));
+            await Promise.allSettled(operations);
+        }
+    }
+    addImage(src) {
+        // ── Defer mode: collect only ──────────────────────────────
+        if (this._deferMode) {
+            if (!this.has(src) && (isBlobImage(src) || isRenderable(src))) {
+                this._collectedUrls.add(src);
+            }
+            return Promise.resolve();
+        }
+        // ── Normal mode: immediate load ───────────────────────────
+        // Wait for any pending operations on this key
+        const pending = this._pendingOperations.get(src);
+        if (pending) {
+            return pending;
+        }
+        if (this.has(src)) {
+            // Move to end for LRU ordering
+            const entry = this._cache.get(src);
+            this._cache.delete(src);
+            this._cache.set(src, entry);
+            return Promise.resolve();
+        }
+        if (isBlobImage(src) || isRenderable(src)) {
+            return this._addImageWithPending(src);
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Shared helper: enqueues loading for a single URL with pending-operation
+     * deduplication and error swallowing. Used by both addImage() (normal mode)
+     * and preloadAll() (batch mode).
+     */
+    _addImageWithPending(src) {
+        const pending = this._pendingOperations.get(src);
+        if (pending) {
+            return pending;
+        }
+        const operation = this._addImageInternal(src);
+        this._pendingOperations.set(src, operation);
+        operation.finally(() => {
+            this._pendingOperations.delete(src);
+        });
+        return operation;
+    }
+    async _addImageInternal(src) {
+        const timeoutMs = this._options.imageTimeout ?? 15000;
+        const imageWithTimeout = this.withTimeout(this.loadImage(src), timeoutMs, `Timed out (${timeoutMs}ms) loading image`);
+        // Handle errors to prevent unhandled rejections
+        imageWithTimeout.catch((error) => {
+            this.context.logger.error(`Failed to load image ${src}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        });
+        // Store the promise with timeout in cache
+        this.set(src, imageWithTimeout);
+    }
+    withTimeout(promise, timeoutMs, message) {
+        if (timeoutMs <= 0) {
+            return promise;
+        }
+        let timeoutId;
+        const timeout = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs);
+        });
+        return Promise.race([promise, timeout]).finally(() => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        });
+    }
+    match(src) {
+        const entry = this._cache.get(src);
+        if (entry) {
+            // Move to end for LRU ordering (O(1))
+            this._cache.delete(src);
+            this._cache.set(src, entry);
+            return entry.value;
+        }
+        return undefined;
+    }
+    /**
+     * Set a value in cache with LRU eviction (O(1) via Map insertion order).
+     * Map preserves insertion order; delete+set on access moves items to the end.
+     * The first key in Map.keys() is always the least recently used.
+     */
+    set(key, value) {
+        if (this._cache.has(key)) {
+            // Update existing entry: move to end of Map
+            this._cache.delete(key);
+        }
+        else if (this._cache.size >= this.maxSize) {
+            // Evict LRU (first key = least recently used) — O(1)
+            const lruKey = this._cache.keys().next().value;
+            if (lruKey !== undefined) {
+                this._cache.delete(lruKey);
+                this.context.logger.debug(`Cache: Evicted LRU entry: ${lruKey}`);
+            }
+        }
+        this._cache.set(key, { value });
+    }
+    /**
+     * Get cache size
+     */
+    size() {
+        return this._cache.size;
+    }
+    /**
+     * Get max cache size
+     */
+    getMaxSize() {
+        return this.maxSize;
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this._cache.clear();
+    }
+    async loadImage(key) {
+        const originChecker = this.context.originChecker;
+        const defaultIsSameOrigin = (src) => originChecker.isSameOrigin(src);
+        const isSameOrigin = typeof this._options.customIsSameOrigin === 'function'
+            ? await this._options.customIsSameOrigin(key, defaultIsSameOrigin)
+            : defaultIsSameOrigin(key);
+        const useCORS = !isInlineImage(key) && this._options.useCORS === true && features_1.FEATURES.SUPPORT_CORS_IMAGES && !isSameOrigin;
+        const useProxy = !isInlineImage(key) &&
+            !isSameOrigin &&
+            !isBlobImage(key) &&
+            typeof this._options.proxy === 'string' &&
+            features_1.FEATURES.SUPPORT_CORS_XHR &&
+            !useCORS;
+        if (!isSameOrigin &&
+            this._options.allowTaint === false &&
+            !isInlineImage(key) &&
+            !isBlobImage(key) &&
+            !useProxy &&
+            !useCORS) {
+            return;
+        }
+        let src = key;
+        if (useProxy) {
+            src = await this.proxy(src);
+        }
+        this.context.logger.debug(`Added image ${key.substring(0, 256)}`);
+        return await new Promise((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => resolve(img);
+            img.onerror = reject;
+            //ios safari 10.3 taints canvas with data urls unless crossOrigin is set to anonymous
+            if (isInlineBase64Image(src) || useCORS) {
+                img.crossOrigin = 'anonymous';
+            }
+            img.src = src;
+            if (img.complete === true) {
+                // Inline XML images may fail to parse, throwing an Error later on
+                setTimeout(() => resolve(img), 500);
+            }
+        });
+    }
+    has(key) {
+        return this._cache.has(key);
+    }
+    keys() {
+        return Promise.resolve(Array.from(this._cache.keys()));
+    }
+    proxy(src) {
+        const proxy = this._options.proxy;
+        if (!proxy) {
+            throw new Error('No proxy defined');
+        }
+        const key = src.substring(0, 256);
+        return new Promise((resolve, reject) => {
+            const responseType = features_1.FEATURES.SUPPORT_RESPONSE_TYPE ? 'blob' : 'text';
+            const xhr = new XMLHttpRequest();
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    if (responseType === 'text') {
+                        resolve(xhr.response);
+                    }
+                    else {
+                        const reader = new FileReader();
+                        reader.addEventListener('load', () => resolve(reader.result), false);
+                        reader.addEventListener('error', (e) => reject(e), false);
+                        reader.readAsDataURL(xhr.response);
+                    }
+                }
+                else {
+                    reject(`Failed to proxy resource ${key} with status code ${xhr.status}`);
+                }
+            };
+            xhr.onerror = reject;
+            const queryString = proxy.indexOf('?') > -1 ? '&' : '?';
+            xhr.open('GET', `${proxy}${queryString}url=${encodeURIComponent(src)}&responseType=${responseType}`);
+            if (responseType !== 'text' && xhr instanceof XMLHttpRequest) {
+                xhr.responseType = responseType;
+            }
+            if (this._options.imageTimeout) {
+                const timeout = this._options.imageTimeout;
+                xhr.timeout = timeout;
+                xhr.ontimeout = () => reject(`Timed out (${timeout}ms) proxying ${key}`);
+            }
+            xhr.send();
+        });
+    }
+}
+exports.Cache = Cache;
+const INLINE_SVG = /^data:image\/svg\+xml/i;
+const INLINE_BASE64 = /^data:image\/.*;base64,/i;
+const INLINE_IMG = /^data:image\/.*/i;
+const isRenderable = (src) => features_1.FEATURES.SUPPORT_SVG_DRAWING || !isSVG(src);
+const isInlineImage = (src) => INLINE_IMG.test(src);
+const isInlineBase64Image = (src) => INLINE_BASE64.test(src);
+const isBlobImage = (src) => src.substring(0, 4) === 'blob';
+const isSVG = (src) => src.slice(-3).toLowerCase() === 'svg' || INLINE_SVG.test(src);

package/dist/lib/core/config-assembler.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleRenderOptions = exports.assembleCloneOptions = exports.assembleWindowOptions = exports.assembleContextOptions = exports.assembleResourceOptions = exports.coerceNumberOptions = void 0;
+const constants_1 = require("./constants");
+/**
+ * Coerce known numeric options from string (or other) values to actual numbers.
+ * Mutates the opts object in place — this is intentionally a normalisation
+ * (not pure) step that runs once at the beginning of renderElement.
+ */
+const coerceNumberOptions = (opts) => {
+    const numKeys = [
+        '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[key] = n;
+            }
+        }
+    });
+};
+exports.coerceNumberOptions = coerceNumberOptions;
+/** Assemble resource loading options from user-provided Options. */
+const assembleResourceOptions = (opts) => ({
+    allowTaint: opts.allowTaint ?? false,
+    imageTimeout: opts.imageTimeout ?? constants_1.DEFAULT_IMAGE_TIMEOUT_MS,
+    proxy: opts.proxy,
+    useCORS: opts.useCORS ?? false,
+    customIsSameOrigin: opts.customIsSameOrigin,
+    maxCacheSize: opts.maxCacheSize
+});
+exports.assembleResourceOptions = assembleResourceOptions;
+/** Assemble context (logging + cache) options, extending resource options. */
+const assembleContextOptions = (opts, config, resourceOptions) => ({
+    logging: opts.logging ?? true,
+    cache: opts.cache ?? config.cache,
+    ...resourceOptions
+});
+exports.assembleContextOptions = assembleContextOptions;
+const DEFAULT_WINDOW_WIDTH = 800;
+const DEFAULT_WINDOW_HEIGHT = 600;
+const DEFAULT_SCROLL = 0;
+const assembleWindowOptions = (opts, defaultView) => {
+    const win = defaultView;
+    return {
+        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
+    };
+};
+exports.assembleWindowOptions = assembleWindowOptions;
+/** Assemble DOM cloning options. */
+const assembleCloneOptions = (opts, config, foreignObjectRendering) => ({
+    allowTaint: opts.allowTaint ?? false,
+    onclone: opts.onclone,
+    ignoreElements: opts.ignoreElements,
+    iframeContainer: opts.iframeContainer,
+    inlineImages: foreignObjectRendering,
+    copyStyles: foreignObjectRendering,
+    cspNonce: opts.cspNonce ?? config.cspNonce
+});
+exports.assembleCloneOptions = assembleCloneOptions;
+/** Assemble canvas rendering options. */
+const assembleRenderOptions = (opts, backgroundColor, left, top, width, height, devicePixelRatio) => ({
+    canvas: opts.canvas,
+    backgroundColor,
+    signal: opts.signal,
+    scale: opts.scale ?? 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
+});
+exports.assembleRenderOptions = assembleRenderOptions;

package/dist/lib/core/constants.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Shared numeric constants used across html2canvas-pro.
+ * Centralising magic numbers for maintainability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCE_KEY_LOG_LENGTH = exports.INLINE_IMAGE_RESOLVE_DELAY_MS = exports.IFRAME_READY_POLL_MS = exports.SHADOW_MASK_OFFSET = exports.DEFAULT_IMAGE_TIMEOUT_MS = exports.MAX_IMAGE_CACHE_SIZE = exports.DEFAULT_IMAGE_CACHE_SIZE = exports.PATTERN_CACHE_MAX = exports.PARSE_CACHE_MAX_PER_DESCRIPTOR = void 0;
+/** Maximum entries in the CSS parse cache per descriptor (LRU). */
+exports.PARSE_CACHE_MAX_PER_DESCRIPTOR = 200;
+/** Maximum cached background-image patterns per render session (LRU). */
+exports.PATTERN_CACHE_MAX = 50;
+/** Maximum size of the image-resource cache (entries). */
+exports.DEFAULT_IMAGE_CACHE_SIZE = 100;
+/** Maximum allowed image-resource cache size. */
+exports.MAX_IMAGE_CACHE_SIZE = 10000;
+/** Default image-load timeout in milliseconds. */
+exports.DEFAULT_IMAGE_TIMEOUT_MS = 15000;
+/** Z-axis mask offset used during box-shadow rendering. */
+exports.SHADOW_MASK_OFFSET = 10000;
+/** Polling interval (ms) when waiting for the cloned iframe to become ready. */
+exports.IFRAME_READY_POLL_MS = 50;
+/** Deferred resolution delay (ms) for inline XML images that may fail to parse. */
+exports.INLINE_IMAGE_RESOLVE_DELAY_MS = 500;
+/** Maximum characters logged for image/resource keys. */
+exports.RESOURCE_KEY_LOG_LENGTH = 256;

package/dist/lib/core/context.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+const logger_1 = require("./logger");
+const cache_storage_1 = require("./cache-storage");
+const origin_checker_1 = require("./origin-checker");
+class Context {
+    constructor(options, windowBounds, config) {
+        this.windowBounds = windowBounds;
+        this.instanceName = `#${Context.instanceCount++}`;
+        this.config = config;
+        this.logger = new logger_1.Logger({ id: this.instanceName, enabled: options.logging });
+        this.originChecker = new origin_checker_1.OriginChecker(config.window);
+        this.cache = options.cache ?? config.cache ?? new cache_storage_1.Cache(this, options);
+        this.onError = options.onError;
+    }
+}
+exports.Context = Context;
+Context.instanceCount = 1;

package/dist/lib/core/debugger.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDebugging = void 0;
+const elementDebuggerAttribute = 'data-html2canvas-debug';
+const getElementDebugType = (element) => {
+    if (typeof element.getAttribute !== 'function') {
+        return 0 /* DebuggerType.NONE */;
+    }
+    const attribute = element.getAttribute(elementDebuggerAttribute);
+    switch (attribute) {
+        case 'all':
+            return 1 /* DebuggerType.ALL */;
+        case 'clone':
+            return 2 /* DebuggerType.CLONE */;
+        case 'parse':
+            return 3 /* DebuggerType.PARSE */;
+        case 'render':
+            return 4 /* DebuggerType.RENDER */;
+        default:
+            return 0 /* DebuggerType.NONE */;
+    }
+};
+const isDebugging = (element, type) => {
+    const elementType = getElementDebugType(element);
+    return elementType === 1 /* DebuggerType.ALL */ || type === elementType;
+};
+exports.isDebugging = isDebugging;