domotion-svg 0.11.0 → 0.13.0

package/dist/animation/animator.d.ts

@@ -6,6 +6,7 @@
  */
 import { type CursorAtResolver, type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
 import type { MagicMove } from "./magic-move.js";
+import type { AnimationOverlay, TypingOverlay, TapOverlay, SvgOverlay, BlinkOverlay, IntraFrameAnimation } from "./overlay-schema.js";
 export interface AnimationFrame {
     /** SVG content for this frame (from dom-to-svg) */
     svgContent: string;
@@ -59,162 +60,7 @@ export interface AnimationFrame {
      */
     animations?: IntraFrameAnimation[];
 }
-export interface TypingOverlay {
-    kind: "typing";
-    text: string;
-    x: number;
-    y: number;
-    fontSize?: number;
-    color?: string;
-    /** Delay from frame start before typing begins (ms) */
-    delay?: number;
-    /** Speed per character (ms) */
-    speed?: number;
-    /** Background color to mask placeholder text */
-    bgColor?: string;
-    /**
-     * Field width in px. When set, the typed text WRAPS to this width like a
-     * browser textarea — breaking on spaces (char-breaking over-long words),
-     * advancing one line-height per wrapped line — instead of running off the
-     * right edge on a single line (DM-840). Omit for unbounded single-line text.
-     */
-    bgWidth?: number;
-    /**
-     * Field height in px (used to size the placeholder mask). The mask grows
-     * beyond this if the wrapped text needs more lines, so the typed text always
-     * sits on a clean background.
-     */
-    bgHeight?: number;
-    /**
-     * DM-870: render a blinking insertion caret. The bar sweeps the type
-     * position while typing, then parks at the end of the text and blinks
-     * (opacity 1↔0) until the frame ends. `true` uses defaults (the typing
-     * `color`, 2px wide, ~530ms cadence); an object overrides them.
-     */
-    caret?: boolean | {
-        color?: string;
-        width?: number;
-        blinkMs?: number;
-    };
-}
-export interface TapOverlay {
-    kind: "tap";
-    x: number;
-    y: number;
-    /** Delay from frame start (ms) */
-    delay?: number;
-}
-/**
- * Frame-local SVG overlay: composites a separately-captured SVG (inlined as
- * markup, not referenced as `<image href>`) on top of the captured frame.
- * Used for picture-in-picture effects like sliding a phone-framed preview
- * into the corner of a terminal demo.
- *
- * The overlay is positioned at (x, y), clipped to (width, height), and
- * gets its own `class="ov-<animId>"` wrapper so intra-frame animations
- * (or `enter`/`exit` sugar) can target it without colliding with elements
- * inside the embedded SVG.
- */
-export interface SvgOverlay {
-    kind: "svg";
-    /**
-     * The SVG content to inline. The CLI resolves `src` paths from the
-     * config file's directory and namespaces the embedded SVG's ids before
-     * setting this field.
-     */
-    innerSvg: string;
-    /** Top-left corner in the captured frame's coordinate space. */
-    x: number;
-    y: number;
-    /** Render size — the embedded SVG's viewBox is preserved and scales to fit. */
-    width: number;
-    height: number;
-    /**
-     * Stable id used to key the overlay's wrapper class (`ov-<animId>`) so
-     * `enter`/`exit` / `animations` can target it. The CLI assigns this.
-     */
-    animId: string;
-    /** Slide-in entrance (DM-211). Sugar over `animations`. */
-    enter?: {
-        from: "top" | "bottom" | "left" | "right";
-        duration: number;
-        easing?: string;
-        delay?: number;
-    };
-    /** Slide-out exit (DM-211). */
-    exit?: {
-        from: "top" | "bottom" | "left" | "right";
-        duration: number;
-        easing?: string;
-        delay?: number;
-    };
-}
-/**
- * DM-871: a standalone blinking bar/box, for carets/dots not tied to a typing
- * overlay — a recording dot, an attention pulse on a focused field, a cursor.
- * Renders a rect that toggles opacity on a `periodMs` cycle for the frame's
- * hold (sugar over a rect + a repeating opacity animation).
- */
-export interface BlinkOverlay {
-    kind: "blink";
-    /** Top-left corner in the captured frame's coordinate space. */
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    /** Full on/off cycle in ms (default 1000). */
-    periodMs?: number;
-    /** Fill color (default a light gray). */
-    color?: string;
-    /** Corner radius — set to half the width/height for a dot. */
-    radius?: number;
-    /** Ms after the frame becomes visible before blinking starts. Default 0. */
-    delay?: number;
-}
-export type AnimationOverlay = TypingOverlay | TapOverlay | SvgOverlay | BlinkOverlay;
-/**
- * Animate a CSS property on captured elements that match a selector, while
- * the frame is held on screen. The selector is resolved against the source
- * DOM at capture time (see DM-209) and the matching elements get
- * `class="anim-<id>"` on their rendered SVG groups.
- *
- * Resolution requires the consumer (CLI / `DemoRecorder`) to set
- * `data-domotion-anim="<id>"` on matching DOM elements before capture; the
- * `id` referenced here must be the same id set on the DOM.
- */
-export interface IntraFrameAnimation {
-    /** Anim id — must match the `data-domotion-anim` value set on the DOM pre-capture. */
-    animId: string;
-    /**
-     * CSS property to animate. `clipPath` takes raw CSS `clip-path` values
-     * (e.g. `"inset(0 100% 0 0)"` -> `"inset(0 0 0 0)"`) and is the right
-     * choice for left-to-right reveals like typing-into-captured-text. When
-     * the captured element is wrapped in a `<g class="anim-<id>">`, the
-     * keyframes apply `clip-path` to that wrapper.
-     */
-    property: "width" | "height" | "opacity" | "transform" | "translateX" | "translateY" | "clipPath";
-    /** Start value (CSS string, e.g. `"0%"`, `"240px"`, `"0.3"`). */
-    from: string;
-    /** End value (same syntax as `from`). */
-    to: string;
-    /** Duration in ms. Must be ≤ the parent frame's `duration`. */
-    duration: number;
-    /** CSS easing string. Default `linear`. */
-    easing?: string;
-    /** Ms after the frame becomes visible before animation starts. Default 0. */
-    delay?: number;
-    /**
-     * DM-869: repeat count. A positive integer or `"infinite"`. When set, the
-     * animation loops on its own `duration` clock (CSS `animation-iteration-count`)
-     * rather than playing once — turning a property animation into a blink / pulse
-     * / breathe. The loop is only visible while the frame is on screen (the frame
-     * group's visibility gating). `"infinite"` is the robust choice for a looping
-     * scene; a finite count aligns to the frame's first appearance.
-     */
-    repeat?: number | "infinite";
-    /** DM-869: when true, the loop ping-pongs `from`→`to`→`from` (CSS `animation-direction: alternate`). */
-    alternate?: boolean;
-}
+export type { TypingOverlay, TapOverlay, SvgOverlay, BlinkOverlay, AnimationOverlay, IntraFrameAnimation };
 export interface AnimationConfig {
     width: number;
     height: number;
@@ -260,5 +106,29 @@ export interface AnimationConfig {
      * → no rect, i.e. a transparent SVG that composites over a host background.
      */
     background?: string;
+    /**
+     * DM-1148: whether the LAST frame fades out (over its transition window) to
+     * dissolve back into the loop's frame 0. Default `false` — the last frame
+     * HOLDS solid to 100% and the loop hard-cuts to frame 0, so a one-shot video
+     * ends on the final frame rather than fading to nothing. Set `true` to restore
+     * the cross-dissolve loop (e.g. for a seamless background-loop SVG). Only
+     * affects the crossfade path; cut transitions already hold-then-cut.
+     */
+    loopFade?: boolean;
 }
+/**
+ * DM-1145: re-namespace element ids that COLLIDE across frames. A caller that
+ * reuses identical `svgContent` for multiple frames — e.g. caching a captured
+ * frame and replaying it for a long hold — emits the same baked-in ids in two
+ * frame groups. Duplicate ids are invalid SVG: a `clip-path="url(#id)"` / filter
+ * / `<use href="#id">` resolves to the FIRST match, which for the later frame
+ * lives in an earlier (now `visibility:hidden`) frame group. Chromium renders
+ * that fine during continuous playback, but CLIPS THE ELEMENT AWAY when the
+ * timeline is SEEKED to that frame (paused + `currentTime` set) — exactly what
+ * svg-to-video does, so the element vanishes in the rendered video although the
+ * SVG looks fine when played. Rename each frame's colliding ids (and their
+ * in-frame references) to a frame-unique form. ONLY collisions are touched, so
+ * frames whose ids are already unique are emitted byte-for-byte unchanged.
+ */
+export declare function dedupeFrameIds(frames: AnimationFrame[]): AnimationFrame[];
 export declare function generateAnimatedSvg(config: AnimationConfig): string;

package/dist/animation/animator.js

@@ -118,7 +118,10 @@ function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, tot
  * visible window driven by `fadeInStartPct` (precomputed by the caller, which
  * knows the overlap state). Extracted from `generateAnimatedSvg` (DM-1089).
  */
-function emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec) {
+function emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec, 
+/** DM-1148: the last frame, when the loop must NOT cross-dissolve, holds
+ *  opacity 1 to 100% instead of fading out over its transition window. */
+holdToEnd) {
     const groups = [];
     const keyframes = [];
     groups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
@@ -143,17 +146,75 @@ function emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEn
         const prevEnd = i > 0
             ? `${padBefore(parseFloat(fadeInStartPct), KEYFRAME_EPSILON.display, 2)}%,`
             : "";
-        keyframes.push(`
+        if (holdToEnd) {
+            // DM-1148: the final frame holds solid to 100% (no fade-out); the loop
+            // hard-cuts back to frame 0. The `fd` display window also runs to 100%.
+            // `prevEnd` (the prior frame's fade-out boundary) is empty for a lone
+            // frame-0 animation, which then has no opacity:0 segment at all.
+            const offSeg = prevEnd !== "" ? `0%, ${prevEnd.replace(/,$/, "")} { opacity: 0; }\n      ` : "";
+            keyframes.push(`
+    @keyframes fv-${i} {
+      ${offSeg}${startPct}, 100% { opacity: 1; }
+    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, "100")}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
+        }
+        else {
+            keyframes.push(`
     @keyframes fv-${i} {
       0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
       ${startPct}, ${holdEndPct} { opacity: 1; }
     }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct)}
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
+        }
     }
     return { groups, keyframes };
 }
+/**
+ * DM-1145: re-namespace element ids that COLLIDE across frames. A caller that
+ * reuses identical `svgContent` for multiple frames — e.g. caching a captured
+ * frame and replaying it for a long hold — emits the same baked-in ids in two
+ * frame groups. Duplicate ids are invalid SVG: a `clip-path="url(#id)"` / filter
+ * / `<use href="#id">` resolves to the FIRST match, which for the later frame
+ * lives in an earlier (now `visibility:hidden`) frame group. Chromium renders
+ * that fine during continuous playback, but CLIPS THE ELEMENT AWAY when the
+ * timeline is SEEKED to that frame (paused + `currentTime` set) — exactly what
+ * svg-to-video does, so the element vanishes in the rendered video although the
+ * SVG looks fine when played. Rename each frame's colliding ids (and their
+ * in-frame references) to a frame-unique form. ONLY collisions are touched, so
+ * frames whose ids are already unique are emitted byte-for-byte unchanged.
+ */
+export function dedupeFrameIds(frames) {
+    const seen = new Set();
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return frames.map((frame, i) => {
+        const svg = frame.svgContent;
+        if (svg == null || svg === "")
+            return frame;
+        const defined = new Set();
+        for (const m of svg.matchAll(/\sid="([^"]+)"/g))
+            defined.add(m[1]);
+        const colliding = [...defined].filter((id) => seen.has(id));
+        for (const id of defined)
+            seen.add(id);
+        if (colliding.length === 0)
+            return frame;
+        let out = svg;
+        for (const id of colliding) {
+            const nid = `d${i}-${id}`;
+            const e = esc(id);
+            out = out
+                .replace(new RegExp(`(\\sid=")${e}(")`, "g"), `$1${nid}$2`)
+                .replace(new RegExp(`url\\(#${e}\\)`, "g"), `url(#${nid})`)
+                .replace(new RegExp(`((?:xlink:)?href=")#${e}(")`, "g"), `$1#${nid}$2`);
+            seen.add(nid);
+        }
+        return { ...frame, svgContent: out };
+    });
+}
 export function generateAnimatedSvg(config) {
-    const { width, height, frames } = config;
+    const { width, height } = config;
+    // DM-1145: guard against cross-frame id collisions (reused/cached svgContent).
+    const frames = dedupeFrameIds(config.frames);
     const totalDuration = frames.reduce((sum, f) => sum + frameAdvanceMs(f), 0);
     const totalSec = totalDuration / 1000;
     // Pre-compute per-frame timing windows (used by both the merge pipeline for
@@ -256,7 +317,12 @@ export function generateAnimatedSvg(config) {
             const fadeInStartPct = (i > 0 && !entersViaMagicMove)
                 ? pct(Math.max(0, timeOffset - prevTransDur), totalDuration)
                 : startPct;
-            const r = emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec);
+            // DM-1148: the last frame holds solid to 100% (no loop cross-dissolve)
+            // unless `loopFade` is set. Only the crossfade path fades — cut already
+            // holds-then-cuts — so this is a no-op for cut frames.
+            const isCutFrame = transType === "cut" || transDur === 0;
+            const holdToEnd = i === frames.length - 1 && config.loopFade !== true && !isCutFrame;
+            const r = emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec, holdToEnd);
             frameGroups.push(...r.groups);
             keyframes.push(...r.keyframes);
         }
