From 303620211e3b0e2210d3e0bbb9c20764a0875135 Mon Sep 17 00:00:00 2001
From: Metbcy <Amirbredy1@gmail.com>
Date: Sat, 9 May 2026 22:00:48 +0000
Subject: [PATCH 1/4] feat(scene): add --lottie overlay support to vibe scene
 add

Wire --lottie <path>, --lottie-position, --lottie-scale,
--lottie-opacity, and --lottie-no-loop flags into the scene add
command. When supplied, the Lottie file is copied into assets/ and a
<dotlottie-wc> web component is layered on top of the selected
preset's content.

Position/scale/opacity vocabulary mirrors vibe edit motion-overlay
so users and agents get consistent behavior across both paths.

Closes #208 (scene helper milestone).
---
 .../src/commands/_shared/scene-html-emit.ts   | 109 +++++++++++++++++-
 packages/cli/src/commands/scene.ts            |  67 ++++++++++-
 2 files changed, 173 insertions(+), 3 deletions(-)

diff --git a/packages/cli/src/commands/_shared/scene-html-emit.ts b/packages/cli/src/commands/_shared/scene-html-emit.ts
index 540dbf38..cfaeef6f 100644
--- a/packages/cli/src/commands/_shared/scene-html-emit.ts
+++ b/packages/cli/src/commands/_shared/scene-html-emit.ts
@@ -41,6 +41,40 @@ export interface SceneTranscriptWord {
   end: number;
 }
 
+/**
+ * Position value for Lottie overlays. Mirrors the vocabulary used by
+ * `vibe edit motion-overlay --position`.
+ */
+export type LottiePosition =
+  | "full"
+  | "center"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+
+export const LOTTIE_POSITIONS: readonly LottiePosition[] = [
+  "full",
+  "center",
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right",
+] as const;
+
+export interface LottieOverlayInput {
+  /** Project-relative path to the `.json` or `.lottie` file (e.g. "assets/logo.lottie"). */
+  src: string;
+  /** Overlay position. Defaults to "full". */
+  position?: LottiePosition;
+  /** Scale factor (0.01-2). Defaults to 1. */
+  scale?: number;
+  /** Opacity (0-1). Defaults to 1. */
+  opacity?: number;
+  /** Whether the animation loops. Defaults to true. */
+  loop?: boolean;
+}
+
 export interface EmitSceneInput {
   /** Kebab-case scene id; appears in `data-composition-id` and template id. */
   id: string;
@@ -69,6 +103,12 @@ export interface EmitSceneInput {
    * their headlines are intentionally static.
    */
   transcript?: SceneTranscriptWord[];
+  /**
+   * Optional Lottie animation overlay. When supplied, a `<dotlottie-wc>`
+   * element is layered on top of the preset's content. Uses the same
+   * position/scale/opacity vocabulary as `vibe edit motion-overlay`.
+   */
+  lottie?: LottieOverlayInput;
 }
 
 const GSAP_CDN = "https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js";
@@ -534,6 +574,67 @@ function buildPreset(input: Required<Pick<EmitSceneInput, "id" | "preset" | "dur
   }
 }
 
