html2canvas-pro 2.3.1 → 2.3.3

package/dist/html2canvas-pro.js

@@ -1,5 +1,5 @@
 /*!
-* html2canvas-pro 2.3.1 <https://yorickshan.github.io/html2canvas-pro/>
+* html2canvas-pro 2.3.3 <https://yorickshan.github.io/html2canvas-pro/>
 * Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
 * Released under MIT License
 */
@@ -3962,6 +3962,7 @@
 				if (isIdentToken(token)) switch (token.value) {
 					case "padding-box": return 1;
 					case "content-box": return 2;
+					case "text": return 3;
 				}
 				return 0;
 			});
@@ -8950,60 +8951,6 @@
 		}
 	};
 	//#endregion
-	//#region src/core/util.ts
-	const SMALL_IMAGE = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
-	//#endregion
-	//#region src/render/font-metrics.ts
-	const SAMPLE_TEXT = "Hidden Text";
-	var FontMetrics = class {
-		constructor(document) {
-			this._data = {};
-			this._document = document;
-		}
-		parseMetrics(fontFamily, fontSize) {
-			const container = this._document.createElement("div");
-			const img = this._document.createElement("img");
-			const span = this._document.createElement("span");
-			const body = this._document.body;
-			container.style.visibility = "hidden";
-			container.style.fontFamily = fontFamily;
-			container.style.fontSize = fontSize;
-			container.style.margin = "0";
-			container.style.padding = "0";
-			container.style.whiteSpace = "nowrap";
-			body.appendChild(container);
-			img.src = SMALL_IMAGE;
-			img.width = 1;
-			img.height = 1;
-			img.style.margin = "0";
-			img.style.padding = "0";
-			img.style.verticalAlign = "baseline";
-			span.style.fontFamily = fontFamily;
-			span.style.fontSize = fontSize;
-			span.style.margin = "0";
-			span.style.padding = "0";
-			span.appendChild(this._document.createTextNode(SAMPLE_TEXT));
-			container.appendChild(span);
-			container.appendChild(img);
-			const baseline = img.offsetTop - span.offsetTop + 2;
-			container.removeChild(span);
-			container.appendChild(this._document.createTextNode(SAMPLE_TEXT));
-			container.style.lineHeight = "normal";
-			img.style.verticalAlign = "super";
-			const middle = img.offsetTop - container.offsetTop + 2;
-			body.removeChild(container);
-			return {
-				baseline,
-				middle
-			};
-		}
-		getMetrics(fontFamily, fontSize) {
-			const key = `${fontFamily} ${fontSize}`;
-			if (typeof this._data[key] === "undefined") this._data[key] = this.parseMetrics(fontFamily, fontSize);
-			return this._data[key];
-		}
-	};
-	//#endregion
 	//#region src/render/canvas/text/text-decoration-renderer.ts
 	var TextDecorationRenderer = class {
 		constructor(ctx) {
@@ -9092,6 +9039,33 @@
 		}
 	};
 	//#endregion
+	//#region src/render/canvas/font-utils.ts
+	/**
+	* Font measurement utility
+	*
+	* Provides Canvas API-based baseline measurement that works correctly with
+	* webfonts (which may not be loaded in the original document) and system fonts.
+	*
+	* Fallback chain:
+	*   1. fontBoundingBoxAscent — font-level metric (Chrome 99+, FF 116+, Safari 17.4+)
+	*   2. actualBoundingBoxAscent — glyph-level metric (widely supported)
+	*   3. fallback value — coarse CSS fallback
+	*/
+	const SAMPLE_TEXT = "Mg";
+	/**
+	* Measure the baseline ascent for the currently set font.
+	*
+	* @param ctx - Canvas 2D rendering context with ctx.font already set
+	* @param fallback - Fallback value when no metrics are available (e.g. fontSize.number)
+	* @returns The distance from the text baseline to the top of the bounding box
+	*/
+	const measureBaseline = (ctx, fallback) => {
+		const tm = ctx.measureText(SAMPLE_TEXT);
+		const fmAscent = tm.fontBoundingBoxAscent;
+		const ascent = fmAscent !== void 0 && !Number.isNaN(fmAscent) ? fmAscent : tm.actualBoundingBoxAscent;
+		return ascent !== void 0 && !Number.isNaN(ascent) ? ascent : fallback;
+	};
+	//#endregion
 	//#region src/render/canvas/text-renderer.ts
 	const iOSBrokenFonts = ["-apple-system", "system-ui"];
 	/**
@@ -9144,7 +9118,6 @@
 		constructor(deps) {
 			this.glyphWidthCache = null;
 			this.ctx = deps.ctx;
-			this.fontMetrics = deps.fontMetrics;
 			this.options = deps.options;
 			this.decorationRenderer = new TextDecorationRenderer(deps.ctx);
 		}
@@ -9405,13 +9378,13 @@
 		}
 		async renderTextNode(text, styles, containerBounds) {
 			this.glyphWidthCache = null;
-			const [fontString, fontFamily, fontSize] = this.createFontStyle(styles);
+			const [fontString] = this.createFontStyle(styles);
 			this.ctx.font = fontString;
 			this.ctx.direction = styles.direction === 1 ? "rtl" : "ltr";
 			this.ctx.textAlign = "left";
 			this.ctx.textBaseline = "alphabetic";
 			const paintOrder = styles.paintOrder;
-			const { baseline } = this.fontMetrics.getMetrics(fontFamily, fontSize);
+			const baseline = measureBaseline(this.ctx, styles.fontSize.number);
 			if (styles.webkitLineClamp > 0 && (styles.display & 2) !== 0 && styles.overflowY === 1 && text.textBounds.length > 0) {
 				if (this.renderLineClampedText(text, styles, paintOrder, baseline, containerBounds)) return;
 			}
@@ -10307,7 +10280,7 @@
 	/**
 	* Render form element content: checkbox, radio, text input.
 	*/
