html2canvas-pro 2.0.0 → 2.0.1

package/dist/html2canvas-pro.js

@@ -1,5 +1,5 @@
 /*!
- * html2canvas-pro 2.0.0 <https://yorickshan.github.io/html2canvas-pro/>
+ * html2canvas-pro 2.0.1 <https://yorickshan.github.io/html2canvas-pro/>
  * Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
  * Released under MIT License
  */
@@ -3430,6 +3430,191 @@
     const borderBottomWidth = borderWidthForSide('bottom');
     const borderLeftWidth = borderWidthForSide('left');
 
+    const NONE = { type: 0 /* CLIP_PATH_TYPE.NONE */ };
+    /**
+     * Parse a shape-radius token: <length-percentage> | closest-side | farthest-side.
+     * Defaults to 'closest-side' when no tokens are provided.
+     */
+    const parseShapeRadius = (tokens) => {
+        const [first] = tokens;
+        if (!first)
+            return 'closest-side';
+        if (isIdentToken(first)) {
+            // Any unrecognised keyword (e.g. 'closest-corner') intentionally falls back to
+            // 'closest-side' as the CSS spec requires unknown values to be treated as invalid
+            // and the initial value of <shape-radius> is 'closest-side'.
+            return first.value === 'farthest-side' ? 'farthest-side' : 'closest-side';
+        }
+        return isLengthPercentage(first) ? first : 'closest-side';
+    };
+    /**
+     * Parse a CSS <position> as (cx, cy), each as a LengthPercentage.
+     *
+     * Supports the **1–2 value** subset of the CSS `<position>` syntax.
+     * The 4-value form (`at left 10px top 20px`) is not supported and will be
+     * parsed on a best-effort basis.
+     *
+     * Axis assignment rules:
+     *   - `left` / `right`  → x-axis (cx)
+     *   - `top`  / `bottom` → y-axis (cy)
+     *   - `center` or a <length-percentage> → fills the first unset axis, in order
+     *
+     * Examples:
+     *   "at left"        → cx=0,    cy=50%   (left is x; y defaults to center)
+     *   "at top"         → cx=50%,  cy=0     (top is y; x defaults to center)
+     *   "at center 30%"  → cx=50%,  cy=30%
+     *   "at 30% center"  → cx=30%,  cy=50%
+     *   "at left top"    → cx=0,    cy=0
+     *   "at top left"    → cx=0,    cy=0     (keyword order is irrelevant)
+     *
+     * Unset axes fall back to 50%.
+     */
+    const parsePosition = (tokens) => {
+        let cx = null;
+        let cy = null;
+        for (const token of tokens) {
+            if (isIdentToken(token)) {
+                switch (token.value) {
+                    case 'left':
+                        cx = ZERO_LENGTH;
+                        break;
+                    case 'right':
+                        cx = HUNDRED_PERCENT;
+                        break;
+                    case 'top':
+                        cy = ZERO_LENGTH;
+                        break;
+                    case 'bottom':
+                        cy = HUNDRED_PERCENT;
+                        break;
+                    case 'center':
+                        // `center` fills whichever axis has not yet been claimed.
+                        if (cx === null)
+                            cx = FIFTY_PERCENT;
+                        else if (cy === null)
+                            cy = FIFTY_PERCENT;
+                        break;
+                }
+            }
+            else if (isLengthPercentage(token)) {
+                // Length-percentages are assigned in source order.
+                if (cx === null)
+                    cx = token;
+                else if (cy === null)
+                    cy = token;
+            }
+        }
+        return { cx: cx ?? FIFTY_PERCENT, cy: cy ?? FIFTY_PERCENT };
+    };
+    /**
+     * inset( <length-percentage>{1,4} [ round <'border-radius'> ]? )
+     * The 1-4 shorthand follows the same expansion as margin/padding:
+     *   1 value  → all four sides
+     *   2 values → top/bottom | left/right
+     *   3 values → top | left/right | bottom
+     *   4 values → top | right | bottom | left
+     * The optional `round` clause (border-radius) is parsed but ignored.
+     */
+    const parseInset = (values) => {
+        const lengths = [];
+        for (const token of values) {
+            if (token.type === 31 /* TokenType.WHITESPACE_TOKEN */)
+                continue;
+            if (isIdentToken(token) && token.value === 'round')
+                break;
+            if (isLengthPercentage(token))
+                lengths.push(token);
+        }
+        const v0 = lengths[0] ?? ZERO_LENGTH;
+        const v1 = lengths[1] ?? v0;
+        const v2 = lengths[2] ?? v0;
+        const v3 = lengths[3] ?? v1;
+        return { type: 1 /* CLIP_PATH_TYPE.INSET */, top: v0, right: v1, bottom: v2, left: v3 };
+    };
+    /**
+     * circle( [ <shape-radius> ]? [ at <position> ]? )
+     */
+    const parseCircle = (values) => {
+        const nonWs = values.filter(nonWhiteSpace);
+        const atIdx = nonWs.findIndex((t) => isIdentWithValue(t, 'at'));
+        const radiusTokens = atIdx === -1 ? nonWs : nonWs.slice(0, atIdx);
+        const posTokens = atIdx === -1 ? [] : nonWs.slice(atIdx + 1);
+        return {
+            type: 2 /* CLIP_PATH_TYPE.CIRCLE */,
+            radius: parseShapeRadius(radiusTokens),
+            ...parsePosition(posTokens)
+        };
+    };
+    /**
+     * ellipse( [ <shape-radius>{2} ]? [ at <position> ]? )
+     */
+    const parseEllipse = (values) => {
+        const nonWs = values.filter(nonWhiteSpace);
+        const atIdx = nonWs.findIndex((t) => isIdentWithValue(t, 'at'));
+        const radiusTokens = atIdx === -1 ? nonWs : nonWs.slice(0, atIdx);
+        const posTokens = atIdx === -1 ? [] : nonWs.slice(atIdx + 1);
+        return {
+            type: 3 /* CLIP_PATH_TYPE.ELLIPSE */,
+            rx: parseShapeRadius(radiusTokens.slice(0, 1)),
+            ry: parseShapeRadius(radiusTokens.slice(1, 2)),
+            ...parsePosition(posTokens)
+        };
+    };
+    /**
+     * polygon( [ <fill-rule>, ]? [ <length-percentage> <length-percentage> ]# )
+     * Each comma-separated group defines one vertex (x y).
+     * A leading fill-rule keyword (nonzero/evenodd) is skipped.
+     */
+    const parsePolygon = (values) => {
+        const args = parseFunctionArgs(values);
+        const points = [];
+        for (const arg of args) {
+            if (arg.length === 1 && isIdentToken(arg[0]))
+                continue; // skip fill-rule
+            const lengths = arg.filter(isLengthPercentage);
+            if (lengths.length >= 2) {
+                points.push([lengths[0], lengths[1]]);
+            }
+        }
+        return { type: 4 /* CLIP_PATH_TYPE.POLYGON */, points };
+    };
+    /**
+     * path( [ <fill-rule>, ]? <string> )
+     * The string value is the SVG path data (coordinates in the element's local space).
+     */
+    const parsePath = (values) => {
+        const stringToken = values.find((t) => t.type === 0 /* TokenType.STRING_TOKEN */);
+        if (!stringToken)
+            return NONE;
+        return { type: 5 /* CLIP_PATH_TYPE.PATH */, d: stringToken.value };
+    };
+    const clipPath = {
+        name: 'clip-path',
+        initialValue: 'none',
+        prefix: false,
+        type: 0 /* PropertyDescriptorParsingType.VALUE */,
+        parse: (_context, token) => {
+            if (isIdentToken(token) && token.value === 'none') {
+                return NONE;
+            }
+            if (token.type === 18 /* TokenType.FUNCTION */) {
+                switch (token.name) {
+                    case 'inset':
+                        return parseInset(token.values);
+                    case 'circle':
+                        return parseCircle(token.values);
+                    case 'ellipse':
+                        return parseEllipse(token.values);
+                    case 'polygon':
+                        return parsePolygon(token.values);
+                    case 'path':
+                        return parsePath(token.values);
+                }
+            }
+            return NONE;
+        }
+    };
+
     const color = {
         name: `color`,
         initialValue: 'transparent',
@@ -4628,6 +4813,7 @@
             this.borderBottomWidth = parse(context, borderBottomWidth, declaration.borderBottomWidth);
             this.borderLeftWidth = parse(context, borderLeftWidth, declaration.borderLeftWidth);
             this.boxShadow = parse(context, boxShadow, declaration.boxShadow);
+            this.clipPath = parse(context, clipPath, declaration.clipPath);
             this.color = parse(context, color, declaration.color);
             this.direction = parse(context, direction, declaration.direction);
             this.display = parse(context, display, declaration.display);
@@ -4819,11 +5005,38 @@
      */
     /**
      * Normalize element styles for accurate rendering
-     * This includes disabling animations and resetting transforms
+     * This includes disabling animations and neutralizing transforms.
      */
     class DOMNormalizer {
         /**
-         * Normalize a single element and return original styles
+         * Normalize a single element and return original styles.
+         *
+         * ## Why we replace transforms with an identity value instead of "none"
+         *
+         * `getBoundingClientRect()` returns visual (post-transform) coordinates, so we
+         * must neutralize any active transform before measuring element bounds.
+         *
+         * The naive approach of setting `transform: none` (or `rotate: none`) has a
+         * critical side-effect: per **CSS Transforms Level 2**, an element whose
+         * `transform` is non-none automatically becomes the **containing block** for
+         * all of its `position: absolute` *and* `position: fixed` descendants.
+         * Setting it to `none` destroys that role, causing children to resolve their
+         * percentage dimensions and offsets against an unintended ancestor — which
+         * produces completely wrong bounds.
+         *
+         * Solution: instead of removing the transform, we replace it with a visually
+         * inert identity value:
+         *
+         * - `transform: scale(0.5)` → `transform: translate(0, 0)`
+         *   - `translate(0, 0)` is an identity transform (no visual change, no layout shift).
+         *   - `getBoundingClientRect()` returns the same layout-space coordinates as
+         *     if there were no transform at all.
+         *   - Because the value is still non-none, the element **remains a containing
+         *     block** for both `position: absolute` and `position: fixed` descendants.
+         *
+         * - `rotate: 45deg` → `rotate: 0deg`
+         *   - `0deg` is the identity rotation; `0deg ≠ none`, so the same containing-
+         *     block guarantee holds.
          *
          * @param element - Element to normalize
          * @param styles - Parsed CSS styles
@@ -4839,33 +5052,43 @@
                 originalStyles.animationDuration = element.style.animationDuration;
                 element.style.animationDuration = '0s';
             }
-            // Reset transform for accurate bounds calculation
-            // getBoundingClientRect takes transforms into account
+            // Replace the actual transform with an identity translate so that:
+            //   1. getBoundingClientRect() returns layout-space (unscaled/unrotated) coords.
+            //   2. The element still satisfies "transform != none" and therefore keeps
+            //      its role as a containing block for position:absolute / position:fixed
+            //      descendants (CSS Transforms Level 2 §2.3).
             if (styles.transform !== null) {
                 originalStyles.transform = element.style.transform;
-                element.style.transform = 'none';
+                element.style.transform = 'translate(0, 0)';
             }
-            // Reset rotate property similarly to transform
+            // Same rationale for the standalone `rotate` property.
+            // `rotate: 0deg` is an identity rotation with no visual effect.
+            //
+            // However, individual transform properties (`rotate`, `translate`, `scale`)
+            // are part of CSS Transforms Level 2 and their containing-block guarantee
+            // is not uniformly implemented across all browsers. To be safe, if `rotate`
+            // is the only transform-like property active on this element, we also set
+            // `transform: translate(0, 0)` so that the containing-block role is reliably
+            // preserved via the well-supported `transform` property.
             if (styles.rotate !== null) {
                 originalStyles.rotate = element.style.rotate;
-                element.style.rotate = 'none';
+                element.style.rotate = '0deg';
+                // Individual transform properties (`rotate`, `translate`, `scale`) are
+                // CSS Transforms Level 2 and their containing-block guarantee is not
+                // uniformly implemented in all browsers. If `transform` was not already
+                // set to translate(0,0) in the block above (i.e. this element has
+                // `rotate` but no `transform`), we set it now so the containing-block
+                // role is reliably established via the widely-supported `transform`
+                // property – independently of browser support for individual props.
+                if (originalStyles.transform === undefined) {
+                    originalStyles.transform = element.style.transform;
+                    element.style.transform = 'translate(0, 0)';
+                }
             }
             return originalStyles;
         }
         /**
-         * Normalize element and its descendants recursively
-         *
-         * @param element - Element to normalize
-         * @param styles - Parsed CSS styles
-         * @returns Original styles map for restoration
-         */
-        static normalizeTree(element, styles) {
-            return this.normalizeElement(element, styles);
-            // Could add recursive normalization here if needed
-            // For now, only normalize the element itself
-        }
-        /**
-         * Restore element styles after rendering
+         * Restore element styles after rendering.
          *
          * @param element - Element to restore
          * @param originalStyles - Original styles to restore
@@ -4874,7 +5097,6 @@
             if (!isHTMLElementNode(element)) {
                 return;
             }
-            // Restore each property that was saved
             if (originalStyles.animationDuration !== undefined) {
                 element.style.animationDuration = originalStyles.animationDuration;
             }
@@ -7228,9 +7450,23 @@
             this.target = 2 /* EffectTarget.BACKGROUND_BORDERS */ | 4 /* EffectTarget.CONTENT */;
         }
     }
