domotion-svg 0.2.2 → 0.3.1

package/FEATURES.md

@@ -26,6 +26,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **border-solid**: Solid borders with color
 - [x] **border-radius**: Rounded corners
 - [x] **border-radius-pill**: Fully rounded (pill shape)
+- [x] **inline-box-decoration-break**: wrapped inline backgrounds / borders paint per line-fragment (`slice` + `clone`); first/last fragment own the start/end edges in slice mode, every fragment paints a full box in clone mode
 
 ### Layout
 - [x] **layout-flex-row**: Horizontal flex layout with gap

package/README.md

@@ -36,6 +36,35 @@ yourself to keep the first job's runtime down.
 
 ## Usage
 
+The fastest way in is the `domotion` CLI — no TypeScript, no Playwright bring-up. Point it at a URL or HTML file:
+
+```bash
+# Capture a URL as SVG.
+domotion capture https://example.com -o example.svg
+
+# Capture a local HTML file at a specific viewport, only the .hero region, optimized.
+domotion capture ./demo.html \
+  --width 1200 --height 600 \
+  --selector ".hero" \
+  --optimize \
+  -o hero.svg
+
+# Capture HTML piped on stdin.
+cat demo.html | domotion capture - -o demo.svg
+```
+
+For a multi-frame animated SVG, write a small JSON config and run `domotion animate`:
+
+```bash
+domotion animate ./demo.json
+```
+
+The config describes each frame (input URL or HTML file, duration, transition, optional pre-capture actions like `click` / `fill` / `scroll` / `hover`). See `domotion --help` for the full grammar and the [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/) for a walkthrough.
+
+### Scripting API
+
+When you outgrow the CLI — custom interaction loops, programmatic frame composition, custom overlays — the same primitives are available as a library:
+
 ```ts
 import { captureElementTree, elementTreeToSvg, launchChromium, wrapSvg } from "domotion-svg";
 

package/dist/animation/animator.js

@@ -137,15 +137,22 @@ export function generateAnimatedSvg(config) {
                 const beforeStart = Math.max(0, startNum - 0.001).toFixed(3);
                 const afterEnd = Math.min(100, endNum + 0.001).toFixed(3);
                 // DM-599: cut already uses step-end on the opacity animation, so we
-                // fold display into the same keyframes block — both snap together.
+                // fold visibility into the same keyframes block — both snap together.
+                // DM-641: this used to toggle `display`. The base `.f { display: none }`
+                // rule kept the element out of the render tree at t=0, and Chromium
+                // doesn't tick infinite animations on out-of-tree elements — so the
+                // 0% keyframe never ran and the frame stayed permanently hidden.
+                // Switching to `visibility` leaves the element in the render tree
+                // (still skips painting, which was the DM-599 goal) so the animation
+                // ticks normally.
                 keyframes.push(`
     @keyframes fv-${i} {
-      0% { opacity: 0; display: none; }
-      ${beforeStart}% { opacity: 0; display: none; }
-      ${startNum.toFixed(3)}% { opacity: 1; display: inline; }
-      ${endNum.toFixed(3)}% { opacity: 1; display: inline; }
-      ${afterEnd}% { opacity: 0; display: none; }
-      100% { opacity: 0; display: none; }
+      0% { opacity: 0; visibility: hidden; }
+      ${beforeStart}% { opacity: 0; visibility: hidden; }
+      ${startNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${endNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${afterEnd}% { opacity: 0; visibility: hidden; }
+      100% { opacity: 0; visibility: hidden; }
     }
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
             }
@@ -216,7 +223,7 @@ export function generateAnimatedSvg(config) {
   </defs>
   <style>
     :root { --scene-dur: ${totalSec.toFixed(2)}s; }
-    .f { opacity: 0; display: none; }
+    .f { opacity: 0; visibility: hidden; }
     ${keyframes.join("\n")}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
   <g clip-path="url(#viewport-clip)">
@@ -314,18 +321,22 @@ function pct(ms, total) {
  * latter and the unmerged-path keyframes feed either form.
  */
 function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
+    // DM-641: kept the function name for callers but the toggle is now on
+    // `visibility`, not `display`, for the same reason as `fv-${i}` above —
+    // animating `display` away from an element starting `display: none` never
+    // ticks in Chromium.
     const start = parseFloat(String(visibleStartPct));
     const end = parseFloat(String(visibleEndPct));
     const startMinus = Math.max(0, start - 0.01).toFixed(3);
     const endPlus = Math.min(100, end + 0.01).toFixed(3);
     return `
     @keyframes ${name} {
-      0% { display: none; }
-      ${startMinus}% { display: none; }
-      ${start.toFixed(3)}% { display: inline; }
-      ${end.toFixed(3)}% { display: inline; }
-      ${endPlus}% { display: none; }
-      100% { display: none; }
+      0% { visibility: hidden; }
+      ${startMinus}% { visibility: hidden; }
+      ${start.toFixed(3)}% { visibility: visible; }
+      ${end.toFixed(3)}% { visibility: visible; }
+      ${endPlus}% { visibility: hidden; }
+      100% { visibility: hidden; }
     }`;
 }
 /**

package/dist/animation/animator.test.js

@@ -172,12 +172,15 @@ describe("animator", () => {
         expect(svg).toContain("transform: translateY(240px)");
         expect(svg).toContain("transform: translateY(0px)");
     });
-    it("DM-599: push-left frame gets a paired fd-N display animation alongside fv-N", () => {
+    it("DM-599/DM-641: push-left frame gets a paired fd-N visibility animation alongside fv-N", () => {
         // push-left is unmergeable (the merge fast path only takes crossfade/cut),
         // so it goes through the unmerged emit path that emits per-frame fv-/fp-
         // blocks. The DM-599 optimization adds an fd-N keyframes block that
-        // toggles `display: none ↔ inline` so the frame is dropped from paint
-        // outside its show window.
+        // toggles a paint-skip property so the frame is dropped from paint
+        // outside its show window. DM-641 changed that toggle from `display`
+        // (which parks the CSS-animations engine when an element starts out of
+        // the render tree) to `visibility` (which keeps the element rendered
+        // but skips painting it).
         const svg = generateAnimatedSvg({
             width: 100, height: 100,
             frames: [
@@ -190,17 +193,20 @@ describe("animator", () => {
         expect(svg).toMatch(/@keyframes fd-1\s*{/);
         // … alongside the existing fv-N opacity block.
         expect(svg).toMatch(/@keyframes fv-0\s*{/);
-        // The keyframes flip display between none and inline.
-        expect(svg).toMatch(/display:\s*none/);
-        expect(svg).toMatch(/display:\s*inline/);
+        // The keyframes flip visibility (DM-641 — formerly display).
+        expect(svg).toMatch(/visibility:\s*hidden/);
+        expect(svg).toMatch(/visibility:\s*visible/);
+        // DM-641: must NOT emit display toggles anywhere — those broke the
+        // infinite animation in Chromium.
+        expect(svg).not.toMatch(/display:\s*none/);
+        expect(svg).not.toMatch(/display:\s*inline/);
         // The frame's CSS rule lists BOTH animations, with the fd one tagged
-        // step-end so the display flip is instant (not snap-at-50% of segment).
+        // step-end so the visibility flip is instant.
         expect(svg).toMatch(/\.f-0\s*{\s*animation:[^}]*fv-0[^}]*,[^}]*fd-0[^}]*step-end/);
-        // The base .f rule sets display:none so frames start hidden until the
-        // keyframe flips them in.
-        expect(svg).toMatch(/\.f\s*{[^}]*display:\s*none/);
+        // The base .f rule sets visibility:hidden (was display:none pre-DM-641).
+        expect(svg).toMatch(/\.f\s*{[^}]*visibility:\s*hidden/);
     });
-    it("DM-599: cut frames fold display into fv-N (same step-end timing)", () => {
+    it("DM-599/DM-641: cut frames fold visibility into fv-N (same step-end timing)", () => {
         // Three explicit `cut` frames — the all-mergeable check trips and these
         // route through the MERGE pipeline. But a non-mergeable transition mixed
         // in (e.g. push-left) would route this through the unmerged path. We
@@ -213,19 +219,19 @@ describe("animator", () => {
                 { svgContent: `<rect fill="green"/>`, duration: 1000 },
             ],
         });
-        // The "cut" frame's fv-N keyframes carry the display toggle inline (no
-        // separate fd-N block) since cut already uses step-end on fv-N.
+        // The "cut" frame's fv-N keyframes carry the visibility toggle inline
+        // (no separate fd-N block) since cut already uses step-end on fv-N.
         const fv1Match = svg.match(/@keyframes fv-1\s*{[\s\S]*?\n\s*}/);
         expect(fv1Match).not.toBeNull();
-        expect(fv1Match[0]).toMatch(/display:\s*none/);
-        expect(fv1Match[0]).toMatch(/display:\s*inline/);
+        expect(fv1Match[0]).toMatch(/visibility:\s*hidden/);
+        expect(fv1Match[0]).toMatch(/visibility:\s*visible/);
         // The "cut" frame uses ONLY fv-1 (no fd-1 — it's folded in).
         expect(svg).not.toMatch(/@keyframes fd-1\s*{/);
     });
-    it("DM-599: merged-path keyframes emit display alongside opacity", () => {
+    it("DM-599/DM-641: merged-path keyframes emit visibility alongside opacity", () => {
         // Two crossfade frames with different content route through the merge
         // pipeline. Per-element visibility classes (tN) now toggle BOTH opacity
-        // and display so the browser can skip painting hidden elements.
+        // and visibility so the browser can skip painting hidden elements.
         const svg = generateAnimatedSvg({
             width: 100, height: 100,
             frames: [
@@ -233,12 +239,39 @@ describe("animator", () => {
                 { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000 },
             ],
         });
-        // Each tN keyframe stop with opacity:1 also has display:inline; each
-        // opacity:0 stop has display:none.
+        // Each tN keyframe stop with opacity:1 also has visibility:visible; each
+        // opacity:0 stop has visibility:hidden.
         const tN = svg.match(/@keyframes t\d+\s*{[\s\S]*?\n\s*}/);
         expect(tN).not.toBeNull();
-        expect(tN[0]).toMatch(/opacity:\s*1;\s*display:\s*inline/);
-        expect(tN[0]).toMatch(/opacity:\s*0;\s*display:\s*none/);
+        expect(tN[0]).toMatch(/opacity:\s*1;\s*visibility:\s*visible/);
+        expect(tN[0]).toMatch(/opacity:\s*0;\s*visibility:\s*hidden/);
+    });
+    it("DM-641: never emits `display: none` keyframes (would park Chromium's animation engine)", () => {
+        // Regression. The repro from the ticket: a multi-frame animation with
+        // `cut` transitions produced `@keyframes fv-0 { 0% { opacity:0; display:none } … }`
+        // plus `.f { display: none }`, which Chromium would never tick — so
+        // EVERY frame stayed permanently hidden when the SVG was loaded into a
+        // browser. The fix swapped both sites onto `visibility`. This test pins
+        // the fix on every code path that emits keyframes for the animator.
+        const cutSvg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect/>`, duration: 1000 },
+            ],
+        });
+        expect(cutSvg).not.toMatch(/display:\s*none/);
+        expect(cutSvg).not.toMatch(/display:\s*inline/);
+        const pushSvg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "push-left", duration: 100 } },
+                { svgContent: `<rect/>`, duration: 1000 },
+            ],
+        });
+        expect(pushSvg).not.toMatch(/display:\s*none/);
+        expect(pushSvg).not.toMatch(/display:\s*inline/);
     });
     it("cut transition: timeline boundary is exactly at the frame edge", () => {
         // For two frames each held 1000ms with cut transitions and no overlap,

package/dist/animation/cursor-overlay.js

@@ -114,13 +114,11 @@ function resolveMoveTarget(ev, curX, curY, frameIndex, resolveSelector) {
         return { x: curX + ev.by.dx, y: curY + ev.by.dy };
     if (ev.selector != null) {
         if (resolveSelector == null) {
-            // eslint-disable-next-line no-console
             console.warn(`cursor-overlay: selector "${ev.selector}" used but no resolveSelector provided; skipping`);
             return null;
         }
         const rect = resolveSelector(ev.selector, frameIndex);
         if (rect == null) {
-            // eslint-disable-next-line no-console
             console.warn(`cursor-overlay: selector "${ev.selector}" matched no element in frame ${frameIndex}; skipping`);
             return null;
         }

package/dist/capture/emoji.js

@@ -31,7 +31,12 @@ function loadAppleColorEmojiFont() {
         return null;
     try {
         const opened = fontkit.openSync(APPLE_COLOR_EMOJI_PATH);
-        _aceFont = opened.fonts != null ? opened.fonts[0] : opened;
+        if (opened == null) {
+            _aceFont = null;
+        }
+        else {
+            _aceFont = opened.fonts != null ? opened.fonts[0] : opened;
+        }
     }
     catch {
         _aceFont = null;
@@ -139,23 +144,29 @@ export async function rasterizeBitmapGlyphs(page, tree, viewport) {
                                 const sbixPng = extractEmojiBitmap(cp, g.rect.width);
                                 if (sbixPng != null) {
                                     g.dataUri = `data:image/png;base64,${sbixPng.toString("base64")}`;
-                                    // sbix bitmaps are square. The captured rect uses the line-box
-                                    // height (typically the advance width for emoji) which is
-                                    // shorter than the advance width — Range.getBoundingClientRect
-                                    // returns the line box, not the painted ink. Painting the
-                                    // square bitmap into a non-square rect with preserveAspectRatio
-                                    // ="none" squishes the glyph vertically (DM-438: smiley emoji
-                                    // rendered 20×17 instead of 20×20). Chrome paints the bitmap
-                                    // at em-square aspect with the BOTTOM aligned to the line-box
-                                    // bottom, so extend the rect upward to a square. Scoped to
-                                    // sbix-fed glyphs (Apple Color Emoji on macOS) so DM-401/411
-                                    // /414's flag-emoji regression — driven by page.screenshot's
-                                    // already-rectangular bitmaps — does not return.
-                                    if (g.rect.width > g.rect.height) {
-                                        const bottom = g.rect.y + g.rect.height;
-                                        g.rect.height = g.rect.width;
-                                        g.rect.y = bottom - g.rect.width;
-                                    }
+                                    // sbix bitmaps are square (em-square sized). Chrome paints
+                                    // them centered horizontally on the glyph advance and bottom-
+                                    // aligned to the line-box. The captured rect spans the
+                                    // typographic line-box (advance × line-height), which is
+                                    // bigger than the em-square on either axis when letter-spacing
+                                    // or line-height add slack. DM-438: smiley rendered 20×17 in a
+                                    // 20-wide / 17-tall rect (height shorter than width) — fixed
+                                    // by extending the rect upward to a 20×20 square. DM-801: at
+                                    // font-size 48 with letter-spacing 8, the rect was 56×63
+                                    // (width INCLUDES letter-spacing, height bigger than em-
+                                    // square), so emoji painted as 56×63 — vertically stretched
+                                    // hearts and wide smileys. Snap to fontSize × fontSize
+                                    // centered horizontally on the rect's advance and bottom-
+                                    // aligned vertically; falls back to max(w,h) when fontSize
+                                    // 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));
+                                    g.rect.x += (g.rect.width - fs) / 2;
+                                    g.rect.y += (g.rect.height - fs) / 2;
+                                    g.rect.width = fs;
+                                    g.rect.height = fs;
                                     continue;
                                 }
                             }

package/dist/capture/index.js

@@ -435,7 +435,7 @@ export async function discoverAndRegisterWebfonts(page, observedFontUrls = []) {
     // ran in this scenario registers under fontkit's internal `familyName`,
     // which for license-protected fonts (Sohne) is a copyright string —
     // unmatchable against the CSS-declared `font-family: sohne-var` query.
-    for (const sheetUrl of fromPage.crossOriginSheetUrls ?? []) {
+    for (const sheetUrl of fromPage.crossOriginSheetUrls) {
         let cssText;
         try {
             const resp = await page.context().request.get(sheetUrl);
@@ -482,10 +482,9 @@ export async function discoverAndRegisterWebfonts(page, observedFontUrls = []) {
             // (e.g. an alias whose width happened to disagree with all candidates
             // due to layout shaping that the simple sample didn't exercise).
             const declaredWeight = parseWeightDescriptor(item.weight);
-            const declaredStyle = String(item.style ?? "normal").toLowerCase();
+            const declaredStyle = item.style.toLowerCase();
             const declaredItalic = declaredStyle !== "" && declaredStyle !== "normal";
-            const resolved = item.resolvedLocalName;
-            const candidates = resolved != null ? [resolved] : item.localNames;
+            const candidates = item.resolvedLocalName != null ? [item.resolvedLocalName] : item.localNames;
             for (const localName of candidates) {
                 const key = systemFontKeyForLocalName(localName);
                 if (key != null) {
@@ -592,6 +591,8 @@ async function readFontMetadata(buf) {
     const fontkit = await import("fontkit");
     try {
         const f = fontkit.create(buf);
+        if (f == null)
+            return null;
         const family = f.familyName ?? "";
         if (family === "")
             return null;

package/dist/capture/script/color-norm.d.ts

@@ -1,3 +1,4 @@
 export declare const createColorNorm: () => {
     normColor: (c: any, elColor: any) => any;
+    normGradientColors: (text: any, elColor: any) => any;
 };

package/dist/capture/script/color-norm.js

@@ -40,5 +40,47 @@ export const createColorNorm = () => {
         catch (e) { /* fall through */ }
         return c;
     };
