domotion-svg 0.14.0 → 0.15.0

package/README.md

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

package/dist/animation/animator.js

@@ -829,25 +829,46 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                     return `transform: translateX(${val});`;
                 if (a.property === "translateY")
                     return `transform: translateY(${val});`;
+                if (a.property === "scale")
+                    return `transform: scale(${val});`;
                 if (a.property === "clipPath")
                     return `clip-path: ${val};`;
                 return `${a.property}: ${val};`;
             };
+            // DM-1297: SVG transforms are origin-(0,0); a `transformOrigin` makes a
+            // scale/rotate/translate resolve about the element's OWN box (e.g. a
+            // center-origin scale-pop) instead of the SVG origin. `transform-box:
+            // fill-box` switches the reference box to the element's bounding box.
+            const originDecl = a.transformOrigin != null && a.transformOrigin !== ""
+                ? ` transform-box: fill-box; transform-origin: ${a.transformOrigin};`
+                : "";
             const animName = `f${i}-${a.animId}-${ai}`;
             if (a.repeat != null) {
                 // DM-869: repeating animation (blink / pulse / breathe). The keyframe is
                 // a single from→to cycle on the animation's own `duration` clock, looped
                 // via animation-iteration-count + (optional) direction:alternate. The
                 // loop is only visible while the frame is on screen (the frame group's
-                // visibility gating); `animation-delay` aligns the first cycle to the
-                // frame's appearance. `fill-mode: both` holds `from` before the delay.
+                // visibility gating).
+                //
+                // `animation-delay` positions the first cycle: a POSITIVE delay (after the
+                // frame appears) holds `from` until it elapses then plays; a NEGATIVE delay
+                // (a phase offset) starts the loop already mid-cycle so it never freezes —
+                // the right choice for a seamless ambient loop (DM-1289).
+                //
+                // DM-1289: emit timing-function / delay / fill-mode INSIDE the `animation`
+                // shorthand, not as trailing longhands. The optimizer (csso) merges shared
+                // longhands into a separate, earlier grouped rule; a later `animation`
+                // shorthand then resets `animation-fill-mode` back to `none`, so during a
+                // positive delay the element showed its base value (not `from`) and SNAPPED
+                // when the cycle began. Folding everything into the one shorthand leaves
+                // nothing for the optimizer to hoist out of order.
                 const iterations = a.repeat === "infinite" ? "infinite" : String(a.repeat);
                 const direction = a.alternate === true ? " alternate" : "";
                 out.push(`    @keyframes ${animName} {
       0% { ${propValue(a.from)} }
       100% { ${propValue(a.to)} }
     }
-    .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${iterations}${direction}; animation-timing-function: ${easing}; animation-delay: ${startMs.toFixed(0)}ms; animation-fill-mode: both; }`);
+    .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${easing} ${startMs.toFixed(0)}ms ${iterations}${direction} both;${originDecl} }`);
             }
             else {
                 // One-shot: hold `from` until startPct, animate from→to during
@@ -859,7 +880,7 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
       ${endPct.toFixed(3)}% { ${propValue(a.to)} }
       100% { ${propValue(a.to)} }
     }
-    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing};${originDecl} }`);
             }
         }
     }

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

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

package/dist/animation/embed-namespace.js

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

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

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

package/dist/animation/overlay-schema.js

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

package/dist/cli/animate.d.ts