+    /**
+     * Clips the element and all its descendants to an arbitrary canvas-drawn shape.
+     * The `applyClip` callback is responsible for calling beginPath, the shape
+     * operations, and ctx.clip() — giving each shape type full control over how
+     * the path is constructed (arc, ellipse, lineTo, Path2D, etc.).
+     */
+    class ClipPathEffect {
+        constructor(applyClip) {
+            this.applyClip = applyClip;
+            this.type = 3 /* EffectType.CLIP_PATH */;
+            this.target = 2 /* EffectTarget.BACKGROUND_BORDERS */ | 4 /* EffectTarget.CONTENT */;
+        }
+    }
     const isTransformEffect = (effect) => effect.type === 0 /* EffectType.TRANSFORM */;
     const isClipEffect = (effect) => effect.type === 1 /* EffectType.CLIP */;
     const isOpacityEffect = (effect) => effect.type === 2 /* EffectType.OPACITY */;
+    const isClipPathEffect = (effect) => effect.type === 3 /* EffectType.CLIP_PATH */;
 
     const equalPath = (a, b) => {
         if (a.length === b.length) {
@@ -7305,6 +7541,12 @@
                     this.effects.push(new ClipEffect(paddingBox, 4 /* EffectTarget.CONTENT */));
                 }
             }
