html2canvas-pro 2.2.4 → 2.3.1

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

@@ -7,6 +7,8 @@
  * - Transform effects (matrix transformations)
  * - Clip effects (overflow / border-radius clipping via Path[])
  * - Clip-path effects (CSS clip-path shapes: inset, circle, ellipse, polygon, path)
+ * - Blend effects (mix-blend-mode)
+ * - Filter effects (CSS filter functions)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EffectsRenderer = void 0;
@@ -16,61 +18,104 @@ const effects_1 = require("../effects");
  *
  * Manages rendering effects stack including opacity, transforms, and clipping.
  * Extracted from CanvasRenderer to improve code organization and maintainability.
+ *
+ * ## Save/restore optimisation
+ *
+ * Canvas `save()` / `restore()` snapshot and restore the entire canvas state
+ * (transform matrix, clip region, compositing mode, filter, shadow, …) which
+ * is relatively expensive. The old implementation called `save()` / `restore()`
+ * for every single effect unconditionally.
+ *
+ * This implementation does a **batch pre-scan** before applying effects:
+ *
+ * | Effect type        | Modifies             | Reversible?   | Needs save? |
+ * |--------------------|----------------------|---------------|-------------|
+ * | TransformEffect     | transform matrix     | ❌ irreversible | **YES**     |
+ * | ClipEffect         | clip region          | ❌ cumulative   | **YES**     |
+ * | ClipPathEffect     | clip region          | ❌ cumulative   | **YES**     |
+ * | OpacityEffect      | globalAlpha          | ✅ scalar       | NO          |
+ * | BlendEffect        | globalCompositeOp    | ✅ scalar       | NO          |
+ * | FilterEffect       | filter + shadow      | ✅ string+vec   | NO          |
+ *
+ * When the batch contains *only* lightweight effects (opacity / blend / filter)
+ * we skip `save()` entirely and manually reset properties on pop.
+ *
+ * When the batch contains at least one heavyweight effect (transform / clip /
+ * clip-path) we call `save()` **once** before the first heavyweight effect and
+ * `restore()` **once** when that effect is popped.
  */
 class EffectsRenderer {
     constructor(deps, pathCallback) {
         this.activeEffects = [];
+        /** Whether a canvas state save was performed for the current batch. */
+        this.didSave = false;
+        /** Index (0-based, from start of activeEffects array) of the last
+         *  heavyweight effect in the batch — the one whose pop triggers
+         *  restore(). Set to -1 when no save was performed. */
+        this.saveAtDepth = -1;
         this.ctx = deps.ctx;
         this.pathCallback = pathCallback;
     }
     /**
-     * Apply multiple effects
-     * Clears existing effects and applies new ones
-     *
-     * @param effects - Array of effects to apply
+     * Apply multiple effects.
+     * Clears existing effects and applies new ones.
      */
     applyEffects(effects) {
-        // Clear all existing effects
+        // ── 1. Pop all previously active effects ──────────────────────
         while (this.activeEffects.length) {
             this.popEffect();
         }
-        // Apply new effects
-        effects.forEach((effect) => this.applyEffect(effect));
+        // ── 2. Determine whether to save canvas state ─────────────────
+        this.didSave = false;
+        this.saveAtDepth = -1;
+        const isHeavy = (e) => (0, effects_1.isTransformEffect)(e) || (0, effects_1.isClipEffect)(e) || (0, effects_1.isClipPathEffect)(e);
+        // Pre-compute the index of the *last* heavyweight effect so pop
+        // can reliably match it regardless of how many heavyweight effects
+        // are in the batch (the save was issued before the first, but the
+        // restore must happen when the LAST heavyweight is popped).
+        const lastHeavyIdx = effects.reduceRight((found, e, idx) => (found !== -1 ? found : isHeavy(e) ? idx : -1), -1);
+        // ── 3. Apply each effect ──────────────────────────────────────
+        for (let i = 0; i < effects.length; i++) {
+            const effect = effects[i];
+            if (isHeavy(effect)) {
+                if (!this.didSave) {
+                    this.ctx.save();
+                    this.didSave = true;
+                }
+                if (i === lastHeavyIdx) {
+                    this.saveAtDepth = this.activeEffects.length;
+                }
+            }
+            this.applyEffect(effect);
+        }
     }
     /**
-     * Apply a single effect
-     *
-     * @param effect - Effect to apply
+     * Apply a single effect (called internally by applyEffects).
      */
     applyEffect(effect) {
-        this.ctx.save();
-        if ((0, effects_1.isOpacityEffect)(effect)) {
-            // Opacity: multiply into the current global alpha for nested transparency.
-            this.ctx.globalAlpha = effect.opacity;
-        }
-        else if ((0, effects_1.isTransformEffect)(effect)) {
-            // Transform: translate to origin, apply matrix, translate back.
+        if ((0, effects_1.isTransformEffect)(effect)) {
             this.ctx.translate(effect.offsetX, effect.offsetY);
             this.ctx.transform(effect.matrix[0], effect.matrix[1], effect.matrix[2], effect.matrix[3], effect.matrix[4], effect.matrix[5]);
             this.ctx.translate(-effect.offsetX, -effect.offsetY);
         }
         else if ((0, effects_1.isClipEffect)(effect)) {
-            // Clip (overflow / border-radius): build path via callback then clip.
             this.pathCallback.path(effect.path);
             this.ctx.clip();
         }
         else if ((0, effects_1.isClipPathEffect)(effect)) {
-            // Clip-path: delegate shape drawing (beginPath … clip()) to the effect.
             effect.applyClip(this.ctx);
         }
+        else if ((0, effects_1.isOpacityEffect)(effect)) {
+            // Multiply into current globalAlpha so nested opacity works
+            // without save/restore overhead.
+            this.ctx.globalAlpha *= effect.opacity;
+        }
         else if ((0, effects_1.isBlendEffect)(effect)) {
             this.ctx.globalCompositeOperation = effect.compositeOperation;
         }
         else if ((0, effects_1.isFilterEffect)(effect)) {
-            // Apply all filters except drop-shadow() via ctx.filter.
-            // drop-shadow() is rendered separately through ctx.shadow*
-            // because ctx.filter="drop-shadow(...)" taints the canvas
-            // even for same-origin content (Chrome, Firefox).
+            // drop-shadow() is rendered via ctx.shadow* to avoid canvas
+            // taint; remaining filters go through ctx.filter.
             this.ctx.filter = effect.safeFilterString || 'none';
             if (effect.shadow) {
                 this.ctx.shadowOffsetX = effect.shadow.offsetX;
@@ -82,25 +127,42 @@ class EffectsRenderer {
         this.activeEffects.push(effect);
     }
     /**
-     * Remove the most recent effect
-     * Restores the canvas state before the effect was applied
+     * Remove the most recent effect.
+     * Restores canvas state if needed.
      */
     popEffect() {
+        if (this.activeEffects.length === 0)
+            return;
+        // If the effect being popped is the one that triggered the save,
+        // restore the canvas state now.
+        if (this.didSave && this.activeEffects.length - 1 === this.saveAtDepth) {
+            this.ctx.restore();
+            this.didSave = false;
+            this.saveAtDepth = -1;
+        }
         this.activeEffects.pop();
-        this.ctx.restore();
+        // If the batch had ONLY lightweight effects (no save was performed),
+        // reset properties to their defaults. We only do this when all effects
+        // have been popped (activeEffects is empty), so properties don't
+        // flip mid-batch.
+        if (!this.didSave && this.activeEffects.length === 0) {
+            this.ctx.globalAlpha = 1;
+            this.ctx.globalCompositeOperation = 'source-over';
+            this.ctx.filter = 'none';
+            this.ctx.shadowOffsetX = 0;
+            this.ctx.shadowOffsetY = 0;
+            this.ctx.shadowBlur = 0;
+            this.ctx.shadowColor = 'rgba(0, 0, 0, 0)';
+        }
     }
     /**
-     * Get the current number of active effects
-     *
-     * @returns Number of active effects
+     * Get the current number of active effects.
      */
     getActiveEffectCount() {
         return this.activeEffects.length;
     }
     /**
-     * Check if there are any active effects
-     *
-     * @returns True if there are active effects
+     * Check if there are any active effects.
      */
     hasActiveEffects() {
         return this.activeEffects.length > 0;

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

@@ -93,10 +93,36 @@ const getTextStrokeLineJoin = () => {
  */
 class TextRenderer {
     constructor(deps) {
+        /**
+         * Per-render glyph width cache. Keyed by glyph + font string,
+         * avoids redundant `measureText` calls when letter-spacing is non-zero.
+         * Cleared at the start of each renderTextNode call.
+         */
+        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);
     }
+    /**
+     * Returns the cached width for a glyph+font pair, measuring via
+     * measureText if not yet cached. Only used when letterSpacing !== 0
+     * (the `canRenderWholeText` fast path handles the zero-spacing case).
+     */
+    cachedMeasureText(glyph, fontString) {
+        let cache = this.glyphWidthCache;
+        if (!cache) {
+            cache = new Map();
+            this.glyphWidthCache = cache;
+        }
+        const key = glyph + fontString;
+        let w = cache.get(key);
+        if (w === undefined) {
+            w = this.ctx.measureText(glyph).width;
+            cache.set(key, w);
+        }
+        return w;
+    }
     /**
      * Iterate grapheme clusters one-by-one, applying correct letter-spacing and
      * per-script baseline for each character.
@@ -119,6 +145,7 @@ class TextRenderer {
         }
         const letters = (0, text_1.segmentGraphemes)(text.text);
         const y = text.bounds.top + baseline;
+        const fontString = this.ctx.font;
         let left = text.bounds.left;
         for (const letter of letters) {
             if ((0, exports.hasCJKCharacters)(letter)) {
@@ -130,29 +157,53 @@ class TextRenderer {
             else {
                 renderFn(letter, left, y);
             }
-            left += this.ctx.measureText(letter).width + letterSpacing;
+            left += this.cachedMeasureText(letter, fontString) + letterSpacing;
         }
     }
     iterateVerticalGlyphs(text, letterSpacing, baseline, writingMode, renderFn) {
         const letters = (0, text_1.segmentGraphemes)(text.text);
+        const fontString = this.ctx.font;
+        const rotationAngle = writingMode === 4 /* WRITING_MODE.SIDEWAYS_LR */ ? -Math.PI / 2 : Math.PI / 2;
         let top = text.bounds.top;
-        for (const letter of letters) {
-            if ((0, writing_mode_1.isSidewaysWritingMode)(writingMode) || (!(0, exports.hasCJKCharacters)(letter) && letter.trim().length > 0)) {
-                this.ctx.save();
-                this.ctx.translate(text.bounds.left + baseline, top);
-                this.ctx.rotate(writingMode === 4 /* WRITING_MODE.SIDEWAYS_LR */ ? -Math.PI / 2 : Math.PI / 2);
-                renderFn(letter, 0, 0);
-                this.ctx.restore();
-            }
-            else {
+        for (let i = 0; i < letters.length;) {
+            const letter = letters[i];
+            const isSideways = (0, writing_mode_1.isSidewaysWritingMode)(writingMode) || (!(0, exports.hasCJKCharacters)(letter) && letter.trim().length > 0);
+            if (!isSideways) {
+                // CJK glyph in vertical writing mode — render upright
                 const savedBaseline = this.ctx.textBaseline;
                 if ((0, exports.hasCJKCharacters)(letter)) {
                     this.ctx.textBaseline = 'ideographic';
                 }
                 renderFn(letter, text.bounds.left, top + baseline);
                 this.ctx.textBaseline = savedBaseline;
+                top += this.cachedMeasureText(letter, fontString) + letterSpacing;
+                i++;
+                continue;
+            }
+            // ── Batch consecutive sideways glyphs into one save/restore ──
+            const runStart = i;
+            while (i < letters.length) {
+                const ch = letters[i];
+                if (!(0, writing_mode_1.isSidewaysWritingMode)(writingMode) && !(0, exports.hasCJKCharacters)(ch) && ch.trim().length === 0)
+                    break;
+                if ((0, writing_mode_1.isSidewaysWritingMode)(writingMode) || (!(0, exports.hasCJKCharacters)(ch) && ch.trim().length > 0)) {
+                    i++;
+                }
+                else {
+                    break;
+                }
+            }
+            // Render entire sideways run in one save/restore
+            this.ctx.save();
+            this.ctx.translate(text.bounds.left + baseline, top);
+            this.ctx.rotate(rotationAngle);
+            let runOffset = 0;
+            for (let j = runStart; j < i; j++) {
+                renderFn(letters[j], 0, runOffset);
+                runOffset += this.cachedMeasureText(letters[j], fontString) + letterSpacing;
             }
-            top += this.ctx.measureText(letter).width + letterSpacing;
+            this.ctx.restore();
+            top += runOffset;
         }
     }
     /**
@@ -186,21 +237,21 @@ class TextRenderer {
             });
         }
     }
-    renderTextStrokeWithStyle(text, styles) {
+    renderTextStrokeWithStyle(text, styles, baseline) {
         if (!styles.webkitTextStrokeWidth || !text.text.trim().length) {
             return;
         }
         this.ctx.strokeStyle = (0, color_utilities_1.asString)(styles.webkitTextStrokeColor);
         this.ctx.lineWidth = styles.webkitTextStrokeWidth;
         this.ctx.lineJoin = getTextStrokeLineJoin();
-        this.renderStrokeText(text, styles.letterSpacing, styles.fontSize.number, styles.writingMode);
+        this.renderStrokeText(text, styles.letterSpacing, baseline, styles.writingMode);
         this.ctx.strokeStyle = '';
         this.ctx.lineWidth = 0;
         this.ctx.lineJoin = 'miter';
     }
-    renderTextFillWithShadows(text, styles) {
+    renderTextFillWithShadows(text, styles, baseline) {
         this.ctx.fillStyle = (0, color_utilities_1.asString)(styles.color);
-        this.renderTextWithLetterSpacing(text, styles.letterSpacing, styles.fontSize.number, styles.writingMode);
+        this.renderTextWithLetterSpacing(text, styles.letterSpacing, baseline, styles.writingMode);
         const textShadows = styles.textShadow;
         if (textShadows.length && text.text.trim().length) {
             textShadows
@@ -211,7 +262,7 @@ class TextRenderer {
                 this.ctx.shadowOffsetX = textShadow.offsetX.number * this.options.scale;
                 this.ctx.shadowOffsetY = textShadow.offsetY.number * this.options.scale;
                 this.ctx.shadowBlur = textShadow.blur.number;
-                this.renderTextWithLetterSpacing(text, styles.letterSpacing, styles.fontSize.number, styles.writingMode);
+                this.renderTextWithLetterSpacing(text, styles.letterSpacing, baseline, styles.writingMode);
             });
             this.ctx.shadowColor = '';
             this.ctx.shadowOffsetX = 0;
@@ -223,15 +274,15 @@ class TextRenderer {
      * Helper method to render text with paint order support
      * Reduces code duplication in line-clamp and normal rendering
      */
-    renderTextBoundWithPaintOrder(textBound, styles, paintOrderLayers) {
+    renderTextBoundWithPaintOrder(textBound, styles, paintOrderLayers, baseline) {
         paintOrderLayers.forEach((paintOrderLayer) => {
             switch (paintOrderLayer) {
                 case 0 /* PAINT_ORDER_LAYER.FILL */:
                     this.ctx.fillStyle = (0, color_utilities_1.asString)(styles.color);
-                    this.renderTextWithLetterSpacing(textBound, styles.letterSpacing, styles.fontSize.number, styles.writingMode);
+                    this.renderTextWithLetterSpacing(textBound, styles.letterSpacing, baseline, styles.writingMode);
                     break;
                 case 1 /* PAINT_ORDER_LAYER.STROKE */:
-                    this.renderTextStrokeWithStyle(textBound, styles);
+                    this.renderTextStrokeWithStyle(textBound, styles, baseline);
                     break;
             }
         });
@@ -253,6 +304,8 @@ class TextRenderer {
             // kerning and ligatures when rendering multiple glyphs together, so
             // measuring them as one string is more precise than summing individual widths.
             // Binary search reduces measurements from O(n) to O(log n).
+            // NOTE: can't use cachedMeasureText here — the binary search measures
+            // concatenated substrings, and kerning/ligatures depend on the full string.
             const fits = (n) => this.ctx.measureText(graphemes.slice(0, n).join('')).width + ellipsisWidth <= maxWidth;
             let lo = 0;
             let hi = graphemes.length;
@@ -268,10 +321,11 @@ class TextRenderer {
             return graphemes.slice(0, lo).join('') + ellipsis;
         }
         else {
+            const fontString = this.ctx.font;
             let width = ellipsisWidth;
             const result = [];
             for (const letter of graphemes) {
-                const glyphWidth = this.ctx.measureText(letter).width;
+                const glyphWidth = this.cachedMeasureText(letter, fontString);
                 // Check against glyph width only (no trailing spacing): letter-spacing
                 // is applied *between* characters, not after the final glyph. Using
                 // `glyphWidth + letterSpacing` would incorrectly discard letters that
@@ -309,7 +363,7 @@ class TextRenderer {
      * Groups text bounds by their Y position into visual lines, then renders
      * only the first N-1 complete lines followed by an ellipsis on the Nth line.
      */
-    renderLineClampedText(text, styles, paintOrder, containerBounds) {
+    renderLineClampedText(text, styles, paintOrder, baseline, containerBounds) {
         const lineHeight = styles.fontSize.number * 1.5;
         const lines = [];
         let currentLine = [];
@@ -332,7 +386,7 @@ class TextRenderer {
             return false; // fall through to normal rendering
         // Render full lines (0..N-2)
         for (let i = 0; i < maxLines - 1; i++) {
-            lines[i].forEach((tb) => this.renderTextBoundWithPaintOrder(tb, styles, paintOrder));
+            lines[i].forEach((tb) => this.renderTextBoundWithPaintOrder(tb, styles, paintOrder, baseline));
         }
         // Nth line: truncated with ellipsis
         const lastLine = lines[maxLines - 1];
@@ -345,10 +399,10 @@ class TextRenderer {
             for (const layer of paintOrder) {
                 if (layer === 0 /* PAINT_ORDER_LAYER.FILL */) {
                     this.ctx.fillStyle = (0, color_utilities_1.asString)(styles.color);
-                    this.renderTextWithLetterSpacing(bounds, styles.letterSpacing, styles.fontSize.number, styles.writingMode);
+                    this.renderTextWithLetterSpacing(bounds, styles.letterSpacing, baseline, styles.writingMode);
                 }
                 else if (layer === 1 /* PAINT_ORDER_LAYER.STROKE */) {
-                    this.renderTextStrokeWithStyle(bounds, styles);
+                    this.renderTextStrokeWithStyle(bounds, styles, baseline);
                 }
             }
         }
@@ -358,7 +412,7 @@ class TextRenderer {
      * Render single-line text with text-overflow: ellipsis.
      * Returns true if ellipsis was applied (caller should skip normal rendering).
      */
-    renderEllipsisText(text, styles, paintOrder, containerBounds) {
+    renderEllipsisText(text, styles, paintOrder, baseline, containerBounds) {
         const lineHeight = styles.fontSize.number * 1.5;
         const firstTop = text.textBounds[0].bounds.top;
         const isSingleLine = text.textBounds.every((tb) => Math.abs(tb.bounds.top - firstTop) < lineHeight * 0.5);
@@ -376,25 +430,33 @@ class TextRenderer {
         const bounds = new text_1.TextBounds(truncated, text.textBounds[0].bounds);
         for (const layer of paintOrder) {
             if (layer === 0 /* PAINT_ORDER_LAYER.FILL */)
-                this.renderTextFillWithShadows(bounds, styles);
+                this.renderTextFillWithShadows(bounds, styles, baseline);
             else if (layer === 1 /* PAINT_ORDER_LAYER.STROKE */)
-                this.renderTextStrokeWithStyle(bounds, styles);
+                this.renderTextStrokeWithStyle(bounds, styles, baseline);
         }
         return true;
     }
     async renderTextNode(text, styles, containerBounds) {
-        this.ctx.font = this.createFontStyle(styles)[0];
+        // 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);
+        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);
         // -webkit-line-clamp
         const clamp = styles.webkitLineClamp > 0 &&
             (styles.display & 2 /* DISPLAY.BLOCK */) !== 0 &&
             styles.overflowY === 1 /* OVERFLOW.HIDDEN */ &&
             text.textBounds.length > 0;
         if (clamp) {
-            if (this.renderLineClampedText(text, styles, paintOrder, containerBounds))
+            if (this.renderLineClampedText(text, styles, paintOrder, baseline, containerBounds))
                 return;
         }
         // text-overflow: ellipsis (single-line only)
@@ -402,18 +464,18 @@ class TextRenderer {
             containerBounds &&
             styles.overflowX === 1 /* OVERFLOW.HIDDEN */ &&
             text.textBounds.length > 0;
-        if (ellipsis && this.renderEllipsisText(text, styles, paintOrder, containerBounds))
+        if (ellipsis && this.renderEllipsisText(text, styles, paintOrder, baseline, containerBounds))
             return;
         // Normal rendering: fill + stroke + decorations per text bound
         text.textBounds.forEach((tb) => {
             paintOrder.forEach((layer) => {
                 if (layer === 0 /* PAINT_ORDER_LAYER.FILL */) {
-                    this.renderTextFillWithShadows(tb, styles);
+                    this.renderTextFillWithShadows(tb, styles, baseline);
                     if (styles.textDecorationLine.length)
                         this.renderTextDecoration(tb.bounds, styles);
                 }
                 else if (layer === 1 /* PAINT_ORDER_LAYER.STROKE */) {
-                    this.renderTextStrokeWithStyle(tb, styles);
+                    this.renderTextStrokeWithStyle(tb, styles, baseline);
                 }
             });
         });

package/dist/lib/render/stacking-context.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseStackingContexts = exports.ElementPaint = exports.StackingContext = void 0;
+exports.parseStackingContexts = exports.buildClipPathEffect = exports.resolveAxisRadius = exports.hasOverflowClip = exports.ElementPaint = exports.StackingContext = void 0;
 const bitwise_1 = require("../core/bitwise");
 const bound_curves_1 = require("./bound-curves");
 const effects_1 = require("./effects");
@@ -51,7 +51,7 @@ class ElementPaint {
             const matrix = this.container.styles.transform;
             this.effects.push(new effects_1.TransformEffect(offsetX, offsetY, matrix));
         }
-        if (hasOverflowClip(this.container.styles)) {
+        if ((0, exports.hasOverflowClip)(this.container.styles)) {
             const borderBox = (0, bound_curves_1.calculateBorderBoxPath)(this.curves);
             const paddingBox = (0, bound_curves_1.calculatePaddingBoxPath)(this.curves);
             if ((0, path_1.equalPath)(borderBox, paddingBox)) {
@@ -63,7 +63,7 @@ class ElementPaint {
             }
         }
         if (this.container.styles.clipPath.type !== 0 /* CLIP_PATH_TYPE.NONE */) {
-            const clipPathEffect = buildClipPathEffect(this.container.styles.clipPath, this.container.bounds);
+            const clipPathEffect = (0, exports.buildClipPathEffect)(this.container.styles.clipPath, this.container.bounds);
             if (clipPathEffect) {
                 this.effects.push(clipPathEffect);
             }
@@ -91,7 +91,7 @@ class ElementPaint {
             const croplessEffects = parent.effects.filter((effect) => !(0, effects_1.isClipEffect)(effect));
             if (inFlow || parent.container.styles.position !== 0 /* POSITION.STATIC */ || !parent.parent) {
                 inFlow = [2 /* POSITION.ABSOLUTE */, 3 /* POSITION.FIXED */].indexOf(parent.container.styles.position) === -1;
-                if (hasOverflowClip(parent.container.styles)) {
+                if ((0, exports.hasOverflowClip)(parent.container.styles)) {
                     const borderBox = (0, bound_curves_1.calculateBorderBoxPath)(parent.curves);
                     const paddingBox = (0, bound_curves_1.calculatePaddingBoxPath)(parent.curves);
                     if (!(0, path_1.equalPath)(borderBox, paddingBox)) {
@@ -109,7 +109,9 @@ class ElementPaint {
     }
 }
 exports.ElementPaint = ElementPaint;
+/** @internal – exported for testing only. */
 const hasOverflowClip = (styles) => styles.overflowX !== 0 /* OVERFLOW.VISIBLE */ || styles.overflowY !== 0 /* OVERFLOW.VISIBLE */;
+exports.hasOverflowClip = hasOverflowClip;
 /**
  * Resolve a `closest-side` or `farthest-side` shape-radius keyword to pixels
  * for a single axis. Used by both `circle()` (per-axis) and `ellipse()`.
@@ -119,6 +121,7 @@ const hasOverflowClip = (styles) => styles.overflowX !== 0 /* OVERFLOW.VISIBLE *
  * @param start   - Absolute start of the reference box on this axis.
  * @param end     - Absolute end of the reference box on this axis.
  * @param dimRef  - Reference dimension for resolving a length-percentage value.
+ * @internal – exported for testing only.
  */
 const resolveAxisRadius = (r, center, start, end, dimRef) => {
     if (r === 'closest-side')
@@ -127,12 +130,14 @@ const resolveAxisRadius = (r, center, start, end, dimRef) => {
         return Math.max(center - start, end - center);
     return (0, length_percentage_1.getAbsoluteValue)(r, dimRef);
 };
+exports.resolveAxisRadius = resolveAxisRadius;
 /**
  * Convert a parsed ClipPathValue + element bounds into a ClipPathEffect whose
  * `applyClip` callback draws the clip shape directly onto the canvas context.
  *
  * All coordinates are computed in page-absolute space at construction time so
  * the callback itself is allocation-free and executes synchronously.
+ * @internal – exported for testing only.
  */
 const buildClipPathEffect = (clipPath, bounds) => {
     const { left: bLeft, top: bTop, width: bWidth, height: bHeight } = bounds;
@@ -174,8 +179,8 @@ const buildClipPathEffect = (clipPath, bounds) => {
         case 3 /* CLIP_PATH_TYPE.ELLIPSE */: {
             const cx = bLeft + (0, length_percentage_1.getAbsoluteValue)(clipPath.cx, bWidth);
             const cy = bTop + (0, length_percentage_1.getAbsoluteValue)(clipPath.cy, bHeight);
-            const rx = resolveAxisRadius(clipPath.rx, cx, bLeft, bLeft + bWidth, bWidth);
-            const ry = resolveAxisRadius(clipPath.ry, cy, bTop, bTop + bHeight, bHeight);
+            const rx = (0, exports.resolveAxisRadius)(clipPath.rx, cx, bLeft, bLeft + bWidth, bWidth);
+            const ry = (0, exports.resolveAxisRadius)(clipPath.ry, cy, bTop, bTop + bHeight, bHeight);
             return new effects_1.ClipPathEffect((ctx) => {
                 ctx.beginPath();
                 ctx.ellipse(cx, cy, Math.max(0, rx), Math.max(0, ry), 0, 0, Math.PI * 2);
@@ -239,6 +244,7 @@ const buildClipPathEffect = (clipPath, bounds) => {
         }
     }
 };
+exports.buildClipPathEffect = buildClipPathEffect;
 const parseStackTree = (parent, stackingContext, realStackingContext, listItems) => {
     parent.container.elements.forEach((child) => {
         const treatAsRealStackingContext = child.createsRealStackingContext;

package/dist/types/core/abort-helper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AbortSignal helper utilities.
+ */
+/**
+ * Throw a DOMException if the given AbortSignal is already aborted.
+ * Used at checkpoints throughout the rendering pipeline to support
+ * cancellable renders.
+ *
+ * @param signal - The AbortSignal to check. If undefined or not aborted, this is a no-op.
+ * @throws {DOMException} With name 'AbortError' if the signal has been aborted.
+ */
+export declare const throwIfAborted: (signal?: AbortSignal) => void;

package/dist/types/core/background-parser.d.ts

@@ -0,0 +1,16 @@
+import { type Color } from '../css/types/color';
+import type { Context } from './context';
+/**
+ * Resolve the background colour for the rendered canvas, following CSS
+ * background propagation rules:
+ *
+ * 1. If the target element is `<html>`, inherit the first opaque ancestor
+ *    (doc → body → fallback).
+ * 2. Otherwise use the user-supplied backgroundColor, or opaque white.
+ *
+ * @param context               - Current rendering context.
+ * @param element               - The root element being rendered.
+ * @param backgroundColorOverride - User-supplied override (string | null).
+ * @returns A resolved colour value suitable for filling the canvas.
+ */
+export declare const parseBackgroundColor: (context: Context, element: HTMLElement, backgroundColorOverride?: string | null) => Color;

package/dist/types/core/cache-storage.d.ts

@@ -13,8 +13,33 @@ export declare class Cache {
     private readonly _cache;
     private readonly maxSize;
     private readonly _pendingOperations;
+    /** When true, addImage() collects URLs without starting loads. */
+    private _deferMode;
+    /** URLs collected during defer mode, pending batch preload. */
+    private _collectedUrls;
     constructor(context: Context, _options: ResourceOptions);
+    /**
+     * Enter defer mode: subsequent addImage() calls only collect URLs.
+     * Call preloadAll() to exit defer mode and batch-load all URLs.
+     */
+    startDefer(): void;
+    /**
+     * Exit defer mode and load all collected URLs in parallel, respecting
+     * an optional concurrency cap to avoid overwhelming the browser's network
+     * stack (default: 10 concurrent loads).
+     * After this call returns, all images are either loaded (cache hit) or
+     * failed (logged). Subsequent cache.match() calls return immediately.
+     *
+     * @param concurrency - Max concurrent image loads (1–100, default 10).
+     */
+    preloadAll(concurrency?: number): Promise<void>;
     addImage(src: string): Promise<void>;
+    /**
+     * Shared helper: enqueues loading for a single URL with pending-operation
+     * deduplication and error swallowing. Used by both addImage() (normal mode)
+     * and preloadAll() (batch mode).
+     */
+    private _addImageWithPending;
     private _addImageInternal;
     private withTimeout;
     match(src: string): Promise<HTMLImageElement | HTMLCanvasElement | undefined> | undefined;

package/dist/types/core/config-assembler.d.ts

@@ -0,0 +1,28 @@
+import type { Options } from '../options';
+import type { Html2CanvasConfig } from '../config';
+import type { ResourceOptions } from './cache-storage';
+import type { ContextOptions } from './context';
+import type { CloneConfigurations } from '../dom/document-cloner';
+import type { RenderConfigurations } from '../render/canvas/canvas-renderer';
+/**
+ * Coerce known numeric options from string (or other) values to actual numbers.
+ * Mutates the opts object in place — this is intentionally a normalisation
+ * (not pure) step that runs once at the beginning of renderElement.
+ */
+export declare const coerceNumberOptions: (opts: Partial<Options>) => void;
+/** Assemble resource loading options from user-provided Options. */
+export declare const assembleResourceOptions: (opts: Partial<Options>) => ResourceOptions;
+/** Assemble context (logging + cache) options, extending resource options. */
+export declare const assembleContextOptions: (opts: Partial<Options>, config: Html2CanvasConfig, resourceOptions: ResourceOptions) => ContextOptions;
+/** Assemble window / viewport options. */
+export interface AssembledWindowOptions {
+    windowWidth: number;
+    windowHeight: number;
+    scrollX: number;
+    scrollY: number;
+}
+export declare const assembleWindowOptions: (opts: Partial<Options>, defaultView: Window) => AssembledWindowOptions;
+/** Assemble DOM cloning options. */
+export declare const assembleCloneOptions: (opts: Partial<Options>, config: Html2CanvasConfig, foreignObjectRendering: boolean) => CloneConfigurations;
+/** Assemble canvas rendering options. */
+export declare const assembleRenderOptions: (opts: Partial<Options>, backgroundColor: number | null, left: number, top: number, width: number, height: number, devicePixelRatio: number) => RenderConfigurations;