html2canvas-pro 2.3.1 → 2.3.3

package/dist/html2canvas-pro.cjs

@@ -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
 */
@@ -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;
 		});
@@ -8947,60 +8948,6 @@ const calculateBackgroundRepeatPath = (repeat, [x, y], [width, height], backgrou
 	}
 };
 //#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) {
@@ -9089,6 +9036,33 @@ var TextDecorationRenderer = class {
 	}
 };
 //#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"];
 /**
@@ -9141,7 +9115,6 @@ var TextRenderer = class {
 	constructor(deps) {
 		this.glyphWidthCache = null;
 		this.ctx = deps.ctx;
-		this.fontMetrics = deps.fontMetrics;
 		this.options = deps.options;
 		this.decorationRenderer = new TextDecorationRenderer(deps.ctx);
 	}
@@ -9402,13 +9375,13 @@ var TextRenderer = class {
 	}
 	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;
 		}
@@ -10304,7 +10277,7 @@ async function renderReplacedElements(ctx, context, options, iframeRendererFacto
 /**
 * 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) {
@@ -10331,9 +10304,9 @@ function renderFormElements(ctx, fontMetrics, textRenderer, pathFn, container, s
 		}
 	}
 	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);
@@ -10431,7 +10404,6 @@ var CanvasRenderer = class CanvasRenderer {
 			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";
@@ -10455,7 +10427,6 @@ var CanvasRenderer = class CanvasRenderer {
 		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}`);
@@ -10503,7 +10474,7 @@ var CanvasRenderer = class CanvasRenderer {
 			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) {
@@ -10555,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,
@@ -10577,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);
@@ -10646,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) {
@@ -10654,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 {