mulmocast 2.3.1 → 2.4.0

package/README.md

@@ -59,7 +59,7 @@ Here is the "Hello World" in MulmoScript.
 ```JSON
 {
   "$mulmocast": {
-    "version": "1.0"
+    "version": "1.1"
   },
   "beats": [
     { "text": "Hello World" }
@@ -247,6 +247,8 @@ Top-level keys are applied as **defaults** (script values take precedence). Use
 
 Priority chain: `config (defaults)` < `template/style` < `script` < `config.override` < `presentationStyle (-p)`
 
+> **Note**: `kind: "path"` entries in `mulmo.config.json` are resolved relative to the **script file directory**, not the config file location. This is consistent with all other path resolution in MulmoScript.
+
 Verify the merged result with:
 ```bash
 mulmo tool info merged --script <script.json>
@@ -499,8 +501,6 @@ https://github.com/receptron/mulmocast-cli/tree/main/scripts
 
 CLI Usage
 
-
-
 ```
 mulmo <command> [options]
 
@@ -511,6 +511,7 @@ Commands:
   mulmo movie <file>      Generate movie file
   mulmo pdf <file>        Generate PDF files
   mulmo markdown <file>   Generate markdown files
+  mulmo bundle <file>     Generate bundle files
   mulmo html <file>       Generate html files
   mulmo tool <command>    Generate Mulmo script and other tools
 
@@ -529,13 +530,19 @@ Positionals:
   file  Mulmo Script File                                    [string] [required]
 
 Options:
-      --version  Show version number                                   [boolean]
-  -v, --verbose  verbose log               [boolean] [required] [default: false]
-  -h, --help     Show help                                             [boolean]
-  -o, --outdir   output dir                                             [string]
-  -b, --basedir  base dir                                               [string]
-  -l, --lang     target language                  [string] [choices: "en", "ja"]
-  -f, --force    Force regenerate                     [boolean] [default: false]
+      --version            Show version number                         [boolean]
+  -v, --verbose            verbose log     [boolean] [required] [default: false]
+  -h, --help               Show help                                   [boolean]
+  -o, --outdir             output dir                                   [string]
+  -b, --basedir            base dir                                     [string]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
+  -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
+  -p, --presentationStyle  Presentation Style                           [string]
 ```
 
 ```
@@ -552,8 +559,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -a, --audiodir           Audio output directory                       [string]
 ```
@@ -572,8 +584,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -i, --imagedir           Image output directory                       [string]
 ```
@@ -592,12 +609,19 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -a, --audiodir           Audio output directory                       [string]
   -i, --imagedir           Image output directory                       [string]
-  -c, --caption            Video captions         [string] [choices: "en", "ja"]
+  -c, --caption            Video captions
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
 ```
 
 ```
@@ -614,9 +638,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
-      --dryRun             Dry run                    [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -i, --imagedir           Image output directory                       [string]
       --pdf_mode           PDF mode
@@ -643,6 +671,9 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
       --image_width        Image width (e.g., 400px, 50%, auto)         [string]
 ```
@@ -665,6 +696,9 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
       --image_width        Image width (e.g., 400px, 50%, auto)         [string]
 ```
@@ -687,6 +721,8 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
       --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
 ```
@@ -697,11 +733,16 @@ mulmo tool <command>
 Generate Mulmo script and other tools
 
 Commands:
-  mulmo tool scripting       Generate mulmocast script
-  mulmo tool complete <file> Complete partial MulmoScript with defaults
-  mulmo tool prompt          Dump prompt from template
-  mulmo tool schema          Dump mulmocast schema
-  mulmo tool info [category] Show available options (styles, bgm, voices, etc.)
+  mulmo tool scripting               Generate mulmocast script
+  mulmo tool prompt                  Dump prompt from template
+  mulmo tool schema                  Dump mulmocast schema
+  mulmo tool story_to_script <file>  Generate Mulmo script from story
+  mulmo tool whisper <file>          Process file with whisper
+  mulmo tool complete <file>         Complete MulmoScript with schema defaults
+                                     and optional style
+  mulmo tool info [category]         Show available options (styles, bgm,
+                                     templates, voices, images, movies, llm,
+                                     themes, config, merged)
 
 Options:
       --version  Show version number                                   [boolean]
