@amg555/frameforge-mcp 2.3.4 → 2.3.5

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.3.5] — 2026-11-09
+
+### Added
+- **Integrated Code-Driven Scene Animator** (`src/video-renderer/scene-animator.js`):
+  - Dynamic 24fps HTML5/Canvas animation generator adhering to pure-function-of-time contract `seek(t)`
+  - Contextual motion graphic themes: Code IDE/terminal typing, Data charts & counters, Network node graphs, Flow diagrams, and floating Ken-Burns image cards
+  - Dynamic gradient backgrounds with ambient particle systems and perspective motion grids
+  - High-performance Chromium harness rendering + direct FFmpeg BT.709 H.264 VUI muxing
+- **Full Multilingual & Malayalam Font Support**:
+  - Direct font resolver for Malayalam & Indic scripts (`Nirmala.ttc`, `Noto Sans Malayalam`, `Malayalam Sangam MN`, `Kartika`, `Meera`, `Manjari`)
+  - FFmpeg `text_shaping=1` HarfBuzz layout integration preserving complex conjuncts, chillu letters, and viramas
+  - Unicode-safe slicing and UTF-8 handling in caption and narration filters
+  - Updated `engine.css`, `engine.js`, and `new-project.mjs` typography stacks for seamless multilingual rendering
+
+### Fixed
+- Replaced static solid-color slideshow fallback in `renderer.js` with live code-driven animation engine
+- Fixed `--flag value` space-separated argument parsing in `harness.mjs` CLI
+- Fixed `--out` directory path resolution in `cmdFrames` frame exporter
+
+---
+
 ## [2.3.4] — 2026-11-09
 
 ### Added

package/README.md

