domotion-svg 0.2.2 → 0.3.2

package/dist/capture/types.d.ts

@@ -114,13 +114,51 @@ export interface TextSegment {
         /** Pre-resolved srgb-form CSS color (or "transparent"). Renderer parses
          *  via parseColor and emits as the rect fill. */
         backgroundColor?: string;
+        /** Raw CSS `background-image` value (gradient / url() / multiple
+         *  layers) when the pseudo paints a gradient or image instead of (or in
+         *  addition to) a flat color. DM-767: `.corner::after` accent stripes
+         *  with `background: linear-gradient(...)` need this — without it the
+         *  pseudoBox emit was skipped entirely. Renderer threads through
+         *  `buildBackgroundLayerDef` the same way the regular-element
+         *  background-image path does. */
+        backgroundImage?: string;
         /** Resolved px border-radius (CSS shorthand — single value, four-corner
          *  symmetric). */
         borderRadius?: number;
-        /** Uniform border (single side-width + color). Per-side variation isn't
-         *  supported in this pass; mixed-style borders fall through. */
+        /** Uniform border (single side-width + color). When set, the renderer
+         *  emits `<rect stroke=... stroke-width=...>` around the box. */
         borderWidth?: number;
         borderColor?: string;
+        /** Per-side border widths (px). Always populated; zero when the side
+         *  carries no border. Renderer reads these together with the per-side
+         *  colors below when no `borderWidth` (uniform) is set. */
+        borL?: number;
+        borR?: number;
+        borT?: number;
+        borB?: number;
+        /** Per-side border colors. Set ONLY when the pseudo has a non-uniform
+         *  border (e.g. `border-bottom: 1px solid …` only). For uniform borders
+         *  the renderer uses `borderColor` + `borderWidth` and the per-side
+         *  fields are undefined. Slashdot's `.carouselHeading::after` is the
+         *  motivating fixture — a 1px translucent-white border-bottom on the
+         *  italic "Most Discussed" heading. */
+        borderTopColor?: string;
+        borderRightColor?: string;
+        borderBottomColor?: string;
+        borderLeftColor?: string;
+        /** DM-783: pseudo's own `transform` (rotate/scale/translate/matrix/skew).
+         *  Captured verbatim from `getComputedStyle(host, '::before').transform`,
+         *  which Chrome returns in resolved `matrix(a,b,c,d,e,f)` form — pasteable
+         *  directly into an SVG `<g transform="…">` wrapper. Renderer wraps the
+         *  pseudoBox rect + glyph emit so rotate(45deg) on a `::before { border-
+         *  right; border-bottom }` paints as a check-mark (the rotation pivots
+         *  around the box center per `transformOrigin`). */
+        transform?: string;
+        /** Resolved px transform-origin (e.g. `"50px 50px"` for a 100×100 box's
+         *  default `50% 50%`). Renderer pre-bakes a translate-transform-translate
+         *  matrix so the rotation/scale pivots around the captured origin instead
+         *  of (0, 0). When undefined, renderer defaults to the box center. */
+        transformOrigin?: string;
     };
 }
 export interface CapturedElement {
@@ -194,6 +232,14 @@ export interface CapturedElement {
         borderCollapse: string;
         overflowX: string;
         overflowY: string;
+        /**
+         * CSS `overflow-clip-margin` shorthand value as computed by Chrome
+         * (e.g. `"20px"`, `"content-box 12px"`, or the empty string when the
+         * default `0px` resolves and the element doesn't paint outside its
+         * reference box). Only takes effect when `overflow: clip` (DM-761) —
+         * `hidden` ignores it per CSS Overflow 3.
+         */
+        overflowClipMargin?: string;
         scrollbarGutter: string;
         /** el.scrollHeight / scrollWidth vs client* — used to decide whether to paint a scrollbar. */
         scrollWidth: number;
@@ -226,6 +272,36 @@ export interface CapturedElement {
         maskPosition: string;
         maskRepeat: string;
         maskComposite: string;
+        /**
+         * CSS `mask-clip` — the box (border-box / padding-box / content-box / etc.)
+         * the mask painted area is clipped to. Defaults to `border-box`. Captured
+         * separately from `mask-origin` because Chromium retains both verbatim
+         * (mask-clip controls visibility, mask-origin controls layer positioning).
+         */
+        maskClip?: string;
+        /**
+         * CSS `mask-border-source` / legacy `-webkit-mask-box-image` source.
+         * Chrome exposes this only via the legacy webkit name (DM-758). The
+         * renderer routes it through the mask-image pipeline ONLY for the
+         * "simple" 9-slice cases (`slice 0 fill / 0 / 0` and `slice 1 fill / 0
+         * / 0`) where the entire source is used as a stretched full-element
+         * mask. Real 9-slice tiling (non-zero `width` / `outset`, `round` /
+         * `space` repeat) needs its own implementation.
+         */
+        maskBorderSource?: string;
+        /** Resolved `-webkit-mask-box-image-slice` (e.g. `"1 fill"`, `"30 fill"`). */
+        maskBorderSlice?: string;
+        /** Resolved `-webkit-mask-box-image-width` (e.g. `"0"`, `"20px"`). */
+        maskBorderWidth?: string;
+        /** Resolved `-webkit-mask-box-image-outset` (e.g. `"0"`, `"15px"`). */
+        maskBorderOutset?: string;
+        /** Resolved `-webkit-mask-box-image-repeat` (`stretch` / `repeat` /
+         *  `round` / `space`, optionally one per axis). DM-793. */
+        maskBorderRepeat?: string;
+        /** Intrinsic dimensions of the `mask-border-source` asset (px). Same
+         *  probe pattern as `borderImageIntrinsicWidth`. DM-793. */
+        maskBorderIntrinsicWidth?: number;
+        maskBorderIntrinsicHeight?: number;
         listStyleType: string;
         listStyleImage: string;
         listStylePosition: string;
@@ -239,6 +315,14 @@ export interface CapturedElement {
         backgroundClip: string;
         backgroundOrigin: string;
         backgroundAttachment: string;
+        /**
+         * CSS `background-blend-mode` — per-layer blend mode (comma-separated to
+         * match the layer count). Captured verbatim from `getComputedStyle`. The
+         * renderer applies each layer's mode as `style="mix-blend-mode:<mode>"`
+         * on the layer's `<rect>`, wrapped in a `<g style="isolation:isolate">`
+         * so the blend doesn't escape the element's bg-layer stack.
+         */
+        backgroundBlendMode?: string;
         /**
          * CSS `-webkit-text-fill-color`. When `backgroundClip` is `text` the
          * common pattern is `webkit-text-fill-color: transparent` so the
@@ -248,6 +332,25 @@ export interface CapturedElement {
          * when the rendered text is actually transparent. DM-462.
          */
         webkitTextFillColor?: string;
+        /**
+         * DM-749: Stripe / Resend pattern — when an element has
+         * `webkit-text-fill-color: transparent` but its own background-image is
+         * `none`, the gradient lives on an ANCESTOR with `background-clip:
+         * text`. Chrome's paint propagates that gradient through descendant
+         * glyphs. Captured as the resolved `background-image` string of the
+         * nearest ancestor with `background-clip: text` (walked up to 8 levels).
+         */
+        inheritedTextFillGradient?: string;
+        /** `-webkit-text-stroke-width` (e.g. "2px"). DM-719. */
+        webkitTextStrokeWidth?: string;
+        /** `-webkit-text-stroke-color` (e.g. "rgb(220,38,38)"). DM-719. */
+        webkitTextStrokeColor?: string;
+        /** `paint-order` (e.g. "stroke fill"). Controls whether the text stroke
+         *  paints before or after the fill — `stroke fill` puts the stroke
+         *  UNDER the fill so the fill rests on top of half the stroke width,
+         *  eliminating the chunky "fill-on-top-of-stroke" artifact at large
+         *  stroke widths. DM-719. */
+        paintOrder?: string;
         paddingTop: string;
         paddingRight: string;
         paddingBottom: string;
@@ -457,6 +560,14 @@ export interface CapturedElement {
         transformCreatesSc?: boolean;
         /** CSS transform-style. `preserve-3d` (or anything != `flat`) creates a stacking context per CSS Transforms 2 §4 (DM-589). */
         transformStyle?: string;
+        /**
+         * DM-751: extracted Z translation from `matrix3d(...)` when the
+         * element's transform has a non-zero translateZ component. Used by the
+         * paint-order sort when the parent has `transform-style: preserve-3d`
+         * (CSS Transforms 2 §6 sorts children by Z in 3D space, not z-index).
+         * SVG can't render perspective, so this is paint-order only.
+         */
+        translateZ?: number;
         /** CSS writing-mode (`horizontal-tb` | `vertical-rl` | `vertical-lr` | `sideways-rl` | `sideways-lr`). */
         writingMode?: string;
         /** CSS text-orientation (`mixed` | `upright` | `sideways`). Used in vertical writing-modes. */
@@ -518,7 +629,45 @@ export interface CapturedElement {
          *  `decoration_line_painter.cc`, only solid + double underlines honor
          *  skip-ink; dashed / dotted / wavy ignore it. DM-446. */
         textDecorationSkipInk?: string;
+        /**
+         * `box-decoration-break` — `slice` (default) or `clone`. Controls how
+         * inline elements that wrap across multiple line boxes paint their
+         * background / border / padding / shadow: `slice` paints the box once
+         * across all fragments (first fragment gets the left side, last gets the
+         * right side); `clone` paints a complete box on every fragment. Captured
+         * so the renderer can split the per-fragment paint at line-box boundaries
+         * when `inlineFragments` is present.
+         */
+        boxDecorationBreak?: string;
     };
+    /**
+     * Per-line-fragment rects (viewport-relative px) for inline elements that
+     * wrap across multiple line boxes. Populated by capture when the element
+     * is `display: inline` AND has a non-transparent background or non-zero
+     * border AND `el.getClientRects().length > 1`. When present, the renderer
+     * paints the background + border per-fragment instead of once across the
+     * element's bbox — without this, an inline span like `<span class="hl">…
+     * wrapping text …</span>` paints a single rectangle covering the whole
+     * logical inline (typically the full container width) and the text floats
+     * outside / behind the painted background. Slice vs clone semantics are
+     * driven by `styles.boxDecorationBreak`. See `docs/01-fidelity.md`.
+     */
+    inlineFragments?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** DM-754: the fragmentation axis that produced the `inlineFragments`
+     *  entries. `"inline"` — the element is `display: inline` and wrapped onto
+     *  multiple line boxes (the original DM-721 case); slice mode suppresses
+     *  the LEFT side on non-first fragments and the RIGHT side on non-last.
+     *  `"block"` — the element is block-level inside a multi-column container
+     *  ancestor (DM-754); slice mode suppresses TOP on non-first and BOTTOM on
+     *  non-last. Both axes produce vertically-stacked frag rects in practice,
+     *  so we can't distinguish them geometrically at render time. Defaults to
+     *  `"inline"` when undefined (backwards-compatible with pre-DM-754 captures). */
+    fragmentAxis?: "inline" | "block";
     children: CapturedElement[];
     imageSrc?: string;
     /** Intrinsic pixel dimensions of <img>, used for object-fit: none. */
@@ -618,6 +767,18 @@ export interface CapturedElement {
         height: number;
         dataUri?: string;
     };
+    /**
+     * DM-680: per-axis cumulative ancestor scale, present ONLY when the element
+     * sits inside an anisotropically scaled subtree (e.g. `transform: scale(1.3,
+     * 0.8)`). The geometric mean is already folded into fontSize / fontAscent /
+     * fontDescent at capture time — these fields drive a per-axis correction
+     * `<g transform="scale(cx, cy)">` around the text emission so glyphs render
+     * with the same width / height stretch Chrome paints. Absent when the
+     * cumulative scale is isotropic (uniform scale, or no scale) — the
+     * geometric-mean handling already produces a faithful result there.
+     */
+    cumScaleX?: number;
+    cumScaleY?: number;
     /**
      * For <canvas> / <video> / <iframe> / <object> / <embed>: a viewport-relative
      * content-box rect (border-box minus border + padding) that
@@ -679,6 +840,18 @@ export interface CapturedElement {
      * See `docs/21-mask-fragment-references.md`.
      */
     maskDefs?: MaskFragmentDef[];
+    /**
+     * DM-826: Top-level (root only) collection of `<clipPath>` definitions
+     * referenced by fragment URLs (`clip-path: url("#id")`) anywhere in the
+     * captured tree. CAPTURE_SCRIPT resolves each fragment id via
+     * `document.getElementById` and serialises the `<clipPath>` element's
+     * `outerHTML` here. The renderer copies these into the output `<defs>`
+     * with id rewriting so a captured `<clipPath id="hex">` becomes a
+     * domotion-prefixed clip-path def referenced by elements that point at
+     * `#hex`. Same-document only — external `.svg#fragment` refs are
+     * deferred. See `docs/39-clip-path-fragment-references.md`.
+     */
+    clipPathDefs?: ClipPathFragmentDef[];
     /**
      * DM-494: Raster snapshots of elements referenced by `mask-image:
      * element(#id)`. Top-level (root only) — same-document only (cross-document
@@ -692,6 +865,38 @@ export interface CapturedElement {
      * `docs/22-mask-element-paint-references.md`.
      */
     maskRasters?: MaskRasterRef[];
+    /**
+     * DM-579 box-only pseudo-elements: empty-content `::before` / `::after`
+     * whose effective rect + per-side borders + background are captured for
+     * decorative-separator emission. The renderer in `element-tree-to-svg.ts`
+     * emits one `<rect>` per pseudoBox plus up to four `<line>`s for visible
+     * borders. Captured per element (not just root). Optional — only emitted
+     * when at least one such pseudo exists on this element.
+     */
+    pseudoBoxes?: PseudoBox[];
+}
+export interface PseudoBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    backgroundColor?: string;
+    backgroundImage?: string;
+    borderTopWidth?: number;
+    borderTopColor?: string;
+    borderTopStyle?: string;
+    borderRightWidth?: number;
+    borderRightColor?: string;
+    borderRightStyle?: string;
+    borderBottomWidth?: number;
+    borderBottomColor?: string;
+    borderBottomStyle?: string;
+    borderLeftWidth?: number;
+    borderLeftColor?: string;
+    borderLeftStyle?: string;
+    borderRadius?: number;
+    transform?: string;
+    transformOrigin?: string;
 }
 export interface MaskFragmentDef {
     /** Original DOM id of the captured `<mask>` element. */
@@ -699,6 +904,12 @@ export interface MaskFragmentDef {
     /** Verbatim `outerHTML` of the captured `<mask>` element. */
     outerHTML: string;
 }
+export interface ClipPathFragmentDef {
+    /** Original DOM id of the captured `<clipPath>` element. */
+    id: string;
+    /** Verbatim `outerHTML` of the captured `<clipPath>` element. */
+    outerHTML: string;
+}
 export interface MaskRasterRef {
     /** DOM id referenced by `mask-image: element(#id)` — used by the renderer
      *  to look up the raster from the layer reference. */

package/dist/cli/animate.js

@@ -38,8 +38,8 @@ export async function runAnimate(args, help) {
     const configPath = resolve(positionals[0]);
     if (!existsSync(configPath))
         throw new Error(`animate: config not found: ${configPath}`);
-    const cfg = JSON.parse(readFileSync(configPath, "utf8"));
-    validateAnimateConfig(cfg);
+    const cfgRaw = JSON.parse(readFileSync(configPath, "utf8"));
+    const cfg = validateAnimateConfig(cfgRaw);
     const configDir = dirname(configPath);
     const log = makeLogger(values.quiet === true);
     log(`Launching Chromium…`);
@@ -208,36 +208,171 @@ async function runActions(page, actions) {
             throw new Error(`animate: unknown action type "${a.type}"`);
     }
 }
-function validateAnimateConfig(cfg) {
-    if (typeof cfg.width !== "number" || typeof cfg.height !== "number") {
+const COLOR_SCHEMES = new Set(["light", "dark", "no-preference"]);
+const TRANSITION_TYPES = new Set(["crossfade", "push-left", "scroll", "cut"]);
+const OVERLAY_SLIDE_FROMS = new Set(["top", "bottom", "left", "right"]);
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function validateAnimateConfig(raw) {
+    if (!isObject(raw))
+        throw new Error("animate: config must be an object");
+    if (typeof raw.width !== "number" || typeof raw.height !== "number") {
         throw new Error("animate: config requires numeric width and height");
     }
-    if (!Array.isArray(cfg.frames) || cfg.frames.length === 0) {
+    if (raw.output != null && typeof raw.output !== "string") {
+        throw new Error("animate: config.output must be a string when present");
+    }
+    if (raw.optimize != null && typeof raw.optimize !== "boolean") {
+        throw new Error("animate: config.optimize must be a boolean when present");
+    }
+    if (raw.mobile != null && typeof raw.mobile !== "boolean") {
+        throw new Error("animate: config.mobile must be a boolean when present");
+    }
+    if (raw.colorScheme != null && (typeof raw.colorScheme !== "string" || !COLOR_SCHEMES.has(raw.colorScheme))) {
+        throw new Error(`animate: config.colorScheme must be one of ${[...COLOR_SCHEMES].join(", ")}`);
+    }
+    if (!Array.isArray(raw.frames) || raw.frames.length === 0) {
         throw new Error("animate: config.frames must be a non-empty array");
     }
-    for (let i = 0; i < cfg.frames.length; i++) {
-        const f = cfg.frames[i];
+    for (let i = 0; i < raw.frames.length; i++) {
+        const f = raw.frames[i];
+        if (!isObject(f))
+            throw new Error(`animate: frames[${i}] must be an object`);
         if (typeof f.input !== "string")
             throw new Error(`animate: frames[${i}].input must be a string`);
         if (typeof f.duration !== "number")
             throw new Error(`animate: frames[${i}].duration must be a number`);
+        if (f.transition != null) {
+            if (!isObject(f.transition))
+                throw new Error(`animate: frames[${i}].transition must be an object`);
+            if (typeof f.transition.type !== "string" || !TRANSITION_TYPES.has(f.transition.type)) {
+                throw new Error(`animate: frames[${i}].transition.type must be one of ${[...TRANSITION_TYPES].join(", ")}`);
+            }
+            if (typeof f.transition.duration !== "number") {
+                throw new Error(`animate: frames[${i}].transition.duration must be a number`);
+            }
+        }
+        if (f.scrollTo != null) {
+            if (!Array.isArray(f.scrollTo) || f.scrollTo.length !== 2 || typeof f.scrollTo[0] !== "number" || typeof f.scrollTo[1] !== "number") {
+                throw new Error(`animate: frames[${i}].scrollTo must be a [number, number] tuple`);
+            }
+        }
         if (f.scroll != null) {
+            if (!isObject(f.scroll))
+                throw new Error(`animate: frames[${i}].scroll must be an object`);
             if (typeof f.scroll.pattern !== "string" || f.scroll.pattern.trim() === "") {
                 throw new Error(`animate: frames[${i}].scroll.pattern must be a non-empty string`);
             }
-            // Parse the pattern eagerly so config errors surface before the run
-            // starts (instead of mid-Playwright session). Throws on invalid
-            // grammar with the original error including source position.
             try {
                 parseScrollPattern(f.scroll.pattern);
             }
             catch (e) {
                 throw new Error(`animate: frames[${i}].scroll.pattern is invalid: ${e instanceof Error ? e.message : String(e)}`);
             }
-            if (f.scroll.speed != null && (!Number.isFinite(f.scroll.speed) || f.scroll.speed <= 0)) {
+            if (f.scroll.speed != null && (typeof f.scroll.speed !== "number" || !Number.isFinite(f.scroll.speed) || f.scroll.speed <= 0)) {
                 throw new Error(`animate: frames[${i}].scroll.speed must be a positive number (px/s)`);
             }
         }
+        if (f.actions != null) {
+            if (!Array.isArray(f.actions))
+                throw new Error(`animate: frames[${i}].actions must be an array`);
+            f.actions.forEach((a, ai) => validateAction(a, i, ai));
+        }
+        if (f.animations != null) {
+            if (!Array.isArray(f.animations))
+                throw new Error(`animate: frames[${i}].animations must be an array`);
+            f.animations.forEach((a, ai) => validateFrameAnimation(a, i, ai));
+        }
+        if (f.overlays != null && !Array.isArray(f.overlays)) {
+            throw new Error(`animate: frames[${i}].overlays must be an array`);
+        }
+        // Overlay shape is validated lazily in `resolveSvgOverlays` via
+        // `validateOverlay` — each entry checked at use-site.
+    }
+    return raw;
+}
+function validateAction(a, frameIdx, ai) {
+    if (!isObject(a))
+        throw new Error(`animate: frames[${frameIdx}].actions[${ai}] must be an object`);
+    switch (a.type) {
+        case "click":
+        case "hover":
+            if (typeof a.selector !== "string")
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (${a.type}) requires string selector`);
+            return;
+        case "fill":
+            if (typeof a.selector !== "string" || typeof a.value !== "string") {
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (fill) requires string selector and value`);
+            }
+            return;
+        case "press":
+            if (typeof a.key !== "string")
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (press) requires string key`);
+            return;
+        case "scroll":
+            if (a.x != null && typeof a.x !== "number")
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (scroll) x must be a number`);
+            if (a.y != null && typeof a.y !== "number")
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (scroll) y must be a number`);
+            return;
+        case "wait":
+            if (typeof a.ms !== "number")
+                throw new Error(`animate: frames[${frameIdx}].actions[${ai}] (wait) requires numeric ms`);
+            return;
+        default:
+            throw new Error(`animate: frames[${frameIdx}].actions[${ai}].type "${String(a.type)}" is not a recognised action`);
+    }
+}
+function validateFrameAnimation(a, frameIdx, ai) {
+    if (!isObject(a))
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}] must be an object`);
+    if (typeof a.selector !== "string")
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}].selector must be a string`);
+    if (typeof a.property !== "string")
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}].property must be a string`);
+    if (typeof a.from !== "string")
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}].from must be a string`);
+    if (typeof a.to !== "string")
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}].to must be a string`);
+    if (typeof a.duration !== "number")
+        throw new Error(`animate: frames[${frameIdx}].animations[${ai}].duration must be a number`);
+}
+function validateOverlay(ov, frameIdx, oi) {
+    if (!isObject(ov))
+        throw new Error(`animate: frames[${frameIdx}].overlays[${oi}] must be an object`);
+    switch (ov.kind) {
+        case "typing":
+            if (typeof ov.text !== "string" || typeof ov.x !== "number" || typeof ov.y !== "number") {
+                throw new Error(`animate: frames[${frameIdx}].overlays[${oi}] (typing) requires text/x/y`);
+            }
+            return ov;
+        case "tap":
+            if (typeof ov.x !== "number" || typeof ov.y !== "number") {
+                throw new Error(`animate: frames[${frameIdx}].overlays[${oi}] (tap) requires numeric x and y`);
+            }
+            return ov;
+        case "svg":
+            if (typeof ov.src !== "string" || typeof ov.x !== "number" || typeof ov.y !== "number" || typeof ov.width !== "number" || typeof ov.height !== "number") {
+                throw new Error(`animate: frames[${frameIdx}].overlays[${oi}] (svg) requires src/x/y/width/height`);
+            }
+            if (ov.enter != null)
+                validateOverlaySlide(ov.enter, frameIdx, oi, "enter");
+            if (ov.exit != null)
+                validateOverlaySlide(ov.exit, frameIdx, oi, "exit");
+            return ov;
+        default:
+            throw new Error(`animate: frames[${frameIdx}].overlays[${oi}].kind "${String(ov.kind)}" is not a recognised overlay`);
+    }
+}
+function validateOverlaySlide(s, frameIdx, oi, which) {
+    if (!isObject(s))
+        throw new Error(`animate: frames[${frameIdx}].overlays[${oi}].${which} must be an object`);
+    if (typeof s.from !== "string" || !OVERLAY_SLIDE_FROMS.has(s.from)) {
+        throw new Error(`animate: frames[${frameIdx}].overlays[${oi}].${which}.from must be one of ${[...OVERLAY_SLIDE_FROMS].join(", ")}`);
+    }
+    if (typeof s.duration !== "number") {
+        throw new Error(`animate: frames[${frameIdx}].overlays[${oi}].${which}.duration must be a number`);
     }
 }
 /**
@@ -250,9 +385,10 @@ function resolveSvgOverlays(rawOverlays, configDir, frameIdx) {
         return undefined;
     const out = [];
     let svgIdx = 0;
-    for (const ov of rawOverlays) {
-        if (ov != null && typeof ov === "object" && ov.kind === "svg") {
-            const raw = ov;
+    for (let oi = 0; oi < rawOverlays.length; oi++) {
+        const validated = validateOverlay(rawOverlays[oi], frameIdx, oi);
+        if (validated.kind === "svg" && "src" in rawOverlays[oi]) {
+            const raw = rawOverlays[oi];
             const srcPath = resolve(configDir, raw.src);
             if (!existsSync(srcPath))
                 throw new Error(`animate: svg overlay file not found: ${srcPath}`);
@@ -268,7 +404,7 @@ function resolveSvgOverlays(rawOverlays, configDir, frameIdx) {
             });
         }
         else {
-            out.push(ov);
+            out.push(validated);
         }
     }
     return out;

package/dist/mask.test.js

@@ -27,17 +27,22 @@ describe("buildMaskDef — single-layer gradient masks (DM-395)", () => {
     it("radial-gradient mask centers correctly when sized + positioned", () => {
         // mask-image: radial-gradient(circle, black 40%, transparent 40%);
         // mask-size: 80px; mask-position: 25% 25%
-        // Element at (680, 240); mask should be at gx=680+25, gy=240+10, 80x80.
+        // Element at (680, 240, 180x120). DM-679: single-length mask-size is
+        // `width=80, height=auto`. For gradient layers (no intrinsic size)
+        // `auto` resolves to the container's corresponding axis per CSS
+        // Backgrounds 3 §3.7 + CSS Images 3 §6.2 — so the gradient box is
+        // 80×120 (height = container 120), not 80×80. Position 25% 25% then
+        // gives gx=680 + 0.25*(180-80)=705 and gy=240 + 0.25*(120-120)=240.
         const r = buildMaskDef("m", "radial-gradient(circle, black 40%, transparent 40%)", 680, 240, 180, 120, "match-source", "80px", "25% 25%", "no-repeat", "add");
         expect(r.def).toContain('x="705"');
-        expect(r.def).toContain('y="250"');
+        expect(r.def).toContain('y="240"');
         expect(r.def).toContain('width="80"');
-        expect(r.def).toContain('height="80"');
-        // Center of the 80x80 mask box: cx=745, cy=290.
+        expect(r.def).toContain('height="120"');
+        // Center of the 80x120 mask box: cx=745, cy=300.
         expect(r.def).toMatch(/cx="745"/);
-        expect(r.def).toMatch(/cy="290"/);
-        // farthest-corner radius = sqrt(40^2 + 40^2) ≈ 56.5685.
-        expect(r.def).toMatch(/r="56\.5685"/);
+        expect(r.def).toMatch(/cy="300"/);
+        // farthest-corner radius = sqrt(40^2 + 60^2) ≈ 72.111.
+        expect(r.def).toMatch(/r="72\.111"/);
     });
     it("mask-mode: alpha emits mask-type='alpha'", () => {
         const r = buildMaskDef("m", "linear-gradient(45deg, black, transparent)", 0, 0, 180, 120, "alpha", "auto", "0% 0%", "repeat", "add");

package/dist/render/borders.d.ts

@@ -43,6 +43,15 @@ export declare function parseCornerRadii(styles: {
  *  that the inner corner is the outer corner pulled in by the adjacent border
  *  widths (top + left for TL, top + right for TR, etc.). */
 export declare function insetCornerRadii(c: CornerRadii, top: number, right: number, bottom: number, left: number): CornerRadii;
+/** Grow each corner radius outward by `spread` for an OUTSET box-shadow shape.
+ *  Per CSS Backgrounds 3 §6.4 and Chromium's `FloatRoundedRect::Outset`, a
+ *  corner whose source radius is zero STAYS sharp through any spread — only
+ *  pre-curved corners grow. A naive `corner + spread` produces visibly
+ *  rounded shadow corners on a sharp-cornered box (e.g. concentric outlines
+ *  built from `box-shadow: 0 0 0 Npx`). Use this for outset shadow shapes;
+ *  the dual inset case is already covered by `insetCornerRadii` shrinking to
+ *  zero when the border eats past the radius. */
+export declare function outsetCornerRadiiForShadow(c: CornerRadii, spread: number): CornerRadii;
 /** Emit an SVG path `d` attribute for a rounded rectangle with per-corner radii.
  *  Path goes clockwise from the top-left, using elliptical arc commands at each
  *  corner. Zero-radius corners collapse to a sharp 90° join. */
@@ -82,19 +91,6 @@ export declare function dashArrayForStyle(style: string, width: number): string;
  * them onto the nested `<svg>` is correct in both cases.
  */
 export declare function injectSvgSize(svgHtml: string, w: number, h: number): string;
-/**
- * Render a CSS border-image 9-slice around the element's border box.
- *
- * Supports:
- *   - border-image-source: url(...)         (gradient sources out of scope)
- *   - border-image-slice: t r b l            (percent + length, optional 'fill')
- *   - border-image-width: per-side (falls back to element border-width)
- *   - border-image-outset: per-side
- *   - border-image-repeat: stretch / repeat / round / space
- *
- * Returns { svg, usedIds }. usedIds indicates how many clipIdx values were
- * consumed so the caller can keep its own counter in sync.
- */
 export declare function renderBorderImage(el: CapturedElement, indent: string, idPrefix: string, defsParts: string[], clipIdx: number): {
     svg: string;
     usedIds: number;