-	function renderFormElements(ctx, fontMetrics, textRenderer, pathFn, container, styles) {
+	function renderFormElements(ctx, textRenderer, pathFn, container, styles) {
 		if (container instanceof InputElementContainer) {
 			const size = Math.min(container.bounds.width, container.bounds.height);
 			if (container.type === "checkbox" && container.checked) {
@@ -10334,9 +10307,9 @@
 			}
 		}
 		if (isTextInputElement(container) && container.value.length) {
-			const [font, fontFamily, fontSize] = textRenderer.createFontStyle(styles);
-			const { baseline } = fontMetrics.getMetrics(fontFamily, fontSize);
+			const [font] = textRenderer.createFontStyle(styles);
 			ctx.font = font;
+			const baseline = measureBaseline(ctx, getAbsoluteValue(styles.fontSize, 0));
 			ctx.fillStyle = container instanceof InputElementContainer && container.isPlaceholder ? asString(PLACEHOLDER_COLOR) : asString(styles.color);
 			ctx.textBaseline = "alphabetic";
 			ctx.textAlign = canvasTextAlign(container.styles.textAlign);
@@ -10434,7 +10407,6 @@
 				this.canvas.style.width = `${options.width}px`;
 				this.canvas.style.height = `${options.height}px`;
 			}
-			this.fontMetrics = new FontMetrics(document);
 			this.ctx.scale(this.options.scale, this.options.scale);
 			this.ctx.translate(-options.x, -options.y);
 			this.ctx.textBaseline = "bottom";
@@ -10458,7 +10430,6 @@
 			this.effectsRenderer = new EffectsRenderer({ ctx: this.ctx }, { path: (paths) => this.path(paths) });
 			this.textRenderer = new TextRenderer({
 				ctx: this.ctx,
-				fontMetrics: this.fontMetrics,
 				options: { scale: options.scale }
 			});
 			this.context.logger.debug(`Canvas renderer initialized (${options.width}x${options.height}) with scale ${options.scale}`);
@@ -10506,7 +10477,7 @@
 				width: this.options.width,
 				height: this.options.height
 			}, (ctx, opts) => new CanvasRenderer(ctx, opts), container, curves, styles, (c, cv, img) => this.renderReplacedElement(c, cv, img));
