html2canvas-pro 2.3.2 → 2.3.4

package/README.md

@@ -22,14 +22,18 @@ Next generation JavaScript screenshot tool.
 ## Why html2canvas-pro?
 
 html2canvas-pro is a fork of [niklasvh/html2canvas](https://github.com/niklasvh/html2canvas) that includes various fixes and new features. It offers several advantages over the original html2canvas:
-- Color function `color()` (including relative colors)
-- Color functions `lab()` / `lch()` / `oklab()` / `oklch()`
+- Color functions `color()` (incl. relative colors), `lab()`, `lch()`, `oklab()`, `oklch()`
+- `background-clip: text` support
+- `mix-blend-mode` support
 - `object-fit` support for `<img/>`
 - CSS `clip-path` support (inset, circle, ellipse, polygon, path)
 - CSS `writing-mode` support (horizontal-tb, vertical-rl, vertical-lr)
+- Native `drop-shadow()` filter rendering via the canvas shadow API
 - **Image smoothing control** — CSS `image-rendering` property and `imageSmoothing`/`imageSmoothingQuality` options
 - **Security validation** — Built-in input validation (XSS/SSRF protection)
 - **Performance monitoring** — Built-in performance measurement API
+- **Progress & error callbacks** — `onProgress` / `onError` options and `AbortSignal` cancellation
+- **Performance optimizations** — deferred CSS parsing and LRU caches for gradients & CSS parsing
 - Various bug fixes from the [changelog](./CHANGELOG.md)
 
 If you found this helpful, don't forget to

package/dist/html2canvas-pro.cjs

@@ -1,5 +1,5 @@
 /*!
-* html2canvas-pro 2.3.2 <https://yorickshan.github.io/html2canvas-pro/>
+* html2canvas-pro 2.3.4 <https://yorickshan.github.io/html2canvas-pro/>
 * Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
 * Released under MIT License
 */
@@ -1731,9 +1731,10 @@ const parseFunctionArgs = (tokens) => {
 	let arg = [];
 	tokens.forEach((token) => {
 		if (token.type === 4) {
-			if (arg.length === 0) throw new Error(`Error parsing function args, zero tokens for arg`);
-			args.push(arg);
-			arg = [];
+			if (arg.length) {
+				args.push(arg);
+				arg = [];
+			}
 			return;
 		}
 		if (token.type !== 31) arg.push(token);
@@ -3959,6 +3960,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;
 		});
@@ -6731,7 +6733,8 @@ var CSSParsedCounterDeclaration = class {
 };
 const parseCache = /* @__PURE__ */ new Map();
 const parse = (context, descriptor, style) => {
-	const rawValue = style !== null && typeof style !== "undefined" ? style.toString() : descriptor.initialValue;
+	let rawValue = style !== null && typeof style !== "undefined" ? style.toString() : descriptor.initialValue;
+	if (rawValue.trim() === "") rawValue = descriptor.initialValue;
 	let valueCache = parseCache.get(descriptor);
 	if (valueCache) {
 		const cached = valueCache.get(rawValue);
@@ -10525,6 +10528,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 +10551,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 +10624,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 +10708,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 {