+// ---------------------------------------------------------------------------
+// Lottie overlay layer
+// ---------------------------------------------------------------------------
+
+const DOTLOTTIE_WC_CDN =
+  "https://cdn.jsdelivr.net/npm/@nicepkg/dotlottie-wc@0.5.0/dist/index.js";
+
+/**
+ * Build inline style for a positioned Lottie overlay. Mirrors the logic
+ * in `html-clips.ts → lottieInnerStyle()` so the visual result is
+ * identical to `vibe edit motion-overlay`.
+ */
+function lottieOverlayStyle(input: LottieOverlayInput): string {
+  const pos = input.position ?? "full";
+  const scale = input.scale ?? 1;
+  const opacity = input.opacity ?? 1;
+
+  const base = [
+    "position:absolute",
+    "pointer-events:none",
+    `opacity:${opacity}`,
+  ];
+
+  if (pos === "full") {
+    base.push("inset:0", "width:100%", "height:100%");
+  } else {
+    const pct = Math.round(scale * 100);
+    base.push(`width:${pct}%`, `height:${pct}%`);
+    switch (pos) {
+      case "center":
+        base.push("top:50%", "left:50%", "transform:translate(-50%,-50%)");
+        break;
+      case "top-left":
+        base.push("top:4%", "left:4%");
+        break;
+      case "top-right":
+        base.push("top:4%", "right:4%");
+        break;
+      case "bottom-left":
+        base.push("bottom:4%", "left:4%");
+        break;
+      case "bottom-right":
+        base.push("bottom:4%", "right:4%");
+        break;
+    }
+  }
+  return base.join(";");
+}
+
+/**
+ * Build the `<dotlottie-wc>` markup + module script for a Lottie overlay
+ * layer. Returns `{ markup, script }` to splice into the scene template.
+ */
+function buildLottieOverlay(input: LottieOverlayInput): { markup: string; script: string } {
+  const loop = (input.loop ?? true) ? " loop" : "";
+  const style = lottieOverlayStyle(input);
+  const markup = `<dotlottie-wc id="lottie-overlay" src="${esc(input.src)}" autoplay${loop} style="${style}"></dotlottie-wc>`;
+  const script = `<script type="module" src="${DOTLOTTIE_WC_CDN}"></script>`;
+  return { markup, script };
+}
+
 /**
  * Emit the full per-scene HTML. Returns a complete `<template>`-wrapped
  * composition ready to write to `compositions/scene-<id>.html`.
@@ -561,15 +662,19 @@ export function emitSceneHtml(input: EmitSceneInput): string {
     ></audio>\n`
     : "";
 
+  const lottieLayer = input.lottie ? buildLottieOverlay(input.lottie) : null;
+  const lottieMarkup = lottieLayer ? `\n    ${lottieLayer.markup}` : "";
+  const lottieScript = lottieLayer ? `\n    ${lottieLayer.script}` : "";
+
   return `<template id="scene-${id}-template">
   <div data-composition-id="${id}" data-start="0" data-duration="${dur}" data-width="${input.width}" data-height="${input.height}">
     <style>
       ${parts.css}
     </style>
 
-    ${parts.body}
+    ${parts.body}${lottieMarkup}
 ${audioBlock}
-    <script src="${GSAP_CDN}"></script>
+    <script src="${GSAP_CDN}"></script>${lottieScript}
     <script>
       window.__timelines = window.__timelines || {};
       const tl = gsap.timeline({ paused: true });
diff --git a/packages/cli/src/commands/scene.ts b/packages/cli/src/commands/scene.ts
index 91a7b9b9..9fc769bf 100644
--- a/packages/cli/src/commands/scene.ts
+++ b/packages/cli/src/commands/scene.ts
@@ -42,7 +42,10 @@ import {
   slugifySceneName,
   SCENE_PRESETS,
   SCENE_OVERLAP_SECONDS,
+  LOTTIE_POSITIONS,
   type ScenePreset,
+  type LottiePosition,
+  type LottieOverlayInput,
 } from "./_shared/scene-html-emit.js";
 import { runProjectLint, rootExists, type ProjectLintResult } from "./_shared/scene-lint.js";
 // `executeSceneRender` and `executeSceneBuild` are no longer wired into
@@ -418,10 +421,29 @@ sceneCommand
   )
   .option("--transcribe-language <code>", "BCP-47 language code passed to Whisper (e.g. en, ko)")
   .option("--force", "Overwrite an existing compositions/scene-<id>.html")
+  .option("--lottie <path>", "Lottie animation file (.json/.lottie) to overlay on the scene")
+  .option(
+    "--lottie-position <position>",
+    "Lottie position: full, center, top-left, top-right, bottom-left, bottom-right",
+    "full"
+  )
+  .option("--lottie-scale <number>", "Lottie overlay scale (0.01-2)")
+  .option("--lottie-opacity <number>", "Lottie overlay opacity (0-1)", "1")
+  .option("--lottie-no-loop", "Do not loop the Lottie animation")
   .option("--dry-run", "Preview parameters without writing files or calling APIs")
   .action(async (name: string, options) => {
     const startedAt = Date.now();
     if (options.style) options.style = validatePreset(options.style);
+    if (options.lottiePosition) {
+      const validPositions = ["full", "center", "top-left", "top-right", "bottom-left", "bottom-right"];
+      if (!validPositions.includes(options.lottiePosition)) {
+        exitWithError(
+          usageError(
+            `Invalid --lottie-position "${options.lottiePosition}". Valid: ${validPositions.join(", ")}`
+          )
+        );
+      }
+    }
     if (options.duration !== undefined) options.duration = validateDuration(options.duration);
     let tts: TtsProviderName;
     try {
@@ -450,7 +472,9 @@ sceneCommand
             insertInto: options.insertInto,
             imageProvider: options.imageProvider,
             tts,
-            audio: options.audio, // commander sets `audio: false` when --no-audio is passed
+            audio: options.audio,
+            lottie: options.lottie ?? null,
+            lottiePosition: options.lottiePosition,
             image: options.image,
           },
         },
@@ -480,6 +504,15 @@ sceneCommand
         skipTranscribe: options.transcribe === false,
         transcribeLanguage: options.transcribeLanguage,
         force: !!options.force,
+        lottie: options.lottie
+          ? {
+              src: options.lottie as string,
+              position: (options.lottiePosition as LottiePosition) ?? "full",
+              scale: options.lottieScale !== undefined ? Number(options.lottieScale) : undefined,
+              opacity: options.lottieOpacity !== undefined ? Number(options.lottieOpacity) : 1,
+              loop: !options.lottieNoLoop,
+            }
+          : undefined,
         onProgress: (msg) => {
           if (spinner) spinner.text = msg;
         },
@@ -573,6 +606,8 @@ export interface SceneAddOptions {
   transcribeLanguage?: string;
   /** Overwrite existing compositions/scene-<id>.html. */
   force?: boolean;
