domotion-svg 0.13.3 → 0.15.0

package/README.md

@@ -126,7 +126,8 @@ npm run demos:examples  # run the bundled example demo scripts
 
 - `FEATURES.md` — per-feature support checklist with links to test fixtures.
 - `docs/` — requirements docs covering rendering fidelity, supported CSS features, and known caveats.
-- `CLAUDE.md` — guidance for AI assistants working in this repo.
+- [`llms.txt`](llms.txt) — a concise, self-contained guide for **AI agents using Domotion as a tool** (Claude, Cursor, etc.): the CLIs, the config schema, the template library, the API, and the gotchas. Point your agent at it.
+- `CLAUDE.md` — guidance for AI assistants working *on this repo's* source (different audience from `llms.txt`).
 
 ## License
 

package/dist/animation/animator.js

@@ -273,6 +273,11 @@ export function generateAnimatedSvg(config) {
         const enterStartPct = entersViaOverlap
             ? pct(timeOffset - prevTransDur, totalDuration)
             : startPct;
+        // DM-1207: the last frame holds solid to 100% (no loop cross-dissolve)
+        // unless `loopFade` is set — same rule the crossfade/cut path applies via
+        // DM-1148 (see emitCrossfadeOrCutFrame). For the slide paths (push-left /
+        // scroll) this means: slide in, then hold (no slide-out / fade-out).
+        const holdLastFrame = i === frames.length - 1 && config.loopFade !== true;
         if (transType === "push-left") {
             // Push: slide in from right, slide out to left
             frameGroups.push(`  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${width}" height="${height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${frame.svgContent}\n  </g></g>`);
@@ -282,7 +287,7 @@ export function generateAnimatedSvg(config) {
             // Window is [enterStartPct .. transEndPct] (when the slide has fully
             // exited the viewBox); 0.01% pad on each side keeps the snap inside the
             // existing opacity:0 bookend.
-            keyframes.push(slideKeyframes(i, "X", width, entersViaPush, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec));
+            keyframes.push(slideKeyframes(i, "X", width, entersViaPush, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec, holdLastFrame));
         }
         else if (transType === "scroll") {
             // DM-609: `scroll` now means real geometric scroll between two frames
@@ -294,7 +299,7 @@ export function generateAnimatedSvg(config) {
             // `fd-${i}` display animation). (`entersViaScroll` is already computed in
             // the outer scope above — same value, no need to redeclare/shadow it.)
             frameGroups.push(`  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${width}" height="${height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${frame.svgContent}\n  </g></g>`);
-            keyframes.push(slideKeyframes(i, "Y", height, entersViaScroll, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec));
+            keyframes.push(slideKeyframes(i, "Y", height, entersViaScroll, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec, holdLastFrame));
         }
         else if (transType === "magic-move" && frame.magicMove != null) {
             // DM-898: magic-move. Frame i holds [start..holdEnd] then HARD-CUTS out;
@@ -686,17 +691,39 @@ function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
  * exits to `-size`. 0.1% pads on each bookend keep the snap inside the
  * opacity:0 frame. Emits the fp/fv/fd keyframes + the `.f-`/`.fp-` rules.
  */
-function slideKeyframes(i, axis, size, entersSliding, enterStartPct, startPct, holdEndPct, transEndPct, visStart, visEnd, totalSec) {
+function slideKeyframes(i, axis, size, entersSliding, enterStartPct, startPct, holdEndPct, transEndPct, visStart, visEnd, totalSec, 
+/** DM-1207: the last frame, when the loop must NOT cross-dissolve, slides in
+ *  and then HOLDS solid (transform 0, opacity 1, visible) to 100% — no
+ *  slide-out / fade-out — and the loop hard-cuts back to frame 0. Mirrors the
+ *  crossfade/cut path's DM-1148 holdToEnd. Without it the slide-out keyframes
+ *  ramp the last frame to opacity 0 across its whole hold, washing it out. */
+holdToEnd = false) {
+    const enterBound = padBefore(parseFloat(enterStartPct), KEYFRAME_EPSILON.slide, 2);
+    if (holdToEnd) {
+        return `
+    @keyframes fp-${i} {
+      0%, ${enterBound}% { transform: translate${axis}(${entersSliding ? size : 0}px); }
+      ${startPct} { transform: translate${axis}(0); }
+      100% { transform: translate${axis}(0); }
+    }
+    @keyframes fv-${i} {
+      0%, ${enterBound}% { opacity: 0; }
+      ${enterStartPct} { opacity: 1; }
+      100% { opacity: 1; }
+    }${buildDisplayKeyframes(`fd-${i}`, visStart, "100")}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
+    .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`;
+    }
     return `
     @keyframes fp-${i} {
-      0%, ${padBefore(parseFloat(enterStartPct), KEYFRAME_EPSILON.slide, 2)}% { transform: translate${axis}(${entersSliding ? size : 0}px); }
+      0%, ${enterBound}% { transform: translate${axis}(${entersSliding ? size : 0}px); }
       ${startPct} { transform: translate${axis}(0); }
       ${holdEndPct} { transform: translate${axis}(0); }
       ${transEndPct} { transform: translate${axis}(-${size}px); }
       ${padAfter(parseFloat(transEndPct), KEYFRAME_EPSILON.slide, 2)}%, 100% { transform: translate${axis}(-${size}px); }
     }
     @keyframes fv-${i} {
-      0%, ${padBefore(parseFloat(enterStartPct), KEYFRAME_EPSILON.slide, 2)}% { opacity: 0; }
+      0%, ${enterBound}% { opacity: 0; }
       ${enterStartPct} { opacity: 1; }
       ${transEndPct} { opacity: 1; }
       ${padAfter(parseFloat(transEndPct), KEYFRAME_EPSILON.slide, 2)}%, 100% { opacity: 0; }
@@ -802,25 +829,46 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                     return `transform: translateX(${val});`;
                 if (a.property === "translateY")
                     return `transform: translateY(${val});`;
+                if (a.property === "scale")
+                    return `transform: scale(${val});`;
                 if (a.property === "clipPath")
                     return `clip-path: ${val};`;
                 return `${a.property}: ${val};`;
             };
+            // DM-1297: SVG transforms are origin-(0,0); a `transformOrigin` makes a
+            // scale/rotate/translate resolve about the element's OWN box (e.g. a
+            // center-origin scale-pop) instead of the SVG origin. `transform-box:
+            // fill-box` switches the reference box to the element's bounding box.
+            const originDecl = a.transformOrigin != null && a.transformOrigin !== ""
+                ? ` transform-box: fill-box; transform-origin: ${a.transformOrigin};`
+                : "";
             const animName = `f${i}-${a.animId}-${ai}`;
             if (a.repeat != null) {
                 // DM-869: repeating animation (blink / pulse / breathe). The keyframe is
                 // a single from→to cycle on the animation's own `duration` clock, looped
                 // via animation-iteration-count + (optional) direction:alternate. The
                 // loop is only visible while the frame is on screen (the frame group's
-                // visibility gating); `animation-delay` aligns the first cycle to the
-                // frame's appearance. `fill-mode: both` holds `from` before the delay.
+                // visibility gating).
+                //
+                // `animation-delay` positions the first cycle: a POSITIVE delay (after the
+                // frame appears) holds `from` until it elapses then plays; a NEGATIVE delay
+                // (a phase offset) starts the loop already mid-cycle so it never freezes —
+                // the right choice for a seamless ambient loop (DM-1289).
+                //
+                // DM-1289: emit timing-function / delay / fill-mode INSIDE the `animation`
+                // shorthand, not as trailing longhands. The optimizer (csso) merges shared
+                // longhands into a separate, earlier grouped rule; a later `animation`
+                // shorthand then resets `animation-fill-mode` back to `none`, so during a
+                // positive delay the element showed its base value (not `from`) and SNAPPED
+                // when the cycle began. Folding everything into the one shorthand leaves
+                // nothing for the optimizer to hoist out of order.
                 const iterations = a.repeat === "infinite" ? "infinite" : String(a.repeat);
                 const direction = a.alternate === true ? " alternate" : "";
                 out.push(`    @keyframes ${animName} {
       0% { ${propValue(a.from)} }
       100% { ${propValue(a.to)} }
     }
-    .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${iterations}${direction}; animation-timing-function: ${easing}; animation-delay: ${startMs.toFixed(0)}ms; animation-fill-mode: both; }`);
+    .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${easing} ${startMs.toFixed(0)}ms ${iterations}${direction} both;${originDecl} }`);
             }
             else {
                 // One-shot: hold `from` until startPct, animate from→to during
@@ -832,7 +880,7 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
       ${endPct.toFixed(3)}% { ${propValue(a.to)} }
       100% { ${propValue(a.to)} }
     }
-    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing};${originDecl} }`);
             }
         }
     }

package/dist/animation/embed-namespace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DM-1287 (doc 73): namespace a self-contained animated SVG so it can be nested
+ * INSIDE another animated SVG without its document-global names colliding.
+ *
+ * A template frame embeds a complete `generateAnimatedSvg` document as one
+ * frame's content. SVG/CSS names are document-global — they do NOT scope to a
+ * nested `<svg>` subtree — so the inner document's generated names clash with the
+ * outer animation's identical names (and with sibling template frames):
+ *
+ *  - **element ids** — `id="viewport-clip"`, `id="f0-bg0"`, glyph defs, gradients,
+ *    clips, filters (referenced via `url(#…)` / `href="#…"`).
+ *  - **embedded-font families** — `font-family:"dmf0"` in `@font-face` + the
+ *    `<text font-family="dmf0">` attrs. A duplicate family name makes a later
+ *    `@font-face` win, so text in OTHER frames reshapes to the wrong glyphs.
+ *  - **frame / animation classes** — `class="f f-0"`, `class="anim-…"` and their
+ *    `.f` / `.f-0` / `.anim-…` style selectors.
+ *  - **`@keyframes` names** — `fv-0`, the intra-frame `f0-…` names — and the
+ *    `animation:` references to them. A duplicate `@keyframes` wins globally, so
+ *    the outer frame-visibility timing gets the inner timeline.
+ *  - **the `--scene-dur` custom property** on `:root`.
+ *
+ * The fix: rewrite every such name with a per-frame token. The vocabulary is
+ * fully controlled (domotion's own renderer/animator emits it), so the rewrite is
+ * precise. The token must be a valid CSS-ident prefix (start with a letter).
+ *
+ * This is the same class of problem the `cast` frame sidesteps by sharing the
+ * outer embedded-font builder (`manageFonts: false`); a template runs a fully
+ * independent `composeAnimateConfig`, so it can't share that state and is
+ * namespaced after the fact instead.
+ */
+/** Options for {@link namespaceEmbeddedAnimatedSvg}. */
+export interface NamespaceEmbedOptions {
+    /**
+     * Prefix embedded-font family names (`dmfN`) too. Default `true` — correct when
+     * the nested document carries its own `@font-face` rules (a template frame).
+     *
+     * Pass `false` when the nested document's fonts are DEFERRED to the host
+     * pipeline's shared embedded-font builder (a `cast` frame composed with
+     * `manageFonts: false`): its `font-family="dmfN"` attrs reference an
+     * `@font-face` emitted ONCE at the outer top level, where the names are already
+     * globally unique — prefixing them here would dangle the reference. The class /
+     * keyframe / id / `--scene-dur` collisions still need fixing, so the rest of the
+     * pass runs unchanged.
+     */
+    namespaceFonts?: boolean;
+}
+/**
+ * Prefix every document-global name in a complete animated-SVG document with
+ * `token` (e.g. `"e1_"`). Returns the rewritten SVG string; the input is assumed
+ * to be a single `<svg>…</svg>` document as produced by `generateAnimatedSvg`.
+ */
+export declare function namespaceEmbeddedAnimatedSvg(svg: string, token: string, opts?: NamespaceEmbedOptions): string;

package/dist/animation/embed-namespace.js

@@ -0,0 +1,89 @@
+/**
+ * DM-1287 (doc 73): namespace a self-contained animated SVG so it can be nested
+ * INSIDE another animated SVG without its document-global names colliding.
+ *
+ * A template frame embeds a complete `generateAnimatedSvg` document as one
+ * frame's content. SVG/CSS names are document-global — they do NOT scope to a
+ * nested `<svg>` subtree — so the inner document's generated names clash with the
+ * outer animation's identical names (and with sibling template frames):
+ *
+ *  - **element ids** — `id="viewport-clip"`, `id="f0-bg0"`, glyph defs, gradients,
+ *    clips, filters (referenced via `url(#…)` / `href="#…"`).
+ *  - **embedded-font families** — `font-family:"dmf0"` in `@font-face` + the
+ *    `<text font-family="dmf0">` attrs. A duplicate family name makes a later
+ *    `@font-face` win, so text in OTHER frames reshapes to the wrong glyphs.
+ *  - **frame / animation classes** — `class="f f-0"`, `class="anim-…"` and their
+ *    `.f` / `.f-0` / `.anim-…` style selectors.
+ *  - **`@keyframes` names** — `fv-0`, the intra-frame `f0-…` names — and the
+ *    `animation:` references to them. A duplicate `@keyframes` wins globally, so
+ *    the outer frame-visibility timing gets the inner timeline.
+ *  - **the `--scene-dur` custom property** on `:root`.
+ *
+ * The fix: rewrite every such name with a per-frame token. The vocabulary is
+ * fully controlled (domotion's own renderer/animator emits it), so the rewrite is
+ * precise. The token must be a valid CSS-ident prefix (start with a letter).
+ *
+ * This is the same class of problem the `cast` frame sidesteps by sharing the
+ * outer embedded-font builder (`manageFonts: false`); a template runs a fully
+ * independent `composeAnimateConfig`, so it can't share that state and is
+ * namespaced after the fact instead.
+ */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const byLengthDesc = (a, b) => b.length - a.length;
+/**
+ * Prefix every document-global name in a complete animated-SVG document with
+ * `token` (e.g. `"e1_"`). Returns the rewritten SVG string; the input is assumed
+ * to be a single `<svg>…</svg>` document as produced by `generateAnimatedSvg`.
+ */
+export function namespaceEmbeddedAnimatedSvg(svg, token, opts = {}) {
+    let out = svg;
+    // 1. Element ids + every reference (url(#id) / (xlink:)href="#id"). Longest
+    //    name first so an id that is a textual prefix of another can't partial-match.
+    const ids = new Set();
+    for (const m of out.matchAll(/\sid="([^"]+)"/g))
+        ids.add(m[1]);
+    for (const id of [...ids].sort(byLengthDesc)) {
+        const e = escapeRe(id);
+        out = out
+            .replace(new RegExp(`(\\sid=")${e}(")`, "g"), `$1${token}${id}$2`)
+            .replace(new RegExp(`url\\(#${e}\\)`, "g"), `url(#${token}${id})`)
+            .replace(new RegExp(`((?:xlink:)?href=")#${e}(")`, "g"), `$1#${token}${id}$2`);
+    }
+    // 2. Embedded-font families (`dmfN`). Only the `@font-face` declaration and the
+    //    `font-family` attr/decl contexts — never a bare global replace, since the
+    //    base64 `src` payload could contain the same byte sequence. Skipped when the
+    //    fonts are deferred to a shared outer builder (see NamespaceEmbedOptions).
+    if (opts.namespaceFonts !== false) {
+        out = out
+            .replace(/(font-family:\s*")(dmf\d+)(")/g, `$1${token}$2$3`)
+            .replace(/(font-family=")(dmf\d+)(")/g, `$1${token}$2$3`);
+    }
+    // 3. `@keyframes` names + their `animation:` references. A keyframe name is a
+    //    domotion-generated token (`fv-0`, `f0-f0a0-0`, …) that never appears as an
+    //    id, class, or inside the (hyphen-free) base64 font data, so a word-boundary
+    //    replace across the whole doc is safe. Longest-first for prefix safety.
+    const keyframes = new Set();
+    for (const m of out.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)/g))
+        keyframes.add(m[1]);
+    for (const name of [...keyframes].sort(byLengthDesc)) {
+        out = out.replace(new RegExp(`\\b${escapeRe(name)}\\b`, "g"), `${token}${name}`);
+    }
+    // 4. Classes. Collect the names from `class="…"` attrs (every token is renderer-
+    //    generated), then (a) prefix each token in every class attr, and (b) prefix
+    //    each known name where it appears as a `.name` selector. The selector pass is
+    //    boundary-guarded (`(?![\w-])`) and limited to the collected names so it can
+    //    never touch a decimal like `0.22` / `22.500%` in the CSS.
+    const classes = new Set();
+    for (const m of out.matchAll(/\sclass="([^"]+)"/g)) {
+        for (const t of m[1].split(/\s+/))
+            if (t !== "")
+                classes.add(t);
+    }
+    out = out.replace(/(\sclass=")([^"]+)(")/g, (_full, a, cls, c) => a + cls.split(/\s+/).map((t) => (t !== "" ? token + t : t)).join(" ") + c);
+    for (const name of [...classes].sort(byLengthDesc)) {
+        out = out.replace(new RegExp(`\\.${escapeRe(name)}(?![\\w-])`, "g"), `.${token}${name}`);
+    }
+    // 5. The `--scene-dur` custom property (declaration on `:root` + any `var()`).
+    out = out.replace(/--scene-dur\b/g, `--scene-dur-${token}`);
+    return out;
+}

package/dist/animation/overlay-schema.d.ts

@@ -249,11 +249,13 @@ export declare const intraFrameAnimationSchema: z.ZodObject<{
         opacity: "opacity";
         translateX: "translateX";
         translateY: "translateY";
+        scale: "scale";
     }>;
     from: z.ZodString;
     to: z.ZodString;
     duration: z.ZodNumber;
     easing: z.ZodOptional<z.ZodString>;
+    transformOrigin: z.ZodOptional<z.ZodString>;
     delay: z.ZodOptional<z.ZodNumber>;
     repeat: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"infinite">]>>;
     alternate: z.ZodOptional<z.ZodBoolean>;