@@ -726,15 +767,15 @@ Options:
   -i, --interactive  Generate script in interactive mode with user prompts
                                                                        [boolean]
   -t, --template     Template name to use
-        [string] [choices: "akira_comic", "business", "children_book", "coding",
-           "comic_strips", "drslump_comic", "ghibli_comic", "ghibli_image_only",
-           "ghibli_shorts", "ghost_comic", "onepiece_comic", "podcast_standard",
-               "portrait_movie", "realistic_movie", "sensei_and_taro", "shorts",
-                                       "text_and_image", "text_only", "trailer"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
   -c, --cache        cache dir                                          [string]
   -s, --script       script filename                [string] [default: "script"]
       --llm          llm
-                     [string] [choices: "openai", "anthropic", "gemini", "groq"]
+             [string] [choices: "openai", "anthropic", "gemini", "groq", "mock"]
       --llm_model    llm model                                          [string]
 ```
 
@@ -753,12 +794,15 @@ Options:
   -o, --outdir           output dir                                     [string]
   -b, --basedir          base dir                                       [string]
   -t, --template         Template name to use
-       [string] [choices: "business", "children_book", "coding", "comic_strips",
-                         "ghibli_strips", "podcast_standard", "sensei_and_taro"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
   -s, --script           script filename            [string] [default: "script"]
       --beats_per_scene  beats per scene                   [number] [default: 3]
       --llm              llm
-                     [string] [choices: "openAI", "anthropic", "gemini", "groq"]
+             [string] [choices: "openai", "anthropic", "gemini", "groq", "mock"]
       --llm_model        llm model                                      [string]
       --mode             story to script generation mode
               [string] [choices: "step_wise", "one_step"] [default: "step_wise"]
@@ -774,8 +818,11 @@ Options:
   -v, --verbose   verbose log              [boolean] [required] [default: false]
   -h, --help      Show help                                            [boolean]
   -t, --template  Template name to use
-       [string] [choices: "business", "children_book", "coding", "comic_strips",
-                         "ghibli_strips", "podcast_standard", "sensei_and_taro"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
 ```
 
 ```
@@ -792,18 +839,23 @@ Options:
 ```
 mulmo tool complete <file>
 
-Complete partial MulmoScript with schema defaults and optional style/template
+Complete MulmoScript with schema defaults and optional style
 
 Positionals:
-  file  Input beats file path (JSON)                             [string] [required]
+  file  Input beats file path (JSON)                         [string] [required]
 
 Options:
-      --version   Show version number                                    [boolean]
-  -v, --verbose   verbose log                [boolean] [required] [default: false]
-  -h, --help      Show help                                              [boolean]
-  -o, --output    Output file path (default: <file>_completed.json)       [string]
-  -t, --template  Template name to apply                                  [string]
-  -s, --style     Style name or file path (.json)                         [string]
+      --version   Show version number                                  [boolean]
+  -v, --verbose   verbose log              [boolean] [required] [default: false]
+  -h, --help      Show help                                            [boolean]
+  -o, --output    Output file path (default: <file>_completed.json)     [string]
+  -t, --template  Template name to apply
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
+  -s, --style     Style name or file path (.json)                       [string]
 
 Examples:
   # Complete minimal script with schema defaults
@@ -822,17 +874,21 @@ Examples:
 ```
 mulmo tool info [category]
 
-Show available options for MulmoScript configuration
+Show available options (styles, bgm, templates, voices, images, movies, llm,
+themes, config, merged)
 
 Positionals:
   category  Category to show info for
-    [string] [choices: "styles", "bgm", "templates", "voices", "images", "movies", "llm"]
+  [string] [choices: "styles", "bgm", "templates", "voices", "images", "movies",
+                                            "llm", "themes", "config", "merged"]
 
 Options:
       --version  Show version number                                   [boolean]
   -v, --verbose  verbose log               [boolean] [required] [default: false]
   -h, --help     Show help                                             [boolean]
-  -F, --format   Output format      [string] [choices: "text", "json", "yaml"]
+  -F, --format   Output format
+                    [string] [choices: "text", "json", "yaml"] [default: "text"]
+  -S, --script   Script file path (required for 'merged' category)      [string]
 
 Examples:
   # Show all available categories

package/assets/html/tailwind.html

@@ -43,5 +43,6 @@
 </head>
 <body class="bg-white text-gray-800 h-full flex flex-col">
   ${html_body}
+  ${user_script}
 </body>
 </html>

package/assets/html/tailwind_animated.html

@@ -0,0 +1,259 @@
+<!DOCTYPE html>
+<html lang="en" class="h-full">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    /* Disable all CSS animations/transitions for deterministic frame-based rendering */
+    *, *::before, *::after {
+      animation-play-state: paused !important;
+      transition: none !important;
+    }
+    ${custom_style}
+  </style>
+</head>
+<body class="bg-white text-gray-800 h-full flex flex-col">
+  ${html_body}
+
+  <script>
+    // === MulmoCast Animation Helpers ===
+
+    /**
+     * Easing functions for non-linear interpolation.
+     */
+    const Easing = {
+      linear: (t) => t,
+      easeIn: (t) => t * t,
+      easeOut: (t) => 1 - (1 - t) * (1 - t),
+      easeInOut: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+    };
+
+    /**
+     * Interpolation with clamping and optional easing.
+     *
+     * @param {number} value - Current value (typically frame number)
+     * @param {Object} opts - { input: { inMin, inMax }, output: { outMin, outMax }, easing?: string | function }
+     * @returns {number} Interpolated and clamped value
+     *
+     * @example
+     *   interpolate(frame, { input: { inMin: 0, inMax: 30 }, output: { outMin: 0, outMax: 1 } })
+     *   interpolate(frame, { input: { inMin: 0, inMax: 30 }, output: { outMin: 0, outMax: 1 }, easing: 'easeOut' })
+     */
+    function interpolate(value, opts) {
+      const { inMin, inMax } = opts.input;
+      const { outMin, outMax } = opts.output;
+      if (inMax === inMin) {
+        return outMin;
+      }
+      const easing = !opts.easing ? Easing.linear
+        : typeof opts.easing === 'function' ? opts.easing
+        : Easing[opts.easing] || Easing.linear;
+      const progress = Math.max(0, Math.min(1, (value - inMin) / (inMax - inMin)));
+      return outMin + easing(progress) * (outMax - outMin);
+    }
+
+    // === MulmoAnimation Helper Class ===
+
+    const TRANSFORM_PROPS = { translateX: 'px', translateY: 'px', scale: '', rotate: 'deg' };
+    const SVG_PROPS = ['r', 'cx', 'cy', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'rx', 'ry',
+                       'width', 'height', 'stroke-width', 'stroke-dashoffset', 'stroke-dasharray', 'opacity'];
+
+    function MulmoAnimation() {
+      this._entries = [];
+    }
+
+    /**
+     * Register a property animation on a single element.
+     * @param {string} selector - CSS selector (e.g. '#title')
+     * @param {Object} props - { opacity: [0, 1], translateY: [30, 0], width: [0, 80, '%'] }
+     * @param {Object} opts - { start, end, easing }  (start/end in seconds)
+     */
+    MulmoAnimation.prototype.animate = function(selector, props, opts) {
+      this._entries.push({ kind: 'animate', selector, props, opts: opts || {} });
+      return this;
+    };
+
+    /**
+     * Stagger animation across numbered elements.
+     * Selector must contain {i} placeholder (e.g. '#item{i}').
+     * @param {string} selector - e.g. '#item{i}'
+     * @param {number} count - number of elements (0-indexed)
+     * @param {Object} props - same as animate()
+     * @param {Object} opts - { start, stagger, duration, easing }
+     */
+    MulmoAnimation.prototype.stagger = function(selector, count, props, opts) {
+      this._entries.push({ kind: 'stagger', selector, count, props, opts: opts || {} });
+      return this;
+    };
+
+    /**
+     * Typewriter effect — reveal text character by character.
+     * @param {string} selector - target element selector
+     * @param {string} text - full text to reveal
+     * @param {Object} opts - { start, end }
+     */
+    MulmoAnimation.prototype.typewriter = function(selector, text, opts) {
+      this._entries.push({ kind: 'typewriter', selector, text, opts: opts || {} });
+      return this;
+    };
+
+    /**
+     * Animated counter — interpolate a number and display with optional prefix/suffix.
+     * @param {string} selector - target element selector
+     * @param {[number, number]} range - [from, to]
+     * @param {Object} opts - { start, end, prefix, suffix, decimals }
+     */
+    MulmoAnimation.prototype.counter = function(selector, range, opts) {
+      this._entries.push({ kind: 'counter', selector, range, opts: opts || {} });
+      return this;
+    };
+
+    /**
+     * Code reveal — show lines of code one by one (line-level typewriter).
+     * @param {string} selector - target element selector
+     * @param {string[]} lines - array of code lines
+     * @param {Object} opts - { start, end }
+     */
+    MulmoAnimation.prototype.codeReveal = function(selector, lines, opts) {
+      this._entries.push({ kind: 'codeReveal', selector, lines, opts: opts || {} });
+      return this;
+    };
+
+    /**
+     * Blink — periodic show/hide toggle (e.g. cursor blinking).
+     * @param {string} selector - target element selector
+     * @param {Object} opts - { interval } (half-cycle seconds, default 0.5)
+     */
+    MulmoAnimation.prototype.blink = function(selector, opts) {
+      this._entries.push({ kind: 'blink', selector, opts: opts || {} });
+      return this;
+    };
+
+    /** Resolve easing name string or function to an easing function */
+    MulmoAnimation.prototype._resolveEasing = function(e) {
+      if (!e) return Easing.linear;
+      if (typeof e === 'function') return e;
+      return Easing[e] || Easing.linear;
+    };
+
+    /** Apply props to element at a given progress (0-1) with easing */
+    MulmoAnimation.prototype._applyProps = function(el, props, progress, easingFn) {
+      if (!el) return;
+      const transforms = [];
+      Object.keys(props).forEach((prop) => {
+        const spec = props[prop];
+        const from = spec[0], to = spec[1];
+        const unit = (spec.length > 2) ? spec[2] : null;
+        const val = from + easingFn(progress) * (to - from);
+
+        if (TRANSFORM_PROPS.hasOwnProperty(prop)) {
+          const tUnit = unit || TRANSFORM_PROPS[prop];
+          transforms.push(prop === 'scale' ? 'scale(' + val + ')' : prop + '(' + val + tUnit + ')');
+        } else if (el instanceof SVGElement && SVG_PROPS.indexOf(prop) !== -1) {
+          el.setAttribute(prop, val);
+        } else if (prop === 'opacity') {
+          el.style.opacity = val;
+        } else {
+          const cssUnit = unit || 'px';
+          el.style[prop] = val + cssUnit;
+        }
+      });
+      if (transforms.length > 0) {
+        el.style.transform = transforms.join(' ');
+      }
+    };
+
+    /**
+     * Update all registered animations for the given frame.
+     * @param {number} frame - current frame number
+     * @param {number} fps - frames per second
+     */
+    MulmoAnimation.prototype.update = function(frame, fps) {
+      this._entries.forEach((entry) => {
+        const opts = entry.opts;
+        const easingFn = this._resolveEasing(opts.easing);
+
+        if (entry.kind === 'animate') {
+          const startFrame = (opts.start || 0) * fps;
+          const endFrame = (opts.end || 0) * fps;
+          const progress = Math.max(0, Math.min(1, endFrame === startFrame ? 1 : (frame - startFrame) / (endFrame - startFrame)));
+          const el = document.querySelector(entry.selector);
+          this._applyProps(el, entry.props, progress, easingFn);
+
+        } else if (entry.kind === 'stagger') {
+          const baseStart = (opts.start || 0) * fps;
+          const staggerDelay = (opts.stagger || 0.2) * fps;
+          const dur = (opts.duration || 0.5) * fps;
+          for (let j = 0; j < entry.count; j++) {
+            const sel = entry.selector.replace(/\{i\}/g, j);
+            const sEl = document.querySelector(sel);
+            const sStart = baseStart + j * staggerDelay;
+            const sEnd = sStart + dur;
+            const sProgress = Math.max(0, Math.min(1, sEnd === sStart ? 1 : (frame - sStart) / (sEnd - sStart)));
+            this._applyProps(sEl, entry.props, sProgress, easingFn);
+          }
+
+        } else if (entry.kind === 'typewriter') {
+          const twStart = (opts.start || 0) * fps;
+          const twEnd = (opts.end || 0) * fps;
+          const twProgress = Math.max(0, Math.min(1, twEnd === twStart ? 1 : (frame - twStart) / (twEnd - twStart)));
+          const charCount = Math.floor(twProgress * entry.text.length);
+          const twEl = document.querySelector(entry.selector);
+          if (twEl) twEl.textContent = entry.text.substring(0, charCount);
+
+        } else if (entry.kind === 'counter') {
+          const cStart = (opts.start || 0) * fps;
+          const cEnd = (opts.end || 0) * fps;
+          const cProgress = Math.max(0, Math.min(1, cEnd === cStart ? 1 : (frame - cStart) / (cEnd - cStart)));
+          const cVal = entry.range[0] + easingFn(cProgress) * (entry.range[1] - entry.range[0]);
+          const decimals = opts.decimals || 0;
+          const display = (opts.prefix || '') + cVal.toFixed(decimals) + (opts.suffix || '');
+          const cEl = document.querySelector(entry.selector);
+          if (cEl) cEl.textContent = display;
+
+        } else if (entry.kind === 'codeReveal') {
+          const crStart = (opts.start || 0) * fps;
+          const crEnd = (opts.end || 0) * fps;
+          const crProgress = Math.max(0, Math.min(1, crEnd === crStart ? 1 : (frame - crStart) / (crEnd - crStart)));
+          const lineCount = Math.floor(crProgress * entry.lines.length);
+          const crEl = document.querySelector(entry.selector);
+          if (crEl) crEl.textContent = entry.lines.slice(0, lineCount).join('\n');
+
+        } else if (entry.kind === 'blink') {
+          const interval_s = opts.interval || 0.5;
+          const blinkEl = document.querySelector(entry.selector);
+          if (blinkEl) {
+            const cycle = (frame / fps) / interval_s;
+            blinkEl.style.opacity = (Math.floor(cycle) % 2 === 0) ? 1 : 0;
+          }
+        }
+      });
+    };
+
+    // === MulmoCast Frame State (updated by Puppeteer per frame) ===
+    window.__MULMO = {
+      frame: 0,
+      totalFrames: ${totalFrames},
+      fps: ${fps},
+    };
+  </script>
+
+  ${user_script}
+
+  <script>
+    // Auto-render: if MulmoAnimation is used but render() is not defined, generate it
+    if (typeof render !== 'function' && typeof animation !== 'undefined' && animation instanceof MulmoAnimation) {
+      window.render = function(frame, totalFrames, fps) { animation.update(frame, fps); };
+    }
+
+    // Initial render (frame 0)
+    if (typeof render === 'function') {
+      const result = render(0, window.__MULMO.totalFrames, window.__MULMO.fps);
+      if (result && typeof result.then === 'function') {
+        result.catch(console.error);
+      }
+    }
+  </script>
+</body>
+</html>

package/lib/actions/image_agents.js

@@ -1,6 +1,6 @@
 import { GraphAILogger } from "graphai";
 import { MulmoPresentationStyleMethods, MulmoStudioContextMethods, MulmoBeatMethods, MulmoMediaSourceMethods } from "../methods/index.js";
-import { getBeatPngImagePath, getBeatMoviePaths, getAudioFilePath, getGroupedAudioFilePath } from "../utils/file.js";
+import { getBeatPngImagePath, getBeatMoviePaths, getBeatAnimatedVideoPath, getAudioFilePath, getGroupedAudioFilePath } from "../utils/file.js";
 import { imagePrompt, htmlImageSystemPrompt } from "../utils/prompt.js";
 import { renderHTMLToImage } from "../utils/html_render.js";
 import { beatId } from "../utils/utils.js";
@@ -72,6 +72,24 @@ export const imagePreprocessAgent = async (namedInputs) => {
         const markdown = plugin.markdown ? plugin.markdown({ beat, context, imagePath, ...htmlStyle(context, beat) }) : undefined;
         const html = plugin.html ? await plugin.html({ beat, context, imagePath, ...htmlStyle(context, beat) }) : undefined;
         const isTypeMovie = beat.image.type === "movie";
+        const isAnimatedHtml = MulmoBeatMethods.isAnimatedHtmlTailwind(beat);
+        // animation and moviePrompt cannot be used together
+        if (isAnimatedHtml && beat.moviePrompt) {
+            throw new Error("html_tailwind animation and moviePrompt cannot be used together on the same beat. Use either animation or moviePrompt, not both.");
+        }
+        if (isAnimatedHtml) {
+            const animatedVideoPath = getBeatAnimatedVideoPath(context, index);
+            // ImagePluginPreprocessAgentResponse
+            return {
+                ...returnValue,
+                imagePath, // for thumbnail extraction
+                movieFile: animatedVideoPath, // .mp4 path for the pipeline
+                imageFromMovie: true, // triggers extractImageFromMovie
+                referenceImageForMovie: pluginPath,
+                markdown,
+                html,
+            };
+        }
         // undefined prompt indicates that image generation is not needed
         // ImagePluginPreprocessAgentResponse
         return {
@@ -99,9 +117,12 @@ export const imagePluginAgent = async (namedInputs) => {
     const { context, beat, index, imageRefs } = namedInputs;
     const { imagePath } = getBeatPngImagePath(context, index);
     const plugin = MulmoBeatMethods.getPlugin(beat);
+    // For animated html_tailwind, use the .mp4 path so the plugin writes video there
+    const isAnimatedHtml = MulmoBeatMethods.isAnimatedHtmlTailwind(beat);
+    const effectiveImagePath = isAnimatedHtml ? getBeatAnimatedVideoPath(context, index) : imagePath;
     try {
         MulmoStudioContextMethods.setBeatSessionState(context, "image", index, beat.id, true);
-        const processorParams = { beat, context, imagePath, imageRefs, ...htmlStyle(context, beat) };
+        const processorParams = { beat, context, imagePath: effectiveImagePath, imageRefs, ...htmlStyle(context, beat) };
         await plugin.process(processorParams);
         MulmoStudioContextMethods.setBeatSessionState(context, "image", index, beat.id, false);
     }

package/lib/actions/images.js

@@ -190,7 +190,7 @@ export const beat_graph_data = {
                 return await extractImageFromMovie(namedInputs.movieFile, namedInputs.imageFile);
             },
             inputs: {
-                onComplete: [":movieGenerator"], // to wait for movieGenerator to finish
+                onComplete: [":movieGenerator", ":imagePlugin"], // :imagePlugin for animated html_tailwind video generation
                 imageFile: ":preprocessor.imagePath",
                 movieFile: ":preprocessor.movieFile",
             },
@@ -219,7 +219,7 @@ export const beat_graph_data = {
                 }
             },
             inputs: {
-                onComplete: [":movieGenerator", ":htmlImageGenerator", ":soundEffectGenerator"],
+                onComplete: [":movieGenerator", ":htmlImageGenerator", ":soundEffectGenerator", ":imagePlugin"], // :imagePlugin for animated html_tailwind video generation
                 movieFile: ":preprocessor.movieFile",
                 imageFile: ":preprocessor.imagePath",
                 soundEffectFile: ":preprocessor.soundEffectFile",

package/lib/agents/combine_audio_files_agent.js

@@ -2,6 +2,7 @@ import { assert, GraphAILogger } from "graphai";
 import { silent60secPath, isFile } from "../utils/file.js";
 import { FfmpegContextInit, FfmpegContextGenerateOutput, FfmpegContextInputFormattedAudio, ffmpegGetMediaDuration, } from "../utils/ffmpeg_utils.js";
 import { MulmoMediaSourceMethods } from "../methods/mulmo_media_source.js";
+import { MulmoBeatMethods } from "../methods/index.js";
 import { userAssert } from "../utils/utils.js";
 import { getAudioInputIdsError } from "../utils/error_cause.js";
 const getMovieDuration = async (context, beat) => {
@@ -13,6 +14,10 @@ const getMovieDuration = async (context, beat) => {
             return { duration: duration / speed, hasAudio };
         }
     }
+    // Animated html_tailwind beats with explicit duration act as movie-like for voice_over grouping
+    if (MulmoBeatMethods.isAnimatedHtmlTailwind(beat) && beat.duration !== undefined) {
+        return { duration: beat.duration, hasAudio: false };
+    }
     return { duration: 0, hasAudio: false };
 };
 export const getPadding = (context, beat, index) => {