html2canvas-pro 2.3.2 → 2.3.3

package/dist/html2canvas-pro.cjs

@@ -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
 */
@@ -3959,6 +3959,7 @@ const backgroundClip = {
 			if (isIdentToken(token)) switch (token.value) {
 				case "padding-box": return 1;
 				case "content-box": return 2;
+				case "text": return 3;
 			}
 			return 0;
 		});
@@ -10525,6 +10526,7 @@ var CanvasRenderer = class CanvasRenderer {
 		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,
@@ -10547,17 +10549,21 @@ var CanvasRenderer = class CanvasRenderer {
 				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);
@@ -10616,6 +10622,82 @@ var CanvasRenderer = class CanvasRenderer {
 		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) {
@@ -10624,6 +10706,12 @@ const calculateBackgroundCurvedPaintingArea = (clip, curves) => {
 		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 {