@@ -239,8 +239,15 @@ export declare const animateConfigSchema: z.ZodObject<{
             maxFrameMs: z.ZodOptional<z.ZodNumber>;
             tailMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        template: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        fit: z.ZodOptional<z.ZodEnum<{
+            center: "center";
+            cover: "cover";
+            contain: "contain";
+        }>>;
         continue: z.ZodOptional<z.ZodBoolean>;
-        duration: z.ZodNumber;
+        duration: z.ZodDefault<z.ZodNumber>;
         transition: z.ZodOptional<z.ZodObject<{
             type: z.ZodEnum<{
                 scroll: "scroll";
@@ -540,7 +547,9 @@ export declare const animateConfigSchema: z.ZodObject<{
                 opacity: "opacity";
                 translateX: "translateX";
                 translateY: "translateY";
+                scale: "scale";
             }>;
+            transformOrigin: z.ZodOptional<z.ZodString>;
             alternate: z.ZodOptional<z.ZodBoolean>;
             selector: z.ZodString;
             repeat: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"infinite">]>>;
@@ -606,6 +615,38 @@ export interface ComposeAnimateOptions {
  * a frame's relative `input` / svg-overlay `src` paths (default `process.cwd()`);
  * `log` defaults to a no-op.
  */
+/**
+ * DM-1287 (doc 73): render every `template` frame's named template to a finished
+ * SVG string, ready to nest as that frame's `svgContent`. Returns a map keyed by
+ * frame index (only template frames appear).
+ *
+ * Runs BEFORE the caller's outer font lifecycle so the nested per-template
+ * `composeAnimateFrames` (a template is a front-end onto the same engine) can
+ * clear + manage the module-global font builders without clobbering the outer
+ * run's frames — each template's output carries its own `@font-face`.
+ *
+ * Sizing: the template inherits the config's `width`/`height` when its params
+ * schema declares those fields and the caller left them unset, so it fills the
+ * frame by default. A template whose output differs from the canvas (e.g.
+ * `device-mockup`, which grows by its bezel) is centered; an oversized output is
+ * centered and clipped by the frame viewport. The template's own internal
+ * timeline plays within the frame's `duration` (size `duration` to ≈ the
+ * template's play time, same rule as a `cast` frame).
+ *
+ * Loaded via dynamic `import()` to avoid a static import cycle (the template
+ * subsystem already imports `composeAnimateConfig` from this module).
+ */
+/**
+ * DM-1293: place a nested frame's `content` (a `srcW × srcH` SVG body) inside a
+ * `dstW × dstH` canvas per the `fit` policy, wrapping it in a `<g transform>` when
+ * a translate/scale is needed (and returning it untouched when neither is — the
+ * exact-fit common case). All modes keep the content centered:
+ *  - `center` — 1:1, no scale (oversized content is clipped by the frame viewport).
+ *  - `contain` — scale to fit, preserving aspect (letterboxed).
+ *  - `cover` — scale to fill, preserving aspect (the overflow is clipped).
+ * Exported for unit testing the geometry without a browser.
+ */
+export declare function placeEmbeddedFrame(content: string, srcW: number, srcH: number, dstW: number, dstH: number, fit?: "center" | "contain" | "cover"): string;
 export declare function composeAnimateFrames(browser: Browser, cfg: AnimateConfig, configDirOrOpts?: string | ComposeAnimateOptions, logArg?: (msg: string) => void): Promise<AnimationConfig>;
 /**
  * Capture and compose every frame in `cfg` into one animated SVG string

package/dist/cli/animate.js

@@ -27,6 +27,7 @@ import { composeScrollSvg, executeScrollPattern, parseScrollPattern } from "../s
 import { cullElementsOutsideViewBox } from "../tree-ops/index.js";
 import { optimizeSvg } from "../post-processing/index.js";
 import { frameAdvanceMs } from "../animation/frame-timeline.js";
+import { namespaceEmbeddedAnimatedSvg } from "../animation/embed-namespace.js";
 import { castToAnimatedSvg } from "../terminal/index.js";
 import { applyReadyWaits, isSvgzPath, loadInputIntoPage, makeLogger, resolveOutputPath, timed, writeOutput, } from "./common.js";
 // ── Config schema (DM-843) ──────────────────────────────────────────────────
@@ -206,8 +207,29 @@ const frameSchema = z.object({
     // recorded length (the tool logs it). Mutually exclusive with `input`.
     cast: z.string().optional(),
     term: termOptionsSchema.optional(),
+    // DM-1287 (doc 73): a `template` frame embeds a named Domotion template's
+    // output (e.g. a `lower-third` banner or a `kinetic-text` title) as this
+    // frame's content — most templates emit an animated SVG, which nests like a
+    // `cast` frame. `params` is validated against the named template's own schema
+    // at compose time (path-specific errors). The template inherits the config's
+    // `width`/`height` when its schema has those params and they're unset, so it
+    // fills the frame by default; a smaller/larger output is centered (+ clipped).
+    // Mutually exclusive with `input` / `cast` / `continue`.
+    template: z.string().optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+    // DM-1293: how a `template` frame's output is placed when its size differs from
+    // the canvas. `center` (default) places it 1:1 (oversized → clipped); `contain`
+    // scales it down to fit, preserving aspect (letterboxed); `cover` scales it up
+    // to fill, preserving aspect (cropped). Only meaningful on a template frame.
+    fit: z.enum(["center", "contain", "cover"]).optional(),
     continue: z.boolean().optional(),
-    duration: z.number(),
+    // DM-1294: `duration` is required on every frame EXCEPT a `template` frame,
+    // which may omit it to inherit the template's own play time (its generator
+    // reports `durationMs`). Defaults to `0` (a sentinel for "unset" — a 0 ms frame
+    // is never valid), so the type stays `number` for the timeline math; the
+    // "required-and-positive unless template" rule is enforced in the config-level
+    // superRefine below (it needs the sibling `template` field).
+    duration: z.number().default(0),
     transition: transitionSchema.optional(),
     selector: z.string().optional(),
     wait: z.number().optional(),
@@ -289,8 +311,8 @@ export const animateConfigSchema = z
     .superRefine((cfg, ctx) => {
     // DM-846 §1 cross-frame rules for the continuous-session model.
     cfg.frames.forEach((f, i) => {
-        if (i === 0 && f.input == null && f.cast == null) {
-            ctx.addIssue({ code: "custom", path: ["frames", 0, "input"], message: "frame 0 must load an `input` or a `cast`" });
+        if (i === 0 && f.input == null && f.cast == null && f.template == null) {
+            ctx.addIssue({ code: "custom", path: ["frames", 0, "input"], message: "frame 0 must load an `input`, a `cast`, or a `template`" });
         }
         if (i === 0 && f.continue === true) {
             ctx.addIssue({ code: "custom", path: ["frames", 0, "continue"], message: "frame 0 cannot continue — it has no predecessor" });
@@ -306,6 +328,31 @@ export const animateConfigSchema = z
         if (f.cast != null && f.continue === true) {
             ctx.addIssue({ code: "custom", path: ["frames", i, "cast"], message: "a `cast` frame cannot also `continue` a live page" });
         }
+        // DM-1287: a `template` frame is its own content source — it can't also
+        // load an `input`, embed a `cast`, or continue a live page. `params`
+        // without a `template` has nothing to validate against.
+        if (f.template != null && f.input != null) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "template"], message: "a frame cannot set both `template` and `input`" });
+        }
+        if (f.template != null && f.cast != null) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "template"], message: "a frame cannot set both `template` and `cast`" });
+        }
+        if (f.template != null && f.continue === true) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "template"], message: "a `template` frame cannot also `continue` a live page" });
+        }
+        if (f.params != null && f.template == null) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "params"], message: "`params` requires a `template`" });
+        }
+        // DM-1293: `fit` only governs how a template frame's output is placed.
+        if (f.fit != null && f.template == null) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "fit"], message: "`fit` requires a `template`" });
+        }
+        // DM-1294: `duration` is required (and positive) except on a `template`
+        // frame, which derives it from the template's play time when omitted (the
+        // `0` default is the "unset" sentinel).
+        if (f.duration <= 0 && f.template == null) {
+            ctx.addIssue({ code: "custom", path: ["frames", i, "duration"], message: "`duration` is required and must be > 0 (only a `template` frame may omit it — it inherits the template's play time)" });
+        }
     });
 });
 export async function runAnimate(args, help) {
@@ -392,10 +439,138 @@ function normalizeComposeArgs(configDirOrOpts, log) {
  * a frame's relative `input` / svg-overlay `src` paths (default `process.cwd()`);
  * `log` defaults to a no-op.
  */
+/**
+ * DM-1287 (doc 73): render every `template` frame's named template to a finished
+ * SVG string, ready to nest as that frame's `svgContent`. Returns a map keyed by
+ * frame index (only template frames appear).
+ *
+ * Runs BEFORE the caller's outer font lifecycle so the nested per-template
+ * `composeAnimateFrames` (a template is a front-end onto the same engine) can
+ * clear + manage the module-global font builders without clobbering the outer
+ * run's frames — each template's output carries its own `@font-face`.
+ *
+ * Sizing: the template inherits the config's `width`/`height` when its params
+ * schema declares those fields and the caller left them unset, so it fills the
+ * frame by default. A template whose output differs from the canvas (e.g.
+ * `device-mockup`, which grows by its bezel) is centered; an oversized output is
+ * centered and clipped by the frame viewport. The template's own internal
+ * timeline plays within the frame's `duration` (size `duration` to ≈ the
+ * template's play time, same rule as a `cast` frame).
+ *
+ * Loaded via dynamic `import()` to avoid a static import cycle (the template
+ * subsystem already imports `composeAnimateConfig` from this module).
+ */
+/**
+ * DM-1293: place a nested frame's `content` (a `srcW × srcH` SVG body) inside a
+ * `dstW × dstH` canvas per the `fit` policy, wrapping it in a `<g transform>` when
+ * a translate/scale is needed (and returning it untouched when neither is — the
+ * exact-fit common case). All modes keep the content centered:
+ *  - `center` — 1:1, no scale (oversized content is clipped by the frame viewport).
+ *  - `contain` — scale to fit, preserving aspect (letterboxed).
+ *  - `cover` — scale to fill, preserving aspect (the overflow is clipped).
+ * Exported for unit testing the geometry without a browser.
+ */
+export function placeEmbeddedFrame(content, srcW, srcH, dstW, dstH, fit = "center") {
+    const r = (n) => Math.round(n * 1000) / 1000;
+    let scale = 1;
+    if (fit === "contain")
+        scale = Math.min(dstW / srcW, dstH / srcH);
+    else if (fit === "cover")
+        scale = Math.max(dstW / srcW, dstH / srcH);
+    const ox = r((dstW - srcW * scale) / 2);
+    const oy = r((dstH - srcH * scale) / 2);
+    const parts = [];
+    if (ox !== 0 || oy !== 0)
+        parts.push(`translate(${ox},${oy})`);
+    // `transform` applies right-to-left, so `translate(…) scale(…)` scales first
+    // (about the content's own origin) then offsets — i.e. the scaled box is centered.
+    if (scale !== 1)
+        parts.push(`scale(${r(scale)})`);
+    return parts.length > 0 ? `<g transform="${parts.join(" ")}">${content}</g>` : content;
+}
+async function renderTemplateFrames(cfg, browser, log) {
+    const out = new Map();
+    const idxs = cfg.frames.flatMap((f, i) => (f.template != null ? [i] : []));
+    if (idxs.length === 0)
+        return out;
+    const { loadTemplate } = await import("../templates/registry.js");
+    const { renderTemplateToSvg } = await import("../templates/render.js");
+    for (const i of idxs) {
+        const fc = cfg.frames[i];
+        const name = fc.template;
+        log(`Rendering template "${name}" for frame ${i + 1}/${cfg.frames.length}…`);
+        let template;
+        try {
+            template = await loadTemplate(name);
+        }
+        catch (e) {
+            throw new Error(`animate: frames[${i}].template: ${e.message}`);
+        }
+        // Inherit the canvas size into the template's `width`/`height` params when
+        // its schema declares them and the caller didn't set them, so the template
+        // fills the frame. Introspect the zod object shape; templates without those
+        // params (or non-object schemas) just get no injection.
+        const shape = template.paramsSchema.shape;
+        const base = {};
+        if (shape != null && Object.prototype.hasOwnProperty.call(shape, "width"))
+            base.width = cfg.width;
+        if (shape != null && Object.prototype.hasOwnProperty.call(shape, "height"))
+            base.height = cfg.height;
+        const rawParams = { ...base, ...(fc.params ?? {}) };
+        let result;
+        try {
+            result = await renderTemplateToSvg(template, rawParams, { browser, log: (m) => log(`  ${m}`) });
+        }
+        catch (e) {
+            // Param-validation errors already carry their own `template "x": …` path.
+            throw new Error(`animate: frames[${i}]: ${e.message}`);
+        }
+        const fit = fc.fit ?? "center";
+        if (fit === "center" && (result.width > cfg.width || result.height > cfg.height)) {
+            log(`  note: template output ${result.width}×${result.height} exceeds the ${cfg.width}×${cfg.height} canvas — it will be centered and clipped (set "fit":"contain" to scale it down)`);
+        }
+        // DM-1294: resolve the frame's duration. When the author omitted it, inherit
+        // the template's own play time (`durationMs`); a static template (no intrinsic
+        // duration) MUST carry an explicit `duration`. When the author set one that's
+        // shorter than the template plays, warn — the template will be cut off (same
+        // rule as a `cast` frame).
+        if (fc.duration <= 0) {
+            if (result.durationMs == null) {
+                throw new Error(`animate: frames[${i}].duration: template "${name}" has no intrinsic play time (it's a static template) — set an explicit "duration"`);
+            }
+            fc.duration = result.durationMs;
+            log(`  frame duration defaulted to the template's play time: ${result.durationMs}ms`);
+        }
+        else if (result.durationMs != null && fc.duration < result.durationMs) {
+            log(`  note: frame duration ${fc.duration}ms < template play time ${result.durationMs}ms — the template will be cut off; size duration to ≈ ${result.durationMs}ms`);
+        }
+        // Namespace the template's document-global names (ids, font families, frame
+        // classes, @keyframes, --scene-dur) with a per-frame token so they can't
+        // collide with the outer animation or sibling template frames once nested
+        // into one document (a template is a full `generateAnimatedSvg` SVG, and
+        // SVG/CSS names are document-global, not scoped to a nested `<svg>`).
+        let content = namespaceEmbeddedAnimatedSvg(result.svg, `tf${i}_`);
+        // Strip the XML prolog so the `<svg>` nests cleanly in the animator's frame
+        // group (same as a `cast` frame). Center within the canvas when smaller.
+        content = content.replace(/^<\?xml[^>]*\?>\s*/, "");
+        content = placeEmbeddedFrame(content, result.width, result.height, cfg.width, cfg.height, fit);
+        out.set(i, content);
+    }
+    return out;
+}
 export async function composeAnimateFrames(browser, cfg, configDirOrOpts, logArg) {
     const { configDir, log, onFrame } = normalizeComposeArgs(configDirOrOpts, logArg);
     // DM-852: resolve `${vars}` across every string field before anything runs.
     cfg = interpolateConfigVars(cfg);
+    // DM-1287 (doc 73): render `template` frames UP FRONT, before the outer run's
+    // font lifecycle (clearWebfonts / clearEmbeddedFonts) starts below. A template
+    // is itself a front-end onto `composeAnimateConfig`, so rendering one runs a
+    // NESTED `composeAnimateFrames` that clears + manages the module-global font
+    // builders. Doing it here — before the outer clears — keeps each template's
+    // output fully self-contained (its own `@font-face`) and stops the nested run
+    // from clobbering the outer frames' embedded fonts. Each rendered template SVG
+    // is a finished string by the time the outer loop reaches its frame.
+    const templateRenders = await renderTemplateFrames(cfg, browser, log);
     const ctx = await browser.newContext({
         viewport: { width: cfg.width, height: cfg.height },
         isMobile: cfg.mobile === true,
@@ -482,7 +657,19 @@ export async function composeAnimateFrames(browser, cfg, configDirOrOpts, logArg
                 if (fc.duration < totalDurationMs) {
                     log(`  note: frame duration ${fc.duration}ms < cast play time ${totalDurationMs}ms — the terminal will be cut off; size duration to ≈ ${totalDurationMs}ms`);
                 }
-                const termSvg = castSvg;
+                // DM-1292: the cast SVG is a full `generateAnimatedSvg` document, so its
+                // document-global names (ids, `.f-N` frame classes + `@keyframes fv-N` in
+                // `mode: "full"`, the incremental `ln…` / `tcur…` keyframes, `--scene-dur`)
+                // collide with the outer animation's identical names, or with a sibling
+                // cast frame's, once concatenated — a duplicate `@keyframes`/rule wins
+                // globally and hijacks the wrong frame's timeline (visible when the
+                // timeline is SEEKED, like the DM-1145 id-collision bug). Namespace them
+                // with a per-frame token, exactly like a `template` frame. Fonts are the
+                // ONE exception: `manageFonts: false` defers them to this pipeline's shared
+                // embedded-font builder (one `@font-face` block, already-unique `dmfN`
+                // names) collected after the loop, so we must NOT prefix the cast's
+                // `font-family` references or they'd dangle.
+                const termSvg = namespaceEmbeddedAnimatedSvg(castSvg, `cf${i}_`, { namespaceFonts: false });
                 // The animator wraps `svgContent` in `<g class="f f-N">`, which holds a
                 // nested `<svg>` fine — strip just the XML prolog (same as scroll).
                 frames.push({
@@ -496,6 +683,20 @@ export async function composeAnimateFrames(browser, cfg, configDirOrOpts, logArg
                 frameTrees.push(null);
                 continue;
             }
+            // DM-1287 (doc 73): a `template` frame embeds a named template's output,
+            // pre-rendered above into a finished (self-contained, possibly animated)
+            // SVG string. Nest it exactly like a `cast` frame.
+            if (fc.template != null) {
+                log(`Frame ${i + 1}/${cfg.frames.length}: embedding template "${fc.template}"…`);
+                frames.push({
+                    svgContent: templateRenders.get(i),
+                    duration: fc.duration,
+                    transition: fc.transition,
+                });
+                prevFrameTree = null;
+                frameTrees.push(null);
+                continue;
+            }
             // DM-846 §1: a continued frame (explicit `continue: true`, or a non-first
             // frame that omits `input`) captures the previous frame's live page after
             // running its own actions, instead of reloading. The page persists across
@@ -575,6 +776,7 @@ export async function composeAnimateFrames(browser, cfg, configDirOrOpts, logArg
                         delay: a.delay,
                         repeat: a.repeat,
                         alternate: a.alternate,
+                        transformOrigin: a.transformOrigin,
                     });
                 }
             }