@vibeframe/cli 0.57.3 → 0.58.0

package/dist/index.js

@@ -25611,6 +25611,70 @@ function buildEmptyRootHtml(opts) {
 </html>
 `;
 }
+function buildDesignMd(opts) {
+  const { name, style } = opts;
+  const intro = style ? `Visual identity for **${name}**, scaffolded from the **${style.name}** style (after ${style.designer}). Customise freely \u2014 this file is the single source of truth for every scene's palette, typography, and motion.` : `Visual identity for **${name}**. Fill the sections below before authoring any scene HTML or generating any backdrop. Pick a named style with \`vibe scene styles\` if you want a credible starting point.`;
+  const moodLine = style ? `**Mood:** ${style.mood} \xB7 **Best for:** ${style.bestFor}` : `**Mood:** _(one line \u2014 what should the viewer FEEL?)_`;
+  const palette = style ? `${style.palette.map((c) => `- \`${c}\``).join("\n")}
+
+${style.paletteNotes}` : `- _hex_ \u2014 primary
+- _hex_ \u2014 accent
+
+_2\u20133 colours max. Declare explicit hex values; never name colours abstractly._`;
+  const typography = style ? style.typography : `_One family, two weights. State the role of each (headline / label / body)._`;
+  const composition = style ? style.composition : `_Grid? Centered? Layered? How does negative space behave?_`;
+  const motion = style ? `${style.motion}
+
+**GSAP signature:** ${style.gsapSignature}` : `_How fast? Snappy or fluid? Overshoot or precision?_
+
+**GSAP signature:** _e.g. \`expo.out\`, \`sine.inOut\`, \`back.out(1.8)\`_`;
+  const transition = style ? style.transition : `_Which Hyperframes shader matches the energy? (Cinematic Zoom, Cross-Warp Morph, Glitch, Domain Warp, \u2026)_`;
+  const avoid = style ? style.avoid.map((a) => `- ${a}`).join("\n") : `- _anti-pattern 1_
+- _anti-pattern 2_
+- _anti-pattern 3_`;
+  return `# ${name} \u2014 Design
+
+> **Hard-gate.** This file defines the visual identity of every scene.
+> Author it before generating any HTML, backdrop image, or motion.
+> The Hyperframes \`hyperframes\` skill enforces this: scenes that
+> contradict DESIGN.md are rejected.
+
+${intro}
+
+## Style
+
+${moodLine}
+
+## Palette
+
+${palette}
+
+## Typography
+
+${typography}
+
+## Composition
+
+${composition}
+
+## Motion
+
+${motion}
+
+## Transition
+
+${transition}
+
+## What NOT to do
+
+${avoid}
+
+---
+
+_Browse other named styles: \`vibe scene styles\`_
+${style ? `_This file was seeded by \`vibe scene init --visual-style "${style.name}"\`._` : `_Seed this file from a named style: \`vibe scene init <dir> --visual-style "<name>"\`._`}
+`;
+}
 function buildProjectClaudeMd(name) {
   return `# ${name} \u2014 Scene Authoring Project
 
