html2canvas-pro 2.0.0 → 2.0.1

package/dist/html2canvas-pro.esm.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
  */
@@ -3424,6 +3424,191 @@ const borderRightWidth = borderWidthForSide('right');
 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',
@@ -4622,6 +4807,7 @@ class CSSParsedDeclaration {
         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);
@@ -4813,11 +4999,38 @@ const isDebugging = (element, type) => {
  */
 /**
  * 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
@@ -4833,33 +5046,43 @@ class DOMNormalizer {
             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
@@ -4868,7 +5091,6 @@ class DOMNormalizer {
         if (!isHTMLElementNode(element)) {
             return;
         }
-        // Restore each property that was saved
         if (originalStyles.animationDuration !== undefined) {
             element.style.animationDuration = originalStyles.animationDuration;
         }
@@ -7222,9 +7444,23 @@ class OpacityEffect {
         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) {
@@ -7299,6 +7535,12 @@ class ElementPaint {
                 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;
@@ -7325,6 +7567,126 @@ class ElementPaint {
         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 */);
@@ -8153,7 +8515,8 @@ class BorderRenderer {
  * 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
@@ -8188,21 +8551,25 @@ class EffectsRenderer {
      */
     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);
     }
     /**
@@ -8245,6 +8612,22 @@ class EffectsRenderer {
  */
 // 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
@@ -8302,21 +8685,50 @@ class TextRenderer {
         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);
+            });
         }
     }
     /**
@@ -8334,8 +8746,17 @@ class TextRenderer {
                     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;
             }
@@ -8445,26 +8866,47 @@ class TextRenderer {
     }
     // 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;
         }
@@ -8540,6 +8982,8 @@ class TextRenderer {
                     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 */:
@@ -8548,28 +8992,24 @@ class TextRenderer {
                                     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;
                         }
@@ -8613,19 +9053,18 @@ class TextRenderer {
         // 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) {
@@ -8641,11 +9080,7 @@ class TextRenderer {
                                     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 = '';
@@ -8654,21 +9089,22 @@ class TextRenderer {
                             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;
                 }
@@ -8679,7 +9115,7 @@ class TextRenderer {
         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;
@@ -8703,29 +9139,26 @@ class TextRenderer {
                             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;
+                    }
                 }
             });
         });