@amg555/frameforge-mcp 2.4.9 → 2.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.9",
+  "version": "2.4.10",
   "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 23 MCP tools.",
   "publishConfig": {
     "access": "public"

package/plugins/video-pipeline/skills/html-renderer/references/motion-craft.md

@@ -89,3 +89,4 @@ Never deliver rendered video blind. The production harness must execute automate
 2. **Luminance / Exposure**: Non-blown ($< 96\%$ overexposure).
 3. **Compositional Distribution**: Not corner-confined ($> 12\%$ bbox coverage).
 4. **Motion Delta Verification**: Test frame delta between $t = 30\%$ and $t = 70\%$ to guarantee continuous animation.
+

package/plugins/video-pipeline/skills/html-renderer/references/render-contract.md

@@ -63,3 +63,4 @@ Output MP4s must comply with broadcast and streaming color standards:
 - **Color Matrix**: `BT.709` tags:
   `-colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv`
 - **Audio Synchronization**: Exact audio mux with 18dB voiceover sidechain ducking.
+

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.4.9',   code.includes("version: '2.4.9'"));
+check('SERVER_INFO version 2.4.10',   code.includes("version: '2.4.10'"));
 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('edit_video tool defined', code.includes('edit_video'));
@@ -303,7 +303,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.4.9',        cfWorker.includes("'2.4.9'"));
+check('cf-worker version 2.4.10',        cfWorker.includes("'2.4.10'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/src/harness/lib/verify-quality.mjs

@@ -249,3 +249,4 @@ export async function verifySceneQuality({
     sheetPath: renderedSheetPath,
   };
 }
+

package/src/mcp-server/server.js

@@ -96,7 +96,7 @@ const TOOLS = {
         claims:          { type: 'array' },
         topic:           { type: 'string' },
         style:           { type: 'string', default: 'informative', description: 'e.g. "educational", "comedic", "documentary", "tutorial", "vlog"' },
-        persona:         { type: 'string', default: 'video host', description: 'Who the narrator is, e.g. "travel blogger", "tech reviewer"' },
+        persona:         { type: 'string', default: 'narrator', description: 'Who the narrator is, e.g. "narrator", "travel blogger", "tech reviewer"' },
         format:          { type: 'string', default: 'YouTube video', description: 'e.g. "YouTube short", "Instagram reel", "long-form tutorial"' },
         language:        { type: 'string', default: 'en', description: 'BCP-47 language code for the script' },
         sceneCount:      { type: 'number', default: 55, description: 'Target number of scenes' },
@@ -587,10 +587,11 @@ Example scene:
         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' },
         showCaptions:   { type: 'boolean', default: false, description: 'Display on-screen synchronized subtitles/captions. Default false (clean canvas without text unless explicitly requested in prompt).' },
+        showAnchor:     { type: 'boolean', default: false, description: 'Display on-screen anchor/presenter character. Default false (no anchor unless explicitly requested in prompt).' },
         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, topic = '', style = '', theme = '', showCaptions = false, productionId }) => {
+    handler: async ({ scenes, title = 'FrameForge Video', orientation = 'landscape', voice, language, skipTts = false, parallelism = 1, withMusic = true, musicVolume = 0.07, topic = '', style = '', theme = '', showCaptions = false, showAnchor = false, productionId }) => {
       const { runAssets } = require('../workflows/assets');
       const { runRender } = require('../workflows/render');
 
@@ -670,6 +671,7 @@ Example scene:
         title,
         language,
         showCaptions,
+        showAnchor,
       });
       const renderResult = await runRender({
         productionId: pid,
@@ -684,6 +686,7 @@ Example scene:
         title,
         language,
         showCaptions,
+        showAnchor,
       });
 
       if (!renderResult.passed) {
@@ -1861,7 +1864,7 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.4.9',
+  version: '2.4.10',
 };
 
 const CAPABILITIES = {

package/src/video-renderer/renderer.js

@@ -174,11 +174,16 @@ class VideoRenderer {
     clipVolume = 0,
     colorGrade = null,
     showCaptions = false,
+    showAnchor = false,
   } = {}) {
     const effectiveShowCaptions = Boolean(
       showCaptions ||
       process.env.FRAMEFORGE_SHOW_CAPTIONS === '1'
     );
+    const effectiveShowAnchor = Boolean(
+      showAnchor ||
+      process.env.FRAMEFORGE_SHOW_ANCHOR === '1'
+    );
     const outputPath = path.join(this.vdir, `scene_${sceneIndex}_out.mp4`);
 
     // Idempotency: skip if already rendered and manifest says so
@@ -419,7 +424,8 @@ class VideoRenderer {
         height: renderHeight,
         sceneIndex,
         musicMood,
-        showCaptions,
+        showCaptions: effectiveShowCaptions,
+        showAnchor: effectiveShowAnchor,
         camera: effectiveCam,
         cameraHint: effectiveCam,
       });

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

@@ -279,15 +279,147 @@ function detectAesthetic({
   return 'cyber_tech';
 }
 
+// ── Anchor Requested Detector ───────────────────────────────────────────────
+/** Returns true ONLY if caller explicitly asks for an on-screen anchor, presenter, host, avatar, or talking head in prompt. */
+function detectAnchorRequested(text = '') {
+  if (!text || typeof text !== 'string') return false;
+  return /(?:with|show|display|include|enable|add)\s+(?:an?\s+)?(?:anchor|presenter|host|avatar|spokesperson|talking\s+head|narrator\s+character)|(?:anchor|presenter|host)\s*[:=]\s*(?:true|yes|1|on|always)/i.test(text);
+}
+
 // ── Component Theme Detection ──────────────────────────────────────────────────
 /**
  * Detect the graphic entity to render on the full canvas for a given scene.
  */
-function detectComponentTheme({ visualDescription = '', visual_description = '', prompt = '', caption = '', narration = '', topic = '', imagePath = null, aesthetic = 'cyber_tech' } = {}) {
+function detectComponentTheme({
+  visualDescription = '',
+  visual_description = '',
+  prompt = '',
+  caption = '',
+  narration = '',
+  topic = '',
+  imagePath = null,
+  aesthetic = 'cyber_tech',
+  anchorWanted = true,
+} = {}) {
   if (imagePath) return 'image';
   const visDesc = visualDescription || visual_description || prompt || '';
   const text = `${visDesc} ${caption} ${narration} ${topic}`.toLowerCase();
 
+  // If anchor is NOT requested, suppress all humanoid doodle anchor characters
+  // and route to non-anchor procedural visual archetypes
+  if (!anchorWanted) {
+    // 1. Versus / Comparison / Split Screen
+    if (/(?:^|[^\w])(versus|vs|comparison|compare|pros and cons|pros vs cons|difference between|dichotomy|contrast|side-by-side|before and after|before vs after|split-screen|split screen|modern vs ancient|modern vs prehistoric|then and now|evolution of human)(?:[^\w]|$)/i.test(text)
+        || /വ്യത്യാസം|താരതമ്യം|എതിര്|പോരാട്ടം|തമ്മിൽ|തുലനം|താരതമ്യപ്പെടുത്തൽ/.test(text)) {
+      return 'versus_comparison';
+    }
+
+    // 2. Magnification / Microscope / Fiber / Macro Inspection / Lice
+    if (/(?:^|[^\w])(magnify|magnification|zoom|microscopic|microscope|macro|close up|closeup|inspection|loupe|examine|scrutiny|detail|focal point|focus in|specimen|fiber|weave|parasite|lice|louse)(?:[^\w]|$)/i.test(text)
+        || /സൂക്ഷ്മ|പരിശോധന|വലുതാക്കി കാണുക|സൂക്ഷ്മമായി|നിരീക്ഷണം|മൈക്രോസ്കോപ്പ്|പേൻ/.test(text)) {
+      return 'magnification_focus';
+    }
+
+    // 3. Cognitive Insight / Psychology / Brain / Eureka / Thought / Future Planning / Shame Reflection
+    if (/(?:^|[^\w])(mind|psychology|cognitive|brain|insight|revelation|eureka|intuition|subconscious|thinking|thought|contemplation|intelligence|mental|awareness|neuroscience|concept|idea|epiphany|planning for tomorrow|future planning|foresight|shame|blush|embarrass|mirror|reflection|theory of mind|self-aware|identity)(?:[^\w]|$)/i.test(text)
+        || /മനസ്സ്|ബുദ്ധി|ചിന്ത|മനഃശാസ്ത്രം|ജ്ഞാനം|മസ്തിഷ്കം|ബോധം|കണ്ണാടി|പ്രതിഫലനം|നാണം/.test(text)) {
+      return 'cognitive_insight';
+    }
+
+    // 4. Mechanism / Physics / Machinery / Engine / Needle / Stitching / Cold
+    if (/(?:^|[^\w])(engine|gear|gears|motor|physics|aerodynamics|thrust|turbine|propulsion|piston|hydraulic|kinetic|machine|machinery|circuit|mechanics|thermodynamics|levers|pulley|needle|bone needle|sew|sewing|stitch|stitching|shiver|shivering|cold|freeze|freezing|ice|winter|protection flaw)(?:[^\w]|$)/i.test(text)
+        || /യന്ത്രം|എഞ്ചിൻ|ഭൗതികശാസ്ത്രം|പ്രവർത്തനം|ചലനം|മെക്കാനിസം|ഭൗതികം|സൂചി|തുന്ന|വിറയ്ക്കുക|തണുപ്പ്/.test(text)) {
+      return 'mechanism_physics';
+    }
+
+    // 5. Process / Pipeline / Stages / Assembly / Tribe / Community / Hierarchy / Royal Status
+    if (/(?:^|[^\w])(pipeline|workflow|step by step|steps|stages|phase|phases|production line|assembly|manufacturing|lifecycle|funnel|conveyor|sequence|how it works|how it is made|procedure|tribe|tribal|clan|stranger|meeting strangers|social language|status in society|hierarchy|royal robe|royal robes|crown|sceptre|ornaments|status and power|wealth authority)(?:[^\w]|$)/i.test(text)
+        || /ഘട്ടങ്ങൾ|പ്രക്രിയ|ഘട്ടം|ഉൽപ്പാദനം|വഴികൾ|പ്രവർത്തനരീതി|കൂട്ടമായി|സമൂഹം|ഗോത്രം|സാമൂഹിക സ്ഥാനം/.test(text)) {
+      return 'process_pipeline';
+    }
+
+    // 6. Radar Globe / World Map / Migration
+    if (/(?:^|[^\w])(globe|map|world|geography|radar|international|continent|territory|country|border|location|migration|migrating|migrate|africa highlighted|colder regions|out of africa)(?:[^\w]|$)/i.test(text)
+        || /ഭൂപടം|ലോകം|ഭൂഖണ്ഡം|ഭൂപട|നക്ശാ|ക്ലോബ്|കുടിയേറ്റം|മൈഗ്രേഷൻ/.test(text)) {
+      return 'radar_globe';
+    }
+
+    // 7. Celestial / Orbit
+    if (/(?:^|[^\w])(orbit|satellite|satellites|gps|planet|earth|mars|moon|galaxy|universe|solar|astronomy|gravity|space|telescope|interstellar)(?:[^\w]|$)/i.test(text)
+        || /ബഹിരാകാശ|ഗ്രഹം|ഉപഗ്രഹ|ഭൂമി|നക്ഷത്ര|പ്രപഞ്ച|अंतरिक्ष|ग्रह|तारा|വിൺവെളി/.test(text)) {
+      return 'celestial_orbit';
+    }
+
+    // 8. DNA / Biology
+    if (/(?:^|[^\w])(dna|helix|gene|cell|molecule|biology|organism|protein|virus|bacteria|medical|genetic|chromosome)(?:[^\w]|$)/i.test(text)
+        || /ഡിഎൻഎ|കോശം|തന്മാത്ര|ജീവശാസ്ത്ര|डीएनए|कोशिका/.test(text)) {
+      return 'dna_helix';
+    }
+
+    // 9. Code / Programming
+    if (/(?:^|[^\w])(code|function|syntax|api|javascript|python|typescript|json|sql|query|endpoint|algorithm|struct|cli|terminal|bash|shell|npm|git|compiler|linux|rust)(?:[^\w]|$)/.test(text)
+        || /കോഡിംഗ്|സോഫ്റ്റ്‌വെയർ|പ്രോഗ്രാമിംഗ്|कोड|सॉफ्टवेयर/.test(text)) {
+      return 'code';
+    }
+
+    // 10. Chart / Finance
+    if (/(?:^|[^\w])(chart|data|analytics|growth|graph|statistic|bars|volume|distribution|stock|crypto|bitcoin|market|invest|trading|inflation|economy|gdp|finance|gain|loss|bull|bear|candlestick|price)(?:[^\w]|$)/.test(text)
+        || /നിക്ഷേപ|ഓഹരി|വിപണി|പണം|ചാർട്ട്|शेयर|बाज़ार/.test(text)) {
+      return 'chart';
+    }
+
+    // 11. Nodes / Neural Net
+    if (/(?:^|[^\w])(network|nodes|neural network|neural net|distributed system|server mesh|deep learning)(?:[^\w]|$)/.test(text)
+        || /നെറ്റ്‌വർക്ക്|ശൃംഖല|नेटवर्क/.test(text)) {
+      return 'nodes';
+    }
+
+    // 12. 3D Isometric Geometry
+    if (/(?:^|[^\w])(cube|geometry|3d|wireframe|isometric|matrix|crystal|structure|polyhedron|dimension|architect|blueprint|math)(?:[^\w]|$)/.test(text)
+        || /ജ്യാമിതി|രൂപം|ത്രിമാന|संरचना/.test(text)) {
+      return 'isometric_geometry';
+    }
+
+    // 13. Speed Action / Hunter
+    if (/(?:^|[^\w])(speed|sprint|velocity|fast|run|race|motion|hunter|hunting|spear|savannah|blazing sun|mosquito)(?:[^\w]|$)/.test(text)
+        || /വേഗത|ഓട്ടം|കുന്തം|വേഗം/.test(text)) {
+      return 'speed_action';
+    }
+
+    // 14. Quote / Metric
+    if (/(?:^|[^\w])(quote|saying|proverb|statement|speech|wisdom)(?:[^\w]|$)/.test(text)) return 'quote';
+    if (/(?:^|[^\w])(metric|kpi|target|counter|percentage|ratio|score)(?:[^\w]|$)/.test(text)) return 'metric';
+
+    // 15. Timeline (strictly explicit roadmap/milestone chart requests only)
+    if (/(?:^|[^\w])(timeline|roadmap|milestone chart|milestone roadmap)(?:[^\w]|$)/i.test(text)
+        || /ടൈംലൈൻ|റോഡ്മാപ്പ്/.test(text)) {
+      return 'timeline';
+    }
+
+    // 16. Explainer Presentation (General visual lecture, whiteboard, tutorial, clothing topic, subscribe)
+    if (/(?:^|[^\w])(explain|explainer|presentation|lecture|teach|tutorial|whiteboard|blackboard|breakdown|guide|overview|theory|principles|fundamentals|introduction|summary|lesson|masterclass|subscribe|notification bell|outro|dress|dressing|wearing clothes|shirt|wardrobe|closet|hanger|outfit|wedding dress)(?:[^\w]|$)/i.test(text)
+        || /വിവരണം|പഠിപ്പിക്കുക|ക്ലാസ്|പാഠം|തത്വം|വിവരിക്കുക|സബ്സ്ക്രൈബ്|വസ്ത്രധാരണം/.test(text)) {
+      return 'explainer_presentation';
+    }
+
+    // 17. Waveform
+    if (/(?:^|[^\w])(waveform|audio|sound|equalizer|frequency|acoustics|hz|decibel|music spectrum|voice waveform)(?:[^\w]|$)/i.test(text)
+        || /ശബ്ദതരംഗം|തരംഗം|സംഗീതം|ധ്വനി/.test(text)) {
+      return 'waveform';
+    }
+
+    // Clean aesthetic fallbacks — strictly non-anchor
+    if (aesthetic === 'cosmic_space') return 'celestial_orbit';
+    if (aesthetic === 'cinematic_documentary') return 'explainer_presentation';
+    if (aesthetic === 'finance_executive') return 'chart';
+    if (aesthetic === 'nature_organic') return 'dna_helix';
+    if (aesthetic === 'breaking_news') return 'radar_globe';
+    if (aesthetic === 'cyber_tech') return 'nodes';
+    if (aesthetic === 'minimal_luxury') return 'explainer_presentation';
+    if (aesthetic === 'hype_sports') return 'speed_action';
+    return 'explainer_presentation';
+  }
+
   // ── Doodled Character Actions (Human Stories, History, Evolution, Daily Life) ──
   // 1. Microscope / Lice Theory / Parasite / Genetics (Scene 7)
   if (/(?:^|[^\w])(lice|louse|microscope|fiber|weave|parasite|lice evolution|genetic biology proof)(?:[^\w]|$)/i.test(text)
@@ -616,12 +748,18 @@ function generateSceneHtml({
   height = 1080,
   sceneIndex = 0,
   showCaptions = false,
+  showAnchor = false,
 } = {}) {
   const captionsWanted = Boolean(
     showCaptions ||
     detectCaptionsRequested(prompt || topic) ||
     process.env.FRAMEFORGE_SHOW_CAPTIONS === '1'
   );
+  const anchorWanted = Boolean(
+    showAnchor ||
+    detectAnchorRequested(prompt || topic) ||
+    process.env.FRAMEFORGE_SHOW_ANCHOR === '1'
+  );
   const aestheticKey = detectAesthetic({
     topic,
     style,
@@ -642,6 +780,7 @@ function generateSceneHtml({
     topic,
     imagePath,
     aesthetic: aestheticKey,
+    anchorWanted,
   });
   const clampedDur = Math.max(1, Number(duration) || 3);
 
@@ -734,6 +873,7 @@ function spring(t, delay = 0, tension = ${aesthetic.springTension}, friction = $
 }
 
 const SHOW_CAPTIONS = ${JSON.stringify(captionsWanted)};
+const SHOW_ANCHOR = ${JSON.stringify(anchorWanted)};
 const AESTHETIC = ${JSON.stringify(aestheticKey)};
 const BG_TYPE = ${JSON.stringify(aesthetic.backgroundType)};
 const COMP_THEME = ${JSON.stringify(compTheme)};
@@ -1006,6 +1146,7 @@ function drawMainScene(t) {
     showSpecular = false,
     seed = 100,
   } = {}) {
+    if (!SHOW_ANCHOR) return;
     ctx.save();
     ctx.translate(x, y);
     ctx.scale(scale, scale);
@@ -4345,6 +4486,7 @@ module.exports = {
   detectAesthetic,
   detectComponentTheme,
   detectCaptionsRequested,
+  detectAnchorRequested,
   getScriptFontStack,
   AESTHETICS,
   REGIONAL_FONTS,

package/src/workflows/assets.js

@@ -35,6 +35,8 @@ async function runAssets({
   theme = '',
   title = '',
   language = '',
+  showCaptions = false,
+  showAnchor = false,
 }) {
   const ttsGen    = new TTSProvider();
   const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
@@ -132,6 +134,8 @@ async function runAssets({
         speed:     scene.speed != null ? scene.speed : 1.0,
         clipVolume: scene.clip_volume != null ? scene.clip_volume : (scene.clipVolume != null ? scene.clipVolume : 0),
         colorGrade: scene.color_grade || scene.colorGrade || null,
+        showCaptions: scene.show_captions !== undefined ? scene.show_captions : (scene.showCaptions !== undefined ? scene.showCaptions : showCaptions),
+        showAnchor:   scene.show_anchor !== undefined ? scene.show_anchor : (scene.showAnchor !== undefined ? scene.showAnchor : showAnchor),
       };
     }));
     results.push(...batchResults);

package/src/workflows/render.js

@@ -37,6 +37,7 @@ async function runRender({
   title = '',
   language = '',
   showCaptions = false,
+  showAnchor = false,
 }) {
   const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
   const retryPol  = new RetryPolicy({ maxAttempts: 2, baseDelayMs: 15000 });
@@ -81,6 +82,7 @@ async function runRender({
         clipVolume:        asset.clipVolume,
         colorGrade:        asset.colorGrade,
         showCaptions:      asset.showCaptions !== undefined ? asset.showCaptions : showCaptions,
+        showAnchor:        asset.showAnchor !== undefined ? asset.showAnchor : showAnchor,
         renderWidth,
         renderHeight,
       });

package/src/workflows/script.js

@@ -15,6 +15,7 @@ const { LLMProvider }  = require('../pipeline/providers');
 const { StateMachine } = require('../pipeline/state-machine');
 const { RetryPolicy }  = require('../pipeline/retry-policy');
 const { Telemetry }    = require('../pipeline/telemetry');
+const { detectAnchorRequested } = require('../video-renderer/scene-animator');
 
 const os = require('os');
 const FILES_DIR = process.env.N8N_FILES_DIR || require('path').join(os.homedir(), '.frameforge-files');
@@ -98,7 +99,7 @@ async function runScript({
   claims,
   topic,
   style        = 'informative',
-  persona      = 'video host',
+  persona      = 'narrator',
   format       = 'YouTube video',
   language     = 'en',
   sceneCount   = 55,
@@ -116,13 +117,16 @@ async function runScript({
 
   const facts = claims.slice(0, 8).map(c => c.safe_wording || c.claim).join('; ');
 
-  // If targetDuration is given, adjust scene count guidance (≈ 4.5-5s per scene for high retention).
-  // No ceiling — long-form documentaries, lectures, and podcasts scale dynamically.
-  const targetScenes = targetDuration ? Math.max(8, Math.ceil(targetDuration / 4.5)) : Math.max(sceneCount, 55);
+  // Detect whether caller explicitly requested an on-screen anchor / presenter character
+  const anchorWanted = detectAnchorRequested(topic);
+  const effectivePersona = persona !== 'video host' ? persona : (anchorWanted ? 'video host' : 'narrator');
+
+  // Fast visual pacing: ≈ 2.5-3.2s per scene cut (never monolithic drags)
+  const targetScenes = targetDuration ? Math.max(8, Math.ceil(targetDuration / 2.8)) : Math.max(sceneCount, 55);
 
   const raw = await retryPol.executeStage('Script', async () => {
     const system = [
-      `You are a ${persona} writing a ${format} script.`,
+      `You are a ${effectivePersona} writing a ${format} script.`,
       `Style: ${style}. Language: ${language}.`,
       `Visual aesthetic for image prompts: ${imageStyle}.`,
       'Output ONLY raw JSON. No markdown. Start with { end with }.',
@@ -136,12 +140,16 @@ async function runScript({
       `STYLE: ${style}`,
       `LANGUAGE: ${language}`,
       '',
-      `Write exactly ${targetScenes} scenes (schema_version "2.0.0"). High visual pacing: 4-6 seconds per scene (12-25 spoken words). Never write monolithic 30-50s static scenes. Each scene must have:`,
+      `Write exactly ${targetScenes} scenes (schema_version "2.0.0"). Fast cinematic visual pacing: 2-3.5 seconds per scene (8-16 spoken words). Scene visual cuts must change frequently. Never write long monolithic scenes. Each scene duration matches the spoken voiceover audio.`,
+      anchorWanted
+        ? 'Include an on-screen host/anchor character in the scenes where appropriate.'
+        : 'Do NOT include on-screen host or anchor characters unless asked. Set character to { character_id: "none", pose: "none", emotion: "none" }. Visuals must be dynamic cinematic b-roll, motion graphics, animated diagrams, comparisons, processes, and data visualizations.',
+      'Each scene must have:',
       'scene_id (integer), schema_version "2.0.0",',
-      'narration (15-35 words in the specified language, spoken aloud),',
-      'caption (3-6 words UPPERCASE, text overlay),',
-      'visual_description (vivid description of what the scene looks like — used as image prompt),',
-      'character { character_id (free text or "none"), pose, emotion, position {x,y,scale} },',
+      'narration (8-18 words in the specified language, spoken aloud),',
+      'caption (optional 2-4 uppercase words text overlay only if captions requested, otherwise empty string),',
+      'visual_description (vivid description of the visual motion graphics / b-roll / diagram / scene — used for code-driven animation),',
+      'character { character_id ("none" or identifier), pose, emotion, position {x,y,scale} },',
       'focal_point {x,y,weight},',
       'overlay { type: "prop"|"effect"|"text"|"none" },',
       'sound_effects [ { effect_id, timing: "start"|"middle"|"end", volume } ],',