feat(scene): add --lottie overlay support to vibe scene add

[Metbcy]

What

Adds Lottie animation overlay support to vibe scene add, closing the "scene helper" milestone of #208.

New CLI flags

Flag	Description	Default
--lottie <path>	Path to a .json or .lottie animation file	-
--lottie-position <pos>	full, center, top-left, top-right, bottom-left, bottom-right	full
--lottie-scale <n>	Scale factor (0.01-2)	1
--lottie-opacity <n>	Opacity (0-1)	1
--lottie-no-loop	Play once instead of looping	loops by default

How it works

1. The Lottie file is copied into assets/lottie-<scene-id>.<ext>
2. A <dotlottie-wc> web component (loaded from CDN) is layered on top of whatever preset is selected
3. Position/scale/opacity vocabulary mirrors vibe edit motion-overlay so behavior is consistent across both paths

Example

vibe scene add "intro" \
  --lottie assets/logo-spin.json \
  --lottie-position center \
  --lottie-scale 0.5 \
  --lottie-opacity 0.8

Files changed

• packages/cli/src/commands/_shared/scene-html-emit.ts: New types (LottiePosition, LottieOverlayInput), overlay style builder, <dotlottie-wc> markup emitter, wired into emitSceneHtml()
• packages/cli/src/commands/scene.ts: CLI flags, validation, asset copy, result surface

Refs #208

[vercel]

@Metbcy is attempting to deploy a commit to the Kiyeon Jeon's projects Team on Vercel.

A member of the Team first needs to authorize it.

[kiyeonjeon21]

Thanks for picking this up — the CLI surface and the scene-html-emit wiring look reasonable, but there's a blocker in how the runtime is loaded.

Blocker — the overlay won't render

The injected script points at @nicepkg/dotlottie-wc:

https://cdn.jsdelivr.net/npm/@nicepkg/dotlottie-wc@0.5.0/dist/index.js

That package doesn't exist on npm (404), so the URL is dead and <dotlottie-wc> never gets registered — the overlay just silently doesn't render. The component we already use is @lottiefiles/dotlottie-wc, which is a dependency in packages/cli/package.json.

Have a look at how the pipeline renderer handles this in pipeline/renderers/html-template.ts and project-builder.ts: it vendors the @lottiefiles/dotlottie-wc runtime and calls setWasmUrl(...), since dotLottie needs its WASM player to render. The scene path does load GSAP from jsdelivr, so a CDN load isn't off the table here — but it has to be the real package and the WASM has to resolve.

It'd also be good to add a test that exercises the emit path. scene-html-emit.test.ts has nothing for the lottie branch, which is why CI stayed green despite the dead URL.

Smaller things

• --lottie-scale (0.01–2) and --lottie-opacity (0–1) advertise ranges in the help text but aren't validated — only --lottie-position is. lottieOverlayParams in html-clips.ts clamps both with Math.max/min; worth mirroring.
• Non-full positions default scale to 1, so --lottie-position bottom-right with no --lottie-scale paints a 100%-size overlay in the corner. The existing helper defaults non-full positions to 0.25.
• The --dry-run params object in scene.ts only forwards lottie and lottiePosition — lottieScale / lottieOpacity / lottieNoLoop are dropped from the preview.
• Minor: scene.ts re-lists the position values as a literal array — you already export LOTTIE_POSITIONS, so reuse it. And id="lottie-overlay" is hardcoded, so two scenes with overlays would collide on the id.

[Metbcy]

Thanks for picking this up — the CLI surface and the scene-html-emit wiring look reasonable, but there's a blocker in how the runtime is loaded.

Blocker — the overlay won't render

The injected script points at @nicepkg/dotlottie-wc:

https://cdn.jsdelivr.net/npm/@nicepkg/dotlottie-wc@0.5.0/dist/index.js

That package doesn't exist on npm (404), so the URL is dead and <dotlottie-wc> never gets registered — the overlay just silently doesn't render. The component we already use is @lottiefiles/dotlottie-wc, which is a dependency in packages/cli/package.json.

Have a look at how the pipeline renderer handles this in pipeline/renderers/html-template.ts and project-builder.ts: it vendors the @lottiefiles/dotlottie-wc runtime and calls setWasmUrl(...), since dotLottie needs its WASM player to render. The scene path does load GSAP from jsdelivr, so a CDN load isn't off the table here — but it has to be the real package and the WASM has to resolve.

It'd also be good to add a test that exercises the emit path. scene-html-emit.test.ts has nothing for the lottie branch, which is why CI stayed green despite the dead URL.

Smaller things

• --lottie-scale (0.01–2) and --lottie-opacity (0–1) advertise ranges in the help text but aren't validated — only --lottie-position is. lottieOverlayParams in html-clips.ts clamps both with Math.max/min; worth mirroring.
• Non-full positions default scale to 1, so --lottie-position bottom-right with no --lottie-scale paints a 100%-size overlay in the corner. The existing helper defaults non-full positions to 0.25.
• The --dry-run params object in scene.ts only forwards lottie and lottiePosition — lottieScale / lottieOpacity / lottieNoLoop are dropped from the preview.
• Minor: scene.ts re-lists the position values as a literal array — you already export LOTTIE_POSITIONS, so reuse it. And id="lottie-overlay" is hardcoded, so two scenes with overlays would collide on the id.

Thanks for the context, I'll see if I can have the bigger blockers resolved soon.

[Metbcy]

Thanks for the careful review. Pushed ad5b4a3 to address everything:

Blocker — swapped to @lottiefiles/dotlottie-wc@0.9.12 (matches packages/cli/package.json) and added the setWasmUrl call pointing at @lottiefiles/dotlottie-web@0.71.0/dist/dotlottie-player.wasm, mirroring how pipeline/renderers/html-template.ts wires it.

Smaller things

• --lottie-scale and --lottie-opacity now validated with the same exit-on-error pattern as --lottie-position.
• Non-full positions now default to scale 0.25 (matches lottieOverlayParams in html-clips.ts).
• --dry-run params forward lottieScale / lottieOpacity / lottieLoop.
• scene.ts reuses the exported LOTTIE_POSITIONS constant.
• Overlay id is now per-scene (lottie-overlay-${sceneId}) so multi-scene overlays don't collide.

Tests — added a Lottie overlay layer block to scene-html-emit.test.ts (9 cases) covering the real package name, setWasmUrl invocation, per-scene id, autoplay/loop defaults, scale/opacity clamps, full-vs-corner behavior, and src escape. Locks in the regression so CI would catch the dead-URL bug next time.

[kiyeonjeon21]

Verified the follow-up commit. The Lottie runtime now points at the real @LottieFiles package, sets the WASM URL explicitly, validates the new flags, preserves the corner default scale, includes dry-run params, and adds regression coverage for the emit path. I also checked the package versions and tested this on top of current main with focused scene tests plus build.

The remaining Vercel failure is an authorization issue, not a code issue.