domotion-svg 0.2.2 → 0.3.2

package/src/capture/types.ts

@@ -105,13 +105,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;
   };
 }
 
@@ -186,6 +224,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;
@@ -218,6 +264,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;
@@ -231,6 +307,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
@@ -240,6 +324,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;
@@ -446,6 +549,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. */
@@ -507,7 +618,40 @@ 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. */
@@ -589,6 +733,18 @@ export interface CapturedElement {
    * content region. Detection happens in CAPTURE_SCRIPT.
    */
   elementRaster?: { x: number; y: number; width: number; 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
@@ -636,6 +792,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
@@ -649,6 +817,31 @@ 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 {
@@ -658,6 +851,13 @@ export interface MaskFragmentDef {
   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/src/cli/animate.ts

@@ -129,8 +129,8 @@ export async function runAnimate(args: string[], help: string): Promise<void> {
   const configPath = resolve(positionals[0]);
   if (!existsSync(configPath)) throw new Error(`animate: config not found: ${configPath}`);
 
-  const cfg = JSON.parse(readFileSync(configPath, "utf8")) as AnimateConfig;
-  validateAnimateConfig(cfg);
+  const cfgRaw: unknown = JSON.parse(readFileSync(configPath, "utf8"));
+  const cfg = validateAnimateConfig(cfgRaw);
   const configDir = dirname(configPath);
 
   const log = makeLogger(values.quiet === true);
@@ -304,33 +304,152 @@ async function runActions(page: Page, actions: AnimateAction[]): Promise<void> {
   }
 }
 
-function validateAnimateConfig(cfg: AnimateConfig): void {
-  if (typeof cfg.width !== "number" || typeof cfg.height !== "number") {
+const COLOR_SCHEMES = new Set(["light", "dark", "no-preference"] as const);
+const TRANSITION_TYPES = new Set(["crossfade", "push-left", "scroll", "cut"] as const);
+const OVERLAY_SLIDE_FROMS = new Set(["top", "bottom", "left", "right"] as const);
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function validateAnimateConfig(raw: unknown): AnimateConfig {
+  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 as never))) {
+    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 as never)) {
+        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 as unknown as AnimateConfig;
+}
+
+function validateAction(a: unknown, frameIdx: number, ai: number): void {
+  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: unknown, frameIdx: number, ai: number): void {
+  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: unknown, frameIdx: number, oi: number): AnimationOverlay {
+  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 as unknown as AnimationOverlay;
+    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 as unknown as AnimationOverlay;
+    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 as unknown as AnimationOverlay;
+    default:
+      throw new Error(`animate: frames[${frameIdx}].overlays[${oi}].kind "${String(ov.kind)}" is not a recognised overlay`);
+  }
+}
+
+function validateOverlaySlide(s: unknown, frameIdx: number, oi: number, which: "enter" | "exit"): void {
+  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 as never)) {
+    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`);
   }
 }
 
@@ -343,9 +462,10 @@ function resolveSvgOverlays(rawOverlays: unknown[] | undefined, configDir: strin
   if (rawOverlays == null) return undefined;
   const out: AnimationOverlay[] = [];
   let svgIdx = 0;
-  for (const ov of rawOverlays) {
-    if (ov != null && typeof ov === "object" && (ov as { kind?: string }).kind === "svg") {
-      const raw = ov as { kind: "svg"; src: string; x: number; y: number; width: number; height: number; enter?: SvgOverlay["enter"]; exit?: SvgOverlay["exit"] };
+  for (let oi = 0; oi < rawOverlays.length; oi++) {
+    const validated = validateOverlay(rawOverlays[oi], frameIdx, oi);
+    if (validated.kind === "svg" && "src" in (rawOverlays[oi] as Record<string, unknown>)) {
+      const raw = rawOverlays[oi] as { src: string; x: number; y: number; width: number; height: number; enter?: SvgOverlay["enter"]; exit?: SvgOverlay["exit"] };
       const srcPath = resolve(configDir, raw.src);
       if (!existsSync(srcPath)) throw new Error(`animate: svg overlay file not found: ${srcPath}`);
       const fileText = readFileSync(srcPath, "utf8");
@@ -359,7 +479,7 @@ function resolveSvgOverlays(rawOverlays: unknown[] | undefined, configDir: strin
         enter: raw.enter, exit: raw.exit,
       });
     } else {
-      out.push(ov as AnimationOverlay);
+      out.push(validated);
     }
   }
   return out;

package/src/mask.test.ts

@@ -33,18 +33,23 @@ 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'", () => {