+            if (this.container.styles.clipPath.type !== 0 /* CLIP_PATH_TYPE.NONE */) {
+                const clipPathEffect = buildClipPathEffect(this.container.styles.clipPath, this.container.bounds);
+                if (clipPathEffect) {
+                    this.effects.push(clipPathEffect);
+                }
+            }
         }
         getEffects(target) {
             let inFlow = [2 /* POSITION.ABSOLUTE */, 3 /* POSITION.FIXED */].indexOf(this.container.styles.position) === -1;
@@ -7331,6 +7573,126 @@
             return effects.filter((effect) => contains(effect.target, target));
         }
     }
+    /**
+     * Resolve a `closest-side` or `farthest-side` shape-radius keyword to pixels
+     * for a single axis. Used by both `circle()` (per-axis) and `ellipse()`.
+     *
+     * @param r       - The ShapeRadius (keyword or length-percentage).
+     * @param center  - Absolute center coordinate on this axis (cx or cy).
+     * @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.
+     */
+    const resolveAxisRadius = (r, center, start, end, dimRef) => {
+        if (r === 'closest-side')
+            return Math.min(center - start, end - center);
+        if (r === 'farthest-side')
+            return Math.max(center - start, end - center);
+        return getAbsoluteValue(r, dimRef);
+    };
+    /**
+     * 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.
+     */
+    const buildClipPathEffect = (clipPath, bounds) => {
+        const { left: bLeft, top: bTop, width: bWidth, height: bHeight } = bounds;
+        switch (clipPath.type) {
+            case 1 /* CLIP_PATH_TYPE.INSET */: {
+                const iLeft = getAbsoluteValue(clipPath.left, bWidth);
+                const iTop = getAbsoluteValue(clipPath.top, bHeight);
+                const x = bLeft + iLeft;
+                const y = bTop + iTop;
+                // Clamp to zero: per CSS spec, overlapping insets produce an empty shape.
+                const w = Math.max(0, bWidth - iLeft - getAbsoluteValue(clipPath.right, bWidth));
+                const h = Math.max(0, bHeight - iTop - getAbsoluteValue(clipPath.bottom, bHeight));
+                return new ClipPathEffect((ctx) => {
+                    ctx.beginPath();
+                    ctx.rect(x, y, w, h);
+                    ctx.clip();
+                });
+            }
+            case 2 /* CLIP_PATH_TYPE.CIRCLE */: {
+                const cx = bLeft + getAbsoluteValue(clipPath.cx, bWidth);
+                const cy = bTop + getAbsoluteValue(clipPath.cy, bHeight);
+                let r;
+                if (clipPath.radius === 'closest-side') {
+                    r = Math.min(cx - bLeft, cy - bTop, bLeft + bWidth - cx, bTop + bHeight - cy);
+                }
+                else if (clipPath.radius === 'farthest-side') {
+                    r = Math.max(cx - bLeft, cy - bTop, bLeft + bWidth - cx, bTop + bHeight - cy);
+                }
+                else {
+                    // Per CSS spec, percentage is relative to sqrt(w² + h²) / sqrt(2).
+                    r = getAbsoluteValue(clipPath.radius, Math.sqrt(bWidth * bWidth + bHeight * bHeight) / Math.SQRT2);
+                }
+                return new ClipPathEffect((ctx) => {
+                    ctx.beginPath();
+                    ctx.arc(cx, cy, Math.max(0, r), 0, Math.PI * 2);
+                    ctx.clip();
+                });
+            }
+            case 3 /* CLIP_PATH_TYPE.ELLIPSE */: {
+                const cx = bLeft + getAbsoluteValue(clipPath.cx, bWidth);
+                const cy = bTop + getAbsoluteValue(clipPath.cy, bHeight);
+                const rx = resolveAxisRadius(clipPath.rx, cx, bLeft, bLeft + bWidth, bWidth);
+                const ry = resolveAxisRadius(clipPath.ry, cy, bTop, bTop + bHeight, bHeight);
+                return new ClipPathEffect((ctx) => {
+                    ctx.beginPath();
+                    ctx.ellipse(cx, cy, Math.max(0, rx), Math.max(0, ry), 0, 0, Math.PI * 2);
+                    ctx.clip();
+                });
+            }
+            case 4 /* CLIP_PATH_TYPE.POLYGON */: {
+                // Pre-compute all vertices in page-absolute coordinates.
+                const absPoints = clipPath.points.map(([px, py]) => [bLeft + getAbsoluteValue(px, bWidth), bTop + getAbsoluteValue(py, bHeight)]);
+                return new ClipPathEffect((ctx) => {
+                    ctx.beginPath();
+                    if (absPoints.length > 0) {
+                        ctx.moveTo(absPoints[0][0], absPoints[0][1]);
+                        for (let i = 1; i < absPoints.length; i++) {
+                            ctx.lineTo(absPoints[i][0], absPoints[i][1]);
+                        }
+                        ctx.closePath();
+                    }
+                    // Calling clip() with an empty path (zero points) is intentional:
+                    // it clips the entire region to nothing, which is the correct
+                    // behaviour for a degenerate polygon() per the CSS spec.
+                    ctx.clip();
+                });
+            }
+            case 5 /* CLIP_PATH_TYPE.PATH */: {
+                // path() coordinates are in the element's local space (0,0 = element top-left).
+                // We temporarily translate the canvas origin to the element's position, clip
+                // with the Path2D, then restore only the transform matrix (not the clipping
+                // region) via setTransform so the clip persists for the enclosing
+                // ctx.save() / ctx.restore() pair managed by EffectsRenderer.
+                //
+                // When the element also has a CSS transform, that transform was already applied
+                // by a preceding TransformEffect, so the path coordinates end up correctly in
+                // the element's transformed local space — matching browser behaviour.
+                const { d } = clipPath;
+                return new ClipPathEffect((ctx) => {
+                    try {
+                        const savedTransform = ctx.getTransform();
+                        ctx.translate(bLeft, bTop);
+                        ctx.clip(new Path2D(d));
+                        ctx.setTransform(savedTransform);
+                    }
+                    catch (_e) {
+                        // Path2D or getTransform/setTransform not supported in this environment.
+                    }
+                });
+            }
+            case 0 /* CLIP_PATH_TYPE.NONE */:
+                return null;
+            default: {
+                return null;
+            }
+        }
+    };
     const parseStackTree = (parent, stackingContext, realStackingContext, listItems) => {
         parent.container.elements.forEach((child) => {
             const treatAsRealStackingContext = contains(child.flags, 4 /* FLAGS.CREATES_REAL_STACKING_CONTEXT */);
@@ -8159,7 +8521,8 @@
      * Handles rendering effects including:
      * - Opacity effects
      * - Transform effects (matrix transformations)
-     * - Clip effects (clipping paths)
+     * - Clip effects (overflow / border-radius clipping via Path[])
+     * - Clip-path effects (CSS clip-path shapes: inset, circle, ellipse, polygon, path)
      */
     /**
      * Effects Renderer
@@ -8194,21 +8557,25 @@
          */
         applyEffect(effect) {
             this.ctx.save();
-            // Apply opacity effect
             if (isOpacityEffect(effect)) {
+                // Opacity: multiply into the current global alpha for nested transparency.
                 this.ctx.globalAlpha = effect.opacity;
             }
-            // Apply transform effect
-            if (isTransformEffect(effect)) {
+            else if (isTransformEffect(effect)) {
+                // Transform: translate to origin, apply matrix, translate back.
                 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);
             }
-            // Apply clip effect
-            if (isClipEffect(effect)) {
+            else if (isClipEffect(effect)) {
+                // Clip (overflow / border-radius): build path via callback then clip.
                 this.pathCallback.path(effect.path);
                 this.ctx.clip();
             }
+            else if (isClipPathEffect(effect)) {
+                // Clip-path: delegate shape drawing (beginPath … clip()) to the effect.
+                effect.applyClip(this.ctx);
+            }
             this.activeEffects.push(effect);
         }
         /**
@@ -8251,6 +8618,22 @@
      */
     // iOS font fix - see https://github.com/niklasvh/html2canvas/pull/2645
     const iOSBrokenFonts = ['-apple-system', 'system-ui'];
+    /**
+     * Detect CJK (Chinese, Japanese, Korean) characters in a string.
+     * CJK characters use the ideographic baseline in browsers, which differs
+     * from the alphabetic baseline used for Latin script.
+     *
+     * Covers:
+     *   U+2E80–U+2FFF  CJK Radicals Supplement, Kangxi Radicals
+     *   U+3000–U+30FF  CJK Symbols & Punctuation (。、「」…), Hiragana, Katakana
+     *   U+3400–U+4DBF  CJK Extension A
+     *   U+4E00–U+9FFF  CJK Unified Ideographs (most common Chinese/Japanese/Korean)
+     *   U+AC00–U+D7AF  Hangul Syllables
+     *   U+F900–U+FAFF  CJK Compatibility Ideographs
+     *   U+FF01–U+FFEF  Halfwidth and Fullwidth Forms (Ａ Ｂ １ ２ ！ ？ etc.)
+     */
+    const CJK_CHAR_REGEX = /[\u2E80-\u2FFF\u3000-\u30FF\u3400-\u4DBF\u4E00-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF\uFF01-\uFFEF]/;
+    const hasCJKCharacters = (text) => CJK_CHAR_REGEX.test(text);
     /**
      * Detect iOS version from user agent
      * Returns null if not iOS or version cannot be determined
@@ -8308,21 +8691,50 @@
             this.options = deps.options;
         }
         /**
-         * Render text with letter spacing
-         * Public method used by list rendering
+         * Iterate grapheme clusters one-by-one, applying correct letter-spacing and
+         * per-script baseline for each character.
+         *
+         * Issue #73: When letter-spacing is non-zero, text must be rendered character by
+         * character. This helper centralises two fixes applied during that iteration:
+         *   1. Add `letterSpacing` to each character's advance width (was previously
+         *      omitted, causing characters to render without any spacing).
+         *   2. Switch to the ideographic baseline for CJK glyphs so their vertical
+         *      position matches how browsers lay them out in the DOM.
+         *
+         * The `renderFn` callback receives (letter, x, y) and performs the actual draw
+         * call (fillText or strokeText), allowing fill and stroke paths to share one
+         * implementation.
+         */
+        iterateLettersWithLetterSpacing(text, letterSpacing, baseline, renderFn) {
+            const letters = segmentGraphemes(text.text);
+            const y = text.bounds.top + baseline;
+            let left = text.bounds.left;
+            for (const letter of letters) {
+                if (hasCJKCharacters(letter)) {
+                    const savedBaseline = this.ctx.textBaseline;
+                    this.ctx.textBaseline = 'ideographic';
+                    renderFn(letter, left, y);
+                    this.ctx.textBaseline = savedBaseline;
+                }
+                else {
+                    renderFn(letter, left, y);
+                }
+                left += this.ctx.measureText(letter).width + letterSpacing;
+            }
+        }
+        /**
+         * Render text with letter-spacing applied (fill pass).
+         * When letterSpacing is 0 the whole string is drawn in one call; otherwise each
+         * grapheme is drawn individually so spacing and CJK baseline are applied correctly.
          */
         renderTextWithLetterSpacing(text, letterSpacing, baseline) {
             if (letterSpacing === 0) {
-                // Use alphabetic baseline for consistent text positioning across browsers
-                // Issue #129: text.bounds.top + text.bounds.height causes text to render too low
                 this.ctx.fillText(text.text, text.bounds.left, text.bounds.top + baseline);
             }
             else {
-                const letters = segmentGraphemes(text.text);
-                letters.reduce((left, letter) => {
-                    this.ctx.fillText(letter, left, text.bounds.top + baseline);
-                    return left + this.ctx.measureText(letter).width;
-                }, text.bounds.left);
+                this.iterateLettersWithLetterSpacing(text, letterSpacing, baseline, (letter, x, y) => {
+                    this.ctx.fillText(letter, x, y);
+                });
             }
         }
         /**
@@ -8340,8 +8752,17 @@
                         if (styles.webkitTextStrokeWidth && textBound.text.trim().length) {
                             this.ctx.strokeStyle = asString(styles.webkitTextStrokeColor);
                             this.ctx.lineWidth = styles.webkitTextStrokeWidth;
-                            this.ctx.lineJoin = !!window.chrome ? 'miter' : 'round';
-                            this.renderTextWithLetterSpacing(textBound, styles.letterSpacing, styles.fontSize.number);
+                            this.ctx.lineJoin =
+                                typeof window !== 'undefined' && !!window.chrome ? 'miter' : 'round';
+                            if (styles.letterSpacing === 0) {
+                                this.ctx.strokeText(textBound.text, textBound.bounds.left, textBound.bounds.top + styles.fontSize.number);
+                            }
+                            else {
+                                this.iterateLettersWithLetterSpacing(textBound, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.strokeText(letter, x, y));
+                            }
+                            this.ctx.strokeStyle = '';
+                            this.ctx.lineWidth = 0;
+                            this.ctx.lineJoin = 'miter';
                         }
                         break;
                 }
@@ -8451,26 +8872,47 @@
         }
         // Helper method to truncate text and add ellipsis if needed
         truncateTextWithEllipsis(text, maxWidth, letterSpacing) {
-            const ellipsis = '...';
+            // Use the Unicode ellipsis character (U+2026) whose width the browser measures
+            // as a single glyph, matching native text-overflow behaviour more closely.
+            const ellipsis = '\u2026';
             const ellipsisWidth = this.ctx.measureText(ellipsis).width;
+            // Segment into grapheme clusters so multi-byte characters (emoji, composed
+            // sequences) are never split mid-character.
+            const graphemes = segmentGraphemes(text);
             if (letterSpacing === 0) {
-                let truncated = text;
-                while (this.ctx.measureText(truncated).width + ellipsisWidth > maxWidth && truncated.length > 0) {
-                    truncated = truncated.slice(0, -1);
+                // Measure the whole candidate string for accuracy: the browser applies
+                // 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).
+                const fits = (n) => this.ctx.measureText(graphemes.slice(0, n).join('')).width + ellipsisWidth <= maxWidth;
+                let lo = 0;
+                let hi = graphemes.length;
+                while (lo < hi) {
+                    const mid = (lo + hi + 1) >> 1;
+                    if (fits(mid)) {
+                        lo = mid;
+                    }
+                    else {
+                        hi = mid - 1;
+                    }
                 }
-                return truncated + ellipsis;
+                return graphemes.slice(0, lo).join('') + ellipsis;
             }
             else {
-                const letters = segmentGraphemes(text);
                 let width = ellipsisWidth;
-                let result = [];
-                for (const letter of letters) {
-                    const letterWidth = this.ctx.measureText(letter).width + letterSpacing;
-                    if (width + letterWidth > maxWidth) {
+                const result = [];
+                for (const letter of graphemes) {
+                    const glyphWidth = this.ctx.measureText(letter).width;
+                    // 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
+                    // fit as the last character before the ellipsis.
+                    if (width + glyphWidth > maxWidth) {
                         break;
                     }
                     result.push(letter);
-                    width += letterWidth;
+                    // Accumulate glyph + inter-character spacing for the *next* iteration.
+                    width += glyphWidth + letterSpacing;
                 }
                 return result.join('') + ellipsis;
             }
@@ -8546,6 +8988,8 @@
                         const firstBound = lastLine[0];
                         const availableWidth = containerBounds.width - (firstBound.bounds.left - containerBounds.left);
                         const truncatedText = this.truncateTextWithEllipsis(lastLineText, availableWidth, styles.letterSpacing);
+                        // Build TextBounds once; reused for fill and stroke without re-allocating.
+                        const truncatedBounds = new TextBounds(truncatedText, firstBound.bounds);
                         paintOrder.forEach((paintOrderLayer) => {
                             switch (paintOrderLayer) {
                                 case 0 /* PAINT_ORDER_LAYER.FILL */:
@@ -8554,28 +8998,24 @@
                                         this.ctx.fillText(truncatedText, firstBound.bounds.left, firstBound.bounds.top + styles.fontSize.number);
                                     }
                                     else {
-                                        const letters = segmentGraphemes(truncatedText);
-                                        letters.reduce((left, letter) => {
-                                            this.ctx.fillText(letter, left, firstBound.bounds.top + styles.fontSize.number);
-                                            return left + this.ctx.measureText(letter).width + styles.letterSpacing;
-                                        }, firstBound.bounds.left);
+                                        this.iterateLettersWithLetterSpacing(truncatedBounds, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.fillText(letter, x, y));
                                     }
                                     break;
                                 case 1 /* PAINT_ORDER_LAYER.STROKE */:
                                     if (styles.webkitTextStrokeWidth && truncatedText.trim().length) {
                                         this.ctx.strokeStyle = asString(styles.webkitTextStrokeColor);
                                         this.ctx.lineWidth = styles.webkitTextStrokeWidth;
-                                        this.ctx.lineJoin = !!window.chrome ? 'miter' : 'round';
+                                        this.ctx.lineJoin =
+                                            typeof window !== 'undefined' && !!window.chrome ? 'miter' : 'round';
                                         if (styles.letterSpacing === 0) {
                                             this.ctx.strokeText(truncatedText, firstBound.bounds.left, firstBound.bounds.top + styles.fontSize.number);
                                         }
                                         else {
-                                            const letters = segmentGraphemes(truncatedText);
-                                            letters.reduce((left, letter) => {
-                                                this.ctx.strokeText(letter, left, firstBound.bounds.top + styles.fontSize.number);
-                                                return left + this.ctx.measureText(letter).width + styles.letterSpacing;
-                                            }, firstBound.bounds.left);
+                                            this.iterateLettersWithLetterSpacing(truncatedBounds, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.strokeText(letter, x, y));
                                         }
+                                        this.ctx.strokeStyle = '';
+                                        this.ctx.lineWidth = 0;
+                                        this.ctx.lineJoin = 'miter';
                                     }
                                     break;
                             }
@@ -8619,19 +9059,18 @@
             // If ellipsis is needed, render the truncated text once
             if (needsEllipsis) {
                 const firstBound = text.textBounds[0];
+                // Build TextBounds once; reused across paint layers and every shadow pass
+                // to avoid repeated allocation inside forEach callbacks.
+                const truncatedBounds = new TextBounds(truncatedText, firstBound.bounds);
                 paintOrder.forEach((paintOrderLayer) => {
                     switch (paintOrderLayer) {
-                        case 0 /* PAINT_ORDER_LAYER.FILL */:
+                        case 0 /* PAINT_ORDER_LAYER.FILL */: {
                             this.ctx.fillStyle = asString(styles.color);
                             if (styles.letterSpacing === 0) {
                                 this.ctx.fillText(truncatedText, firstBound.bounds.left, firstBound.bounds.top + styles.fontSize.number);
                             }
                             else {
-                                const letters = segmentGraphemes(truncatedText);
-                                letters.reduce((left, letter) => {
-                                    this.ctx.fillText(letter, left, firstBound.bounds.top + styles.fontSize.number);
-                                    return left + this.ctx.measureText(letter).width + styles.letterSpacing;
-                                }, firstBound.bounds.left);
+                                this.iterateLettersWithLetterSpacing(truncatedBounds, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.fillText(letter, x, y));
                             }
                             const textShadows = styles.textShadow;
                             if (textShadows.length && truncatedText.trim().length) {
@@ -8647,11 +9086,7 @@
                                         this.ctx.fillText(truncatedText, firstBound.bounds.left, firstBound.bounds.top + styles.fontSize.number);
                                     }
                                     else {
-                                        const letters = segmentGraphemes(truncatedText);
-                                        letters.reduce((left, letter) => {
-                                            this.ctx.fillText(letter, left, firstBound.bounds.top + styles.fontSize.number);
-                                            return left + this.ctx.measureText(letter).width + styles.letterSpacing;
-                                        }, firstBound.bounds.left);
+                                        this.iterateLettersWithLetterSpacing(truncatedBounds, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.fillText(letter, x, y));
                                     }
                                 });
                                 this.ctx.shadowColor = '';
@@ -8660,21 +9095,22 @@
                                 this.ctx.shadowBlur = 0;
                             }
                             break;
+                        }
                         case 1 /* PAINT_ORDER_LAYER.STROKE */:
                             if (styles.webkitTextStrokeWidth && truncatedText.trim().length) {
                                 this.ctx.strokeStyle = asString(styles.webkitTextStrokeColor);
                                 this.ctx.lineWidth = styles.webkitTextStrokeWidth;
-                                this.ctx.lineJoin = !!window.chrome ? 'miter' : 'round';
+                                this.ctx.lineJoin =
+                                    typeof window !== 'undefined' && !!window.chrome ? 'miter' : 'round';
                                 if (styles.letterSpacing === 0) {
                                     this.ctx.strokeText(truncatedText, firstBound.bounds.left, firstBound.bounds.top + styles.fontSize.number);
                                 }
                                 else {
-                                    const letters = segmentGraphemes(truncatedText);
-                                    letters.reduce((left, letter) => {
-                                        this.ctx.strokeText(letter, left, firstBound.bounds.top + styles.fontSize.number);
-                                        return left + this.ctx.measureText(letter).width + styles.letterSpacing;
-                                    }, firstBound.bounds.left);
+                                    this.iterateLettersWithLetterSpacing(truncatedBounds, styles.letterSpacing, styles.fontSize.number, (letter, x, y) => this.ctx.strokeText(letter, x, y));
                                 }
+                                this.ctx.strokeStyle = '';
+                                this.ctx.lineWidth = 0;
+                                this.ctx.lineJoin = 'miter';
                             }
                             break;
                     }
@@ -8685,7 +9121,7 @@
             text.textBounds.forEach((text) => {
                 paintOrder.forEach((paintOrderLayer) => {
                     switch (paintOrderLayer) {
-                        case 0 /* PAINT_ORDER_LAYER.FILL */:
+                        case 0 /* PAINT_ORDER_LAYER.FILL */: {
                             this.ctx.fillStyle = asString(styles.color);
                             this.renderTextWithLetterSpacing(text, styles.letterSpacing, styles.fontSize.number);
                             const textShadows = styles.textShadow;
@@ -8709,29 +9145,26 @@
                                 this.renderTextDecoration(text.bounds, styles);
                             }
                             break;
-                        case 1 /* PAINT_ORDER_LAYER.STROKE */:
+                        }
+                        case 1 /* PAINT_ORDER_LAYER.STROKE */: {
                             if (styles.webkitTextStrokeWidth && text.text.trim().length) {
                                 this.ctx.strokeStyle = asString(styles.webkitTextStrokeColor);
                                 this.ctx.lineWidth = styles.webkitTextStrokeWidth;
-                                this.ctx.lineJoin = !!window.chrome ? 'miter' : 'round';
-                                // Issue #110: Use baseline (fontSize) for consistent positioning with fill
-                                // Previously used text.bounds.height which caused stroke to render too low
+                                this.ctx.lineJoin =
+                                    typeof window !== 'undefined' && !!window.chrome ? 'miter' : 'round';
                                 const baseline = styles.fontSize.number;
                                 if (styles.letterSpacing === 0) {
                                     this.ctx.strokeText(text.text, text.bounds.left, text.bounds.top + baseline);
                                 }
                                 else {
-                                    const letters = segmentGraphemes(text.text);
-                                    letters.reduce((left, letter) => {
-                                        this.ctx.strokeText(letter, left, text.bounds.top + baseline);
-                                        return left + this.ctx.measureText(letter).width;
-                                    }, text.bounds.left);
+                                    this.iterateLettersWithLetterSpacing(text, styles.letterSpacing, baseline, (letter, x, y) => this.ctx.strokeText(letter, x, y));
                                 }
+                                this.ctx.strokeStyle = '';
+                                this.ctx.lineWidth = 0;
+                                this.ctx.lineJoin = 'miter';
                             }
-                            this.ctx.strokeStyle = '';
-                            this.ctx.lineWidth = 0;
-                            this.ctx.lineJoin = 'miter';
                             break;
+                        }
                     }
                 });
             });