-    return { normColor };
+    // DM-800: Chromium retains wide-gamut color functions verbatim inside
+    // computed gradient stops (e.g. `linear-gradient(90deg, oklch(0.89 0.04
+    // 264), …)`). The render-side `parseColor` doesn't speak oklch/lab/lch/
+    // oklab/hwb and falls back to black for any stop it can't decode,
+    // collapsing the tinted-gradient strip to mostly-black bars. Walk the
+    // gradient text and replace each wide-gamut color call with its
+    // normColor-resolved form so the renderer only sees rgb()/color(srgb).
+    // `color-mix(...)` doesn't appear here because Chromium pre-resolves it
+    // inside gradients to its target color space (e.g. `color-mix(in oklch,
+    // red, blue)` serializes as `oklch(...)`), but we match it defensively in
+    // case future Chromium versions change that.
+    const normGradientColors = (text, elColor) => {
+        if (text == null || text === '' || text === 'none')
+            return text;
+        // Match a color-function identifier followed by a balanced (...) group.
+        const fnRe = /\b(oklch|oklab|lab|lch|hwb|hsl|hsla|color|color-mix)\(/gi;
+        var out = '';
+        var i = 0;
+        while (i < text.length) {
+            fnRe.lastIndex = i;
+            const m = fnRe.exec(text);
+            if (m == null) {
+                out += text.slice(i);
+                break;
+            }
+            out += text.slice(i, m.index);
+            // Walk forward consuming balanced parens.
+            var depth = 1;
+            var j = m.index + m[0].length;
+            while (j < text.length && depth > 0) {
+                const ch = text[j++];
+                if (ch === '(')
+                    depth++;
+                else if (ch === ')')
+                    depth--;
+            }
+            const call = text.slice(m.index, j);
+            out += normColor(call, elColor);
+            i = j;
+        }
+        return out;
+    };
+    return { normColor, normGradientColors };
 };

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