+  /** Lottie animation overlay options. */
+  lottie?: LottieOverlayInput;
   /** Progress sink (CLI spinner / agent stream). */
   onProgress?: (msg: string) => void;
 }
@@ -595,6 +630,7 @@ export interface SceneAddResult {
   transcriptPath?: string;
   /** Number of word entries emitted into the transcript JSON. */
   transcriptWordCount?: number;
+  lottiePath?: string;
   error?: string;
 }
 
@@ -872,6 +908,33 @@ export async function executeSceneAdd(opts: SceneAddOptions): Promise<SceneAddRe
     }
   }
 
+  // -- Asset: Lottie overlay ------------------------------------------------
+  let lottieRelPath: string | undefined;
+  let lottieAbsPath: string | undefined;
+  let lottieInput: LottieOverlayInput | undefined;
+
+  if (opts.lottie) {
+    const sourceAbs = resolve(opts.lottie.src);
+    if (!(await pathExists(sourceAbs))) {
+      return errResult(`Lottie file not found: ${sourceAbs}`);
+    }
+    const ext = (sourceAbs.match(/\.([a-z0-9]+)$/i)?.[1] ?? "json").toLowerCase();
+    if (ext !== "json" && ext !== "lottie") {
+      return errResult(`Unsupported Lottie file extension: .${ext}. Use .json or .lottie.`);
+    }
+    lottieRelPath = `assets/lottie-${id}.${ext}`;
+    lottieAbsPath = resolve(projectDir, lottieRelPath);
+    await mkdir(dirname(lottieAbsPath), { recursive: true });
+    await copyFile(sourceAbs, lottieAbsPath);
+    lottieInput = {
+      src: lottieRelPath,
+      position: opts.lottie.position,
+      scale: opts.lottie.scale,
+      opacity: opts.lottie.opacity,
+      loop: opts.lottie.loop,
+    };
+  }
+
   // -- Decide scene duration -----------------------------------------------
   // Scene duration must be ≥ narration audio length, otherwise the parent
   // clip's data-duration cuts the audio short. The previous heuristic
@@ -914,6 +977,7 @@ export async function executeSceneAdd(opts: SceneAddOptions): Promise<SceneAddRe
     imagePath: imageRelPath,
     audioPath: audioRelPath,
     transcript: transcriptWords,
+    lottie: lottieInput,
   });
   await mkdir(dirname(scenePath), { recursive: true });
   await writeFile(scenePath, sceneHtml, "utf-8");
@@ -945,6 +1009,7 @@ export async function executeSceneAdd(opts: SceneAddOptions): Promise<SceneAddRe
     rootPath: relative(process.cwd(), rootPath) || rootPath,
     audioPath: audioAbsPath ? relative(process.cwd(), audioAbsPath) || audioAbsPath : undefined,
     imagePath: imageAbsPath ? relative(process.cwd(), imageAbsPath) || imageAbsPath : undefined,