@@ -25618,6 +25682,16 @@ This project is **bilingual**: it works with both VibeFrame (\`vibe\`) and
 HeyGen Hyperframes (\`hyperframes\`). You can run either CLI inside this
 directory.
 
+## Visual identity hard-gate
+
+**Author \`DESIGN.md\` before any scene HTML.** It defines palette,
+typography, motion, and transition rules. Both the agent-driven path and
+the fallback emit reference it; scenes that contradict DESIGN.md are
+rejected by the Hyperframes \`hyperframes\` skill.
+
+Browse named styles: \`vibe scene styles\`. Re-seed from one with
+\`vibe scene init . --visual-style "Swiss Pulse"\` (idempotent).
+
 ## Skills \u2014 USE THESE FIRST
 
 **Always invoke the relevant skill before authoring scenes.** Skills encode
@@ -25626,14 +25700,23 @@ semantics, VibeFrame pipeline conventions) that are NOT in generic web docs.
 
 | Skill             | Command          | When to use                                                                           |
 | ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
-| **vibe-scene**    | \`/vibe-scene\`    | Authoring / editing per-scene HTML in this project \u2014 preferred                        |
-| **hyperframes**   | \`/hyperframes\`   | Fallback: direct HF authoring (install via \`npx skills add heygen-com/hyperframes\`) |
+| **hyperframes**   | \`/hyperframes\`   | Cinematic-quality composition \u2014 DESIGN.md hard-gate, named styles, motion principles  |
+| **vibe-scene**    | \`/vibe-scene\`    | VibeFrame's authoring loop, AI assets, lint feedback, pipeline integration            |
 | **gsap**          | \`/gsap\`          | GSAP tweens, timelines, easing                                                        |
 
-If the skill is not available, follow the **Key Rules** below.
+Install the Hyperframes skills once per machine:
+
+\`\`\`bash
+npx skills add heygen-com/hyperframes
+\`\`\`
+
+Restart your agent session (or reload the skill list) after installing.
+If skills aren't available, follow the **Key Rules** below \u2014 they cover
+the framework-level minimum, not the cinematic craft layer.
 
 ## Project structure
 
+- \`DESIGN.md\` \u2014 visual identity contract (palette, type, motion, transitions)
 - \`index.html\` \u2014 root composition (timeline)
 - \`compositions/scene-*.html\` \u2014 per-scene HTML authored by you or the agent
 - \`assets/\` \u2014 shared media (narration audio, images, video)
@@ -25751,6 +25834,17 @@ async function scaffoldSceneProject(opts) {
     await writeFile4(claudePath, buildProjectClaudeMd(name), "utf-8");
     created.push(claudePath);
   }
+  const designPath = resolve5(dir, "DESIGN.md");
+  if (await pathExists(designPath)) {
+    skipped.push(designPath);
+  } else {
+    await writeFile4(
+      designPath,
+      buildDesignMd({ name, style: opts.visualStyle }),
+      "utf-8"
+    );
+    created.push(designPath);
+  }
   const gitignorePath = resolve5(dir, ".gitignore");
   if (await pathExists(gitignorePath)) {
     skipped.push(gitignorePath);
@@ -25774,6 +25868,180 @@ var init_scene_project = __esm({
   }
 });
 
+// src/commands/_shared/visual-styles.ts
+function listVisualStyles() {
+  return STYLES;
+}
+function getVisualStyle(query) {
+  const q = query.trim().toLowerCase();
+  return STYLES.find(
+    (s) => s.name.toLowerCase() === q || s.slug === q
+  );
+}
+function visualStyleNames() {
+  return STYLES.map((s) => `"${s.name}"`).join(", ");
+}
+var STYLES;
+var init_visual_styles = __esm({
+  "src/commands/_shared/visual-styles.ts"() {
+    "use strict";
+    STYLES = [
+      {
+        name: "Swiss Pulse",
+        slug: "swiss-pulse",
+        designer: "Josef M\xFCller-Brockmann",
+        mood: "Clinical, precise",
+        bestFor: "SaaS dashboards, developer tools, APIs, metrics",
+        palette: ["#1a1a1a", "#ffffff", "#0066FF"],
+        paletteNotes: "Black, white, ONE accent \u2014 electric blue (#0066FF) or amber (#FFB300). Never both accents at once.",
+        typography: "Helvetica or Inter Bold for headlines, Regular for labels. Numbers dominate at 80\u2013120px.",
+        composition: "Grid-locked. Every element snaps to an invisible 12-column grid. Hard cuts only \u2014 no decorative transitions.",
+        motion: "Animated counters count up from 0. Entries are fast and snap into place. Nothing floats.",
+        transition: "Cinematic Zoom or SDF Iris (precise, geometric)",
+        gsapSignature: "expo.out, power4.out \u2014 fast arrivals, hard stops",
+        avoid: [
+          "Decorative transitions (fades, dissolves) \u2014 use hard cuts",
+          "Two accent colours competing in one frame",
+          "Off-grid placement or floating elements"
+        ]
+      },
+      {
+        name: "Velvet Standard",
+        slug: "velvet-standard",
+        designer: "Massimo Vignelli",
+        mood: "Premium, timeless",
+        bestFor: "Luxury products, enterprise software, keynotes, investor decks",
+        palette: ["#000000", "#ffffff", "#1a237e"],
+        paletteNotes: "Black, white, ONE rich accent \u2014 deep navy (#1a237e) or gold (#c9a84c).",
+        typography: "Thin sans-serif, ALL CAPS, wide letter-spacing (0.15em+). Sequential reveals only.",
+        composition: "Generous negative space. Symmetrical, centered, architectural precision. Nothing busy.",
+        motion: "Slow, deliberate. Sequential reveals with long holds. No frantic motion.",
+        transition: "Cross-Warp Morph (elegant, organic flow between scenes)",
+        gsapSignature: "sine.inOut, power1 \u2014 nothing snaps, everything glides",
+        avoid: [
+          "Tight letter-spacing \u2014 kills the premium register",
+          "Bouncy or elastic easings \u2014 too playful",
+          "Multiple elements arriving at once \u2014 break sequence"
+        ]
+      },
+      {
+        name: "Deconstructed",
+        slug: "deconstructed",
+        designer: "Neville Brody",
+        mood: "Industrial, raw",
+        bestFor: "Tech news, developer launches, security products, punk-energy reveals",
+        palette: ["#1a1a1a", "#D4501E", "#f0f0f0"],
+        paletteNotes: "Dark grey (#1a1a1a), rust orange (#D4501E), raw white (#f0f0f0).",
+        typography: "Type at angles, overlapping edges, escaping frames. Bold industrial weight.",
+        composition: "Gritty textures \u2014 scan-line effects, glitch artifacts baked into the design.",
+        motion: "Text SLAMS and SHATTERS. Letters scramble then snap to final position.",
+        transition: "Glitch shader or Whip Pan (breaks the rules, feels aggressive)",
+        gsapSignature: "back.out(2.5), steps(8), elastic.out(1.2, 0.4) \u2014 intentional irregularity",
+        avoid: [
+          "Polished, centered compositions \u2014 must feel raw",
+          "Smooth fades \u2014 use glitch / scramble entries",
+          "Soft easings \u2014 every motion lands hard"
+        ]
+      },
+      {
+        name: "Maximalist Type",
+        slug: "maximalist-type",
+        designer: "Paula Scher",
+        mood: "Loud, kinetic",
+        bestFor: "Big product launches, milestone announcements, high-energy hype videos",
+        palette: ["#E63946", "#FFD60A", "#000000", "#ffffff"],
+        paletteNotes: "Bold saturated: red (#E63946), yellow (#FFD60A), black, white \u2014 maximum contrast.",
+        typography: "Text IS the visual. Overlapping type layers at different scales and angles, filling 50\u201380% of frame.",
+        composition: "Text layered OVER footage \u2014 never empty backgrounds. 2\u20133 second rapid-fire scenes.",
+        motion: "Everything is kinetic \u2014 slamming, sliding, scaling. No static moments.",
+        transition: "Ridged Burn (explosive, dramatic, impossible to ignore)",
+        gsapSignature: "expo.out, back.out(1.8) \u2014 fast arrivals, hard stops",
+        avoid: [
+          "Static moments \u2014 every frame must move",
+          "Empty backgrounds \u2014 text and footage must layer",
+          "Single typeface at a single size \u2014 must be layered"
+        ]
+      },
+      {
+        name: "Data Drift",
+        slug: "data-drift",
+        designer: "Refik Anadol",
+        mood: "Futuristic, immersive",
+        bestFor: "AI products, ML platforms, data companies, speculative tech",
+        palette: ["#0a0a0a", "#7c3aed", "#06b6d4"],
+        paletteNotes: "Iridescent \u2014 deep black (#0a0a0a), electric purple (#7c3aed), cyan (#06b6d4).",
+        typography: "Thin futuristic sans-serif \u2014 floating, weightless, minimal text.",
+        composition: "Fluid morphing compositions. Extreme scale shifts (micro \u2192 macro). Particles coalesce into numbers.",
+        motion: "Light traces data paths through the frame. Smooth, continuous, organic \u2014 nothing hard.",
+        transition: "Gravitational Lens or Domain Warp (otherworldly distortion)",
+        gsapSignature: "sine.inOut, power2.out \u2014 smooth, continuous, organic",
+        avoid: [
+          "Hard cuts \u2014 break the immersion",
+          "Heavy/bold typography \u2014 too grounded",
+          "Static compositions \u2014 must feel like flow"
+        ]
+      },
+      {
+        name: "Soft Signal",
+        slug: "soft-signal",
+        designer: "Stefan Sagmeister",
+        mood: "Intimate, warm",
+        bestFor: "Wellness brands, personal stories, lifestyle products, human-centered apps",
+        palette: ["#F5A623", "#FFF8EC", "#C4A3A3", "#8FAF8C"],
+        paletteNotes: "Warm amber (#F5A623), cream (#FFF8EC), dusty rose (#C4A3A3), sage green (#8FAF8C).",
+        typography: "Handwritten-style or humanist serif fonts. Personal, lowercase, delicate.",
+        composition: "Close-up framing feel \u2014 single element fills the frame. Nothing feels corporate.",
+        motion: "Slow drifts and floats, never snaps. Soft organic motion throughout.",
+        transition: "Thermal Distortion (warm, flowing, like heat shimmer)",
+        gsapSignature: "sine.inOut, power1.inOut \u2014 everything breathes",
+        avoid: [
+          "Sharp geometric layouts \u2014 break the warmth",
+          "Hard easings or snaps \u2014 too clinical",
+          "Cool tones (blue/green-blue) without warm balance"
+        ]
+      },
+      {
+        name: "Folk Frequency",
+        slug: "folk-frequency",
+        designer: "Eduardo Terrazas",
+        mood: "Cultural, vivid",
+        bestFor: "Consumer apps, food platforms, community products, festive launches",
+        palette: ["#FF1493", "#0047AB", "#FFE000", "#009B77"],
+        paletteNotes: "Vivid folk: hot pink (#FF1493), cobalt blue (#0047AB), sun yellow (#FFE000), emerald (#009B77).",
+        typography: "Bold warm rounded type. Every frame feels handcrafted.",
+        composition: "Pattern and repetition \u2014 folk art rhythm and density. Layered compositions with rich visual texture.",
+        motion: "Colorful motion \u2014 elements bounce, pop, and spin into place with joy.",
+        transition: "Swirl Vortex or Ripple Waves (hypnotic, celebratory)",
+        gsapSignature: "back.out(1.6), elastic.out(1, 0.5) \u2014 overshoots feel intentional",
+        avoid: [
+          "Muted or monochrome palettes \u2014 kill the celebration",
+          "Pure flat / minimal compositions \u2014 must feel layered",
+          "Linear easings \u2014 motion should feel joyful"
+        ]
+      },
+      {
+        name: "Shadow Cut",
+        slug: "shadow-cut",
+        designer: "Hans Hillmann",
+        mood: "Dark, cinematic",
+        bestFor: "Security products, dramatic reveals, investigative content, intense launches",
+        palette: ["#0a0a0a", "#3a3a3a", "#ffffff", "#C1121F"],
+        paletteNotes: "Near-monochrome \u2014 deep blacks (#0a0a0a), cold greys (#3a3a3a), stark white + ONE accent (blood red #C1121F or toxic green #39FF14).",
+        typography: "Sharp angular text like film noir title cards. Heavy contrast, no softness.",
+        composition: "Heavy shadow \u2014 elements emerge from darkness. The reveal IS the narrative.",
+        motion: "Slow creeping push-ins, dramatic scale reveals. Silence before the hit matters.",
+        transition: "Domain Warp (dissolves reality before revealing the next scene)",
+        gsapSignature: "power4.in for exits, power3.out for dramatic reveals \u2014 pause before the hit",
+        avoid: [
+          "Bright or saturated palettes \u2014 kill the cinematic mood",
+          "Bouncy easings \u2014 break the tension",
+          "Quick cuts \u2014 let the reveal breathe"
+        ]
+      }
+    ];
+  }
+});
+
 // src/commands/_shared/scene-html-emit.ts
 function esc(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -25799,6 +26067,52 @@ function buildTranscriptTweens(transcript, targetSelector) {
     return `tl.fromTo('${sel}', { opacity: 0, y: 10 }, { opacity: 1, y: 0, duration: 0.18, ease: 'power2.out' }, ${start});`;
   }).join("\n      ");
 }
+function crossfadeTweens(scope, dur) {
+  return `tl.from('${scope}', { opacity: 0, duration: ${SCENE_OVERLAP_SECONDS}, ease: 'power2.out' }, 0);
+      tl.to('${scope}', { opacity: 0, duration: ${SCENE_OVERLAP_SECONDS}, ease: 'power2.in' }, ${(dur - SCENE_OVERLAP_SECONDS).toFixed(2)});`;
+}
+function fitFontSize(text, baseMaxPx, minPx, comfortableChars) {
+  const charCount = text.length;
+  if (charCount <= comfortableChars) return baseMaxPx;
+  const ratio = comfortableChars / charCount;
+  return Math.max(minPx, Math.round(baseMaxPx * ratio));
+}
+function fitKineticFontSize(words) {
+  const totalChars = words.join(" ").length;
+  if (totalChars <= 18) return 180;
+  if (totalChars <= 26) return 140;
+  if (totalChars <= 38) return 110;
+  if (totalChars <= 54) return 90;
+  return 72;
+}
+function kenBurnsTween(scope, dur, endScale = 1.08) {
+  return `tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: ${endScale}, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);`;
+}
+function idleHeroPulse(scope, selector, idleStart, dur) {
+  const cycleDur = 1.5;
+  const idleEnd = dur - SCENE_OVERLAP_SECONDS;
+  const window2 = idleEnd - idleStart;
+  if (window2 < cycleDur) return "";
+  const plays = Math.max(1, Math.floor(window2 / cycleDur));
+  const repeat = plays - 1;
+  return `tl.to('${scope} ${selector}', { scale: 1.04, y: -8, duration: ${cycleDur}, yoyo: true, repeat: ${repeat}, ease: 'sine.inOut' }, ${idleStart.toFixed(2)});`;
+}
+function kineticWordBobs(scope, wordCount, idleStart, dur) {
+  const cycleDur = 1.8;
+  const idleEnd = dur - SCENE_OVERLAP_SECONDS;
+  const window2 = idleEnd - idleStart;
+  if (window2 < cycleDur) return "";
+  const plays = Math.max(1, Math.floor(window2 / cycleDur));
+  const repeat = plays - 1;
+  const lines = [];
+  for (let i = 0; i < wordCount; i++) {
+    const start = (idleStart + i * 0.18).toFixed(2);
+    lines.push(
+      `tl.to('${scope} #w-${i}', { y: -12, duration: ${cycleDur}, yoyo: true, repeat: ${repeat}, ease: 'sine.inOut' }, ${start});`
+    );
+  }
+  return lines.join("\n      ");
+}
 function buildPreset(input) {
   const id = input.id;
   const scope = `[data-composition-id="${id}"]`;
@@ -25835,7 +26149,8 @@ function buildPreset(input) {
       const captionInner = useWordSync ? renderTranscriptSpans(transcript) : esc(captionText);
       const wordCss = useWordSync ? `
       ${scope} .caption .word { display: inline-block; opacity: 0; }` : "";
-      const timeline = useWordSync ? buildTranscriptTweens(transcript, `${scope} .caption .word`) : `tl.from('${scope} .caption', { opacity: 0, y: 28, duration: 0.45, ease: 'power3.out' }, 0.05);`;
+      const captionFontPx = fitFontSize(captionText, 56, 28, 60);
+      const captionTween = useWordSync ? buildTranscriptTweens(transcript, `${scope} .caption .word`) : `tl.from('${scope} .caption', { opacity: 0, y: 28, duration: 0.45, ease: 'power3.out' }, 0.05);`;
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -25843,21 +26158,27 @@ function buildPreset(input) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .caption {
         position: absolute;
         left: 8%; right: 8%; bottom: 12%;
         text-align: center;
-        font-size: 56px;
+        font-size: ${captionFontPx}px;
         font-weight: 700;
         line-height: 1.2;
+        overflow-wrap: break-word;
         text-shadow: 0 4px 20px rgba(0,0,0,0.65);
       }${wordCss}`,
         body: `${backdropMarkup}
     <div class="caption" id="caption">${captionInner}</div>`,