package/dist/animation/overlay-schema.js

@@ -189,8 +189,9 @@ export const intraFrameAnimationSchema = z.object({
      * captured element is wrapped in a `<g class="anim-<id>">`, the keyframes
      * apply `clip-path` to that wrapper.
      */
-    property: z.enum(["width", "height", "opacity", "transform", "translateX", "translateY", "clipPath"]),
-    /** Start value (CSS string, e.g. `"0%"`, `"240px"`, `"0.3"`). */
+    property: z.enum(["width", "height", "opacity", "transform", "translateX", "translateY", "scale", "clipPath"]),
+    /** Start value (CSS string, e.g. `"0%"`, `"240px"`, `"0.3"`). For `scale`,
+     *  a unitless factor (`"0.6"` -> `"1"`). */
     from: z.string(),
     /** End value (same syntax as `from`). */
     to: z.string(),
@@ -198,6 +199,16 @@ export const intraFrameAnimationSchema = z.object({
     duration: z.number(),
     /** CSS easing string. Default `linear`. */
     easing: z.string().optional(),
+    /**
+     * DM-1297: transform-origin for a `transform` / `scale` / `translate*`
+     * animation (e.g. `"center"`, `"50% 50%"`, `"left top"`). SVG transforms are
+     * origin-(0,0) by default, so a `scale`/`rotate` would shrink/orbit toward the
+     * SVG origin instead of the element's own box. Setting this emits
+     * `transform-box: fill-box; transform-origin: <value>` on the animated group so
+     * the transform resolves about the element's OWN bounding box — e.g. a
+     * center-origin scale-pop. Ignored for non-transform properties.
+     */
+    transformOrigin: z.string().optional(),
     /** Ms after the frame becomes visible before animation starts. Default 0. */
     delay: z.number().optional(),
     /**

package/dist/capture/emoji.d.ts

@@ -17,6 +17,43 @@
  */
 import type { Page } from "@playwright/test";
 import type { CapturedElement } from "./types.js";
+/**
+ * Snap an Apple Color Emoji sbix bitmap to the SQUARE box Chrome actually
+ * paints it in.
+ *
+ * Chrome paints a color-emoji glyph as a square whose side equals the glyph
+ * ADVANCE — the captured `Range.getBoundingClientRect()` width, minus any
+ * letter-spacing Chrome appends to the right of the advance. Two facts make
+ * the advance (not the font size) the correct side:
+ *  - At small font sizes Chrome enforces a minimum emoji advance that exceeds
+ *    the font size — e.g. a 20px advance at font-size 16 (~1.25×). Sizing the
+ *    overlay to the font size painted the emoji ~20% too small (DM-1198: "our
+ *    emojis seem a lot smaller").
+ *  - The sbix PNG is a full square bitmap (the emoji fills a square em), so
+ *    drawing it into an advance × advance box reproduces both full-bleed emoji
+ *    and ones with transparent margins (e.g. 📈) without distortion.
+ *
+ * Geometry:
+ *  - Horizontal: the bitmap sits flush at the advance's left (`rect.x`); any
+ *    letter-spacing pads to the RIGHT, so no horizontal shift is applied
+ *    (DM-919 — the original DM-381 centering pass wrongly shifted it right
+ *    whenever letter-spacing > 0).
+ *  - Vertical: the square is centered in the captured rect's line box, which
+ *    matches Chrome within ~1px across sizes (DM-438 — a 20×17 rect extends
+ *    upward to a 20×20 square; DM-801 — a 56×63 rect with 8px letter-spacing
+ *    snaps to 48×48).
+ */
+export declare function emojiSquareRect(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, letterSpacing: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 /**
  * For every text segment CAPTURE_SCRIPT flagged with a rasterRect (contains a
  * color-bitmap glyph like U+2713 ✓ or an emoji), ask Playwright for a

package/dist/capture/emoji.js

@@ -97,6 +97,42 @@ function extractEmojiBitmap(codepoint, paintedWidthPx) {
     _sbixCache.set(cacheKey, result);
     return result;
 }
+/**
+ * Snap an Apple Color Emoji sbix bitmap to the SQUARE box Chrome actually
+ * paints it in.
+ *
+ * Chrome paints a color-emoji glyph as a square whose side equals the glyph
+ * ADVANCE — the captured `Range.getBoundingClientRect()` width, minus any
+ * letter-spacing Chrome appends to the right of the advance. Two facts make
+ * the advance (not the font size) the correct side:
+ *  - At small font sizes Chrome enforces a minimum emoji advance that exceeds
+ *    the font size — e.g. a 20px advance at font-size 16 (~1.25×). Sizing the
+ *    overlay to the font size painted the emoji ~20% too small (DM-1198: "our
+ *    emojis seem a lot smaller").
+ *  - The sbix PNG is a full square bitmap (the emoji fills a square em), so
+ *    drawing it into an advance × advance box reproduces both full-bleed emoji
+ *    and ones with transparent margins (e.g. 📈) without distortion.
+ *
+ * Geometry:
+ *  - Horizontal: the bitmap sits flush at the advance's left (`rect.x`); any
+ *    letter-spacing pads to the RIGHT, so no horizontal shift is applied
+ *    (DM-919 — the original DM-381 centering pass wrongly shifted it right
+ *    whenever letter-spacing > 0).
+ *  - Vertical: the square is centered in the captured rect's line box, which
+ *    matches Chrome within ~1px across sizes (DM-438 — a 20×17 rect extends
+ *    upward to a 20×20 square; DM-801 — a 56×63 rect with 8px letter-spacing
+ *    snaps to 48×48).
+ */
+export function emojiSquareRect(rect, letterSpacing) {
+    const ls = Math.max(0, letterSpacing) || 0;
+    const side = Math.max(1, rect.width - ls);
+    return {
+        x: rect.x,
+        y: rect.y + (rect.height - side) / 2,
+        width: side,
+        height: side,
+    };
+}
 /**
  * For every text segment CAPTURE_SCRIPT flagged with a rasterRect (contains a
  * color-bitmap glyph like U+2713 ✓ or an emoji), ask Playwright for a
@@ -178,28 +214,12 @@ export async function rasterizeBitmapGlyphs(page, tree, viewport) {
                                     // isn't carried on the segment (only the SVG path needs it,
                                     // not the existing screenshot path which already round-trips
                                     // a rectangular PNG).
-                                    const elFs = parseFloat(el.styles.fontSize ?? "") || 0;
-                                    const fs = seg.fontSize ?? (elFs > 0 ? elFs : Math.max(g.rect.width, g.rect.height));
-                                    // DM-919: Chrome's per-emoji paint origin = advance start
-                                    // (rect.x) when there's NO letter-spacing — the bitmap
-                                    // sits flush at the left of the advance. When letter-
-                                    // spacing > 0, Chrome ADDS the letter-spacing to the
-                                    // advance, which captures as a wider rect — the bitmap
-                                    // is still at rect.x (the spacing pads to the right).
-                                    // The original DM-381 centering pass mis-handled this:
-                                    // it shifted the bitmap by `(rect.width - fs) / 2`,
-                                    // moving the emoji right whenever letter-spacing >0.
-                                    // Pull out the captured letter-spacing and subtract it
-                                    // from rect.width FIRST, then center the bitmap inside
-                                    // the REAL advance — handles both the centered emoji-
-                                    // alone case (where rect.w ≈ fs) and the letter-spaced
-                                    // case (where rect.w = fs + letter-spacing).
                                     const ls = parseFloat(el.styles.letterSpacing ?? "") || 0;
-                                    const advanceW = Math.max(fs, g.rect.width - Math.max(0, ls));
-                                    g.rect.x += (advanceW - fs) / 2;
-                                    g.rect.y += (g.rect.height - fs) / 2;
-                                    g.rect.width = fs;
-                                    g.rect.height = fs;
+                                    const sq = emojiSquareRect(g.rect, ls);
+                                    g.rect.x = sq.x;
+                                    g.rect.y = sq.y;
+                                    g.rect.width = sq.width;
+                                    g.rect.height = sq.height;
                                     continue;
                                 }
                             }

package/dist/capture/script/dotted-circle-detect.js

@@ -57,13 +57,20 @@ export const createDottedCircleDetect = () => {
         }
         return { cnt, w: cnt > 0 ? (maxx - minx + 1) : 0 };
     };
-    // Does Chrome auto-insert a U+25CC before this lone mark in `font`?
+    // Does Chrome auto-insert a U+25CC before this lone mark/cluster-letter in
+    // `font`? Probes category M (combining marks), category Lo (some Brahmic
+    // cluster-initial LETTERS — e.g. Soyombo U+11A84) AND category Lm (modifier
+    // LETTERS the Universal Shaping Engine also circles when orphaned — e.g. Kirat
+    // Rai U+16D6B/6C, length / vowel modifiers that paint "◌ □" when stranded).
+    // The ink heuristic below is the real gate (a normal letter renders WITHOUT a
+    // circle, so bare ≠ comb → false), so including Lo / Lm only widens what's
+    // probed, never forces a false positive.
     const markGetsDottedCircle = (cp, ch, font) => {
         if (cp < 0x0900)
             return false;
         if (font == null || font === '')
             return false;
-        if (!/\p{M}/u.test(ch))
+        if (!/\p{M}|\p{Lo}|\p{Lm}/u.test(ch))
             return false;
         const key = cp + '|' + font;
         const hit = _cache.get(key);

package/dist/capture/script/emoji-detect.js

@@ -30,11 +30,20 @@ export const createEmojiDetect = () => {
         // painting as a dropped/empty path-mode glyph: ✅ ✊ ✋. Unconditional like
         // the ✨ ❌ ➡ family above — emoji presentation wins over the cascade.
         0x2705, 0x270A, 0x270B,
-        // DM-728: U+2B?? "Miscellaneous Symbols and Arrows" block with default
-        // emoji presentation per Unicode emoji-data — Chrome paints these as
-        // Apple Color Emoji glyphs without needing the U+FE0F variation
-        // selector. The fixture's ⭐ U+2B50 in `20-deep-font-palette.html` was
-        // painting as a hollow tofu before this list was extended.
+    ]);
+    // DM-1165: the Miscellaneous Symbols and Arrows (U+2B??) code points with
+    // default emoji presentation — ⬅⬆⬇ (2B05-07), ⬛⬜ (2B1B/1C), ⭐ (2B50),
+    // ⭕ (2B55). DM-728 added these to `rasterCps` unconditionally for the ⭐ in
+    // `20-deep-font-palette.html`, but Chrome's choice is actually CASCADE-
+    // DEPENDENT: when the element's font stack reaches a monochrome symbol/math
+    // font that covers them first, Chrome paints text, not color. Verified via
+    // `CSS.getPlatformFontsForNode` on the 2B00 fixture (cells lead with "Apple
+    // Symbols"): 2B05→Apple Symbols, 2B1B & 2B50→STIX Two Math — all MONOCHROME,
+    // so the unconditional raster was stamping blue emoji / a yellow star over
+    // Chrome's black arrows / hollow star. Probe per-element via `isColorGlyph`
+    // in `needsRaster` instead (color → raster, monochrome → path). A Set so the
+    // membership test in `needsRaster` is O(1).
+    const emojiPresentation2B = new Set([
         0x2B05, 0x2B06, 0x2B07, 0x2B1B, 0x2B1C, 0x2B50, 0x2B55,
     ]);
     // Codepoints in the U+2600-26FF Misc Symbols block with EmojiPresentation=Yes
@@ -200,6 +209,43 @@ export const createEmojiDetect = () => {
         // cascade DOES reach the color font still rasters correctly.
         if (cp >= 0x1F700 && cp <= 0x1F77F)
             return isColorGlyph(cp, font);
+        // DM-1168: the two Emoji_Presentation=Yes code points in the Enclosed CJK
+        // Letters and Months block (U+3200-32FF) — ㊗ U+3297 CIRCLED IDEOGRAPH
+        // CONGRATULATION and ㊙ U+3299 CIRCLED IDEOGRAPH SECRET. Chrome paints them
+        // as Apple Color Emoji by default (the fixture cells show the red circled
+        // ideographs). But several macOS text fonts (Hiragino, Arial Unicode) also
+        // cover them with a MONOCHROME glyph, so a `lang=ja` cascade that reaches
+        // Hiragino first paints text, not color. Probe Chrome's actual per-element
+        // choice via the canvas (color → raster, monochrome → path), exactly like
+        // the DM-1025 emojiPresentation26 / DM-1125 alchemical branches.
+        if (cp === 0x3297 || cp === 0x3299)
+            return isColorGlyph(cp, font);
+        // DM-1173: 〽 U+303D PART ALTERNATION MARK (CJK Symbols and Punctuation,
+        // U+3000-303F). Emoji=Yes but text-default presentation, so Chrome paints
+        // the color glyph only when the cascade reaches Apple Color Emoji and no
+        // text font covers it first (many do — Hiragino, M+ 1p, Shippori Mincho).
+        // The fixture cell paints the orange color mark, so probe per-element font
+        // (color → raster, monochrome → path) like the branches above.
+        if (cp === 0x303D)
+            return isColorGlyph(cp, font);
+        // DM-1165: the U+2B?? emoji-presentation symbols (arrows ⬅⬆⬇, squares ⬛⬜,
+        // ⭐, ⭕). Cascade-dependent — Chrome paints text when the stack reaches a
+        // monochrome symbol/math font first (Apple Symbols / STIX Two Math), color
+        // otherwise. See `emojiPresentation2B` above.
+        if (emojiPresentation2B.has(cp))
+            return isColorGlyph(cp, font);
+        // DM-1167: the ONLY two codepoints in the Misc Symbols & Pictographs block
+        // (U+1F300-1F5FF) that a macOS text font also covers monochrome are
+        // 🌐 U+1F310 (GLOBE WITH MERIDIANS) and 🎤 U+1F3A4 (MICROPHONE) — Apple
+        // Symbols carries both. When the element's cascade leads with Apple Symbols
+        // (the html-test `.f1` cells do; CSS.getPlatformFontsForNode confirms),
+        // Chrome paints the MONOCHROME path glyph, not the color emoji. Probe
+        // Chrome's actual per-element choice (color → raster, monochrome → path)
+        // exactly like the DM-1125 Alchemical / DM-1168 ㊗㊙ branches, instead of
+        // unconditionally stamping the Apple Color Emoji bitmap over Chrome's text
+        // glyph. The common Apple-Color-Emoji-first cell still rasters (probe → true).
+        if (cp === 0x1F310 || cp === 0x1F3A4)
+            return isColorGlyph(cp, font);
         // Main emoji blocks: Misc Symbols & Pictographs, Emoticons, Transport &
         // Map, Alchemical, Supplemental Symbols & Pictographs, Pictographs
         // Extended-A, Symbols & Pictographs Extended-B.