@@ -9,9 +9,9 @@
 [![npm](https://img.shields.io/npm/v/@amg555/frameforge-mcp.svg?label=npm)](https://www.npmjs.com/package/@amg555/frameforge-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Version](https://img.shields.io/badge/version-2.3.4-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.3.5-blue.svg)](CHANGELOG.md)
 [![MCP Spec](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)
-[![Tests](https://img.shields.io/badge/tests-512%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-539%20passing-brightgreen.svg)](#testing)
 
 </div>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.3.4",
+  "version": "2.3.5",
   "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 17 MCP tools.",
   "publishConfig": {
     "access": "public"
@@ -30,7 +30,7 @@
     "start:local-render": "cross-env RENDER_MODE=full WORKER_PORT=3211 node src/worker/server-render-free.js",
     "db:migrate": "node scripts/db-migrate.js",
     "validate": "node scripts/deep-validate.js",
-    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/renderer.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/harness/lib/pixels.test.js src/harness/lib/verify-purity.test.js src/harness/harness.test.js src/integration.test.js",
+    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/scene-animator.test.js src/video-renderer/renderer.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/harness/lib/pixels.test.js src/harness/lib/verify-purity.test.js src/harness/harness.test.js src/integration.test.js",
     "lint": "echo 'No linter configured — add eslint for production'",
     "check-credentials": "node src/utils/log-redaction.js",
     "generate-assets": "node scripts/generate-initial-assets.js",

package/plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.css

@@ -21,9 +21,9 @@
   --danger:    #ef4444;
 
   /* Typography scale */
-  --font-body:    -apple-system, "Segoe UI", system-ui, sans-serif;
+  --font-body:    -apple-system, "Segoe UI", "Nirmala UI", "Noto Sans Malayalam", "Malayalam Sangam MN", "Kartika", "Meera", "Manjari", system-ui, sans-serif;
   --font-mono:    "Fira Code", "Cascadia Code", "Consolas", monospace;
-  --font-display: "Archivo", "Segoe UI", system-ui, sans-serif;
+  --font-display: "Archivo", "Nirmala UI", "Noto Sans Malayalam", "Malayalam Sangam MN", "Kartika", "Meera", "Manjari", -apple-system, "Segoe UI", system-ui, sans-serif;
 
   /* Spacing */
   --gap-sm:  8px;

package/plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.js

@@ -331,7 +331,7 @@ export function shots(shotList = []) {
  * @param {{ font, color, x, y, size, weight, align, opacity, duration }} opts
  */
 export function text(str, {
-  font     = '48px/1.3 system-ui',
+  font     = '48px/1.3 "Nirmala UI", "Noto Sans Malayalam", "Malayalam Sangam MN", "Kartika", system-ui, sans-serif',
   color    = '#ffffff',
   x        = 'center',
   y        = 100,

package/scripts/deep-validate.js

@@ -20,7 +20,7 @@ check('batch handling',              code.includes('Array.isArray(body)'));
 check('ping handler',                code.includes("method === 'ping'"));
 check('notifications/init',          code.includes("notifications/initialized"));
 check('body size limit',             code.includes('MAX_BODY_BYTES'));
-check('SERVER_INFO version 2.3.4',   code.includes("version: '2.3.4'"));
+check('SERVER_INFO version 2.3.5',   code.includes("version: '2.3.5'"));
 check('18 tools defined (incl get_job_status)', code.includes('get_job_status'));
 check('export_to_editor tool defined', code.includes('export_to_editor'));
 check('voxforge TTS provider', code.includes('voxforge'));
@@ -293,7 +293,7 @@ check('cf-worker has checkRateLimit',   cfWorker.includes('checkRateLimit'));
 check('cf-worker hashes token (SHA-256)', cfWorker.includes('SHA-256'));
 check('cf-worker uses RATE_LIMITS KV',  cfWorker.includes('env.RATE_LIMITS'));
 check('cf-worker returns 429 on limit', cfWorker.includes('429'));
-check('cf-worker version 2.3.4',        cfWorker.includes("'2.3.4'"));
+check('cf-worker version 2.3.5',        cfWorker.includes("'2.3.5'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/scripts/html-renderer/new-project.mjs

@@ -97,7 +97,7 @@ const indexHtml = `<!DOCTYPE html>
   <!-- Preload primary typeface — must resolve before frame 0 (fonts.ready gate) -->
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Archivo:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css2?family=Archivo:ital,wght@0,100..900;1,100..900&family=Noto+Sans+Malayalam:wght@400;600;700;800;900&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="reel/engine.css">
   <style>
     /* Project-level overrides — edit here */
@@ -105,7 +105,7 @@ const indexHtml = `<!DOCTYPE html>
       --primary: #ffffff;
       --accent:  #3b82f6;
       --bg:      #0d1117;
-      --font:    'Archivo', system-ui, sans-serif;
+      --font:    'Archivo', 'Nirmala UI', 'Noto Sans Malayalam', 'Malayalam Sangam MN', 'Kartika', system-ui, sans-serif;
     }
   </style>
 </head>

package/src/harness/bin/harness.mjs

@@ -39,8 +39,19 @@ const extras = [];
 for (let i = 1; i < argv.length; i++) {
   const arg = argv[i];
   if (arg.startsWith('--')) {
-    const [k, v] = arg.slice(2).split('=');
-    flags[k] = v ?? true;
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx !== -1) {
+      const k = arg.slice(2, eqIdx);
+      const v = arg.slice(eqIdx + 1);
+      flags[k] = v;
+    } else {
+      const k = arg.slice(2);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[k] = argv[++i];
+      } else {
+        flags[k] = true;
+      }
+    }
   } else {
     extras.push(arg);
   }
@@ -56,7 +67,7 @@ function resolveProjectFile(filename, fallback) {
 const HTML_FILE   = flags.html ? path.resolve(CWD, flags.html) : resolveProjectFile('index.html', resolveProjectFile('studio.html'));
 const OUT_DIR     = flags.outDir ? path.resolve(CWD, flags.outDir) : path.join(CWD, 'out');
 const CHECK_DIR   = path.join(OUT_DIR, 'check');
-const FRAMES_DIR  = path.join(OUT_DIR, 'frames');
+const FRAMES_DIR  = flags.frames ? path.resolve(CWD, flags.frames) : flags.out ? path.resolve(CWD, flags.out) : path.join(OUT_DIR, 'frames');
 const PURITY_LOG  = path.join(CHECK_DIR, 'purity_report.json');
 
 fs.mkdirSync(OUT_DIR, { recursive: true });
@@ -214,17 +225,19 @@ async function cmdFrames() {
   const fps = parseInt(flags.fps || '30', 10);
   const workers = parseInt(flags.workers || '4', 10);
   const duration = flags.duration ? parseFloat(flags.duration) : 2.0;
-  const totalFrames = Math.round(duration * fps);
+  const first = flags.first !== undefined ? parseInt(flags.first, 10) : 0;
+  const last = flags.last !== undefined ? parseInt(flags.last, 10) : (Math.round(duration * fps) - 1);
+  const totalFrames = last - first + 1;
 
-  console.log(`📦 Rendering Frame Range [0..${totalFrames - 1}] (${duration}s @ ${fps}fps, workers=${workers})`);
+  console.log(`📦 Rendering Frame Range [${first}..${last}] (${totalFrames} frames @ ${fps}fps, workers=${workers})`);
   const { browser } = await launchHarnessBrowser();
 
   const res = await renderFrameJobs({
     browser,
     htmlPath: HTML_FILE,
     framesDir: FRAMES_DIR,
-    first: 0,
-    last: totalFrames - 1,
+    first,
+    last,
     fps,
     workers,
     width: parseInt(flags.width || '1920', 10),

package/src/mcp-server/server.js

@@ -1372,7 +1372,7 @@ Operations (used with action="edit"):
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.3.4',
+  version: '2.3.5',
 };
 
 const CAPABILITIES = {

package/src/video-renderer/renderer.js

@@ -29,6 +29,26 @@ const DEFAULT_FILES_DIR = process.env.N8N_FILES_DIR || path.join(os.homedir(), '
 
 const { buildCameraFilter, selectCameraHint } = require('../animation/animation-system');
 const { AudioMixer }                          = require('../audio-mixer/mixer');
+const { generateSceneHtml }                   = require('./scene-animator');
+const { findChromePath }                      = require('../harness/lib/browser.mjs');
+
+// ── Cross-platform Indic / Malayalam font resolver ────────────────────────────
+const INDIC_FONTS = [
+  // Windows
+  'C:\\Windows\\Fonts\\Nirmala.ttc',
+  'C:\\Windows\\Fonts\\NirmalaB.ttf',
+  'C:\\Windows\\Fonts\\Nirmala.ttf',
+  'C:\\Windows\\Fonts\\kartika.ttf',
+  'C:\\Windows\\Fonts\\kartikab.ttf',
+  // macOS
+  '/System/Library/Fonts/Supplemental/Malayalam Sangam MN.ttc',
+  '/System/Library/Fonts/Supplemental/Malayalam MN.ttc',
+  // Linux
+  '/usr/share/fonts/opentype/noto/NotoSansMalayalam-Bold.ttf',
+  '/usr/share/fonts/truetype/noto/NotoSansMalayalam-Bold.ttf',
+  '/usr/share/fonts/truetype/malayalam/Meera.ttf',
+  '/usr/share/fonts/truetype/lohit-malayalam/Lohit-Malayalam.ttf',
+];
 
 // ── Cross-platform font resolver ──────────────────────────────────────────────
 // Checked in priority order. First existing file wins. Covers:
@@ -61,10 +81,16 @@ const FONTS = [
 ];
 
 /** Return the first font file that exists, or '' if none found. */
-function resolveFont() {
+function resolveFont(text = '') {
   // Allow explicit override via FFMPEG_FONT env var
   const override = process.env.FFMPEG_FONT;
   if (override && fs.existsSync(override)) return override;
+
+  const hasIndic = /[\u0D00-\u0D7F\u0900-\u0DFF]/.test(text || '');
+  if (hasIndic) {
+    const indicFont = INDIC_FONTS.find(f => f && fs.existsSync(f));
+    if (indicFont) return indicFont;
+  }
   return FONTS.find(f => f && fs.existsSync(f)) || '';
 }
 
@@ -80,23 +106,46 @@ class VideoRenderer {
   }
 
   /**
-   * Render a single scene: image or video clip + voice → scene_N_out.mp4
+   * Render a single scene: code-driven animated video or clip + voice → scene_N_out.mp4
    *
    * @param {{
-   *   sceneIndex:   number,
-   *   imagePath?:   string,
-   *   videoPath?:   string,   // optional user clip / B-roll
-   *   voicePath:    string,
-   *   caption?:     string,
-   *   camera?:      string,   // camera_hint from scene schema v1.0.0
-   *   focalPoint?:  { x: number, y: number },
-   *   manifest?:    ArtifactManifest  // optional — enables idempotency
-   *   renderWidth?: number,   // default 1920
-   *   renderHeight?: number,  // default 1080
+   *   sceneIndex:         number,
+   *   imagePath?:         string,
+   *   videoPath?:         string,   // optional user clip / B-roll
+   *   voicePath:          string,
+   *   caption?:           string,
+   *   narration?:         string,
+   *   visualDescription?: string,
+   *   visualType?:        string,
+   *   language?:          string,
+   *   musicMood?:         string,
+   *   camera?:            string,   // camera_hint from scene schema v1.0.0
+   *   focalPoint?:        { x: number, y: number },
+   *   manifest?:          ArtifactManifest  // optional — enables idempotency
+   *   renderWidth?:       number,   // default 1920
+   *   renderHeight?:      number,   // default 1080
+   *   fps?:               number,   // default 24
    * }} opts
    * @returns {string} outputPath
    */
-  renderScene({ sceneIndex, imagePath, videoPath, voicePath, caption = '', camera, focalPoint, manifest, renderWidth = 1920, renderHeight = 1080 } = {}) {
+  renderScene({
+    sceneIndex,
+    imagePath,
+    videoPath,
+    voicePath,
+    caption = '',
+    narration = '',
+    visualDescription = '',
+    visualType = 'code_animation',
+    language = '',
+    musicMood = 'neutral',
+    camera,
+    focalPoint,
+    manifest,
+    renderWidth = 1920,
+    renderHeight = 1080,
+    fps = 24,
+  } = {}) {
     const outputPath = path.join(this.vdir, `scene_${sceneIndex}_out.mp4`);
 
     // Idempotency: skip if already rendered and manifest says so
@@ -108,83 +157,107 @@ class VideoRenderer {
     fs.mkdirSync(this.vdir, { recursive: true });
 
     // Duration from voice file.
-    // No hard 60s cap — long scenes (documentary, lecture, podcast) can run as long as
-    // the narration dictates. The per-scene ffmpeg timeout (5 min) is the real ceiling.
-    //
-    // Fix: guard voicePath=null/undefined before calling ffprobe.
-    // _getAudioDuration(null) → ffprobe stdout empty → parseFloat('') = NaN → clampedDur=NaN
-    // → ffmpeg receives "-t NaN" → scene silently produces 0-byte output → concat breaks A/V sync.
     if (!voicePath || !fs.existsSync(voicePath)) {
       throw new Error(`Scene ${sceneIndex} render failed: voicePath is missing or does not exist (${voicePath})`);
     }
     const dur        = this._getAudioDuration(voicePath);
     const clampedDur = Math.max(2, Number.isFinite(dur) ? dur + 0.15 : 3.15);
 
-    const mediaSource    = videoPath || imagePath;
-    const captionFilter  = this._captionFilter(caption);
+    const isVideoInput = Boolean(videoPath) || (videoPath && /\.(mp4|mov|webm|mkv|m4v)$/i.test(videoPath));
 
-    // No image and no video: procedural motion-graphics scene.
-    // Cycles through sleek modern palettes with vignette shading.
-    if (!mediaSource) {
-      const PALETTES = ['0d1117', '0f172a', '13111c', '0c1a24', '18181b'];
-      const bgColor  = PALETTES[sceneIndex % PALETTES.length];
-      const vfFilters = ['vignette=PI/4'];
-      if (captionFilter) vfFilters.push(captionFilter);
-      const vf = vfFilters.join(',');
+    // Priority 1: User-supplied video clip
+    if (isVideoInput) {
+      const captionFilter = this._captionFilter(caption);
+      const scaleFilter = `scale=${renderWidth}:${renderHeight}:force_original_aspect_ratio=increase:flags=lanczos,crop=${renderWidth}:${renderHeight}`;
+      const vf = [scaleFilter, captionFilter].filter(Boolean).join(',');
 
       const result = spawnSync('ffmpeg', [
         '-nostdin', '-y', '-threads', '2',
-        '-f', 'lavfi', '-i', `color=c=#${bgColor}:s=${renderWidth}x${renderHeight}:r=30`,
-        '-i', voicePath,
-        '-map', '0:v:0', '-map', '1:a:0',
-        // apad=whole_dur pads audio to exactly clampedDur so -t never truncates mid-word.
-        // Specifying whole_dur is mandatory: without it -apad on a color source runs forever.
+        '-stream_loop', '-1', '-i', videoPath, '-i', voicePath,
+        '-vf', vf || `scale=${renderWidth}:${renderHeight},format=yuv420p`,
         '-af', `apad=whole_dur=${clampedDur}`,
         '-t', String(clampedDur),
-        '-vf', vf,
+        '-map', '0:v:0', '-map', '1:a:0',
         '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '22',
         '-profile:v', 'high', '-level', '4.1',
         '-color_range', 'tv', '-colorspace', 'bt709',
         '-color_primaries', 'bt709', '-color_trc', 'bt709',
-        '-pix_fmt', 'yuv420p',
+        '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709',
         '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
         '-movflags', '+faststart',
+        '-pix_fmt', 'yuv420p',
         outputPath,
       ], { timeout: 5 * 60 * 1000, encoding: 'utf8' });
 
       if (result.status !== 0) {
-        throw new Error(`Scene ${sceneIndex} (no-image fallback) render failed: ${(result.stderr || '').slice(-300)}`);
+        const err = `Scene ${sceneIndex} render failed: ${(result.stderr || '').slice(-300)}`;
+        manifest?.setSceneFailed(sceneIndex, err);
+        throw new Error(err);
       }
+
       manifest?.setSceneRendered(sceneIndex, outputPath);
       return outputPath;
     }
 
-    const isVideoInput = Boolean(videoPath) || /\.(mp4|mov|webm|mkv|m4v)$/i.test(mediaSource);
+    // Priority 2: Code-driven animated video scene via Chromium + Harness
+    // Produces pure-function-of-t 24fps motion graphics (kinetic typography,
+    // spring motion, animated particles, graphs, code typing, full multilingual Indic/Malayalam support).
+    const chrome = findChromePath();
+    if (chrome && process.env.FRAMEFORGE_NO_BROWSER !== '1') {
+      try {
+        return this._renderCodeAnimationScene({
+          sceneIndex,
+          imagePath,
+          voicePath,
+          caption,
+          narration,
+          visualDescription,
+          clampedDur,
+          renderWidth,
+          renderHeight,
+          fps,
+          outputPath,
+          manifest,
+          musicMood,
+        });
+      } catch (err) {
+        console.warn(`[Renderer] Code-driven browser scene render failed (${err.message}), falling back to procedural animation`);
+      }
+    }
 
+    // Priority 3: Procedural dynamic animated fallback (dynamic moving gradients / camera drift)
+    const captionFilter = this._captionFilter(caption);
     let inputArgs = [];
     let vf = '';
 
-    if (isVideoInput) {
-      // Loop video clip if shorter than duration, scale/crop to target resolution
-      inputArgs = ['-stream_loop', '-1', '-i', mediaSource, '-i', voicePath];
-      const scaleFilter = `scale=${renderWidth}:${renderHeight}:force_original_aspect_ratio=increase:flags=lanczos,crop=${renderWidth}:${renderHeight}`;
-      vf = [scaleFilter, captionFilter].filter(Boolean).join(',');
-    } else {
-      // Image input with AnimationSystem camera motion
-      inputArgs = ['-loop', '1', '-i', mediaSource, '-i', voicePath];
+    if (imagePath && fs.existsSync(imagePath)) {
+      inputArgs = ['-loop', '1', '-i', imagePath, '-i', voicePath];
       const hint = camera || selectCameraHint(sceneIndex, focalPoint || {});
       const fx   = focalPoint ? { focalX: focalPoint.x, focalY: focalPoint.y } : {};
       const cameraFilter = buildCameraFilter(hint, { duration: clampedDur, w: renderWidth, h: renderHeight, ...fx });
       vf = [cameraFilter, captionFilter].filter(Boolean).join(',');
+    } else {
+      const PALETTES = [
+        { bg: '0d1117', c1: '38bdf8' },
+        { bg: '0f172a', c1: '818cf8' },
+        { bg: '13111c', c1: 'c084fc' },
+        { bg: '0c1a24', c1: '34d399' },
+        { bg: '18181b', c1: 'fbbf24' },
+      ];
+      const pal = PALETTES[sceneIndex % PALETTES.length];
+      inputArgs = [
+        '-f', 'lavfi', '-i', `gradients=s=${renderWidth}x${renderHeight}:r=30:c0=0x${pal.bg}:c1=0x${pal.c1}:speed=0.5:type=radial`,
+        '-i', voicePath,
+      ];
+      const vfFilters = ['vignette=PI/4'];
+      if (captionFilter) vfFilters.push(captionFilter);
+      vf = vfFilters.join(',');
     }
 
     const result = spawnSync('ffmpeg', [
       '-nostdin', '-y', '-threads', '2',
       ...inputArgs,
       '-vf', vf || `scale=${renderWidth}:${renderHeight},format=yuv420p`,
-      // apad=whole_dur pads audio to exactly clampedDur, preventing mid-word truncation
-      // when voice is fractionally shorter than clampedDur and avoiding infinite padding
-      // on looped-image inputs. -t then hard-caps output length at clampedDur.
       '-af', `apad=whole_dur=${clampedDur}`,
       '-t', String(clampedDur),
       '-map', '0:v:0', '-map', '1:a:0',
@@ -192,6 +265,7 @@ class VideoRenderer {
       '-profile:v', 'high', '-level', '4.1',
       '-color_range', 'tv', '-colorspace', 'bt709',
       '-color_primaries', 'bt709', '-color_trc', 'bt709',
+      '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709',
       '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
       '-movflags', '+faststart',
       '-pix_fmt', 'yuv420p',
@@ -199,7 +273,7 @@ class VideoRenderer {
     ], { timeout: 5 * 60 * 1000, encoding: 'utf8' });
 
     if (result.status !== 0) {
-      const err = `Scene ${sceneIndex} render failed: ${(result.stderr || '').slice(-300)}`;
+      const err = `Scene ${sceneIndex} (no-image fallback) render failed: ${(result.stderr || '').slice(-300)}`;
       manifest?.setSceneFailed(sceneIndex, err);
       throw new Error(err);
     }
@@ -208,6 +282,91 @@ class VideoRenderer {
     return outputPath;
   }
 
+  _renderCodeAnimationScene({
+    sceneIndex,
+    imagePath,
+    voicePath,
+    caption,
+    narration,
+    visualDescription,
+    clampedDur,
+    renderWidth,
+    renderHeight,
+    fps = 24,
+    outputPath,
+    manifest,
+    musicMood,
+  }) {
+    const htmlContent = generateSceneHtml({
+      caption,
+      narration,
+      visualDescription,
+      imagePath,
+      duration: clampedDur,
+      width: renderWidth,
+      height: renderHeight,
+      sceneIndex,
+      musicMood,
+    });
+
+    const animHtmlPath = path.join(this.vdir, `scene_${sceneIndex}_anim.html`);
+    const framesDir    = path.join(this.vdir, `scene_${sceneIndex}_frames`);
+    fs.writeFileSync(animHtmlPath, htmlContent, 'utf8');
+    fs.mkdirSync(framesDir, { recursive: true });
+
+    const harnessBin = path.resolve(__dirname, '../harness/bin/harness.mjs');
+    const totalFrames = Math.max(1, Math.round(clampedDur * fps));
+    const lastFrame = totalFrames - 1;
+
+    const res = spawnSync(process.execPath, [
+      harnessBin,
+      'frames',
+      '--html', animHtmlPath,
+      '--out', framesDir,
+      '--fps', String(fps),
+      '--first', '0',
+      '--last', String(lastFrame),
+      '--workers', '4',
+    ], { encoding: 'utf8', timeout: 5 * 60 * 1000 });
+
+    if (res.status !== 0) {
+      throw new Error(`Harness frame rendering failed: ${(res.stderr || res.stdout || '').slice(-400)}`);
+    }
+
+    const framesPattern = path.join(framesDir, 'f%06d.jpg');
+    const encResult = spawnSync('ffmpeg', [
+      '-nostdin', '-y', '-threads', '2',
+      '-framerate', String(fps),
+      '-pattern_type', 'sequence',
+      '-i', framesPattern,
+      '-i', voicePath,
+      '-map', '0:v:0', '-map', '1:a:0',
+      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20',
+      '-profile:v', 'high', '-level', '4.1',
+      '-color_range', 'tv', '-colorspace', 'bt709',
+      '-color_primaries', 'bt709', '-color_trc', 'bt709',
+      '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709',
+      '-pix_fmt', 'yuv420p',
+      '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+      '-af', `apad=whole_dur=${clampedDur}`,
+      '-t', String(clampedDur),
+      '-movflags', '+faststart',
+      outputPath,
+    ], { timeout: 5 * 60 * 1000, encoding: 'utf8' });
+
+    if (encResult.status !== 0) {
+      throw new Error(`Scene ${sceneIndex} video encode failed: ${(encResult.stderr || '').slice(-300)}`);
+    }
+
+    try {
+      fs.rmSync(framesDir, { recursive: true, force: true });
+      fs.unlinkSync(animHtmlPath);
+    } catch (_) {}
+
+    manifest?.setSceneRendered(sceneIndex, outputPath);
+    return outputPath;
+  }
+
   /**
    * Assemble all scene_N_out.mp4 files into final_video.mp4,
    * then pass through AudioMixer for sidechain ducking + LUFS normalisation.
@@ -276,19 +435,22 @@ class VideoRenderer {
 
   _captionFilter(caption) {
     if (!caption || !this.font) return '';
+    const resolvedFont = resolveFont(caption) || this.font;
+    if (!resolvedFont) return '';
+
+    const hasIndic = /[\u0D00-\u0D7F\u0900-\u0DFF]/.test(caption);
     // Sanitize caption for ffmpeg drawtext.
-    // Strip all characters that need ffmpeg escaping or that break the drawtext
-    // filter syntax. After stripping : and %, re-escaping them is a no-op — removed.
-    const safe = caption
-      .replace(/['"\\:;|<>{}[\]()!@#$%^&*+=]/g, '')
-      .replace(/\s+/g, ' ')
-      .trim()
-      .slice(0, 45)
-      .toUpperCase();
+    // Strip syntax-breaking characters; preserve full Unicode letters & viramas.
+    const safe = Array.from(
+      caption.replace(/['"\\:;|<>{}[\]()!@#$%^&*+=]/g, '').replace(/\s+/g, ' ').trim()
+    ).slice(0, 45).join('');
     if (!safe) return '';
-    const safeFont = this.font.replace(/\\/g, '/').replace(/:/g, '\\:');
+
+    const safeText = hasIndic ? safe : safe.toUpperCase();
+    const safeFont = resolvedFont.replace(/\\/g, '/').replace(/:/g, '\\:');
+    const shaping = hasIndic ? ':text_shaping=1' : '';
     // Bottom-center, safe zone: 100px from bottom + UI button zone
-    return `drawtext=fontfile='${safeFont}':text='${safe}':fontsize=68:fontcolor=white:bordercolor=black:borderw=4:x=(w-text_w)/2:y=h-180:line_spacing=10`;
+    return `drawtext=fontfile='${safeFont}'${shaping}:text='${safeText}':fontsize=68:fontcolor=white:bordercolor=black:borderw=4:x=(w-text_w)/2:y=h-180:line_spacing=10`;
   }
 
   // ── Helpers ───────────────────────────────────────────────────────────────

package/src/video-renderer/scene-animator.js

@@ -0,0 +1,459 @@
+'use strict';
+/**
+ * Scene Animator — Code-Driven HTML/Canvas Scene Generator
+ *
+ * Generates self-contained HTML/Canvas animation scenes conforming to the
+ * FrameForge frame-purity contract:
+ * - window.DURATION = seconds
+ * - window.seek = async (t) => draws frame at time t
+ * - Every frame is a pure function of t (no Date.now, no Math.random without seed)
+ * - Multilingual typography support: Malayalam, Indic, CJK, Arabic, Latin
+ *
+ * Supported component themes:
+ * - 'code': IDE/terminal window with typing code and cursor
+ * - 'chart': Animated bar chart, progress ring, and metric counter
+ * - 'nodes': Pulsing network nodes with traveling energy packets
+ * - 'diagram': Flowchart steps with directional energy arrows
+ * - 'image': Floating Ken-Burns card embedding user-provided image
+ * - 'kinetic': Audio spectrum visualizer + isometric geometry
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Multilingual font family stack prioritizing Indic/Malayalam system fonts
+const FONT_STACK = `'Nirmala UI', 'Noto Sans Malayalam', 'Malayalam Sangam MN', 'Kartika', 'Meera', 'Manjari', -apple-system, 'Segoe UI', system-ui, sans-serif`;
+
+/**
+ * Detect the best visual theme from visual description, caption, and media.
+ */
+function detectTheme({ visualDescription = '', caption = '', imagePath = null } = {}) {
+  if (imagePath) return 'image';
+  const text = `${visualDescription} ${caption}`.toLowerCase();
+  if (/\b(code|function|syntax|api|javascript|python|typescript|json|sql|query|endpoint|algorithm|struct|cli|terminal|bash|shell|npm|git)\b/.test(text)) {
+    return 'code';
+  }
+  if (/\b(chart|data|metric|analytics|growth|graph|statistic|stats|revenue|percent|count|number)\b/.test(text)) {
+    return 'chart';
+  }
+  if (/\b(network|node|ai|model|neural|pipeline|architecture|cloud|server|system|mesh|connect)\b/.test(text)) {
+    return 'nodes';
+  }
+  if (/\b(diagram|flow|step|process|workflow|sequence|lifecycle|cycle)\b/.test(text)) {
+    return 'diagram';
+  }
+  return 'kinetic';
+}
+
+/**
+ * Generate a complete self-contained HTML scene string.
+ *
+ * @param {object} opts
+ * @param {string} opts.caption
+ * @param {string} [opts.narration]
+ * @param {string} [opts.visualDescription]
+ * @param {string} [opts.imagePath]
+ * @param {number} opts.duration
+ * @param {number} [opts.width]
+ * @param {number} [opts.height]
+ * @param {number} [opts.sceneIndex]
+ * @param {string} [opts.musicMood]
+ * @returns {string} HTML document
+ */
+function generateSceneHtml({
+  caption = '',
+  narration = '',
+  visualDescription = '',
+  imagePath = null,
+  duration = 3,
+  width = 1920,
+  height = 1080,
+  sceneIndex = 0,
+  musicMood = 'neutral',
+} = {}) {
+  const theme = detectTheme({ visualDescription, caption, imagePath });
+  const clampedDur = Math.max(1, Number(duration) || 3);
+
+  // Convert imagePath to data URL if local file exists
+  let imageDataUri = '';
+  if (imagePath && fs.existsSync(imagePath)) {
+    try {
+      const ext = path.extname(imagePath).toLowerCase().slice(1) || 'jpeg';
+      const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg';
+      const b64 = fs.readFileSync(imagePath).toString('base64');
+      imageDataUri = `data:${mime};base64,${b64}`;
+    } catch (_) {}
+  }
+
+  // Color palettes based on scene index and music mood
+  const PALETTES = [
+    { bg0: '#142036', bg1: '#0b111c', bg2: '#05080f', accent: '#38bdf8', accent2: '#818cf8', tag: 'CYBER TECH' },
+    { bg0: '#231436', bg1: '#110a1c', bg2: '#07040d', accent: '#c084fc', accent2: '#f43f5e', tag: 'DEEP DYNAMICS' },
+    { bg0: '#0e261f', bg1: '#071511', bg2: '#030a08', accent: '#34d399', accent2: '#38bdf8', tag: 'SYSTEM ACTIVE' },
+    { bg0: '#291d0e', bg1: '#150f07', bg2: '#0a0703', accent: '#fbbf24', accent2: '#f97316', tag: 'HIGH IMPACT' },
+    { bg0: '#161d2b', bg1: '#0d131d', bg2: '#06090e', accent: '#60a5fa', accent2: '#a78bfa', tag: 'INTELLIGENCE' },
+  ];
+  const pal = PALETTES[sceneIndex % PALETTES.length];
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body {
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      background: ${pal.bg2};
+      font-family: ${FONT_STACK};
+      -webkit-font-smoothing: antialiased;
+    }
+    canvas {
+      width: 100%;
+      height: 100%;
+      display: block;
+    }
+  </style>
+</head>
+<body>
+<canvas id="stage" width="${width}" height="${height}"></canvas>
+<script>
+window.DURATION = ${clampedDur};
+const canvas = document.getElementById('stage');
+const ctx = canvas.getContext('2d');
+const W = ${width};
+const H = ${height};
+
+// Seeded PRNG for frame purity (same t -> exact same frame)
+function sfc32(a, b, c, d) {
+  return function() {
+    a >>>= 0; b >>>= 0; c >>>= 0; d >>>= 0;
+    let t = (a + b | 0) + d | 0;
+    d = d + 1 | 0;
+    a = b ^ b >>> 9;
+    b = c + (c << 3) | 0;
+    c = c << 21 | c >>> 11;
+    c = c + t | 0;
+    return (t >>> 0) / 4294967296;
+  };
+}
+
+const rng = sfc32(${42 + sceneIndex * 17}, ${1337 + sceneIndex * 31}, ${7 + sceneIndex * 11}, 99);
+const PARTICLES = Array.from({ length: 54 }, () => ({
+  x: rng() * W,
+  y: rng() * H,
+  vx: (rng() - 0.5) * 50,
+  vy: (rng() - 0.5) * 35 - 15,
+  r: 1.5 + rng() * 3.5,
+  alpha: 0.3 + rng() * 0.5
+}));
+
+// Spring dynamics function
+function spring(t, delay = 0, tension = 160, friction = 14) {
+  const dt = t - delay;
+  if (dt <= 0) return 0;
+  const omega = Math.sqrt(tension);
+  const zeta = friction / (2 * omega);
+  if (zeta < 1) {
+    const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+    return 1 - Math.exp(-zeta * omega * dt) * (Math.cos(omegaD * dt) + (zeta * omega / omegaD) * Math.sin(omegaD * dt));
+  }
+  return 1 - Math.exp(-omega * dt);
+}
+
+const THEME = ${JSON.stringify(theme)};
+const CAPTION = ${JSON.stringify(caption)};
+const NARRATION = ${JSON.stringify(narration)};
+const TAG = ${JSON.stringify(pal.tag)};
+const ACCENT = ${JSON.stringify(pal.accent)};
+const ACCENT2 = ${JSON.stringify(pal.accent2)};
+const BG0 = ${JSON.stringify(pal.bg0)};
+const BG1 = ${JSON.stringify(pal.bg1)};
+const BG2 = ${JSON.stringify(pal.bg2)};
+const IMAGE_SRC = ${JSON.stringify(imageDataUri)};
+
+let cachedImage = null;
+if (IMAGE_SRC) {
+  cachedImage = new Image();
+  cachedImage.src = IMAGE_SRC;
+}
+
+window.seek = async (t) => {
+  // ── 1. Dynamic Moving Gradient Background ────────────────────────────────
+  const cx = W / 2 + Math.sin(t * 0.7) * 160;
+  const cy = H / 2 + Math.cos(t * 0.5) * 90;
+  const bgGrad = ctx.createRadialGradient(cx, cy, 60, W / 2, H / 2, W * 0.85);
+  bgGrad.addColorStop(0, BG0);
+  bgGrad.addColorStop(0.55, BG1);
+  bgGrad.addColorStop(1, BG2);
+  ctx.fillStyle = bgGrad;
+  ctx.fillRect(0, 0, W, H);
+
+  // ── 2. Subtle Moving Perspective Grid ───────────────────────────────────
+  ctx.save();
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.04)';
+  ctx.lineWidth = 1;
+  const gridShift = (t * 30) % 60;
+  for (let x = 0; x <= W; x += 60) {
+    ctx.beginPath();
+    ctx.moveTo(x, 0);
+    ctx.lineTo(x, H);
+    ctx.stroke();
+  }
+  for (let y = gridShift; y <= H; y += 60) {
+    ctx.beginPath();
+    ctx.moveTo(0, y);
+    ctx.lineTo(W, y);
+    ctx.stroke();
+  }
+  ctx.restore();
+
+  // ── 3. Floating Dust & Energy Particles ──────────────────────────────────
+  ctx.save();
+  for (let i = 0; i < PARTICLES.length; i++) {
+    const p = PARTICLES[i];
+    const px = (p.x + p.vx * t + W * 10) % W;
+    const py = (p.y + p.vy * t + H * 10) % H;
+    const pulse = 0.4 + 0.6 * Math.sin(t * 3.2 + i * 0.5);
+    ctx.fillStyle = ACCENT;
+    ctx.globalAlpha = p.alpha * pulse * 0.7;
+    ctx.beginPath();
+    ctx.arc(px, py, p.r, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  ctx.restore();
+
+  // ── 4. Central Graphic Card matching Theme ──────────────────────────────
+  ctx.save();
+  const cardSpring = spring(t, 0.08, 140, 13);
+  const cardScale = Math.min(1.04, Math.max(0, cardSpring));
+  const cardY = H * 0.40 + (1 - cardSpring) * 50;
+  ctx.translate(W / 2, cardY);
+  ctx.scale(cardScale, cardScale);
+
+  const cardW = Math.round(W * 0.55);
+  const cardH = Math.round(H * 0.38);
+
+  // Card backdrop with glassmorphic border
+  ctx.fillStyle = 'rgba(11, 17, 28, 0.82)';
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.12)';
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.roundRect(-cardW / 2, -cardH / 2, cardW, cardH, 20);
+  ctx.fill();
+  ctx.stroke();
+
+  // Accent edge highlight
+  ctx.strokeStyle = ACCENT;
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.moveTo(-cardW / 2 + 30, -cardH / 2);
+  ctx.lineTo(cardW / 2 - 30, -cardH / 2);
+  ctx.stroke();
+
+  if (THEME === 'code') {
+    // IDE Titlebar
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.05)';
+    ctx.beginPath();
+    ctx.roundRect(-cardW / 2, -cardH / 2, cardW, 40, [20, 20, 0, 0]);
+    ctx.fill();
+    // Window dots
+    ctx.fillStyle = '#ff5f56'; ctx.beginPath(); ctx.arc(-cardW / 2 + 25, -cardH / 2 + 20, 6, 0, Math.PI * 2); ctx.fill();
+    ctx.fillStyle = '#ffbd2e'; ctx.beginPath(); ctx.arc(-cardW / 2 + 45, -cardH / 2 + 20, 6, 0, Math.PI * 2); ctx.fill();
+    ctx.fillStyle = '#27c93f'; ctx.beginPath(); ctx.arc(-cardW / 2 + 65, -cardH / 2 + 20, 6, 0, Math.PI * 2); ctx.fill();
+    // Tab title
+    ctx.font = '14px monospace';
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.6)';
+    ctx.textAlign = 'left';
+    ctx.fillText('scene-pipeline.js', -cardW / 2 + 90, -cardH / 2 + 25);
+
+    // Code lines with typing effect
+    const codeLines = [
+      'import { FrameForge } from "@amg555/frameforge";',
+      'const engine = new FrameForge.AnimationEngine({ t });',
+      'await engine.renderScene({',
+      '  status: "ACTIVE_24FPS",',
+      '  fidelity: "BROADCAST_BT709"',
+      '});'
+    ];
+    ctx.font = '18px "Fira Code", monospace';
+    const typeProg = Math.min(1, t / (window.DURATION * 0.75));
+    const totalChars = codeLines.join('\\n').length;
+    let charsToShow = Math.floor(totalChars * typeProg);
+
+    let lineY = -cardH / 2 + 80;
+    for (let l = 0; l < codeLines.length; l++) {
+      const line = codeLines[l];
+      const sliceLen = Math.min(line.length, charsToShow);
+      const textToDraw = line.slice(0, sliceLen);
+      charsToShow = Math.max(0, charsToShow - line.length - 1);
+
+      // Line number
+      ctx.fillStyle = 'rgba(255, 255, 255, 0.25)';
+      ctx.fillText(String(l + 1).padStart(2, '0'), -cardW / 2 + 30, lineY);
+      // Syntax text
+      ctx.fillStyle = l === 0 ? ACCENT : l === 1 ? ACCENT2 : '#e2e8f0';
+      ctx.fillText(textToDraw, -cardW / 2 + 75, lineY);
+      lineY += 32;
+    }
+  } else if (THEME === 'chart') {
+    // Animated bar chart + metrics
+    const bars = 8;
+    const barW = (cardW - 140) / bars;
+    const startX = -cardW / 2 + 70;
+    const baseLine = cardH / 2 - 50;
+
+    for (let b = 0; b < bars; b++) {
+      const barSpring = spring(t, 0.15 + b * 0.05, 120, 12);
+      const targetH = 50 + ((b * 37) % 140);
+      const curH = targetH * Math.min(1.05, Math.max(0, barSpring));
+      const bx = startX + b * barW;
+      const by = baseLine - curH;
+
+      const barGrad = ctx.createLinearGradient(0, by, 0, baseLine);
+      barGrad.addColorStop(0, ACCENT);
+      barGrad.addColorStop(1, ACCENT2);
+      ctx.fillStyle = barGrad;
+      ctx.beginPath();
+      ctx.roundRect(bx, by, barW - 12, curH, 6);
+      ctx.fill();
+    }
+    // Animated Counter
+    const counterVal = Math.round(spring(t, 0.2, 100, 10) * 98.4);
+    ctx.font = 'bold 36px monospace';
+    ctx.fillStyle = '#ffffff';
+    ctx.textAlign = 'right';
+    ctx.fillText(counterVal + '% METRIC GAIN', cardW / 2 - 40, -cardH / 2 + 50);
+  } else if (THEME === 'nodes') {
+    // Interconnected pulsing network nodes
+    const nodeCoords = [
+      [-cardW * 0.35, -30], [-cardW * 0.15, 40], [0, -50],
+      [cardW * 0.15, 30], [cardW * 0.35, -20]
+    ];
+    // Connections
+    ctx.strokeStyle = 'rgba(56, 189, 248, 0.35)';
+    ctx.lineWidth = 2;
+    for (let i = 0; i < nodeCoords.length - 1; i++) {
+      ctx.beginPath();
+      ctx.moveTo(nodeCoords[i][0], nodeCoords[i][1]);
+      ctx.lineTo(nodeCoords[i + 1][0], nodeCoords[i + 1][1]);
+      ctx.stroke();
+
+      // Energy packet along connection
+      const packetPos = (t * 0.8 + i * 0.25) % 1;
+      const ex = nodeCoords[i][0] + (nodeCoords[i + 1][0] - nodeCoords[i][0]) * packetPos;
+      const ey = nodeCoords[i][1] + (nodeCoords[i + 1][1] - nodeCoords[i][1]) * packetPos;
+      ctx.fillStyle = ACCENT;
+      ctx.beginPath();
+      ctx.arc(ex, ey, 5, 0, Math.PI * 2);
+      ctx.fill();
+    }
+    // Nodes
+    for (let i = 0; i < nodeCoords.length; i++) {
+      const [nx, ny] = nodeCoords[i];
+      const pulse = 1 + 0.25 * Math.sin(t * 4 + i);
+      ctx.fillStyle = ACCENT2;
+      ctx.beginPath();
+      ctx.arc(nx, ny, 14 * pulse, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.fillStyle = '#ffffff';
+      ctx.beginPath();
+      ctx.arc(nx, ny, 6, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  } else if (THEME === 'image' && cachedImage && cachedImage.complete && cachedImage.naturalWidth > 0) {
+    // Ken-Burns floating image
+    const zoom = 1.0 + (t / window.DURATION) * 0.07;
+    ctx.save();
+    ctx.beginPath();
+    ctx.roundRect(-cardW / 2 + 12, -cardH / 2 + 12, cardW - 24, cardH - 24, 14);
+    ctx.clip();
+    ctx.scale(zoom, zoom);
+    ctx.drawImage(cachedImage, -cardW / 2 + 12, -cardH / 2 + 12, cardW - 24, cardH - 24);
+    ctx.restore();
+  } else {
+    // Kinetic Audio Spectrum Bars
+    const bars = 28;
+    const barW = (cardW - 80) / bars;
+    const startX = -cardW / 2 + 40;
+    for (let b = 0; b < bars; b++) {
+      const phase = t * 4.5 + b * 0.3;
+      const hVal = 25 + 95 * Math.abs(Math.sin(phase) * Math.cos(phase * 0.8));
+      const bx = startX + b * barW;
+      const by = 20 - hVal / 2;
+
+      const barGrad = ctx.createLinearGradient(0, by, 0, by + hVal);
+      barGrad.addColorStop(0, ACCENT);
+      barGrad.addColorStop(1, ACCENT2);
+      ctx.fillStyle = barGrad;
+      ctx.beginPath();
+      ctx.roundRect(bx, by, barW - 6, hVal, 4);
+      ctx.fill();
+    }
+  }
+
+  // Tag Badge
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.08)';
+  ctx.beginPath();
+  ctx.roundRect(-cardW / 2 + 25, -cardH / 2 + 20, 140, 30, 15);
+  ctx.fill();
+  ctx.font = 'bold 13px system-ui, sans-serif';
+  ctx.fillStyle = ACCENT;
+  ctx.textAlign = 'center';
+  ctx.fillText(TAG, -cardW / 2 + 95, -cardH / 2 + 40);
+
+  ctx.restore();
+
+  // ── 5. Kinetic Typography with Multilingual / Malayalam Support ─────────
+  ctx.save();
+  const textSpring = spring(t, 0.22, 150, 13);
+  const textY = H * 0.77 + (1 - textSpring) * 45;
+  const textAlpha = Math.min(1, Math.max(0, textSpring));
+
+  ctx.globalAlpha = textAlpha;
+  ctx.textAlign = 'center';
+
+  // Primary Caption / Headline
+  ctx.font = 'bold 54px ' + ${JSON.stringify(FONT_STACK)};
+  ctx.shadowColor = 'rgba(0, 0, 0, 0.95)';
+  ctx.shadowBlur = 20;
+  ctx.shadowOffsetY = 6;
+  ctx.fillStyle = '#ffffff';
+  ctx.fillText(CAPTION, W / 2, textY);
+
+  // Subtitle / Narration preview
+  if (NARRATION) {
+    ctx.font = '400 28px ' + ${JSON.stringify(FONT_STACK)};
+    ctx.fillStyle = 'rgba(226, 232, 240, 0.88)';
+    ctx.shadowBlur = 12;
+    const cleanNarr = NARRATION.length > 95 ? NARRATION.slice(0, 95) + '...' : NARRATION;
+    ctx.fillText(cleanNarr, W / 2, textY + 62);
+  }
+  ctx.restore();
+
+  // ── 6. Progress Scrubber ────────────────────────────────────────────────
+  ctx.save();
+  const progress = Math.min(1, Math.max(0, t / window.DURATION));
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.08)';
+  ctx.fillRect(0, H - 8, W, 8);
+
+  const progGrad = ctx.createLinearGradient(0, 0, W, 0);
+  progGrad.addColorStop(0, ACCENT);
+  progGrad.addColorStop(1, ACCENT2);
+  ctx.fillStyle = progGrad;
+  ctx.fillRect(0, H - 8, W * progress, 8);
+  ctx.restore();
+};
+window.ready = true;
+</script>
+</body>
+</html>`;
+}
+
+module.exports = {
+  generateSceneHtml,
+  detectTheme,
+  FONT_STACK,
+};

package/src/workflows/assets.js

@@ -88,6 +88,10 @@ async function runAssets({ productionId, scenes, parallelism = 1, skipTts = fals
         caption:   scene.caption,
         camera:    scene.camera_hint || scene.camera || 'static',
         focalPoint: scene.focal_point || null,
+        narration: scene.narration || '',
+        visualDescription: scene.visual_description || scene.narration || '',
+        musicMood: scene.music_mood || 'neutral',
+        language:  scene.language || '',
       };
     }));
     results.push(...batchResults);

package/src/workflows/render.js

@@ -42,13 +42,18 @@ async function runRender({ productionId, sceneAssets, withMusic = true, musicVol
     const idx = asset.sceneId - 1;
     try {
       const scenePath = renderer.renderScene({
-        sceneIndex: idx,
-        imagePath:  asset.imagePath,
-        videoPath:  asset.videoPath,
-        voicePath:  asset.voicePath,
-        caption:    asset.caption || '',
-        camera:     asset.camera  || 'static',
-        focalPoint: asset.focalPoint || null,
+        sceneIndex:        idx,
+        imagePath:         asset.imagePath,
+        videoPath:         asset.videoPath,
+        voicePath:         asset.voicePath,
+        caption:           asset.caption || '',
+        narration:         asset.narration || '',
+        visualDescription: asset.visualDescription || '',
+        visualType:        asset.visualType || 'code_animation',
+        musicMood:         asset.musicMood || 'neutral',
+        language:          asset.language || '',
+        camera:            asset.camera  || 'static',
+        focalPoint:        asset.focalPoint || null,
         renderWidth,
         renderHeight,
       });