-        timeline
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      ${captionTween}
+      ${idleHeroPulse(scope, "#caption", 1, dur)}`
       };
     }
     case "announcement": {
+      const fontSize = fitFontSize(headline, 160, 72, 22);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -25865,6 +26186,7 @@ function buildPreset(input) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .announce {
         position: absolute; inset: 0;
         display: flex; align-items: center; justify-content: center;
@@ -25873,10 +26195,11 @@ function buildPreset(input) {
       }
       ${scope} .announce h1 {
         margin: 0;
-        font-size: 160px;
+        font-size: ${fontSize}px;
         font-weight: 900;
         letter-spacing: -4px;
-        line-height: 1;
+        line-height: 1.05;
+        overflow-wrap: break-word;
         background: linear-gradient(90deg, #8e2de2, #00c9ff);
         -webkit-background-clip: text; background-clip: text; color: transparent;
         text-shadow: 0 8px 40px rgba(142,45,226,0.35);
@@ -25886,8 +26209,12 @@ function buildPreset(input) {
         // Faster, snappier entrance and no tail fade-out — see the
         // matching note in the `simple` case above. The headline stays
         // on screen until the producer cuts to the next clip; the next
-        // scene's own fade-in handles the visual transition.
-        timeline: `tl.from('${scope} #headline', { opacity: 0, scale: 0.92, duration: 0.55, ease: 'power3.out' }, 0.05);`
+        // scene's own fade-in handles the visual transition. Backdrop
+        // Ken-Burns fills what used to be 80% dead static frame.
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      tl.from('${scope} #headline', { opacity: 0, scale: 0.92, duration: 0.55, ease: 'power3.out' }, 0.05);
+      ${idleHeroPulse(scope, "#headline", 1, dur)}`
       };
     }
     case "explainer": {
@@ -25899,6 +26226,7 @@ function buildPreset(input) {
       const wordCss = useWordSync ? `
       ${scope} #subtitle .word { display: inline-block; opacity: 0; }` : "";
       const subtitleTween = useWordSync ? buildTranscriptTweens(transcript, `${scope} #subtitle .word`) : sub ? `tl.from('${scope} #subtitle', { opacity: 0, y: 30, duration: 0.55, ease: 'power3.out' }, 0.55);` : "";
+      const titleFontPx = fitFontSize(headline, 110, 56, 30);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -25906,6 +26234,7 @@ function buildPreset(input) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .stage {
         position: absolute; inset: 0;
         display: flex; flex-direction: column; justify-content: center;
@@ -25916,11 +26245,13 @@ function buildPreset(input) {
         color: #00c9ff; font-weight: 600;
       }
       ${scope} .title {
-        font-size: 110px; font-weight: 800; letter-spacing: -2px;
+        font-size: ${titleFontPx}px; font-weight: 800; letter-spacing: -2px;
         line-height: 1.05; margin: 0;
+        overflow-wrap: break-word;
       }
       ${scope} .subtitle {
         font-size: 38px; font-weight: 300; color: #c0c0d0; max-width: 80%;
+        overflow-wrap: break-word;
       }${wordCss}`,
         body: `${backdropMarkup}
     <div class="stage">
@@ -25928,9 +26259,12 @@ function buildPreset(input) {
       <h1 class="title" id="title">${esc(headline)}</h1>${sub ? `
       <div class="subtitle" id="subtitle">${subtitleInner}</div>` : ""}
     </div>`,
-        timeline: `tl.from('${scope} #kicker', { opacity: 0, y: 16, duration: 0.4, ease: 'power2.out' }, 0.1);
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      tl.from('${scope} #kicker', { opacity: 0, y: 16, duration: 0.4, ease: 'power2.out' }, 0.1);
       tl.from('${scope} #title', { opacity: 0, y: 60, duration: 0.7, ease: 'power3.out' }, 0.25);
-      ${subtitleTween}`
+      ${subtitleTween}
+      ${idleHeroPulse(scope, "#title", 1.2, dur)}`
       };
     }
     case "kinetic-type": {
@@ -25946,6 +26280,9 @@ function buildPreset(input) {
         const start = (0.05 + i * stagger).toFixed(2);
         return `tl.from('${scope} #w-${i}', { opacity: 0, y: 80, scale: 0.8, duration: 0.45, ease: 'back.out(1.8)' }, ${start});`;
       }).join("\n      ");
+      const kineticFontPx = fitKineticFontSize(words);
+      const lastWordEntryEnd = useWordSync ? Math.max(...transcript.map((w) => w.end + 0.2)) : 0.05 + (words.length - 1) * stagger + 0.45 + 0.2;
+      const idleStart = Math.max(1, Number(lastWordEntryEnd.toFixed(2)));
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -25953,21 +26290,28 @@ function buildPreset(input) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .kinetic {
         position: absolute; inset: 0;
         display: flex; align-items: center; justify-content: center;
+        flex-wrap: wrap; gap: 8px 16px;
         text-align: center; padding: 0 6%;
-        font-size: 180px; font-weight: 900; letter-spacing: -6px;
+        font-size: ${kineticFontPx}px; font-weight: 900; letter-spacing: -6px;
         line-height: 1; text-shadow: 0 6px 30px rgba(0,0,0,0.6);
+        overflow-wrap: break-word;
       }
       ${scope} .kinetic .word { display: inline-block; margin: 0 12px; }`,
         body: `${backdropMarkup}
     <div class="kinetic">${wordSpans}</div>`,
-        timeline: tweens
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      ${tweens}
+      ${kineticWordBobs(scope, words.length, idleStart, dur)}`
       };
     }
     case "product-shot": {
       const label = kicker || humanise(id);
+      const headlineFontPx = fitFontSize(headline, 72, 40, 50);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -25985,22 +26329,26 @@ function buildPreset(input) {
       }
       ${scope} .product-headline {
         position: absolute; left: 8%; right: 8%; bottom: 14%;
-        font-size: 72px; font-weight: 800; letter-spacing: -1px;
-        line-height: 1.1; text-shadow: 0 4px 20px rgba(0,0,0,0.7);
+        font-size: ${headlineFontPx}px; font-weight: 800; letter-spacing: -1px;
+        line-height: 1.1; overflow-wrap: break-word;
+        text-shadow: 0 4px 20px rgba(0,0,0,0.7);
       }${subhead ? `
       ${scope} .product-sub {
         position: absolute; left: 8%; right: 8%; bottom: 8%;
         font-size: 28px; font-weight: 400; color: #d0d0e0;
+        overflow-wrap: break-word;
         text-shadow: 0 2px 10px rgba(0,0,0,0.7);
       }` : ""}`,
         body: `${backdropMarkup}
     <div class="label" id="label">${esc(label)}</div>
     <div class="product-headline" id="headline">${esc(headline)}</div>${subhead ? `
     <div class="product-sub" id="subhead">${esc(subhead)}</div>` : ""}`,
-        timeline: `tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: 1.08, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);
+        timeline: `${crossfadeTweens(scope, dur)}
+      tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: 1.12, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);
       tl.from('${scope} #label', { opacity: 0, x: -30, duration: 0.5, ease: 'power3.out' }, 0.2);
       tl.from('${scope} #headline', { opacity: 0, y: 40, duration: 0.6, ease: 'power3.out' }, 0.4);${subhead ? `
