@amg555/frameforge-mcp 2.7.3 → 2.7.7

package/.claude-plugin/marketplace.json

@@ -1,8 +1,8 @@
 {
   "name": "frameforge",
   "displayName": "FrameForge — AI Video Production",
-  "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 28 MCP tools. Whisper, yt-dlp, broadcast audio, 24 film styles, ClaudeAnimationBase, onetake 39-move library, HyperFrames motion craft.",
-  "version": "2.7.3",
+  "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 34 MCP tools. Whisper, yt-dlp, broadcast audio, 24 film styles, ClaudeAnimationBase, onetake 39-move library, HyperFrames motion craft. 62 Motion Graphics Styles.",
+  "version": "2.7.7",
   "homepage": "https://github.com/AMG555/FrameForge",
   "plugins": [
     {
@@ -12,7 +12,7 @@
         {
           "name": "video-pipeline",
           "displayName": "FrameForge Video Pipeline",
-          "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 28 MCP tools. Includes Whisper transcription, yt-dlp ingestion, broadcast-grade audio, upstream skills sync.",
+          "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 34 MCP tools. Includes Whisper transcription, yt-dlp ingestion, broadcast-grade audio, upstream skills sync. 62 Motion Graphics Styles via list_motion_styles + get_motion_style_prompt.",
           "triggerPhrases": [
             "make a video about",
             "produce a reel on",

package/AGENTS.md

@@ -0,0 +1,33 @@
+# Multi-Agent Workspace Instructions — FrameForge
+
+This workspace equips agents with complete video production, procedural motion graphics, automated QA, and reverse engineering capabilities.
+
+---
+
+## ⚠️ ZERO AI IMAGES RULE (CODE-DRIVEN FIRST)
+- **NEVER generate AI images from the beginning.**
+- **Always default to FrameForge's code-driven animation tools**: 62 procedural motion styles (`list_motion_styles`, `get_motion_style_prompt`), 6 viral faceless shorts engines, Playwright canvas rendering, and kinetic typography.
+- **DO NOT call AI image generation or generate diffusion pictures** unless the user explicitly prompts: "generate AI images" or "use AI image generation".
+
+---
+
+## Workspace Skills Hierarchy
+
+1. **Procedural Motion Graphics:**
+   - `motion-styles`: 62 styles scraped from `FrameForge Motion Library`. Full reference sources in `plugins/motion-styles/sources/`, ready-to-copy prompts in `plugins/motion-styles/prompts/`.
+   - `faceless-shorts`: 6 procedural 3D/2D vertical styles with Kokoro AI voice and word-level caption alignment.
+   - `ai-video-editor`: Full talking-head editor with mistake cutting, local Whisper, and 7 canvas motion-graphics styles.
+   - `html-renderer`: FrameForge time-based canvas engine with 12fps organic boil, camera springs, and audio ducking.
+
+2. **Quality & Engineering Automation (gstack):**
+   - Use `gstack-review` and `gstack-qa` to verify code integrity and render pipelines.
+   - Use `gstack-design-review` to inspect visual motion graphics, contrast, layout, and mobile safe zones.
+   - Use `gstack-investigate` for systematic root-cause debugging of any pipeline failures.
+
+3. **Reverse Engineering & Extraction (rea):**
+   - Use `reverse-engineer-anything` and the `rea` MCP server to analyze external WebGL shaders, Three.js bundles, audio synthesis chains, and canvas effects to port them into FrameForge.
+
+4. **FrameForge Core MCP Pipeline:**
+   - 34 tools available via stdio (`src/mcp-server/stdio.js`) and HTTP (`src/mcp-server/server.js`).
+   - Use `list_motion_styles` and `get_motion_style_prompt` for instant access to any of the 62 Motion graphics style prompts and codebases.
+

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.7.7] — 2026-11-12
+
+### Changed
+- Slimmed npm tarball distribution: excluded `.agent/` cache and vendor artifacts via `.npmignore` (size reduced from 48MB to 28MB).
+- Upgraded version manifests across core MCP server and sync engine to v2.7.7.
+
+---
+
+## [2.7.6] — 2026-11-12
+
+### Added
+- **Tools 33–34: `list_motion_styles` + `get_motion_style_prompt`** — catalog all 62 Motion Graphics Styles from FrameForge Motion Library, retrieve the full Claude prompt for any style by id.
+- **`plugins/motion-styles/catalog.json`** — 62 Motion graphics style entries (id, name, family, look, how, fonts, demo, replace, keep, sizes, voLine, sheet, sound, full, voMix).
+- **`plugins/faceless-shorts/`** — faceless-shorts v7 (YouTube upload via Zapier, updated aiinsight-shorts fork).
+- **`plugins/ai-video-editor/`** — ai-video-editor v2 (7-style talking-head editor: Warm Canvas, Creator Motion Graphics, Clean Tech, Software Walkthrough, Data Story, Chalk Talk, Pop Info; Python/faster-whisper/Playwright pipeline).
+
+### Fixed
+- **Gradient-only output (critical)**: Root cause was a `ReferenceError` (`effectiveShowCaptions`/`effectiveShowAnchor` were in scope of `renderScene` but not passed into `_renderCodeAnimationScene`). The browser harness silently threw, fell through to the ffmpeg gradient fallback, producing plain color scenes on every render. Fixed in commit `8d2c41f` — all scenes now render as full-canvas animated HTML.
+- **Portrait render crop**: `--width`/`--height` flags were missing from the harness `frames` subprocess call; portrait scenes defaulted to 1920×1080 landscape crop. Fixed.
+- **SFX missing**: `sound_effects` collected in scenes but never wired through `assets.js → render.js → renderer.js → mixer.js`. Full pipeline now connected.
+
+### Changed
+- `package.json` version `2.7.5 → 2.7.6`, description updated to `34 MCP tools`.
+- `SERVER_INFO.version` bumped to `2.7.6`.
+
+---
+
+## [2.7.4] — 2026-11-12
+
+### Fixed
+- **Direct Canvas DataURL Frame Extraction**: Implemented `window.renderAt(t, mime, q)` and synchronous `canvas.toDataURL()` extraction in `src/harness/lib/capture.mjs` and `src/video-renderer/scene-animator.js`. Completely avoids Chromium CDP `Page.captureScreenshot` compositor locks on Windows, eliminating frame capture crashes and timeouts.
+- **Fixed Canvas State Matrix Drift**: Restored missing `ctx.restore()` in `src/video-renderer/scene-animator.js` (`doodle_map_migration`), keeping canvas transform stack depth strictly balanced at 0 across all render frames.
+- **Eliminated Rotating Black Center Fallback Artifact**: Replaced harsh radial gradient with smooth linear ambient gradient and guaranteed title/caption text overlay in `src/video-renderer/renderer.js` fallback path.
+- **Worker Concurrency & Reliability**: Added 3-attempt retry backoff and size validation in `src/harness/lib/jobs.mjs`. Set default worker concurrency to 2 to eliminate Windows paging file / RAM memory spikes.
+- **Zero-Token Local Render Guarantee**: Confirmed zero LLM token consumption across all code-driven animation, media ingest, edit-only, and video assembly workflows.
+
+---
+
 ## [2.7.3] — 2026-11-12
 
 ### Added
@@ -23,6 +61,17 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.7.4] — 2026-11-12
+
+### Fixed
+- **Direct Canvas DataURL Frame Extraction**: Implemented `window.renderAt(t, mime, q)` and synchronous `canvas.toDataURL()` extraction in `src/harness/lib/capture.mjs` and `src/video-renderer/scene-animator.js`. Completely avoids Chromium CDP `Page.captureScreenshot` compositor locks on Windows, eliminating frame capture crashes and timeouts.
+- **Fixed Canvas State Matrix Drift**: Restored missing `ctx.restore()` in `src/video-renderer/scene-animator.js` (`doodle_map_migration`), keeping canvas transform stack depth strictly balanced at 0 across all render frames.
+- **Eliminated Rotating Black Center Fallback Artifact**: Replaced harsh radial gradient with smooth linear ambient gradient and guaranteed title/caption text overlay in `src/video-renderer/renderer.js` fallback path.
+- **Worker Concurrency & Reliability**: Added 3-attempt retry backoff and size validation in `src/harness/lib/jobs.mjs`. Set default worker concurrency to 2 to eliminate Windows paging file / RAM memory spikes.
+- **Zero-Token Local Render Guarantee**: Confirmed zero LLM token consumption across all code-driven animation, media ingest, edit-only, and video assembly workflows.
+
+---
+
 ## [2.7.3] — 2026-11-12
 
 ### Added

package/CLAUDE.md

@@ -20,11 +20,22 @@ You are a **video producer** working inside FrameForge. Your job is to design sc
 
 ## WHAT YOU MAY DO
 
-- Call any of the 28 FrameForge MCP tools (listed below)
+- Call any of the FrameForge MCP tools (listed below)
 - Write scene arrays, narration text, captions, and visual descriptions **in your context**
 - Write animation code in `edit.js` inside a **scaffolded project directory** (e.g. `.frameforge-files/my-animation/edit.js`)
 - Read files inside `.frameforge-files/` to inspect rendered output
 
+## ⚠️ ZERO-DIFFUSION RULE: CODE-DRIVEN ANIMATION FIRST
+
+- **NEVER generate AI diffusion images from the beginning.**
+- **Always default to FrameForge's code-driven animation tools**:
+  - 62 procedural motion styles (`list_motion_styles`, `get_motion_style_prompt`)
+  - 6 faceless shorts engines (`deep-dive`, `night-file`, `inside-out`, `stick-story`, `paper-atlas`, `tall-tale`)
+  - Pure-function-of-time `t` canvas animation (`scaffold_animation_project`, `render_animation`)
+  - Procedural kinetic cards, SVG/Canvas graphics, and typography
+  - User-supplied footage/photos (`video_path`, `image_path`)
+- **ONLY generate AI images if the user EXPLICITLY prompts for it** (e.g. *"generate AI images for this"*, *"use DALL-E/FLUX"*, *"generate AI pictures"*). Until the user explicitly asks with those exact words, NEVER call AI image generation or generate diffusion pictures.
+
 ## WHAT YOU MUST NEVER DO
 
 - **Create files** anywhere in this repository — not in `src/`, `scripts/`, `docs/`, `plugins/`, `cloudflare-mcp/`, and not in the project root either. No helper scripts, no wrapper files, no markdown notes.
@@ -58,7 +69,7 @@ If you're not sure what a tool does — call it with the obvious parameters. The
 
 ## THREE PATHS — PICK ONE
 
-> **The primary path is Path 2 (code-driven animation).** Every frame is a pure function of time `t`, rendered by Playwright + FFmpeg. This is what produces the high-quality, viral-style motion graphics clips. Path 1 (FFmpeg + AI images) is the fast fallback when Playwright is unavailable or the user wants a quick draft. Path 3 (auto-research) is for unattended batch.
+> **The primary path is Path 2 (code-driven animation).** Every frame is a pure function of time `t`, rendered by Playwright + FFmpeg. This is what produces the high-quality, viral-style motion graphics clips. Path 1 (FFmpeg + procedural kinetic typography & user media) is the fast direct scene render. Zero AI diffusion images generated unless user explicitly prompts for AI diffusion. Path 3 (auto-research) is for unattended batch.
 
 ### Path 1 — You write the scenes (code animation & user media)
 
@@ -287,17 +298,17 @@ get_job_status({ jobId })   // poll every 30s until status = "SUCCEEDED"
 | `export_to_editor` | Send finished animation to Premiere / Resolve / CapCut / After Effects / Remotion |
 | `external_platform_call` | HTTP bridge to **any** app — pass `platformUrl` directly, no env setup needed |
 
-**Secondary — FFmpeg + AI images (fast draft, no Playwright needed):**
+**Secondary — FFmpeg + Procedural Kinetic Cards & User Media:**
 
 | Tool | What it does |
 |------|-------------|
-| `create_video_from_script` | Full render from scenes you provide — voice, images, FFmpeg, QC |
+| `create_video_from_script` | Full render from scenes you provide — voice, procedural kinetic cards, FFmpeg, QC |
 | `render_from_scenes` | Re-render from an existing scenes manifest |
 | `ingest_media` | Import your own clips, images, audio into a scenes manifest |
 | `edit_scenes` | Patch captions, swap media files, append scenes |
 | `assemble_video` | FFmpeg render + quality gate → master MP4 |
 | `render_tts` | Generate voice audio for one scene |
-| `generate_scene_image` | Generate one scene image |
+| `generate_scene_image` | Register code-driven card (only generates AI image if user explicitly prompted for AI images) |
 | `publish_video` | Deliver via file copy or HTTP webhook |
 
 **Media ingestion (yt-dlp & Whisper):**
@@ -562,7 +573,7 @@ export_to_editor({ editor: "resolve", action: "status", jobId: "..." })
 | Field | Required | Notes |
 |-------|----------|-------|
 | `narration` | ✅ | Spoken aloud. Drives TTS and scene length. |
-| `visual_description` | ✅ (or `image_path`) | AI image prompt. Be specific. |
+| `visual_description` | ✅ (or `image_path`) | Visual layout and card concept for procedural rendering (only AI image prompt if user explicitly asks for AI images). |
 | `caption` | optional | Overlay text, max 40 chars. |
 | `camera_hint` | optional | `zoom_in` `zoom_out` `pan_left` `pan_right` `ken_burns` `static` `auto` |
 | `music_mood` | optional | `tense` `calm` `energetic` `mysterious` `neutral` `dramatic` `humorous` |

package/GEMINI.md

@@ -0,0 +1,63 @@
+# FrameForge — Agent & Skills Activation Guide
+
+This project is configured with full agent skills, multi-engine video rendering, and reverse engineering tools.
+
+---
+
+## ⚠️ ZERO AI IMAGES RULE (CODE-DRIVEN FIRST)
+- **NEVER generate AI images from the beginning.**
+- **Always default to FrameForge's code-driven animation tools**: 62 procedural motion styles (`list_motion_styles`, `get_motion_style_prompt`), 6 viral faceless shorts engines, Playwright canvas rendering, and kinetic typography.
+- **DO NOT call AI image generation or generate diffusion pictures** unless the user explicitly prompts: "generate AI images" or "use AI image generation".
+
+---
+
+## Active Skills in this Workspace
+
+### 1. `motion-styles` — 62 Motion-Graphics Styles
+- **Source:** Scraped directly from [FrameForge Motion Library](FrameForge Motion Library).
+- **Location:** `.agent/skills/motion-styles/` and `plugins/motion-styles/`
+- **Catalog:** `plugins/motion-styles/catalog.json` (all 62 styles with sheet rules, sound design rules, size rules, and prompt metadata).
+- **Reference Code:** `plugins/motion-styles/sources/<styleId>.html` (complete standalone working HTML files with canvas animation, Three.js shaders, math helpers, and synthesized Web Audio SFX).
+- **Ready-to-Copy Prompts:** `plugins/motion-styles/prompts/<styleId>.md` (standard direct prompts + voiceover/storyboard prompts).
+- **Catalog Index:** `plugins/motion-styles/LIBRARY.md`
+- **MCP Tools:**
+  - `list_motion_styles`: Browse by family (Kinetic Type, Hand-Drawn, Screen and UI, Data, Talking Head, Illustrated, 3D, Retro, Shorts Format, Edit Overlay, Character Story).
+  - `get_motion_style_prompt`: Fetch the full prompt for any style, with optional topic, voiceover timing mode (`mode: "vo"`), storyboard-first (`storyboard: true`), and embedded source code (`includeSource: true`).
+
+### 2. `ai-video-editor` — Talking Head Video Editor
+- **Location:** `.agent/skills/ai-video-editor/` and `plugins/ai-video-editor/`
+- **Engine:** Whisper (faster-whisper) + FFmpeg + Chromium canvas compositor.
+- **Workflow:** Cuts silences, removes retakes/mistakes, applies motion graphics in 7 styles (Warm Canvas, Creator Motion Graphics, Clean Tech, Software Walkthrough, Data Story, Chalk Talk, Pop Info), normalizes loudness, renders final MP4.
+
+### 3. `faceless-shorts` — Viral Vertical Video Engine
+- **Location:** `.agent/skills/faceless-shorts/` and `plugins/faceless-shorts/`
+- **Engine:** Kokoro local AI voice + Whisper word-level timing + 3D/2D procedural canvas + FFmpeg.
+- **Styles:** Deep Dive 3D (Zack D. Films style), Night File 3D (true crime/mystery), Inside Out (2D x-ray), Stick Story (survival steps), Paper Atlas (historical cut paper), Tall Tale 3D (cartoon 3D storytime).
+
+### 4. `video-pipeline` & `html-renderer` — FrameForge Native Engines
+- **Location:** `.agent/skills/video-pipeline/` and `.agent/skills/html-renderer/`
+- **Capabilities:** 34 MCP tools covering end-to-end video synthesis, TTS, audio mastering (`mix_audio_pro`), scene quality verification, and Playwright code animation.
+
+### 5. `gstack` Suite — Automated QA, Review, & Engineering
+- **Location:** `.agent/skills/gstack-*/`
+- **Key Skills:**
+  - `gstack-review` & `gstack-qa`: Automated code and behavioral test suites.
+  - `gstack-design-review`: Visual QA for motion graphics, layout, spacing, and typography.
+  - `gstack-investigate`: Root cause analysis for FFmpeg, audio mix, or render glitches.
+  - `gstack-autoplan`: Multi-perspective engineering, design, and developer experience review.
+
+### 6. `reverse-engineer-anything` (`rea`)
+- **Location:** `.agent/skills/reverse-engineer-anything/`
+- **MCP Server:** `rea`
+- **Capabilities:** Reverse-engineer WebGL shaders, Three.js bundles, compiled media binaries, canvas render routines, and third-party motion graphics pipelines.
+
+---
+
+## Quick Reference Commands
+
+- Pre-flight checks: `npm run doctor`
+- Run test suite: `npm test`
+- Structural validator: `npm run validate`
+- Browse Motion styles: Call MCP `list_motion_styles` or inspect `plugins/motion-styles/LIBRARY.md`
+- Retrieve style prompt: Call MCP `get_motion_style_prompt({ styleId: "creator-motion", topic: "..." })`
+