@amg555/frameforge-mcp 2.3.5 → 2.3.6

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.3.6] — 2026-11-09
+
+### Added
+- **Full-Canvas Cinematic Procedural Entities** (`src/video-renderer/scene-animator.js`):
+  - Completely eliminated the rigid PPT card slideshow pattern. Every scene now renders a living, full-canvas animated universe.
+  - 3D Celestial Orbital Simulation: Earth with rotating longitude/latitude wireframes, tilted elliptical orbits, orbiting satellites with solar panels, expanding spherical radio wavefront pulses, and ground target beacon.
+  - 3D Rotating DNA Double-Helix: Sinusoidal backbones with perspective depth, nucleotide base-pair rungs, and molecular spore drift.
+  - Full-Canvas Financial Candlesticks: Realistic Japanese candlesticks with upper/lower wicks, glowing Exponential Moving Average (EMA) ribbon curve, volume bars, and price tickers.
+  - 3D Tactical Radar Globe: Rotating spherical grid with 360-degree radar sweep sector and pinging incident coordinates.
+  - 3D Wireframe Polyhedra: Pure mathematical 3D perspective projection (octahedron/cubes) with coordinate axes.
+  - Historical Milestone Roadmaps: Flowing chronological paths with golden era seals and progressive illumination pulses.
+  - Full-Canvas Neural Mesh: 4-tier neural network with glowing energy packets traveling along active synapses.
+- **Direct Agent Code & HTML Execution** (`src/video-renderer/renderer.js`, `src/mcp-server/server.js`, `src/workflows/render.js`, `src/workflows/assets.js`):
+  - Added support for `html` (complete page conforming to `window.DURATION` and `window.seek(t)`) and `code` (canvas drawing instructions for `t`) across `create_video_from_script`, `render_from_scenes`, and workflow pipelines.
+  - Enables Claude Code, Opus 5.5, Cursor, and IBM Bob to write custom animation programs that FrameForge renders directly without template overrides.
+  - Added `wrapCodeInHarnessHtml()` helper to embed pure Canvas drawing code into a compliant virtual-clock harness page.
+- **Cinematic Broadcast Lower-Third Overlays**:
+  - Replaced repetitive center-card text with glassmorphic lower-third broadcast banners leaving the upper 75% of the frame completely open for motion graphics.
+  - Accent color left tab, tag pills, high-contrast drop-shadow typography, and subtle bottom progress bar.
+- **Multilingual Typography Integration**:
+  - Full native DirectWrite/HarfBuzz font support for Malayalam (`Nirmala UI`, `Noto Sans Malayalam`), Hindi/Devanagari, Tamil, Telugu, Arabic, and CJK with zero broken glyphs.
+
+---
+
 ## [2.3.5] — 2026-11-09
 
 ### Added

package/README.md