+    lottiePath: lottieAbsPath ? relative(process.cwd(), lottieAbsPath) || lottieAbsPath : undefined,
     transcriptPath: transcriptAbsPath
       ? relative(process.cwd(), transcriptAbsPath) || transcriptAbsPath
       : undefined,

From 06dfa06b48f052ec68b19e4a3580dc218e3b272c Mon Sep 17 00:00:00 2001
From: Metbcy <Amirbredy1@gmail.com>
Date: Sat, 9 May 2026 22:25:32 +0000
Subject: [PATCH 2/4] fix: update envelope snapshot for --lottie flags and
 remove unused import

---
 .../envelope-snapshots.test.ts.snap           | 30 +++++++++++++++++++
 packages/cli/src/commands/scene.ts            |  1 -
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/packages/cli/src/commands/__snapshots__/envelope-snapshots.test.ts.snap b/packages/cli/src/commands/__snapshots__/envelope-snapshots.test.ts.snap
index ffb53b42..f5639cfb 100644
--- a/packages/cli/src/commands/__snapshots__/envelope-snapshots.test.ts.snap
+++ b/packages/cli/src/commands/__snapshots__/envelope-snapshots.test.ts.snap
@@ -3447,6 +3447,36 @@ exports[`CLI --describe schemas (drift detection) > vibe scene add --describe 1`
         "description": "Small label above the headline (explainer / product-shot)",
         "type": "string",
       },