-      tl.from('${scope} #subhead', { opacity: 0, y: 20, duration: 0.5, ease: 'power3.out' }, 0.65);` : ""}`
+      tl.from('${scope} #subhead', { opacity: 0, y: 20, duration: 0.5, ease: 'power3.out' }, 0.65);` : ""}
+      ${idleHeroPulse(scope, "#headline", 1.2, dur)}`
       };
     }
   }
@@ -26046,7 +26394,7 @@ ${audioBlock}
 </template>
 `;
 }
-function nextSceneStart(rootHtml) {
+function nextSceneStart(rootHtml, overlap = 0) {
   const clipRegex = /<div\s+class="clip"[^>]*?\sdata-start="([\d.]+)"[^>]*?\sdata-duration="([\d.]+)"/gi;
   let maxEnd = 0;
   let match;
@@ -26054,14 +26402,15 @@ function nextSceneStart(rootHtml) {
     const end = parseFloat(match[1]) + parseFloat(match[2]);
     if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
   }
-  return maxEnd;
+  return Math.max(0, maxEnd - overlap);
 }
 function buildClipReference(opts) {
   const start = Number(opts.start.toFixed(3));
   const duration = Number(opts.duration.toFixed(3));
   const track = opts.trackIndex ?? 1;
   const src = opts.src ?? `compositions/scene-${opts.id}.html`;
-  return `<div class="clip" data-composition-id="${esc(opts.id)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}"></div>`;
+  const zIndex = Math.max(1, 1e6 - Math.floor(start * 1e3));
+  return `<div class="clip" data-composition-id="${esc(opts.id)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}" style="z-index: ${zIndex};"></div>`;
 }
 function insertClipIntoRoot(rootHtml, clip) {
   const clipDiv = buildClipReference(clip);
@@ -26094,7 +26443,7 @@ function readRootDims(rootHtml) {
   if (!widthMatch || !heightMatch) return null;
   return { width: parseInt(widthMatch[1], 10), height: parseInt(heightMatch[1], 10) };
 }
-var SCENE_PRESETS, GSAP_CDN;
+var SCENE_PRESETS, GSAP_CDN, SCENE_OVERLAP_SECONDS;
 var init_scene_html_emit = __esm({
   "src/commands/_shared/scene-html-emit.ts"() {
     "use strict";
@@ -26106,6 +26455,7 @@ var init_scene_html_emit = __esm({
       "product-shot"
     ];
     GSAP_CDN = "https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js";
+    SCENE_OVERLAP_SECONDS = 0.4;
   }
 });
 
@@ -26789,6 +27139,18 @@ function validatePreset(value) {
   }
   return value;
 }
+function validateVisualStyle(value) {
+  const found = getVisualStyle(value);
+  if (!found) {
+    exitWithError(
+      usageError(
+        `Unknown visual style: ${value}`,
+        `Valid: ${visualStyleNames()}. Browse details with \`vibe scene styles\`.`
+      )
+    );
+  }
+  return found;
+}
 async function pathExists2(p) {
   try {
     await access4(p);
@@ -27002,7 +27364,20 @@ async function executeSceneAdd(opts) {
   }
   const cfg = await loadVibeProjectConfig(projectDir);
   const fallback2 = cfg?.defaultSceneDuration ?? 5;
-  const duration = opts.duration ?? narrationDuration ?? fallback2;
+  const NARRATION_TAIL_BUFFER = 0.5;
+  const userDur = opts.duration;
+  const audioMinDur = narrationDuration !== void 0 ? narrationDuration + SCENE_OVERLAP_SECONDS + NARRATION_TAIL_BUFFER : void 0;
+  let duration;
+  if (userDur !== void 0 && audioMinDur !== void 0) {
+    duration = Math.max(userDur, audioMinDur);
+  } else if (audioMinDur !== void 0) {
+    duration = audioMinDur;
+  } else if (userDur !== void 0) {
+    duration = userDur;
+  } else {
+    duration = fallback2;
+  }
+  duration = Number(duration.toFixed(2));
   opts.onProgress?.("Emitting scene HTML...");
   const sceneHtml = emitSceneHtml({
     id,
@@ -27020,8 +27395,10 @@ async function executeSceneAdd(opts) {
   await mkdir4(dirname3(scenePath), { recursive: true });
   await writeFile6(scenePath, sceneHtml, "utf-8");
   opts.onProgress?.("Updating root composition...");
-  const start = nextSceneStart(rootHtmlBefore);
-  const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration });
+  const start = nextSceneStart(rootHtmlBefore, SCENE_OVERLAP_SECONDS);
+  const existingClipCount = (rootHtmlBefore.match(/<div\s+class="clip"/g) || []).length;
+  const trackIndex = existingClipCount % 2 + 1;
+  const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration, trackIndex });
   await writeFile6(rootPath, updated, "utf-8");
   const transcriptAbsPath = transcriptRelPath ? resolve10(projectDir, transcriptRelPath) : void 0;
   return {
@@ -27080,6 +27457,7 @@ var init_scene = __esm({
     init_dist2();
     init_tts_resolve();
     init_scene_project();
+    init_visual_styles();
     init_scene_html_emit();
     init_scene_lint();
     init_scene_render();
@@ -27104,21 +27482,28 @@ Examples:
 
 A scene project is bilingual: it works with both \`vibe\` and \`npx hyperframes\`.
 Run 'vibe schema scene.<command>' for structured parameter info.`);
-    sceneCommand.command("init").description("Scaffold a new scene project (or safely augment an existing Hyperframes project)").argument("<dir>", "Project directory (created if it doesn't exist)").option("-n, --name <name>", "Project name (defaults to directory basename)").option("-r, --ratio <ratio>", "Aspect ratio: 16:9, 9:16, 1:1, 4:5", "16:9").option("-d, --duration <sec>", "Default root composition duration (seconds)", "10").option("--dry-run", "Preview parameters without writing files").action(async (dir, options) => {
+    sceneCommand.command("init").description("Scaffold a new scene project (or safely augment an existing Hyperframes project)").argument("<dir>", "Project directory (created if it doesn't exist)").option("-n, --name <name>", "Project name (defaults to directory basename)").option("-r, --ratio <ratio>", "Aspect ratio: 16:9, 9:16, 1:1, 4:5", "16:9").option("-d, --duration <sec>", "Default root composition duration (seconds)", "10").option("--visual-style <name>", `Seed DESIGN.md from a named style (browse via \`vibe scene styles\`). E.g. "Swiss Pulse"`).option("--dry-run", "Preview parameters without writing files").action(async (dir, options) => {
       const aspect = validateAspect(options.ratio);
       const duration = validateDuration(options.duration);
       const name = options.name ?? basename4(dir.replace(/\/+$/, ""));
+      const visualStyle = options.visualStyle ? validateVisualStyle(options.visualStyle) : void 0;
       if (options.dryRun) {
         outputResult({
           dryRun: true,
           command: "scene init",
-          params: { dir, name, aspect, duration }
+          params: {
+            dir,
+            name,
+            aspect,
+            duration,
+            visualStyle: visualStyle?.name ?? null
+          }
         });
         return;
       }
       const spinner2 = isJsonMode() ? null : ora(`Scaffolding scene project at ${dir}...`).start();
       try {
-        const result = await scaffoldSceneProject({ dir, name, aspect, duration });
+        const result = await scaffoldSceneProject({ dir, name, aspect, duration, visualStyle });
         if (isJsonMode()) {
           outputResult({
             success: true,
@@ -27127,6 +27512,7 @@ Run 'vibe schema scene.<command>' for structured parameter info.`);
             name,
             aspect,
             duration,
+            visualStyle: visualStyle?.name ?? null,
             created: result.created,
             merged: result.merged,
             skipped: result.skipped
@@ -27143,7 +27529,13 @@ Run 'vibe schema scene.<command>' for structured parameter info.`);
         console.log();
         console.log(source_default.bold.cyan("Next steps"));
         console.log(source_default.dim("\u2500".repeat(60)));
-        console.log(`  ${source_default.cyan("vibe scene add")} <name>    ${source_default.dim("# author a scene via AI")}`);
+        if (visualStyle) {
+          console.log(`  ${source_default.dim("DESIGN.md seeded with")} ${source_default.bold(visualStyle.name)} ${source_default.dim("\u2014 review and customise.")}`);
+        } else {
+          console.log(`  ${source_default.cyan("vibe scene styles")}        ${source_default.dim("# pick a named style for DESIGN.md")}`);
+        }
+        console.log(`  ${source_default.cyan("npx skills add heygen-com/hyperframes")}  ${source_default.dim("# load the cinematic-craft skill set")}`);
+        console.log(`  ${source_default.cyan("vibe scene add")} <name>    ${source_default.dim("# fallback path: 5-preset emit")}`);
         console.log(`  ${source_default.cyan("vibe scene lint")}          ${source_default.dim("# validate HTML")}`);
         console.log(`  ${source_default.cyan("vibe scene render")}        ${source_default.dim("# render to MP4")}`);
       } catch (error) {
@@ -27152,6 +27544,69 @@ Run 'vibe schema scene.<command>' for structured parameter info.`);
         exitWithError(generalError(`Failed to scaffold: ${msg}`));
       }
     });
+    sceneCommand.command("styles").description("List vendored visual styles (or show one) for DESIGN.md seeding").argument("[name]", "Style name to inspect (omit to list all)").action((name) => {
+      if (!name) {
+        const all = listVisualStyles();
+        if (isJsonMode()) {
+          outputResult({
+            success: true,
+            command: "scene styles",
+            count: all.length,
+            styles: all.map((s) => ({
+              name: s.name,
+              slug: s.slug,
+              designer: s.designer,
+              mood: s.mood,
+              bestFor: s.bestFor
+            }))
+          });
+          return;
+        }
+        console.log();
+        console.log(source_default.bold.cyan("Visual styles"));
+        console.log(source_default.dim("\u2500".repeat(60)));
+        for (const s of all) {
+          console.log(
+            `  ${source_default.bold(s.name.padEnd(18))} ${source_default.dim(s.mood.padEnd(24))} ${source_default.dim(s.bestFor)}`
+          );
+        }
+        console.log();
+        console.log(source_default.dim("Show details: "), source_default.cyan('vibe scene styles "<name>"'));
+        console.log(source_default.dim("Seed DESIGN.md:"), source_default.cyan('vibe scene init <dir> --visual-style "<name>"'));
+        return;
+      }
+      const style = getVisualStyle(name);
+      if (!style) {
+        exitWithError(
+          usageError(
+            `Unknown visual style: ${name}`,
+            `Valid: ${visualStyleNames()}.`
+          )
+        );
+        return;
+      }
+      if (isJsonMode()) {
+        outputResult({ success: true, command: "scene styles", style });
+        return;
+      }
+      console.log();
+      console.log(source_default.bold.cyan(style.name), source_default.dim(`\u2014 ${style.designer}`));
+      console.log(source_default.dim("\u2500".repeat(60)));
+      console.log(`${source_default.bold("Mood:")}        ${style.mood}`);
+      console.log(`${source_default.bold("Best for:")}    ${style.bestFor}`);
+      console.log(`${source_default.bold("Palette:")}     ${style.palette.join(", ")}`);
+      console.log(source_default.dim("              ") + style.paletteNotes);
+      console.log(`${source_default.bold("Typography:")}  ${style.typography}`);
+      console.log(`${source_default.bold("Composition:")} ${style.composition}`);
+      console.log(`${source_default.bold("Motion:")}      ${style.motion}`);
+      console.log(`${source_default.bold("GSAP:")}        ${style.gsapSignature}`);
+      console.log(`${source_default.bold("Transition:")}  ${style.transition}`);
+      console.log();
+      console.log(source_default.bold("Avoid:"));
+      for (const a of style.avoid) console.log(`  ${source_default.red("\u2022")} ${a}`);
+      console.log();
+      console.log(source_default.dim("Seed DESIGN.md:"), source_default.cyan(`vibe scene init <dir> --visual-style "${style.name}"`));
+    });
     sceneCommand.command("add").description("Add a new scene to a project: AI narration + image + per-scene HTML").argument("<name>", "Scene name (slugified into the composition id)").option("--style <preset>", `Style preset: ${SCENE_PRESETS.join(", ")}`, "simple").option("--narration <text>", "Narration text (or path to a .txt file). Drives TTS + scene duration.").option("--narration-file <path>", "Existing narration audio file (.wav/.mp3). Skips TTS \u2014 useful with hyperframes tts, Mac say, or other external tools.").option("-d, --duration <sec>", "Explicit scene duration in seconds (overrides narration audio)").option("--visuals <prompt>", "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider").option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option("--tts <provider>", "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)", "auto").option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option("--no-audio", "Skip TTS even when --narration is provided (useful for tests/agent dry runs)").option("--no-image", "Skip image generation even when --visuals is provided").option("--no-transcribe", "Skip Whisper word-level transcribe step (no transcript-<id>.json emitted)").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("--dry-run", "Preview parameters without writing files or calling APIs").action(async (name, options) => {
       if (options.style) options.style = validatePreset(options.style);
       if (options.duration !== void 0) options.duration = validateDuration(options.duration);
@@ -30822,7 +31277,12 @@ async function executeSegmentsToScenes(opts) {
   const dims = aspectToDims(aspect);
   const preset = opts.scenePreset ?? DEFAULT_PRESET;
   const projectName = opts.projectName ?? basename7(outputDir);
-  const totalDuration = opts.segments.reduce((sum, s) => sum + (s.duration || 0), 0) || 10;
+  const totalDuration = (() => {
+    const sum = opts.segments.reduce((acc, s) => acc + (s.duration || 0), 0);
+    if (sum <= 0) return 10;
+    const joins = Math.max(0, opts.segments.length - 1);
+    return Math.max(0.1, sum - joins * SCENE_OVERLAP_SECONDS);
+  })();
   const baseError = (error) => ({
     success: false,
     outputDir,
@@ -30895,9 +31355,10 @@ async function executeSegmentsToScenes(opts) {
       id,
       start: clipStart,
       duration,
+      trackIndex: i % 2 + 1,
       src: `compositions/${id}.html`
     });
-    clipStart += duration;
+    clipStart += duration - SCENE_OVERLAP_SECONDS;
   }
   await writeFile10(rootAbs, rootHtml, "utf-8");
   let lintResult;
@@ -57538,7 +57999,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.57.3",
+  version: "0.58.0",
   description: "VibeFrame CLI - natural language video editing from the terminal",
   private: false,
   license: "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.57.3",
+  "version": "0.58.0",
   "description": "VibeFrame CLI - natural language video editing from the terminal",
   "private": false,
   "license": "MIT",
@@ -149,8 +149,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.57.3",
-    "@vibeframe/core": "0.57.3"
+    "@vibeframe/ai-providers": "0.58.0",
+    "@vibeframe/core": "0.58.0"
   },
   "engines": {
     "node": ">=20"