@@ -24,6 +24,12 @@ export const createEmojiDetect = () => {
     const rasterCps = new Set([
         0x2713, 0x2714, 0x2716, 0x2717, 0x2728, 0x2753, 0x2754, 0x2755, 0x2757,
         0x274C, 0x274E, 0x2795, 0x2796, 0x2797, 0x27A1, 0x27B0, 0x27BF,
+        // 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.
+        0x2B05, 0x2B06, 0x2B07, 0x2B1B, 0x2B1C, 0x2B50, 0x2B55,
     ]);
     // Codepoints in the U+2600-26FF Misc Symbols block with EmojiPresentation=Yes
     // per Unicode emoji-data: Chrome paints these as color emoji by default
@@ -49,6 +55,14 @@ export const createEmojiDetect = () => {
         0x2696, 0x2697, 0x2699, 0x269B, 0x269C, 0x26A0, 0x26A7, 0x26B0,
         0x26B1, 0x26C8, 0x26CF, 0x26D1, 0x26D3, 0x26E9, 0x26F0, 0x26F1,
         0x26F4, 0x26F7, 0x26F8, 0x26F9,
+        // DM-728: Dingbats block (U+27??) codepoints with text-default
+        // presentation that flip to color emoji when paired with U+FE0F. The
+        // fixture's ❤️ (U+2764 + U+FE0F) heart was painting as a small black
+        // monochrome glyph before this entry was added; with it, the VS-16
+        // pairing routes through the raster overlay path so Apple Color Emoji
+        // paints the red heart Chrome shows.
+        0x2702, 0x2708, 0x2709, 0x270C, 0x270D, 0x270F, 0x2712, 0x2716,
+        0x2733, 0x2734, 0x2744, 0x2747, 0x2763, 0x2764,
     ]);
     const needsRaster = (cp, nextCp) => {
         if (rasterCps.has(cp))