+      "lottie": {
+        "description": "Lottie animation file (.json/.lottie) to overlay on the scene",
+        "type": "string",
+      },
+      "lottieNoLoop": {
+        "description": "Do not loop the Lottie animation",
+        "type": "boolean",
+      },
+      "lottieOpacity": {
+        "default": 1,
+        "description": "Lottie overlay opacity (0-1)",
+        "type": "number",
+      },
+      "lottiePosition": {
+        "default": "full",
+        "description": "Lottie position: full, center, top-left, top-right, bottom-left, bottom-right",
+        "enum": [
+          "full",
+          "center",
+          "top-left",
+          "top-right",
+          "bottom-left",
+          "bottom-right",
+        ],
+        "type": "string",
+      },
+      "lottieScale": {
+        "description": "Lottie overlay scale (0.01-2)",
+        "type": "number",
+      },
       "name": {
         "description": "Scene name (slugified into the composition id)",
         "type": "string",
diff --git a/packages/cli/src/commands/scene.ts b/packages/cli/src/commands/scene.ts
index 9fc769bf..96c6b3a1 100644
--- a/packages/cli/src/commands/scene.ts
+++ b/packages/cli/src/commands/scene.ts
@@ -42,7 +42,6 @@ import {
   slugifySceneName,
   SCENE_PRESETS,
   SCENE_OVERLAP_SECONDS,
-  LOTTIE_POSITIONS,
   type ScenePreset,
   type LottiePosition,
   type LottieOverlayInput,

From 987e731f306b7458aa842439c4164edac043c767 Mon Sep 17 00:00:00 2001
From: Metbcy <Amirbredy1@gmail.com>
Date: Sat, 9 May 2026 22:31:57 +0000
Subject: [PATCH 3/4] docs: regenerate CLI reference for lottie flags

---
 docs/cli-reference.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 2e8f7439..f03bf812 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -1357,6 +1357,11 @@ Cost tier: `free`
 - `noTranscribe` _(boolean)_ — Skip Whisper word-level transcribe step (no transcript-<id>.json emitted)
 - `transcribeLanguage` _(string)_ — BCP-47 language code passed to Whisper (e.g. en, ko)
 - `force` _(boolean)_ — Overwrite an existing compositions/scene-<id>.html
+- `lottie` _(string)_ — Lottie animation file (.json/.lottie) to overlay on the scene
+- `lottiePosition` _(string)_ _(full \| center \| top-left \| top-right \| bottom-left \| bottom-right)_ _(default: `"full"`)_ — Lottie position: full, center, top-left, top-right, bottom-left, bottom-right
+- `lottieScale` _(number)_ — Lottie overlay scale (0.01-2)
+- `lottieOpacity` _(number)_ _(default: `1`)_ — Lottie overlay opacity (0-1)
+- `lottieNoLoop` _(boolean)_ — Do not loop the Lottie animation
 - `dryRun` _(boolean)_ — Preview parameters without writing files or calling APIs
 
 #### `vibe scene compose-prompts`

From ad5b4a3d7627357eee172af1294a1d68a0b42db4 Mon Sep 17 00:00:00 2001
From: Metbcy <amirbredy1@gmail.com>
Date: Sun, 17 May 2026 18:11:16 +0000
Subject: [PATCH 4/4] fix(scene): use real @lottiefiles dotlottie-wc + validate
 lottie flags

Address PR review blocker: the injected overlay script pointed at
@nicepkg/dotlottie-wc which doesn't exist on npm (404), so
<dotlottie-wc> never registered and the overlay silently never
rendered.

- swap CDN to @lottiefiles/dotlottie-wc@0.9.12 (matches package.json)
- import setWasmUrl and point it at @lottiefiles/dotlottie-web's
  dotlottie-player.wasm, mirroring pipeline/renderers/html-template.ts
  (the runtime can't render without the WASM player URL)
- mirror html-clips.ts clamps: scale [0.01, 2], opacity [0, 1]
- default non-full positions to scale 0.25 so corner overlays
  don't paint full-screen
- scope overlay id per-scene (lottie-overlay-${sceneId}) so two
  scenes with overlays don't collide on the DOM id
- validate --lottie-scale and --lottie-opacity ranges (help text
  already advertised them; only --lottie-position was validated)
- reuse LOTTIE_POSITIONS in scene.ts instead of re-listing literals
- forward lottieScale / lottieOpacity / lottieLoop in --dry-run so
  preview matches the actual run
- add 9 regression tests covering the lottie branch of
  scene-html-emit (real package, setWasmUrl, per-scene id, clamps,
  defaults, escape)
---
 .../commands/_shared/scene-html-emit.test.ts  | 112 ++++++++++++++++++
 .../src/commands/_shared/scene-html-emit.ts   |  50 ++++++--
 packages/cli/src/commands/scene.ts            |  33 +++++-
 3 files changed, 180 insertions(+), 15 deletions(-)

diff --git a/packages/cli/src/commands/_shared/scene-html-emit.test.ts b/packages/cli/src/commands/_shared/scene-html-emit.test.ts
index 678c0986..63742979 100644
--- a/packages/cli/src/commands/_shared/scene-html-emit.test.ts
+++ b/packages/cli/src/commands/_shared/scene-html-emit.test.ts
@@ -630,3 +630,115 @@ describe("emitSceneHtml — robust defaults across input variability", () => {
     }
   });
 });