@@ -9,7 +9,7 @@
 [![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.5-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.3.6-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-539%20passing-brightgreen.svg)](#testing)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.3.5",
+  "version": "2.3.6",
   "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"

package/plugins/video-pipeline/skills/video-pipeline/SKILL.md

@@ -137,21 +137,36 @@ npm run setup
 
 ## Workflow (step-by-step)
 
-### Path 1 — Agent-First (FFmpeg + AI images)
+### Path 1 — Agent-First (Code-Driven Motion Graphics or Direct Custom Code)
 
-**You are already running an LLM — use it.** Write the scenes yourself and hand
-them to FrameForge for rendering. No `GROQ_API_KEY` or any other LLM key needed.
-FrameForge only runs FFmpeg, TTS, and image generation:
+**You are already running an LLM (Claude Code / Opus 5.5 / Cursor / Bob) — use it.**
+Write the scenes yourself and hand them to FrameForge for rendering. No external API key needed.
+FrameForge renders full-canvas, broadcast-quality motion graphics (24fps pure function of `t`) with zero slideshow/card patterns:
 
-```
+- **Option A — Natural Description:** Provide `visual_description` (e.g. "Earth rotating with 4 satellite orbits and microwave beams intersecting"). FrameForge automatically synthesizes a full-canvas procedural 3D/2D animation entity (orbital mechanics, 3D DNA helix, candlestick charts, neural mesh, 3D wireframe polyhedra).
+- **Option B — Direct Agent Code:** Provide `html` (complete page with `window.DURATION` & `window.seek(t)`) or `code` (canvas drawing instructions for `t`). FrameForge executes your program directly via headless Chromium.
+- **Option C — Multilingual & Regional Scripts:** Pass `language: "ml"` (Malayalam), `"hi"` (Hindi), etc. Native DirectWrite/HarfBuzz font stacks (`Nirmala UI`, `Noto Sans Malayalam`) render conjuncts without broken glyphs.
+
+```js
 create_video_from_script({
+  topic: "GPS Satellites and Orbital Mechanics",
+  style: "cosmic_space",
+  language: "en",
   scenes: [
-    { narration: "WiFi sends data as radio waves...", caption: "RADIO WAVES",
-      visual_description: "router emitting waves, flat illustration" },
-    { narration: "Your device picks up the signal...", caption: "YOUR DEVICE",
-      visual_description: "laptop receiving signal, clean diagram" }
+    {
+      narration: "GPS uses trilateration from atomic clock satellites orbiting Earth.",
+      caption: "TRILATERATION",
+      visual_description: "3D Earth rotating with 4 satellite orbits and microwave beams converging",
+      // Optional: you can pass your own Canvas code or complete HTML:
+      // code: "ctx.fillStyle = '#0c1116'; ctx.fillRect(0,0,W,H); ..."
+    },
+    {
+      narration: "Relativistic time dilation requires nanosecond daily corrections.",
+      caption: "TIME DILATION",
+      visual_description: "Quantum atomic clock oscillation with compounding nanosecond curve"
+    }
   ],
-  title: "How WiFi Works"
+  title: "How GPS Actually Works"
 })
 ```
 
@@ -160,8 +175,6 @@ Then deliver it:
 publish_video({ productionId, masterPath, channels: ["file"] })
 ```
 
-> **Image generation fallback:** If the configured image provider is unavailable, FrameForge automatically falls back to a dark-background placeholder per scene — the render completes. Switch to `PROVIDER_IMAGE=falai` for a more reliable free provider.
-
 ### Path 2 — Code-Driven Animated Video (Playwright + ffmpeg, no AI images)
 
 Use when: the user wants Remotion-style motion graphics, image gen is unavailable, or they ask for "animated video" or "make it look good". Every pixel is a pure function of time `t`.

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.5',   code.includes("version: '2.3.5'"));
+check('SERVER_INFO version 2.3.6',   code.includes("version: '2.3.6'"));
 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.5',        cfWorker.includes("'2.3.5'"));
+check('cf-worker version 2.3.6',        cfWorker.includes("'2.3.6'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/src/cli/make.js

@@ -410,6 +410,9 @@ async function runSingleVideo(args, topic, outDir, workflows) {
     skipImages,
     skipTts:      args.noTts,
     enableAiImages,
+    topic,
+    title,
+    style: args.style || '',
   });
   log('Assets', `✅  ${assetsResult.sceneCount} scenes prepared`);
 
@@ -418,6 +421,9 @@ async function runSingleVideo(args, topic, outDir, workflows) {
   const renderResult = await runRender({
     productionId,
     sceneAssets: assetsResult.sceneAssets,
+    topic,
+    title,
+    style: args.style || '',
   });
   if (!renderResult.passed) {
     throw new Error(`Quality gate FAILED: ${JSON.stringify(renderResult.qcReport?.checks?.filter(c => !c.passed).map(c => c.name))}`);

package/src/mcp-server/server.js

@@ -349,9 +349,14 @@ const TOOLS = {
         skipTts:      { type: 'boolean', default: false, description: 'Skip TTS synthesis (use audio_path in scenes)' },
         withMusic:    { type: 'boolean', default: true },
         musicVolume:  { type: 'number',  default: 0.07 },
+        topic:        { type: 'string',  description: 'Overall topic/genre for visual theme and aesthetic selection' },
+        style:        { type: 'string',  description: 'Visual style/theme override (e.g. cinematic_documentary, finance_executive, cyber_tech, retro_synthwave, nature_organic, hype_sports, minimal_luxury, breaking_news, cosmic_space)' },
+        theme:        { type: 'string',  description: 'Theme preset alias' },
+        title:        { type: 'string',  description: 'Video title' },
+        language:     { type: 'string',  description: 'BCP-47 language hint (e.g. ml, hi, en, ta)' },
       },
     },
-    handler: async ({ productionId, scenes, orientation = 'landscape', skipImages = false, skipTts = false, withMusic = true, musicVolume = 0.07 }) => {
+    handler: async ({ productionId, scenes, orientation = 'landscape', skipImages = false, skipTts = false, withMusic = true, musicVolume = 0.07, topic = '', style = '', theme = '', title = '', language = '' }) => {
       const syncFs = require('fs');
       const { runAssets }   = require('../workflows/assets');
       const { runRender }   = require('../workflows/render');
@@ -392,6 +397,11 @@ const TOOLS = {
         parallelism:  4,
         skipImages,
         skipTts,
+        topic,
+        style,
+        theme,
+        title,
+        language,
         imageWidth:  renderWidth,
         imageHeight: renderHeight,
       });
@@ -404,6 +414,11 @@ const TOOLS = {
         musicVolume,
         renderWidth,
         renderHeight,
+        topic,
+        style,
+        theme,
+        title,
+        language,
       });
 
       if (!renderResult.passed) {
@@ -518,8 +533,9 @@ Named presets (set EXTERNAL_PLATFORM_NAME to one of these and omit platformUrl):
     description: `Agent-first video creation. YOU (the IDE agent) provide the complete scenes array — FrameForge renders it.
 Features:
 - Code-driven animation and kinetic typography by default (broadcast quality, zero AI artifacts).
+- Supports direct agent/user code: pass "html" (complete page with window.seek(t)) or "code" (canvas drawing instructions for t).
+- Procedural full-canvas cinematic animations (celestial orbits, DNA helices, candlestick charts, neural nets, 3D wireframe geometry).
 - Supports manual user clips (video_path) and manual images (image_path).
-- Optional AI diffusion generation via enableAiImages: true.
 - No internal LLM or research required. Primary path for Claude Code, IBM Bob, Cursor, and any agentic IDE.
 
 Example scene:
@@ -527,6 +543,8 @@ Example scene:
   "narration": "The text spoken aloud in this scene",
   "caption": "OVERLAY TEXT",
   "visual_description": "Description of the scene visual / animation",
+  "html": "<!doctype html>... window.seek = async (t) => { ... }",
+  "code": "/* canvas drawing code for t */",
   "camera_hint": "zoom_in",
   "music_mood": "energetic",
   "image_path": "/optional/your/own/image.jpg",
@@ -537,7 +555,7 @@ Example scene:
       type: 'object',
       required: ['scenes'],
       properties: {
-        scenes:         { type: 'array',   description: 'Complete scenes array written by the agent. Each scene: { narration, caption, visual_description, camera_hint?, music_mood?, image_path?, video_path?, audio_path?, voice? }' },
+        scenes:         { type: 'array',   description: 'Complete scenes array written by the agent. Each scene: { narration, caption, visual_description, html?, code?, camera_hint?, music_mood?, image_path?, video_path?, audio_path?, voice? }' },
         title:          { type: 'string',  description: 'Video title' },
         orientation:    { type: 'string',  enum: ['landscape', 'portrait'], default: 'landscape', description: 'Output orientation. "landscape" = 1920×1080 (16:9, YouTube/desktop). "portrait" = 1080×1920 (9:16, TikTok/Reels/Shorts).' },
         voice:          { type: 'string',  description: 'edge-tts voice ID for all scenes, e.g. "ml-IN-MidhunNeural" (Malayalam male), "en-US-BrianNeural" (English). Per-scene voice field overrides this. Full list: edge-tts --list-voices' },
@@ -546,10 +564,13 @@ Example scene:
         parallelism:    { type: 'number',  default: 1, description: 'Concurrent TTS synthesis requests (default: 1).' },
         withMusic:      { type: 'boolean', default: true },
         musicVolume:    { type: 'number',  default: 0.07 },
+        topic:          { type: 'string',  description: 'Overall topic/genre for visual aesthetic and background motion (e.g. "Kerala history", "crypto finance", "AI robotics")' },
+        style:          { type: 'string',  description: 'Visual style/theme override (e.g. cinematic_documentary, finance_executive, cyber_tech, retro_synthwave, nature_organic, hype_sports, minimal_luxury, breaking_news, cosmic_space)' },
+        theme:          { type: 'string',  description: 'Theme preset alias' },
         productionId:   { type: 'string',  description: 'Optional — reuse an existing productionId' },
       },
     },
-    handler: async ({ scenes, title = 'FrameForge Video', orientation = 'landscape', voice, language, skipTts = false, parallelism = 1, withMusic = true, musicVolume = 0.07, productionId }) => {
+    handler: async ({ scenes, title = 'FrameForge Video', orientation = 'landscape', voice, language, skipTts = false, parallelism = 1, withMusic = true, musicVolume = 0.07, topic = '', style = '', theme = '', productionId }) => {
       const { runAssets } = require('../workflows/assets');
       const { runRender } = require('../workflows/render');
 
@@ -595,6 +616,12 @@ Example scene:
         video_path:         s.video_path         || null,
         audio_path:         s.audio_path         || null,
         voice:              s.voice              || null,  // per-scene voice override
+        html:               s.html               || null,
+        code:               s.code || s.animation_code || null,
+        topic:              s.topic              || topic || '',
+        style:              s.style              || style || '',
+        theme:              s.theme              || theme || '',
+        language:           s.language           || language || '',
         character:          s.character          || { character_id: 'none', pose: 'none', emotion: 'neutral', position: { x: 0.5, y: 0.8, scale: 1.0 } },
         focal_point:        s.focal_point        || { x: 0.5, y: 0.35, weight: 0.8 },
         overlay:            s.overlay            || { type: 'none' },
@@ -608,8 +635,31 @@ Example scene:
       const renderWidth  = orientation === 'portrait' ? 1080 : 1920;
       const renderHeight = orientation === 'portrait' ? 1920 : 1080;
 
-      const assetsResult = await runAssets({ productionId: pid, scenes: processedScenes, parallelism, skipTts, voice: resolvedVoice });
-      const renderResult = await runRender({ productionId: pid, sceneAssets: assetsResult.sceneAssets, withMusic, musicVolume, renderWidth, renderHeight });
+      const assetsResult = await runAssets({
+        productionId: pid,
+        scenes: processedScenes,
+        parallelism,
+        skipTts,
+        voice: resolvedVoice,
+        topic,
+        style,
+        theme,
+        title,
+        language,
+      });
+      const renderResult = await runRender({
+        productionId: pid,
+        sceneAssets: assetsResult.sceneAssets,
+        withMusic,
+        musicVolume,
+        renderWidth,
+        renderHeight,
+        topic,
+        style,
+        theme,
+        title,
+        language,
+      });
 
       if (!renderResult.passed) {
         return { productionId: pid, passed: false, qcReport: renderResult.qcReport };
@@ -1372,7 +1422,7 @@ Operations (used with action="edit"):
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.3.5',
+  version: '2.3.6',
 };
 
 const CAPABILITIES = {

package/src/video-renderer/renderer.js

@@ -29,7 +29,7 @@ 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 { generateSceneHtml, wrapCodeInHarnessHtml, detectAesthetic, AESTHETICS } = require('./scene-animator');
 const { findChromePath }                      = require('../harness/lib/browser.mjs');
 
 // ── Cross-platform Indic / Malayalam font resolver ────────────────────────────
@@ -117,10 +117,16 @@ class VideoRenderer {
    *   narration?:         string,
    *   visualDescription?: string,
    *   visualType?:        string,
+   *   topic?:             string,
+   *   style?:             string,
+   *   theme?:             string,
+   *   title?:             string,
    *   language?:          string,
    *   musicMood?:         string,
    *   camera?:            string,   // camera_hint from scene schema v1.0.0
    *   focalPoint?:        { x: number, y: number },
+   *   html?:              string,   // direct agent/user pure-t HTML scene
+   *   code?:              string,   // direct agent/user canvas seek(t) drawing code
    *   manifest?:          ArtifactManifest  // optional — enables idempotency
    *   renderWidth?:       number,   // default 1920
    *   renderHeight?:      number,   // default 1080
@@ -137,10 +143,16 @@ class VideoRenderer {
     narration = '',
     visualDescription = '',
     visualType = 'code_animation',
+    topic = '',
+    style = '',
+    theme = '',
+    title = '',
     language = '',
     musicMood = 'neutral',
     camera,
     focalPoint,
+    html = null,
+    code = null,
     manifest,
     renderWidth = 1920,
     renderHeight = 1080,
@@ -212,6 +224,13 @@ class VideoRenderer {
           caption,
           narration,
           visualDescription,
+          topic,
+          style,
+          theme,
+          title,
+          language,
+          html,
+          code,
           clampedDur,
           renderWidth,
           renderHeight,
@@ -237,16 +256,13 @@ class VideoRenderer {
       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];
+      const aestheticKey = detectAesthetic({ topic, style, theme, title, narration, visualDescription, caption, language, musicMood });
+      const aesthetic = AESTHETICS[aestheticKey] || AESTHETICS.cyber_tech;
+      const pal = aesthetic.palettes[sceneIndex % aesthetic.palettes.length];
+      const c0 = (pal.bg0 || '#0d1117').replace('#', '');
+      const c1 = (pal.accent || '#38bdf8').replace('#', '');
       inputArgs = [
-        '-f', 'lavfi', '-i', `gradients=s=${renderWidth}x${renderHeight}:r=30:c0=0x${pal.bg}:c1=0x${pal.c1}:speed=0.5:type=radial`,
+        '-f', 'lavfi', '-i', `gradients=s=${renderWidth}x${renderHeight}:r=30:c0=0x${c0}:c1=0x${c1}:speed=0.5:type=radial`,
         '-i', voicePath,
       ];
       const vfFilters = ['vignette=PI/4'];
@@ -289,6 +305,13 @@ class VideoRenderer {
     caption,
     narration,
     visualDescription,
+    topic = '',
+    style = '',
+    theme = '',
+    title = '',
+    language = '',
+    html = null,
+    code = null,
     clampedDur,
     renderWidth,
     renderHeight,
@@ -297,17 +320,40 @@ class VideoRenderer {
     manifest,
     musicMood,
   }) {
-    const htmlContent = generateSceneHtml({
-      caption,
-      narration,
-      visualDescription,
-      imagePath,
-      duration: clampedDur,
-      width: renderWidth,
-      height: renderHeight,
-      sceneIndex,
-      musicMood,
-    });
+    let htmlContent;
+    if (html && typeof html === 'string' && html.trim().length > 0) {
+      htmlContent = html;
+      if (!htmlContent.includes('window.DURATION')) {
+        htmlContent = htmlContent.replace('<script>', `<script>\nwindow.DURATION = ${clampedDur};\n`);
+      }
+    } else if (code && typeof code === 'string' && code.trim().length > 0) {
+      htmlContent = wrapCodeInHarnessHtml({
+        code,
+        duration: clampedDur,
+        width: renderWidth,
+        height: renderHeight,
+        language,
+        style,
+        topic,
+      });
+    } else {
+      htmlContent = generateSceneHtml({
+        caption,
+        narration,
+        visualDescription,
+        imagePath,
+        topic,
+        style,
+        theme,
+        title,
+        language,
+        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`);