@@ -382,12 +448,14 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
     const color = overlay.color ?? "#e6edf3";
     const typeStartMs = frameStart + delay;
     const id = `t${frameIdx}`;
-    // DM-840: wrap to bgWidth so typed text behaves like a browser field
-    // (textarea) — wrapping to the next line instead of running off the right
-    // edge. Text starts at overlay.x and the bg rect starts at overlay.x-2 with
-    // width bgWidth, so the usable text width is bgWidth-4. With no bgWidth we
-    // keep the original single-line behavior (maxChars = Infinity).
-    const maxLineWidth = overlay.bgWidth != null ? overlay.bgWidth - 4 : Infinity;
+    // DM-840 / DM-1134: wrap to `wrapWidth` so typed text behaves like a browser
+    // field (textarea) — wrapping to the next line instead of running off the
+    // right edge. Text starts at overlay.x and the bg rect starts at overlay.x-2
+    // with the mask width, so the usable text width is wrapWidth-4. With no wrap
+    // width we keep the original single-line behavior (maxChars = Infinity).
+    // `wrapWidth` supersedes the deprecated `bgWidth` (which fed both wrap + mask).
+    const wrapWidth = overlay.wrapWidth ?? overlay.bgWidth;
+    const maxLineWidth = wrapWidth != null ? wrapWidth - 4 : Infinity;
     const maxChars = maxLineWidth === Infinity ? Infinity : Math.max(1, Math.floor(maxLineWidth / charWidth));
     const lines = wrapTypingText(overlay.text, maxChars);
     const visibleChars = Math.max(1, lines.reduce((n, l) => n + l.length, 0));
