html2canvas-pro 2.3.1 → 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

@@ -7,7 +7,6 @@ const path_1 = require("../path");
 const bound_curves_1 = require("../bound-curves");
 const background_1 = require("../background");
 const box_sizing_1 = require("../box-sizing");
-const font_metrics_1 = require("../font-metrics");
 const text_renderer_1 = require("./text-renderer");
 const background_renderer_1 = require("./background-renderer");
 const border_renderer_1 = require("./border-renderer");
@@ -17,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;
@@ -33,7 +35,6 @@ class CanvasRenderer {
             this.canvas.style.width = `${options.width}px`;
             this.canvas.style.height = `${options.height}px`;
         }
-        this.fontMetrics = new font_metrics_1.FontMetrics(document);
         this.ctx.scale(this.options.scale, this.options.scale);
         this.ctx.translate(-options.x, -options.y);
         this.ctx.textBaseline = 'bottom';
@@ -63,7 +64,6 @@ class CanvasRenderer {
         this.effectsRenderer = new effects_renderer_1.EffectsRenderer({ ctx: this.ctx }, { path: (paths) => this.path(paths) });
         this.textRenderer = new text_renderer_1.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}`);
@@ -120,7 +120,7 @@ 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));
-        (0, content_renderer_1.renderFormElements)(this.ctx, this.fontMetrics, this.textRenderer, this.path.bind(this), container, styles);
+        (0, content_renderer_1.renderFormElements)(this.ctx, this.textRenderer, this.path.bind(this), container, styles);
         await (0, content_renderer_1.renderListMarker)(this.ctx, this.context, this.textRenderer, paint, container, styles);
     }
     async renderStackContent(stack) {
@@ -208,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()
@@ -300,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) => {
@@ -313,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/lib/render/canvas/content-renderer.js

@@ -15,6 +15,7 @@ const bounds_1 = require("../../css/layout/bounds");
 const text_1 = require("../../css/layout/text");
 const vector_1 = require("../vector");
 const box_sizing_1 = require("../box-sizing");
+const font_utils_1 = require("./font-utils");
 const image_rendering_1 = require("../../css/property-descriptors/image-rendering");
 const length_percentage_1 = require("../../css/types/length-percentage");
 const line_height_1 = require("../../css/property-descriptors/line-height");
@@ -73,7 +74,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 input_element_container_1.InputElementContainer) {
         const size = Math.min(container.bounds.width, container.bounds.height);
         if (container.type === input_element_container_1.CHECKBOX && container.checked) {
@@ -101,9 +102,10 @@ 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);
+        // Use Canvas API to measure baseline from the actual rendered font
         ctx.font = font;
+        const baseline = (0, font_utils_1.measureBaseline)(ctx, (0, length_percentage_1.getAbsoluteValue)(styles.fontSize, 0));
         const isPlaceholder = container instanceof input_element_container_1.InputElementContainer && container.isPlaceholder;
         ctx.fillStyle = isPlaceholder ? (0, color_utilities_1.asString)(input_element_container_1.PLACEHOLDER_COLOR) : (0, color_utilities_1.asString)(styles.color);
         ctx.textBaseline = 'alphabetic';

package/dist/lib/render/canvas/font-utils.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.measureBaseline = void 0;
+const SAMPLE_TEXT = 'Mg'; // characters with both ascender and descender
+/**
+ * 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 !== undefined && !Number.isNaN(fmAscent) ? fmAscent : tm.actualBoundingBoxAscent;
+    return ascent !== undefined && !Number.isNaN(ascent) ? ascent : fallback;
+};
+exports.measureBaseline = measureBaseline;

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

@@ -18,6 +18,7 @@ const color_utilities_1 = require("../../css/types/color-utilities");
 const parser_1 = require("../../css/syntax/parser");
 const writing_mode_1 = require("../../css/property-descriptors/writing-mode");
 const text_decoration_renderer_1 = require("./text/text-decoration-renderer");
+const font_utils_1 = require("./font-utils");
 // iOS font fix - see https://github.com/niklasvh/html2canvas/pull/2645
 const iOSBrokenFonts = ['-apple-system', 'system-ui'];
 /**
@@ -100,7 +101,6 @@ class TextRenderer {
          */
         this.glyphWidthCache = null;
         this.ctx = deps.ctx;
-        this.fontMetrics = deps.fontMetrics;
         this.options = deps.options;
         this.decorationRenderer = new text_decoration_renderer_1.TextDecorationRenderer(deps.ctx);
     }
@@ -440,16 +440,17 @@ class TextRenderer {
         // Reset glyph width cache at the start of each text node render —
         // the font may change between nodes.
         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 /* DIRECTION.RTL */ ? 'rtl' : 'ltr';
         this.ctx.textAlign = 'left';
         this.ctx.textBaseline = 'alphabetic';
         const paintOrder = styles.paintOrder;
-        // Use the measured baseline from FontMetrics instead of fontSize,
-        // which correctly accounts for fonts with large descenders (e.g. Paul)
-        // where the alphabetic baseline is closer to the top of the em-square.
-        const { baseline } = this.fontMetrics.getMetrics(fontFamily, fontSize);
+        // Compute baseline using the actual rendered font via Canvas API.
+        // This ensures correct positioning whether using webfonts (which may not
+        // be loaded in the original document but are active in the Canvas) or
+        // system fonts.
+        const baseline = (0, font_utils_1.measureBaseline)(this.ctx, styles.fontSize.number);
         // -webkit-line-clamp
         const clamp = styles.webkitLineClamp > 0 &&
             (styles.display & 2 /* DISPLAY.BLOCK */) !== 0 &&

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

@@ -37,7 +37,6 @@ export declare class CanvasRenderer {
     ctx: CanvasRenderingContext2D;
     private readonly context;
     private readonly options;
-    private readonly fontMetrics;
     private readonly backgroundRenderer;
     private readonly borderRenderer;
     private readonly borderImageRenderer;
@@ -58,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/dist/types/render/canvas/content-renderer.d.ts

@@ -5,7 +5,6 @@ import { BoundCurves } from '../bound-curves';
 import { Vector } from '../vector';
 import { Context } from '../../core/context';
 import { TextRenderer } from './text-renderer';
-import { FontMetrics } from '../font-metrics';
 import { Color } from '../../css/types/color';
 import { CSSParsedDeclaration } from '../../css/index';
 /**
@@ -36,7 +35,7 @@ export declare function renderReplacedElements(ctx: CanvasRenderingContext2D, co
 /**
  * Render form element content: checkbox, radio, text input.
  */
-export declare function renderFormElements(ctx: CanvasRenderingContext2D, fontMetrics: FontMetrics, textRenderer: TextRenderer, pathFn: (paths: Vector[]) => void, container: ElementContainer, styles: CSSParsedDeclaration): void;
+export declare function renderFormElements(ctx: CanvasRenderingContext2D, textRenderer: TextRenderer, pathFn: (paths: Vector[]) => void, container: ElementContainer, styles: CSSParsedDeclaration): void;
 /**
  * Render list-item marker (image or text).
  */

package/dist/types/render/canvas/font-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+export declare const measureBaseline: (ctx: CanvasRenderingContext2D, fallback: number) => number;

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

@@ -15,13 +15,11 @@ import { CSSParsedDeclaration } from '../../css';
 import { Bounds } from '../../css/layout/bounds';
 import { TextBounds } from '../../css/layout/text';
 import { WRITING_MODE } from '../../css/property-descriptors/writing-mode';
-import { FontMetrics } from '../font-metrics';
 /**
  * Dependencies required for TextRenderer
  */
 export interface TextRendererDependencies {
     ctx: CanvasRenderingContext2D;
-    fontMetrics: FontMetrics;
     options: {
         scale: number;
     };
@@ -35,7 +33,6 @@ export declare const hasCJKCharacters: (text: string) => boolean;
  */
 export declare class TextRenderer {
     private readonly ctx;
-    private readonly fontMetrics;
     private readonly options;
     private readonly decorationRenderer;
     /**

package/package.json

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