html2canvas-pro 2.3.2 → 2.3.3

package/dist/lib/css/property-descriptors/background-clip.js

@@ -15,6 +15,8 @@ exports.backgroundClip = {
                         return 1 /* BACKGROUND_CLIP.PADDING_BOX */;
                     case 'content-box':
                         return 2 /* BACKGROUND_CLIP.CONTENT_BOX */;
+                    case 'text':
+                        return 3 /* BACKGROUND_CLIP.TEXT */;
                 }
             }
             return 0 /* BACKGROUND_CLIP.BORDER_BOX */;

package/dist/lib/render/canvas/canvas-renderer.js

@@ -16,6 +16,9 @@ const canvas_path_1 = require("./canvas-path");
 const object_fit_1 = require("../object-fit");
 const content_renderer_1 = require("./content-renderer");
 const constants_1 = require("../../core/constants");
+const writing_mode_1 = require("../../css/property-descriptors/writing-mode");
+const font_utils_1 = require("./font-utils");
+const text_1 = require("../../css/layout/text");
 class CanvasRenderer {
     constructor(context, options) {
         this.context = context;
@@ -205,23 +208,31 @@ class CanvasRenderer {
         this.effectsRenderer.applyEffects(paint.getEffects(2 /* EffectTarget.BACKGROUND_BORDERS */));
         const styles = paint.container.styles;
         const hasBackground = !(0, color_utilities_1.isTransparent)(styles.backgroundColor) || styles.backgroundImage.length;
+        const hasTextClip = hasTextBackgroundClip(styles);
         const borders = [
             { style: styles.borderTopStyle, color: styles.borderTopColor, width: styles.borderTopWidth },
             { style: styles.borderRightStyle, color: styles.borderRightColor, width: styles.borderRightWidth },
             { style: styles.borderBottomStyle, color: styles.borderBottomColor, width: styles.borderBottomWidth },
             { style: styles.borderLeftStyle, color: styles.borderLeftColor, width: styles.borderLeftWidth }
         ];
-        const backgroundPaintingArea = calculateBackgroundCurvedPaintingArea((0, background_1.getBackgroundValueForIndex)(styles.backgroundClip, 0), paint.curves);
+        const backgroundClipValue = (0, background_1.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 (!(0, color_utilities_1.isTransparent)(styles.backgroundColor)) {
-                this.ctx.fillStyle = (0, color_utilities_1.asString)(styles.backgroundColor);
-                this.ctx.fill();
+            // Handle background-clip: text
+            if (hasTextClip && paint.container.textNodes.length > 0) {
+                await this.renderTextClippedBackground(paint);
+            }
+            else {
+                this.ctx.save();
+                this.path(backgroundPaintingArea);
+                this.ctx.clip();
+                if (!(0, color_utilities_1.isTransparent)(styles.backgroundColor)) {
+                    this.ctx.fillStyle = (0, color_utilities_1.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()
@@ -297,6 +308,103 @@ 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 ownerDocument = this.canvas.ownerDocument ?? document;
+        const offscreen = ownerDocument.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;
+        }
+        // ── Set up font matching the main context ──
+        const [fontString] = this.textRenderer.createFontStyle(styles);
+        offCtx.font = fontString;
+        offCtx.textBaseline = 'alphabetic';
+        offCtx.textAlign = 'left';
+        offCtx.direction = styles.direction === 1 /* DIRECTION.RTL */ ? 'rtl' : 'ltr';
+        // Measure baseline from the actual rendered font
+        const baseline = (0, font_utils_1.measureBaseline)(offCtx, styles.fontSize.number);
+        // ── Draw background onto offscreen canvas ──
+        const bgRenderer = new background_renderer_1.BackgroundRenderer({
+            ctx: offCtx,
+            context: this.context,
+            canvas: offscreen,
+            options: { width, height, scale: 1 }
+        });
+        if (!(0, color_utilities_1.isTransparent)(styles.backgroundColor)) {
+            offCtx.fillStyle = (0, color_utilities_1.asString)(styles.backgroundColor);
+            offCtx.fillRect(0, 0, width, height);
+        }
+        // Background images are positioned relative to the element bounds,
+        // so we need the BackgroundRenderer to compute offsets in the same
+        // coordinate space as the main renderer.  We do that by translating
+        // the offscreen context so that the element origin (bounds.left, bounds.top)
+        // falls at (0, 0).
+        offCtx.save();
+        offCtx.translate(-bounds.left, -bounds.top);
+        await bgRenderer.renderBackgroundImage(container);
+        offCtx.restore();
+        // ── Clip background to text glyphs ──
+        // destination-in: keep background pixels only where the source (text) is non-transparent.
+        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) {
+                // Offset from element bounds to canvas-local coordinates
+                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);
+                }
+            }
+        }
+        // ── Composite back to main canvas ──
+        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 = (0, text_1.segmentGraphemes)(text.text);
+        let offset = x;
+        for (const letter of letters) {
+            if ((0, writing_mode_1.isVerticalWritingMode)(writingMode)) {
+                // Vertical writing mode: not yet supported for text-clip;
+                // fall back to single fillText call.
+                ctx.fillText(text.text, x, y);
+                return;
+            }
+            ctx.fillText(letter, offset, y);
+            offset += ctx.measureText(letter).width + letterSpacing;
+        }
+    }
 }
 exports.CanvasRenderer = CanvasRenderer;
 const calculateBackgroundCurvedPaintingArea = (clip, curves) => {
@@ -310,3 +418,9 @@ const calculateBackgroundCurvedPaintingArea = (clip, curves) => {
             return (0, bound_curves_1.calculatePaddingBoxPath)(curves);
     }
 };
+/**
+ * Check if any background layer uses background-clip: text
+ */
+const hasTextBackgroundClip = (styles) => {
+    return styles.backgroundClip.some((clip) => clip === 3 /* BACKGROUND_CLIP.TEXT */);
+};

package/dist/types/css/property-descriptors/background-clip.d.ts

@@ -2,7 +2,8 @@ import { IPropertyListDescriptor } from '../property-descriptor';
 export declare const enum BACKGROUND_CLIP {
     BORDER_BOX = 0,
     PADDING_BOX = 1,
-    CONTENT_BOX = 2
+    CONTENT_BOX = 2,
+    TEXT = 3
 }
 export type BackgroundClip = BACKGROUND_CLIP[];
 export declare const backgroundClip: IPropertyListDescriptor<BackgroundClip>;

package/dist/types/render/canvas/canvas-renderer.d.ts

@@ -57,4 +57,22 @@ export declare class CanvasRenderer {
     formatPath(paths: Path[]): void;
     renderNodeBackgroundAndBorders(paint: ElementPaint): Promise<void>;
     render(element: ElementContainer): Promise<HTMLCanvasElement>;
+    /**
+     * 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.
+     */
+    private renderTextClippedBackground;
+    /**
+     * 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.
+     */
+    private renderTextMaskWithLetterSpacing;
 }

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.3.2",
+  "version": "2.3.3",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",