+
+// ── Lottie overlay layer ────────────────────────────────────────────────────
+//
+// Regression coverage for the bug where the emit path pointed at a
+// non-existent CDN package (`@nicepkg/dotlottie-wc`), so `<dotlottie-wc>`
+// never registered and the overlay silently did not render. These tests
+// pin the loader to the real package (`@lottiefiles/dotlottie-wc`),
+// require an explicit `setWasmUrl(...)` call (the runtime needs its
+// WASM player or it 404s), and lock in the per-scene id so multiple
+// scenes with overlays don't collide.
+
+describe("emitSceneHtml — Lottie overlay layer", () => {
+  const lottieBase = {
+    ...baseInput,
+    preset: "simple" as const,
+    lottie: {
+      src: "assets/lottie-intro.json",
+      position: "full" as const,
+    },
+  };
+
+  it("renders nothing Lottie-related when no overlay is provided", () => {
+    const html = emitSceneHtml({ ...baseInput, preset: "simple" });
+    expect(html).not.toContain("dotlottie-wc");
+    expect(html).not.toContain("setWasmUrl");
+  });
+
+  it("loads the runtime from the real @lottiefiles/dotlottie-wc package on jsdelivr", () => {
+    const html = emitSceneHtml(lottieBase);
+    // The custom element + a module script that registers it must both ship.
+    expect(html).toContain("<dotlottie-wc");
+    expect(html).toContain('src="assets/lottie-intro.json"');
+    expect(html).toContain("@lottiefiles/dotlottie-wc");
+    // Guard against regression to the broken package name.
+    expect(html).not.toContain("@nicepkg/dotlottie-wc");
+    // Pinned version must track packages/cli/package.json (^0.9.12).
+    expect(html).toMatch(/@lottiefiles\/dotlottie-wc@0\.9\.\d+/);
+  });
+
+  it("calls setWasmUrl with the dotlottie-web WASM URL so the player can render", () => {
+    const html = emitSceneHtml(lottieBase);
+    expect(html).toContain("setWasmUrl");
+    expect(html).toContain("@lottiefiles/dotlottie-web");
+    expect(html).toMatch(/dotlottie-web@0\.71\.\d+\/dist\/dotlottie-player\.wasm/);
+  });
+
+  it("scopes the overlay id per scene to avoid collisions between scenes", () => {
+    const a = emitSceneHtml({ ...lottieBase, id: "intro" });
+    const b = emitSceneHtml({ ...lottieBase, id: "outro" });
+    expect(a).toContain('id="lottie-overlay-intro"');
+    expect(b).toContain('id="lottie-overlay-outro"');
+    // No leftover unscoped id from the original implementation.
+    expect(a).not.toContain('id="lottie-overlay"');
+  });
+
+  it("emits autoplay + loop by default and drops loop when loop:false", () => {
+    const looping = emitSceneHtml(lottieBase);
+    expect(looping).toMatch(/<dotlottie-wc[^>]*\sautoplay\s+loop\b/);
+
+    const oneShot = emitSceneHtml({
+      ...lottieBase,
+      lottie: { ...lottieBase.lottie, loop: false },
+    });
+    expect(oneShot).toMatch(/<dotlottie-wc[^>]*\sautoplay\b/);
+    expect(oneShot).not.toMatch(/<dotlottie-wc[^>]*\sloop\b/);
+  });
+
+  it("defaults non-full positions to scale 0.25 (matches html-clips.ts)", () => {
+    const html = emitSceneHtml({
+      ...lottieBase,
+      lottie: { src: "assets/x.json", position: "bottom-right" },
+    });
+    // Default corner scale is 0.25 → 25% width/height (not 100% as the prior bug emitted).
+    expect(html).toContain("width:25%");
+    expect(html).toContain("height:25%");
+  });
+
+  it("full position ignores scale and fills the scene", () => {
+    const html = emitSceneHtml({
+      ...lottieBase,
+      lottie: { src: "assets/x.json", position: "full", scale: 0.5 },
+    });
+    expect(html).toContain("inset:0");
+    expect(html).toContain("width:100%");
+    expect(html).toContain("height:100%");
+  });
+
+  it("clamps scale to [0.01, 2] and opacity to [0, 1]", () => {
+    const overscale = emitSceneHtml({
+      ...lottieBase,
+      lottie: { src: "assets/x.json", position: "top-left", scale: 5, opacity: 5 },
+    });
+    expect(overscale).toContain("width:200%");
+    expect(overscale).toContain("opacity:1");
+
+    const underscale = emitSceneHtml({
+      ...lottieBase,
+      lottie: { src: "assets/x.json", position: "top-left", scale: -1, opacity: -1 },
+    });
+    expect(underscale).toContain("width:1%");
+    expect(underscale).toContain("opacity:0");
+  });
+
+  it("escapes the lottie src to prevent HTML injection via the file path", () => {
+    const html = emitSceneHtml({
+      ...lottieBase,
+      lottie: { src: 'evil"><script>alert(1)</script>', position: "full" },
+    });
+    expect(html).not.toContain("<script>alert(1)");
+    expect(html).toContain("&quot;");
+  });
+});
diff --git a/packages/cli/src/commands/_shared/scene-html-emit.ts b/packages/cli/src/commands/_shared/scene-html-emit.ts
index cfaeef6f..f1d72922 100644
--- a/packages/cli/src/commands/_shared/scene-html-emit.ts
+++ b/packages/cli/src/commands/_shared/scene-html-emit.ts
@@ -578,18 +578,35 @@ function buildPreset(input: Required<Pick<EmitSceneInput, "id" | "preset" | "dur
 // Lottie overlay layer
 // ---------------------------------------------------------------------------
 
-const DOTLOTTIE_WC_CDN =
-  "https://cdn.jsdelivr.net/npm/@nicepkg/dotlottie-wc@0.5.0/dist/index.js";
+// `@lottiefiles/dotlottie-wc` is the real package used by the pipeline
+// renderer (see `pipeline/renderers/html-template.ts` + `project-builder.ts`).
+// The scene-emit path can't vendor the runtime into the project dir without
+// adding an asset-copy step to `executeSceneAdd`, so we load it from
+// jsdelivr the same way we load GSAP. The WASM URL must be set explicitly
+// because dotLottie's web component otherwise tries to fetch the WASM
+// from a path relative to the importing module — which would 404 on the
+// jsdelivr CDN (the WASM lives in the sibling `@lottiefiles/dotlottie-web`
+// package, not in `dotlottie-wc/dist/`).
+const DOTLOTTIE_WC_VERSION = "0.9.12";
+const DOTLOTTIE_WEB_VERSION = "0.71.0";
+const DOTLOTTIE_WC_CDN = `https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-wc@${DOTLOTTIE_WC_VERSION}/dist/index.js`;
+const DOTLOTTIE_WASM_CDN = `https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web@${DOTLOTTIE_WEB_VERSION}/dist/dotlottie-player.wasm`;
 
 /**
  * Build inline style for a positioned Lottie overlay. Mirrors the logic
  * in `html-clips.ts → lottieInnerStyle()` so the visual result is
  * identical to `vibe edit motion-overlay`.
+ *
+ * Defaults match `html-clips.ts`:
+ *   - scale defaults to 1 for `full`, 0.25 for any other position
+ *   - opacity defaults to 1
+ *   - scale is clamped to [0.01, 2], opacity to [0, 1]
  */
 function lottieOverlayStyle(input: LottieOverlayInput): string {
   const pos = input.position ?? "full";
-  const scale = input.scale ?? 1;
-  const opacity = input.opacity ?? 1;
+  const rawScale = input.scale ?? (pos === "full" ? 1 : 0.25);
+  const scale = Math.max(0.01, Math.min(2, rawScale));
+  const opacity = Math.max(0, Math.min(1, input.opacity ?? 1));
 
   const base = [
     "position:absolute",
@@ -600,7 +617,7 @@ function lottieOverlayStyle(input: LottieOverlayInput): string {
   if (pos === "full") {
     base.push("inset:0", "width:100%", "height:100%");
   } else {
-    const pct = Math.round(scale * 100);
+    const pct = scale * 100;
     base.push(`width:${pct}%`, `height:${pct}%`);
     switch (pos) {
       case "center":
@@ -626,12 +643,27 @@ function lottieOverlayStyle(input: LottieOverlayInput): string {
 /**
  * Build the `<dotlottie-wc>` markup + module script for a Lottie overlay
  * layer. Returns `{ markup, script }` to splice into the scene template.
+ *
+ * The script imports the web component module and calls `setWasmUrl(...)`
+ * with an explicit CDN URL so the dotLottie runtime can locate its WASM
+ * player. Without this call, the WASM fetch fails and the overlay never
+ * paints. See the equivalent setup in
+ * `pipeline/renderers/html-template.ts` (which vendors the runtime
+ * locally for the producer-served pipeline path).
  */
-function buildLottieOverlay(input: LottieOverlayInput): { markup: string; script: string } {
+function buildLottieOverlay(
+  input: LottieOverlayInput,
+  sceneId: string,
+): { markup: string; script: string } {
   const loop = (input.loop ?? true) ? " loop" : "";
   const style = lottieOverlayStyle(input);
-  const markup = `<dotlottie-wc id="lottie-overlay" src="${esc(input.src)}" autoplay${loop} style="${style}"></dotlottie-wc>`;
-  const script = `<script type="module" src="${DOTLOTTIE_WC_CDN}"></script>`;
+  // Per-scene id avoids DOM-id collisions when multiple scenes carry overlays.
+  const overlayId = `lottie-overlay-${sceneId}`;
+  const markup = `<dotlottie-wc id="${overlayId}" src="${esc(input.src)}" autoplay${loop} style="${style}"></dotlottie-wc>`;
+  const script = `<script type="module">
+      import { setWasmUrl } from "${DOTLOTTIE_WC_CDN}";
+      setWasmUrl("${DOTLOTTIE_WASM_CDN}");
+    </script>`;
   return { markup, script };
 }
 
@@ -662,7 +694,7 @@ export function emitSceneHtml(input: EmitSceneInput): string {
     ></audio>\n`
     : "";
 
-  const lottieLayer = input.lottie ? buildLottieOverlay(input.lottie) : null;
+  const lottieLayer = input.lottie ? buildLottieOverlay(input.lottie, id) : null;
   const lottieMarkup = lottieLayer ? `\n    ${lottieLayer.markup}` : "";
   const lottieScript = lottieLayer ? `\n    ${lottieLayer.script}` : "";
 
diff --git a/packages/cli/src/commands/scene.ts b/packages/cli/src/commands/scene.ts
index 96c6b3a1..2776686a 100644
--- a/packages/cli/src/commands/scene.ts
+++ b/packages/cli/src/commands/scene.ts
@@ -42,6 +42,7 @@ import {
   slugifySceneName,
   SCENE_PRESETS,
   SCENE_OVERLAP_SECONDS,
+  LOTTIE_POSITIONS,
   type ScenePreset,
   type LottiePosition,
   type LottieOverlayInput,
@@ -423,7 +424,7 @@ sceneCommand
   .option("--lottie <path>", "Lottie animation file (.json/.lottie) to overlay on the scene")
   .option(
     "--lottie-position <position>",
-    "Lottie position: full, center, top-left, top-right, bottom-left, bottom-right",
+    `Lottie position: ${LOTTIE_POSITIONS.join(", ")}`,
     "full"
   )
   .option("--lottie-scale <number>", "Lottie overlay scale (0.01-2)")
@@ -434,15 +435,32 @@ sceneCommand
     const startedAt = Date.now();
     if (options.style) options.style = validatePreset(options.style);
     if (options.lottiePosition) {
-      const validPositions = ["full", "center", "top-left", "top-right", "bottom-left", "bottom-right"];
-      if (!validPositions.includes(options.lottiePosition)) {
+      if (!LOTTIE_POSITIONS.includes(options.lottiePosition as LottiePosition)) {
         exitWithError(
           usageError(
-            `Invalid --lottie-position "${options.lottiePosition}". Valid: ${validPositions.join(", ")}`
+            `Invalid --lottie-position "${options.lottiePosition}". Valid: ${LOTTIE_POSITIONS.join(", ")}`
           )
         );
       }
     }
+    let lottieScale: number | undefined;
+    if (options.lottieScale !== undefined) {
+      lottieScale = Number(options.lottieScale);
+      if (!Number.isFinite(lottieScale) || lottieScale < 0.01 || lottieScale > 2) {
+        exitWithError(
+          usageError(`Invalid --lottie-scale "${options.lottieScale}". Must be between 0.01 and 2.`)
+        );
+      }
+    }
+    let lottieOpacity = 1;
+    if (options.lottieOpacity !== undefined) {
+      lottieOpacity = Number(options.lottieOpacity);
+      if (!Number.isFinite(lottieOpacity) || lottieOpacity < 0 || lottieOpacity > 1) {
+        exitWithError(
+          usageError(`Invalid --lottie-opacity "${options.lottieOpacity}". Must be between 0 and 1.`)
+        );
+      }
+    }
     if (options.duration !== undefined) options.duration = validateDuration(options.duration);
     let tts: TtsProviderName;
     try {
@@ -474,6 +492,9 @@ sceneCommand
             audio: options.audio,
             lottie: options.lottie ?? null,
             lottiePosition: options.lottiePosition,
+            lottieScale: lottieScale ?? null,
+            lottieOpacity: options.lottieOpacity !== undefined ? lottieOpacity : null,
+            lottieLoop: !options.lottieNoLoop,
             image: options.image,
           },
         },
@@ -507,8 +528,8 @@ sceneCommand
           ? {
               src: options.lottie as string,
               position: (options.lottiePosition as LottiePosition) ?? "full",
-              scale: options.lottieScale !== undefined ? Number(options.lottieScale) : undefined,
-              opacity: options.lottieOpacity !== undefined ? Number(options.lottieOpacity) : 1,
+              scale: lottieScale,
+              opacity: options.lottieOpacity !== undefined ? lottieOpacity : 1,
               loop: !options.lottieNoLoop,
             }
           : undefined,