-			renderFormElements(this.ctx, this.fontMetrics, this.textRenderer, this.path.bind(this), container, styles);
+			renderFormElements(this.ctx, this.textRenderer, this.path.bind(this), container, styles);
 			await renderListMarker(this.ctx, this.context, this.textRenderer, paint, container, styles);
 		}
 		async renderStackContent(stack) {
@@ -10558,6 +10529,7 @@
 			this.effectsRenderer.applyEffects(paint.getEffects(2));
 			const styles = paint.container.styles;
 			const hasBackground = !isTransparent(styles.backgroundColor) || styles.backgroundImage.length;
+			const hasTextClip = hasTextBackgroundClip(styles);
 			const borders = [
 				{
 					style: styles.borderTopStyle,
@@ -10580,17 +10552,21 @@
 					width: styles.borderLeftWidth
 				}
 			];
-			const backgroundPaintingArea = calculateBackgroundCurvedPaintingArea(getBackgroundValueForIndex(styles.backgroundClip, 0), paint.curves);
+			const backgroundClipValue = getBackgroundValueForIndex(styles.backgroundClip, 0);
+			const backgroundPaintingArea = calculateBackgroundCurvedPaintingArea(backgroundClipValue, paint.curves);
 			if (hasBackground || styles.boxShadow.length) {
-				this.ctx.save();
-				this.path(backgroundPaintingArea);
-				this.ctx.clip();
-				if (!isTransparent(styles.backgroundColor)) {
-					this.ctx.fillStyle = asString(styles.backgroundColor);
-					this.ctx.fill();
+				if (hasTextClip && paint.container.textNodes.length > 0) await this.renderTextClippedBackground(paint);
+				else {
+					this.ctx.save();
+					this.path(backgroundPaintingArea);
+					this.ctx.clip();
+					if (!isTransparent(styles.backgroundColor)) {
+						this.ctx.fillStyle = asString(styles.backgroundColor);
+						this.ctx.fill();
+					}
+					await this.backgroundRenderer.renderBackgroundImage(paint.container);
+					this.ctx.restore();
 				}
-				await this.backgroundRenderer.renderBackgroundImage(paint.container);
-				this.ctx.restore();
 				styles.boxShadow.slice(0).reverse().forEach((shadow) => {
 					this.ctx.save();
 					const borderBoxArea = calculateBorderBoxPath(paint.curves);
@@ -10649,6 +10625,82 @@
 			this.effectsRenderer.applyEffects([]);
 			return this.canvas;
 		}
+		/**
+		* Render background clipped to text shape using offscreen canvas with destination-in compositing.
+		* This implements background-clip: text support.
+		*
+		* Algorithm:
+		*   1. Draw background (color + images) onto an offscreen canvas
+		*   2. Use destination-in compositing to clip the background to the text glyph shapes
+		*   3. Composite the result back onto the main canvas
+		*
+		* The offscreen canvas uses CSS-pixel dimensions (not device-pixel) because the
+		* background renderer handles scaling internally via BackgroundRenderer options.
+		*/
+		async renderTextClippedBackground(paint) {
+			const container = paint.container;
+			const styles = container.styles;
+			const bounds = container.bounds;
+			if (bounds.width <= 0 || bounds.height <= 0) return;
+			const offscreen = (this.canvas.ownerDocument ?? document).createElement("canvas");
+			const width = Math.ceil(bounds.width);
+			const height = Math.ceil(bounds.height);
+			offscreen.width = width;
+			offscreen.height = height;
+			const offCtx = offscreen.getContext("2d");
+			if (!offCtx) return;
+			const [fontString] = this.textRenderer.createFontStyle(styles);
+			offCtx.font = fontString;
+			offCtx.textBaseline = "alphabetic";
+			offCtx.textAlign = "left";
+			offCtx.direction = styles.direction === 1 ? "rtl" : "ltr";
+			const baseline = measureBaseline(offCtx, styles.fontSize.number);
+			const bgRenderer = new BackgroundRenderer({
+				ctx: offCtx,
+				context: this.context,
+				canvas: offscreen,
+				options: {
+					width,
+					height,
+					scale: 1
+				}
+			});
+			if (!isTransparent(styles.backgroundColor)) {
+				offCtx.fillStyle = asString(styles.backgroundColor);
+				offCtx.fillRect(0, 0, width, height);
+			}
+			offCtx.save();
+			offCtx.translate(-bounds.left, -bounds.top);
+			await bgRenderer.renderBackgroundImage(container);
+			offCtx.restore();
+			offCtx.globalCompositeOperation = "destination-in";
+			offCtx.fillStyle = "#000";
+			const writingMode = styles.writingMode;
+			const letterSpacing = styles.letterSpacing;
+			for (const textNode of container.textNodes) for (const textBound of textNode.textBounds) {
+				const localLeft = textBound.bounds.left - bounds.left;
+				const localTop = textBound.bounds.top - bounds.top + baseline;
+				if (letterSpacing > 0) this.renderTextMaskWithLetterSpacing(offCtx, textBound, letterSpacing, localLeft, localTop, writingMode);
+				else offCtx.fillText(textBound.text, localLeft, localTop);
+			}
+			this.ctx.drawImage(offscreen, bounds.left, bounds.top);
+		}
+		/**
+		* Render text glyphs one-by-one as a mask, applying letter-spacing between characters.
+		* This ensures the mask matches how the text renderer lays out the characters.
+		*/
+		renderTextMaskWithLetterSpacing(ctx, text, letterSpacing, x, y, writingMode) {
+			const letters = segmentGraphemes(text.text);
+			let offset = x;
+			for (const letter of letters) {
+				if (isVerticalWritingMode(writingMode)) {
+					ctx.fillText(text.text, x, y);
+					return;
+				}
+				ctx.fillText(letter, offset, y);
+				offset += ctx.measureText(letter).width + letterSpacing;
+			}
+		}
 	};
 	const calculateBackgroundCurvedPaintingArea = (clip, curves) => {
 		switch (clip) {
@@ -10657,6 +10709,12 @@
 			default: return calculatePaddingBoxPath(curves);
 		}
 	};
+	/**
+	* Check if any background layer uses background-clip: text
+	*/
+	const hasTextBackgroundClip = (styles) => {
+		return styles.backgroundClip.some((clip) => clip === 3);
+	};
 	//#endregion
 	//#region src/render/canvas/foreignobject-renderer.ts
 	var ForeignObjectRenderer = class {