@@ -410,11 +478,16 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
     const disappearPct = pct(disappearMs, totalDuration);
     // Background mask — grown to cover every wrapped line so the typed text
     // always lands on a clean field instead of the captured placeholder.
-    if (overlay.bgColor != null) {
-        const bgW = overlay.bgWidth ?? longestLineChars * charWidth + 8;
-        const bgH = Math.max(overlay.bgHeight ?? fontSize + 6, lines.length * lineHeight + 6);
+    // DM-1134: the mask is sized by `mask: { width, height, color }`, independent
+    // of the wrap width; the legacy `bgColor` / `bgWidth` / `bgHeight` are the
+    // deprecated fallbacks (`bgWidth` also fed the wrap above). Mask width
+    // defaults to the wrap width, then to the longest typed line.
+    const maskColor = overlay.mask?.color ?? overlay.bgColor;
+    if (maskColor != null) {
+        const bgW = overlay.mask?.width ?? wrapWidth ?? longestLineChars * charWidth + 8;
+        const bgH = Math.max(overlay.mask?.height ?? overlay.bgHeight ?? fontSize + 6, lines.length * lineHeight + 6);
         const bgStartPct = pct(typeStartMs, totalDuration);
-        parts.push(`  <rect class="${id}-bg" x="${overlay.x - 2}" y="${overlay.y - fontSize + 2}" width="${bgW}" height="${bgH}" fill="${overlay.bgColor}" rx="2" />`);
+        parts.push(`  <rect class="${id}-bg" x="${overlay.x - 2}" y="${overlay.y - fontSize + 2}" width="${bgW}" height="${bgH}" fill="${maskColor}" rx="2" />`);
         cssRules.push(`
     @keyframes ${id}-bg { 0%, ${bgStartPct} { opacity: 0; } ${pct(typeStartMs + 50, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${disappearPct}, 100% { opacity: 0; } }
     .${id}-bg { animation: ${id}-bg ${totalSec.toFixed(2)}s infinite; }`);

package/dist/animation/index.d.ts

@@ -2,3 +2,4 @@ export { buildMagicMove, type MagicMove, type MagicMoveSlide, } from "./magic-mo
 export { generateAnimatedSvg, type AnimationConfig, type AnimationFrame, type AnimationOverlay, type TypingOverlay, type TapOverlay, type SvgOverlay, type IntraFrameAnimation, } from "./animator.js";
 export { cursorOverlayMarkup, resolveCursorScript, cursorAtPoint, type CursorOverlay, type CursorEvent, type CursorMoveEvent, type CursorClickEvent, type CursorShowEvent, type CursorHideEvent, type CursorStyle, type CursorTimelineEntry, type SelectorResolver, type CursorAtResolver, } from "./cursor-overlay.js";
 export { CURSOR_GLYPHS, CURSOR_CATEGORIES, cursorGlyphSvg, type CursorGlyph } from "./cursor-glyphs.js";
+export { resolveOverlays, type OverlayAnchor, type AnchoredOverlay } from "./resolve-overlays.js";

package/dist/animation/index.js

@@ -7,3 +7,7 @@ export { buildMagicMove, } from "./magic-move.js";
 export { generateAnimatedSvg, } from "./animator.js";
 export { cursorOverlayMarkup, resolveCursorScript, cursorAtPoint, } from "./cursor-overlay.js";
 export { CURSOR_GLYPHS, CURSOR_CATEGORIES, cursorGlyphSvg } from "./cursor-glyphs.js";
+// DM-1132: lower selector-anchored overlays into concrete-coordinate overlays
+// against a live page — the resolution step the declarative CLI uses, now
+// reachable by imperative `captureElementTree` + `generateAnimatedSvg` callers.
+export { resolveOverlays } from "./resolve-overlays.js";

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

@@ -0,0 +1,261 @@
+/**
+ * Single source of truth for the animation overlay + intra-frame-animation
+ * shapes (DM-1131).
+ *
+ * These zod schemas define the *resolved* (runtime) overlay shapes that
+ * `generateAnimatedSvg` consumes — concrete `x` / `y` / `bgWidth`, no
+ * selector `anchor`. The TypeScript types the public API exports
+ * (`TypingOverlay`, `AnimationOverlay`, …) are derived from them via
+ * `z.infer`, so there is exactly ONE definition of each shape.
+ *
+ * The declarative-config layer (`src/cli/animate.ts`) builds its *authoring*
+ * overlay schemas by EXTENDING these base schemas (adding `anchor` /
+ * `maxWidth`, relaxing `x` / `y` to defaulted), so the two views can no longer
+ * drift: rename a field here and both the renderer types and the config
+ * validator (plus its generated JSON Schema) move together, or fail to
+ * compile. Before this split the renderer hand-wrote the interfaces and the
+ * CLI hand-wrote a parallel zod schema — a rename on one side was invisible to
+ * the other (the `Overlay` → `AnimationOverlay` regression that motivated this).
+ *
+ * Field docs live here as comments; the consumer-facing contract is
+ * `docs/api.md` + `docs/08-animation-model.md` / `docs/43-declarative-animate-
+ * config.md`. Keep this file's field set in lockstep with those docs.
+ */
+import { z } from "zod";
+/**
+ * Slide-in / slide-out descriptor shared by SVG overlays (`enter` / `exit`)
+ * — DM-211. Sugar over an intra-frame animation.
+ */
+export declare const overlaySlideSchema: z.ZodObject<{
+    from: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        top: "top";
+        bottom: "bottom";
+    }>;
+    duration: z.ZodNumber;
+    easing: z.ZodOptional<z.ZodString>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type OverlaySlide = z.infer<typeof overlaySlideSchema>;
+/**
+ * The placeholder cover painted behind a typing overlay's text, sized
+ * independently of the wrap width (DM-1134). All three fields are optional:
+ * `width` defaults to the wrap width (then to the longest typed line),
+ * `height` grows to fit the wrapped lines, and the mask only paints when a
+ * `color` is resolvable.
+ */
+export declare const typingMaskSchema: z.ZodObject<{
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TypingMask = z.infer<typeof typingMaskSchema>;
+/**
+ * A typed-text reveal layered onto a captured frame.
+ *
+ * DM-1134: wrapping and the placeholder mask are now separate knobs —
+ * `wrapWidth` controls where the text line-breaks (browser-textarea style,
+ * DM-840) and `mask: { width, height, color }` controls the cover. The legacy
+ * `bgWidth` / `bgHeight` / `bgColor` fields still work (deprecated aliases):
+ * `bgWidth` feeds both `wrapWidth` and `mask.width`, `bgHeight` → `mask.height`,
+ * `bgColor` → `mask.color`. Prefer the new fields in new code.
+ */
+export declare const typingOverlaySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"typing">;
+    text: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    fontSize: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+    delay: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    wrapWidth: z.ZodOptional<z.ZodNumber>;
+    mask: z.ZodOptional<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    bgColor: z.ZodOptional<z.ZodString>;
+    bgWidth: z.ZodOptional<z.ZodNumber>;
+    bgHeight: z.ZodOptional<z.ZodNumber>;
+    caret: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        color: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        blinkMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export type TypingOverlay = z.infer<typeof typingOverlaySchema>;
+/** A tap-ripple at `(x, y)`, frame-relative. */
+export declare const tapOverlaySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tap">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type TapOverlay = z.infer<typeof tapOverlaySchema>;
+/**
+ * Frame-local SVG overlay: composites a separately-captured SVG (inlined as
+ * markup, not referenced as `<image href>`) on top of the captured frame.
+ * Used for picture-in-picture effects like sliding a phone-framed preview
+ * into the corner of a terminal demo.
+ *
+ * The overlay is positioned at (x, y), clipped to (width, height), and gets
+ * its own `class="ov-<animId>"` wrapper so intra-frame animations (or
+ * `enter`/`exit` sugar) can target it without colliding with elements inside
+ * the embedded SVG.
+ *
+ * Note: this is the RESOLVED shape — the declarative config takes a `src` file
+ * path and the CLI reads / namespaces it into `innerSvg` + `animId`.
+ */
+export declare const svgOverlaySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"svg">;
+    innerSvg: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    animId: z.ZodString;
+    enter: z.ZodOptional<z.ZodObject<{
+        from: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>;
+        duration: z.ZodNumber;
+        easing: z.ZodOptional<z.ZodString>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    exit: z.ZodOptional<z.ZodObject<{
+        from: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>;
+        duration: z.ZodNumber;
+        easing: z.ZodOptional<z.ZodString>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SvgOverlay = z.infer<typeof svgOverlaySchema>;
+/**
+ * DM-871: a standalone blinking bar/box, for carets/dots not tied to a typing
+ * overlay — a recording dot, an attention pulse on a focused field, a cursor.
+ * Renders a rect that toggles opacity on a `periodMs` cycle for the frame's
+ * hold (sugar over a rect + a repeating opacity animation).
+ */
+export declare const blinkOverlaySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"blink">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    periodMs: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+    radius: z.ZodOptional<z.ZodNumber>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type BlinkOverlay = z.infer<typeof blinkOverlaySchema>;
+/** The resolved overlay union `generateAnimatedSvg` consumes per frame. */
+export declare const animationOverlaySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"typing">;
+    text: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    fontSize: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+    delay: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    wrapWidth: z.ZodOptional<z.ZodNumber>;
+    mask: z.ZodOptional<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    bgColor: z.ZodOptional<z.ZodString>;
+    bgWidth: z.ZodOptional<z.ZodNumber>;
+    bgHeight: z.ZodOptional<z.ZodNumber>;
+    caret: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        color: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        blinkMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"tap">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"svg">;
+    innerSvg: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    animId: z.ZodString;
+    enter: z.ZodOptional<z.ZodObject<{
+        from: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>;
+        duration: z.ZodNumber;
+        easing: z.ZodOptional<z.ZodString>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    exit: z.ZodOptional<z.ZodObject<{
+        from: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>;
+        duration: z.ZodNumber;
+        easing: z.ZodOptional<z.ZodString>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"blink">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    periodMs: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+    radius: z.ZodOptional<z.ZodNumber>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export type AnimationOverlay = z.infer<typeof animationOverlaySchema>;
+/**
+ * Animate a CSS property on captured elements that match a selector, while the
+ * frame is held on screen. The selector is resolved against the source DOM at
+ * capture time (see DM-209) and the matching elements get `class="anim-<id>"`
+ * on their rendered SVG groups.
+ *
+ * Resolution requires the consumer (CLI / `DemoRecorder`) to set
+ * `data-domotion-anim="<id>"` on matching DOM elements before capture; the
+ * `id` referenced here must be the same id set on the DOM.
+ */
+export declare const intraFrameAnimationSchema: z.ZodObject<{
+    animId: z.ZodString;
+    property: z.ZodEnum<{
+        width: "width";
+        clipPath: "clipPath";
+        height: "height";
+        transform: "transform";
+        opacity: "opacity";
+        translateX: "translateX";
+        translateY: "translateY";
+    }>;
+    from: z.ZodString;
+    to: z.ZodString;
+    duration: z.ZodNumber;
+    easing: 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>;
+}, z.core.$strip>;
+export type IntraFrameAnimation = z.infer<typeof intraFrameAnimationSchema>;