html2canvas-pro 2.5.3 → 2.6.0

package/dist/html2canvas-pro.esm.js

@@ -1,5 +1,5 @@
 /*!
-* html2canvas-pro 2.5.3 <https://yorickshan.github.io/html2canvas-pro/>
+* html2canvas-pro 2.6.0 <https://yorickshan.github.io/html2canvas-pro/>
 * Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
 * Released under MIT License
 */
@@ -242,6 +242,30 @@ var Validator = class {
 		};
 	}
 	/**
+	* Validate the backgroundColor option
+	*
+	* @param backgroundColor - CSS color string or null (transparent)
+	* @returns Validation result
+	*/
+	validateBackgroundColor(backgroundColor) {
+		if (backgroundColor === null) return {
+			valid: true,
+			sanitized: null
+		};
+		if (typeof backgroundColor !== "string" || backgroundColor.length === 0) return {
+			valid: false,
+			error: "backgroundColor must be a CSS color string or null"
+		};
+		if (/[^a-zA-Z0-9%(),.#\s/-]/.test(backgroundColor)) return {
+			valid: false,
+			error: `backgroundColor contains characters that cannot appear in a CSS color: ${backgroundColor}`
+		};
+		return {
+			valid: true,
+			sanitized: backgroundColor
+		};
+	}
+	/**
 	* Validate image timeout
 	*
 	* @param timeout - Timeout in milliseconds
@@ -386,6 +410,10 @@ var Validator = class {
 			const nonceResult = this.validateCspNonce(options.cspNonce);
 			if (!nonceResult.valid) errors.push(`CSP nonce: ${nonceResult.error}`);
 		}
+		if (options.backgroundColor !== void 0) {
+			const colorResult = this.validateBackgroundColor(options.backgroundColor);
+			if (!colorResult.valid) errors.push(`backgroundColor: ${colorResult.error}`);
+		}
 		if (this.config.customValidator) {
 			const customResult = this.config.customValidator(options, "options");
 			if (!customResult.valid) errors.push(`Custom validation: ${customResult.error}`);
@@ -6521,6 +6549,15 @@ const SHADOW_MASK_OFFSET = 1e4;
 */
 const CLONE_READY_TIMEOUT_MS = 3e4;
 /**
+* Total time (ms) to wait for the clone's external stylesheets (link and
+* @import chains) to apply. Shorter than the document readiness window: a
+* stylesheet that needs longer usually means a hung CDN, and rendering with
+* a 10s-old layout beats blocking the capture for 30s. A missed deadline
+* resolves with a warning (the capture continues with a possibly unstyled
+* clone).
+*/
+const STYLESHEET_READY_TIMEOUT_MS = 1e4;
+/**
 * Hard ceiling (ms) for the cloned iframe's load event itself. If the event
 * never fires, the mount is rejected instead of hanging forever.
 */
@@ -8034,7 +8071,49 @@ const imagesReady = (document) => {
 	return Promise.all([].slice.call(document.images, 0).map(imageReady));
 };
 /**
-* Wait until every external stylesheet link of the clone has been applied or
+* Whether every CSS rule of the sheet (and of the @import chains it pulls
+* in) has been applied. A sheet is "attached" as soon as its rules are
+* readable; an external @import inside it may still be loading, which shows
+* up as an inaccessible CSSImportRule.sheet. `cssRules` can throw for
+* cross-origin sheets without a CORS-approved response — those rules cannot
+* be inspected, so the sheet counts as ready rather than blocking the render
+* forever.
+*/
+const isSheetFullyApplied = (sheet, depth = 0) => {
+	if (!sheet || depth > MAX_IMPORT_DEPTH) return true;
+	let rules;
+	try {
+		rules = sheet.cssRules;
+	} catch (_e) {
+		return true;
+	}
+	if (!rules) return true;
+	for (let i = 0; i < rules.length; i++) {
+		const rule = rules[i];
+		if (!rule || !("styleSheet" in rule)) continue;
+		const inner = rule.styleSheet;
+		if (!inner || !isSheetFullyApplied(inner, depth + 1)) return false;
+	}
+	return true;
+};
+const MAX_IMPORT_DEPTH = 32;
+/** Collect every <link> in the document, including links inside shadow roots. */
+const collectLinks = (root, out) => {
+	const links = root.querySelectorAll("link");
+	for (let i = 0; i < links.length; i++) {
+		const link = links[i];
+		if (link) out.push(link);
+	}
+	const walker = (root.ownerDocument ?? root).createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+	let current = walker.nextNode();
+	while (current) {
+		const shadowRoot = current.shadowRoot;
+		if (shadowRoot) collectLinks(shadowRoot, out);
+		current = walker.nextNode();
+	}
+};
+/**
+* Wait until every external stylesheet of the clone has been applied or
 * definitively failed, or the readiness budget expires.
 *
 * The clone is mounted by adoptNode() into an already-closed document
@@ -8047,35 +8126,68 @@ const imagesReady = (document) => {
 * an unstyled layout (issue #245). Inline <style> clones apply
 * synchronously and document-level adopted stylesheets are serialised at
 * clone time, so neither needs this wait.
+*
+* Readiness is polled rather than purely event-driven because a <style>
+* clone serialised from `createStyleClone` re-fetches its external @import
+* rules without firing link load/error events, and shadow-root links are
+* equally event-hostile in some engines. The poll covers both; link events
+* remain as the settle path for plain <link> fetches.
 * @internal – exported for testing only.
 */
-const stylesheetsReady = (documentClone, logger, signal) => {
+const stylesheetsReady = (documentClone, logger, signal, timeoutMs = STYLESHEET_READY_TIMEOUT_MS) => {
 	if (signal?.aborted) return Promise.resolve();
 	const pending = [];
-	const links = documentClone.getElementsByTagName("link");
-	for (let i = 0; i < links.length; i++) {
-		const link = links[i];
-		if (!link || link.sheet) continue;
+	const links = [];
+	collectLinks(documentClone, links);
+	for (const link of links) {
+		if (link.sheet) continue;
 		const rel = (link.getAttribute("rel") ?? "").trim().toLowerCase().split(/\s+/);
 		if (!rel.includes("stylesheet") || rel.includes("alternate") || link.disabled || !link.getAttribute("href")) continue;
 		pending.push(new Promise((resolve) => {
-			let timer;
+			const href = link.href;
 			const settle = () => {
 				link.removeEventListener("load", settle);
 				link.removeEventListener("error", settle);
 				signal?.removeEventListener("abort", onAbort);
-				clearTimeout(timer);
+				clearInterval(timer);
 				resolve();
 			};
 			const onAbort = () => settle();
-			timer = setTimeout(() => {
-				logger?.warn(`Stylesheet ${link.href} did not finish loading within ${CLONE_READY_TIMEOUT_MS / 1e3}s; continuing with a possibly unstyled clone`);
-				settle();
-			}, CLONE_READY_TIMEOUT_MS);
+			if (link.sheet) {
+				resolve();
+				return;
+			}
 			link.addEventListener("load", settle);
 			link.addEventListener("error", settle);
 			signal?.addEventListener("abort", onAbort, { once: true });
-			if (link.sheet) settle();
+			let elapsed = 0;
+			const timer = setInterval(() => {
+				elapsed += 50;
+				if (link.sheet) settle();
+				else if (elapsed >= timeoutMs) {
+					logger?.warn(`Stylesheet ${href} did not finish loading within ${timeoutMs / 1e3}s; continuing with a possibly unstyled clone`);
+					settle();
+				}
+			}, 50);
+		}));
+	}
+	const styleElements = documentClone.getElementsByTagName("style");
+	for (let i = 0; i < styleElements.length; i++) {
+		const style = styleElements[i];
+		const sheet = style?.sheet;
+		if (!sheet || !style?.textContent?.includes("@import")) continue;
+		if (isSheetFullyApplied(sheet)) continue;
+		pending.push(new Promise((resolve) => {
+			let elapsed = 0;
+			const timer = setInterval(() => {
+				elapsed += 50;
+				const currentSheet = style.sheet;
+				if (currentSheet && isSheetFullyApplied(currentSheet) || elapsed >= timeoutMs) {
+					if (elapsed >= timeoutMs && !isSheetFullyApplied(currentSheet ?? null)) logger?.warn(`@import chain in an inline <style> did not finish loading within ${timeoutMs / 1e3}s; continuing with a possibly unstyled clone`);
+					clearInterval(timer);
+					resolve();
+				}
+			}, 50);
 		}));
 	}
 	if (pending.length === 0) return Promise.resolve();
@@ -8233,7 +8345,10 @@ const mountCloneInIFrame = (context, ownerDocument, windowSize, mount) => {
 	addBase(adoptedNode, baseUri);
 	documentClone.replaceChild(adoptedNode, documentClone.documentElement);
 	const stylesheetWait = stylesheetsReady(documentClone, context.logger, mount.signal);
-	return iframeLoad;
+	return iframeLoad.catch((error) => {
+		iframe.parentNode?.removeChild(iframe);
+		throw error;
+	});
 };
 //#endregion
 //#region src/dom/document-cloner.ts
@@ -9756,7 +9871,7 @@ const parseStackTree = (parent, stackingContext, realStackingContext, listItems)
 		if (treatAsRealStackingContext || createsStackingContext) {
 			const parentStack = treatAsRealStackingContext || child.styles.isPositioned() ? realStackingContext : stackingContext;
 			const stack = new StackingContext(paintContainer);
-			if (child.styles.isPositioned() || child.styles.opacity < 1 || child.styles.isTransformed()) {
+			if (treatAsRealStackingContext || child.styles.isPositioned() || child.styles.opacity < 1 || child.styles.isTransformed()) {
 				const order = child.styles.zIndex.order;
 				if (order < 0) {
 					let index = 0;
@@ -12054,6 +12169,7 @@ const paintRadialLayer = (ctx, layer, area) => {
 	ctx.fillStyle = rasterized.lastColor;
 	ctx.fillRect(area.left, area.top, area.width, area.height);
 	ctx.drawImage(rasterized.canvas, area.left + cx - rx, area.top + cy - ry, rx * 2, ry * 2);
+	releaseSurface(rasterized.canvas);
 };
 /** Draw one gradient layer filling the whole mask area. */
 const paintGradientLayer = (ctx, layer, area) => {
@@ -12967,7 +13083,10 @@ var CanvasRenderer = class CanvasRenderer {
 		maskCanvas.width = surface.width;
 		maskCanvas.height = surface.height;
 		const maskCtx = maskCanvas.getContext("2d");
-		if (!maskCtx) return;
+		if (!maskCtx) {
+			releaseSurface(maskCanvas);
+			return;
+		}
 		maskCtx.scale(this.options.scale, this.options.scale);
 		maskCtx.translate(-bounds.left, -bounds.top);
 		try {
@@ -12979,6 +13098,7 @@ var CanvasRenderer = class CanvasRenderer {
 			}, async (url) => await this.context.cache.match(url));
 		} catch (error) {
 			this.context.logger.error(`Error rendering mask-image: ${error instanceof Error ? error.message : error}`);
+			releaseSurface(maskCanvas);
 			return;
 		}
 		ctx.save();
@@ -12988,6 +13108,7 @@ var CanvasRenderer = class CanvasRenderer {
 			ctx.drawImage(maskCanvas, 0, 0);
 		} finally {
 			ctx.restore();
+			releaseSurface(maskCanvas);
 		}
 	}
 	/**
@@ -13392,6 +13513,7 @@ var CanvasRenderer = class CanvasRenderer {
 			ctx.fillStyle = rasterized.lastColor;
 			ctx.fillRect(0, 0, width, height);
 			ctx.drawImage(rasterized.canvas, cx - rx, cy - ry, rx * 2, ry * 2);
+			releaseSurface(rasterized.canvas);
 			return canvas;
 		}
 		if (source.type === 5 || source.type === 6) {
@@ -13541,14 +13663,19 @@ var ForeignObjectRenderer = class {
 		const svg = createForeignObjectSVG(this.options.width, this.options.height, 0, 0, element);
 		const imagePromise = loadSerializedSVG(svg);
 		restoreRootOffsets();
-		const img = await imagePromise;
-		if (this.options.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
-		if (this.options.backgroundColor) {
-			this.ctx.fillStyle = asString(this.options.backgroundColor);
-			this.ctx.fillRect(this.options.x, this.options.y, this.options.width, this.options.height);
+		try {
+			const img = await imagePromise;
+			if (this.options.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
+			if (this.options.backgroundColor) {
+				this.ctx.fillStyle = asString(this.options.backgroundColor);
+				this.ctx.fillRect(this.options.x, this.options.y, this.options.width, this.options.height);
+			}
+			this.ctx.drawImage(img, this.options.x, this.options.y, this.options.width, this.options.height);
+			return this.canvas;
+		} catch (error) {
+			if (!this.options.canvas) releaseSurface(this.canvas);
+			throw error;
 		}
-		this.ctx.drawImage(img, this.options.x, this.options.y, this.options.width, this.options.height);
-		return this.canvas;
 	}
 };
 /**
@@ -14104,19 +14231,17 @@ const renderElement = async (element, opts, config) => {
 	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");
-	emitProgress(opts.onProgress, context, "clone", 30);
-	if (signal?.aborted) {
-		if (opts.removeContainer ?? true) DocumentCloner.destroy(container);
-		throwIfAborted(signal);
-	}
-	const { width, height, left, top } = isBodyElement(clonedElement) || isHTMLElement(clonedElement) ? parseDocumentSize(clonedElement.ownerDocument) : parseBounds(context, clonedElement);
-	const backgroundColor = parseBackgroundColor(context, clonedElement, opts.backgroundColor);
-	const renderOptions = assembleRenderOptions(opts, backgroundColor, left, top, width, height, defaultView.devicePixelRatio ?? 1);
+	let container;
 	let canvas;
 	let root;
 	try {
+		container = await documentCloner.toIFrame(ownerDocument, windowBounds);
+		perfMonitor.end("clone");
+		emitProgress(opts.onProgress, context, "clone", 30);
+		throwIfAborted(signal);
+		const { width, height, left, top } = isBodyElement(clonedElement) || isHTMLElement(clonedElement) ? parseDocumentSize(clonedElement.ownerDocument) : parseBounds(context, clonedElement);
+		const backgroundColor = parseBackgroundColor(context, clonedElement, opts.backgroundColor);
+		const renderOptions = assembleRenderOptions(opts, backgroundColor, left, top, width, height, defaultView.devicePixelRatio ?? 1);
 		if (foreignObjectRendering) {
 			context.logger.debug(`Document cloned, using foreign object rendering`);
 			perfMonitor.start("render-foreignobject");
@@ -14150,7 +14275,7 @@ const renderElement = async (element, opts, config) => {
 		try {
 			if (root) root.restoreTree();
 		} finally {
-			if (opts.removeContainer ?? true) DocumentCloner.destroy(container);
+			if (container && (opts.removeContainer ?? true)) DocumentCloner.destroy(container);
 			perfMonitor.end("cleanup");
 		}
 	}