html2canvas-pro 2.3.2 → 2.3.3

package/dist/html2canvas-pro.js

@@ -1,5 +1,5 @@
 /*!
-* html2canvas-pro 2.3.2 <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;
 			});
@@ -10528,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,
@@ -10550,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);
@@ -10619,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) {
@@ -10627,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 {