@amg555/frameforge-mcp 2.4.8 → 2.4.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.8",
-  "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 21 MCP tools.",
+  "version": "2.4.9",
+  "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"
   },
@@ -31,7 +31,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/workflows/ingest.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 src/video-editor/editor.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/workflows/ingest.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 src/video-editor/editor.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/lib/verify-quality.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/html-renderer/references/motion-craft.md

@@ -0,0 +1,91 @@
+# Motion Craft Reference — 10 Hard Motion Craft Rules
+
+This guide defines the production motion design standards implemented across FrameForge and the HTML-as-compositor rendering pipeline.
+
+---
+
+## 1. Springs, Not Linear Easing
+Real physical motion never moves at constant velocity or abrupt linear ramps. Every entrance and transition must model a damped harmonic oscillator:
+
+$$\ddot{x} + 2\zeta\omega\dot{x} + \omega^2 x = 0$$
+
+- **Default tension**: `160 - 200`
+- **Default friction**: `13 - 16`
+- **Closed-form function**: `spring(t, delay, tension, friction)` maps pure time $t$ to normalized displacement $[0, 1]$ with natural overshoot and settling.
+
+---
+
+## 2. Three-Property Entrances
+Never animate a single property (such as opacity alone or scale alone). High-production visuals orchestrate three coordinated properties for every entering entity:
+1. **Scale**: $0.88 \to 1.0$ (spatial arrival)
+2. **Opacity**: $0.0 \to 1.0$ (perceptual fade)
+3. **Translation**: $Y: +40\text{px} \to 0\text{px}$ or $X: \pm 60\text{px} \to 0\text{px}$ (directional momentum)
+
+---
+
+## 3. Staggered Entrance Choreography
+Never trigger all elements simultaneously. When rendering cards, list items, or diagram nodes:
+- Stagger siblings by $0.15\text{s} - 0.28\text{s}$ relative to base timestamp.
+- Hierarchy flows from primary anchor $\to$ structural components $\to$ explanatory callouts $\to$ micro-badges.
+
+---
+
+## 4. Asymmetric Timing: Exits Faster Than Entrances
+- **Entrances**: Informative, welcoming, gentle settling ($0.5\text{s} - 0.8\text{s}$ duration).
+- **Exits**: Crisp, decisive, purposeful ($0.2\text{s} - 0.35\text{s}$ duration). Exits must clear the stage without lingering.
+
+---
+
+## 5. Five-Layer Depth Stack
+Every scene must maintain clear atmospheric depth across 5 distinct visual layers:
+- **Layer 1: Ambient Backdrop** — Radial gradients, atmospheric tint, depth falloff.
+- **Layer 2: Environment / Context** — Architectural wainscoting, blueprint grid, floor plane, distant mountain ridges, or starry cosmos.
+- **Layer 3: Primary Visual Entity** — The core subject (doodle character, cutaway engine, split comparison cards, neural insight core, or optical loupe).
+- **Layer 4: Explanatory Callouts & Overlays** — Connecting vector lines, animated pulse packets, telemetry tags, and indicator badges.
+- **Layer 5: Foreground Framing & Vignette** — Subtle radial corner shading, specular glass arcs, or foreground foliage.
+
+---
+
+## 6. Continuous Audio-Driven Camera Progression
+Scenes must never switch camera angles at arbitrary fixed timer intervals. Camera motion is a continuous parametric function of speech duration:
+
+$$p = \frac{t}{\text{DURATION}}$$
+
+- **Dynamic zoom**: $1.0 + p \times 0.08$
+- **Dynamic pan**: Organic Lissajous drift ($\sin(0.4t) \times 6\text{px}$)
+- **Cut synchronization**: Scene cuts occur strictly on spoken sentence boundaries and audio cues.
+
+---
+
+## 7. Continuous Life (Zero Frozen PowerPoint Slides)
+Every frame must contain subtle life. An audience detects static images instantly:
+- Rotating gears ($t \times \omega$)
+- Oscillating telemetry needles and wave pulses
+- Flowing data packets along pipeline tracks
+- Gentle character breathing and foliage sway ($\sin(3t) \times 4\text{px}$)
+
+---
+
+## 8. Hand-Drawn Boil Wobble at 12fps
+When rendering hand-drawn doodle characters and sketch line work, apply authentic 12fps line boil wobble:
+- Quantize step to 12fps: `step = Math.floor(t * 12)`
+- Use seeded deterministic trigonometric noise:
+  `Math.sin(seed * 19.37 + step * 2.41) * 2.4`
+- Never use `Math.random()` inside the render loop.
+
+---
+
+## 9. Regional Typography & HarfBuzz Text Shaping
+Ensure professional typographic hierarchy:
+- Auto-detect script (Malayalam: Manjari / Gayathri / Chilanka; Devanagari: Noto Sans Devanagari; Latin: Inter / Rajdhani / Cinzel).
+- Maintain WCAG AAA contrast ratios against backgrounds.
+- Gate on-screen subtitles: display narration text only when explicitly requested in prompt.
+
+---
+
+## 10. Closed-Loop Visual QA Gate
+Never deliver rendered video blind. The production harness must execute automated quality checks across 4 axes:
+1. **Content Presence**: Non-blank ($> 1.5\%$ foreground variance).
+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

@@ -0,0 +1,65 @@
+# Render Contract — Deterministic Frame Specification
+
+This document specifies the strict mathematical and runtime contract required for all FrameForge HTML-as-compositor rendering engines.
+
+---
+
+## 1. Pure Mathematical Function of Time: $F(t) \to \text{Pixels}$
+
+Every scene page must behave as a pure, stateless function of time $t$ in seconds:
+
+$$\text{Frame}(t) = \mathcal{R}(\text{SceneState}(t))$$
+
+- **Zero Memory Leaks**: Frame $N$ must never depend on whether Frame $N-1$ was previously rendered.
+- **Out-of-Order Parallelism**: Frames can be rendered out of sequence across multiple worker threads (e.g. Worker 1 renders $t=1.0\text{s}$, Worker 2 renders $t=0.2\text{s}$, Worker 3 renders $t=2.5\text{s}$).
+
+---
+
+## 2. Virtual Clock Interception
+
+The harness injects a virtual clock prior to page script execution (`capture.mjs`):
+
+- **Overridden APIs**:
+  - `window.performance.now()` $\to$ returns $t \times 1000$
+  - `Date.now()` $\to$ returns `virtualEpoch + t * 1000`
+  - `window.Date` constructor $\to$ anchored to `VirtualDate(t)`
+  - `requestAnimationFrame(cb)` $\to$ registered into a synchronized callback queue
+  - `CSS Animations` $\to$ synced via `document.getAnimations().forEach(a => a.currentTime = t * 1000)`
+
+---
+
+## 3. Seeded PRNG Determinism Invariant
+
+Standard `Math.random()` produces divergent frames on repeated renders and breaks cache hashing.
+- **Forbidden**: `Math.random()`
+- **Required**: Seeded PRNG (`sfc32` or deterministic integer hashing).
+- **Time-Synchronized Reseed**:
+  ```javascript
+  let _seed = (0x2F6E2B1 ^ Math.imul(Math.floor(t * 1000), 0x9E3779B9)) | 0;
+  function prng() {
+    _seed = (_seed + 0x6D2B79F5) | 0;
+    let x = Math.imul(_seed ^ (_seed >>> 15), 1 | _seed);
+    x = (x + Math.imul(x ^ (x >>> 7), 61 | x)) ^ x;
+    return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+  }
+  ```
+
+---
+
+## 4. Three-Point Purity Gate (`verify-purity.mjs`)
+
+Every scene must pass the 3-point purity gate prior to full-rate production encoding:
+1. **Repeat Check**: Sampling $t = 1.0\text{s}$ twice in succession must yield identical SHA-256 frame hashes.
+2. **Wander Check**: Seeking forward $0\text{s} \to 2.5\text{s}$ and then jumping back to $1.0\text{s}$ must yield the identical hash as the cold seek.
+3. **Cold Jump Check**: Spawning a fresh browser session and seeking immediately to $1.0\text{s}$ must match the sequential seek.
+
+---
+
+## 5. Master Encoding Contract (`encode.mjs`)
+
+Output MP4s must comply with broadcast and streaming color standards:
+- **Codec**: `libx264` (Profile: High, Level: 4.2)
+- **Pixel Format**: `yuv420p`
+- **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/plugins/video-pipeline/skills/video-pipeline/references/motion-craft.md

@@ -0,0 +1,91 @@
+# Motion Craft Reference — 10 Hard Motion Craft Rules
+
+This guide defines the production motion design standards implemented across FrameForge and the HTML-as-compositor rendering pipeline.
+
+---
+
+## 1. Springs, Not Linear Easing
+Real physical motion never moves at constant velocity or abrupt linear ramps. Every entrance and transition must model a damped harmonic oscillator:
+
+$$\ddot{x} + 2\zeta\omega\dot{x} + \omega^2 x = 0$$
+
+- **Default tension**: `160 - 200`
+- **Default friction**: `13 - 16`
+- **Closed-form function**: `spring(t, delay, tension, friction)` maps pure time $t$ to normalized displacement $[0, 1]$ with natural overshoot and settling.
+
+---
+
+## 2. Three-Property Entrances
+Never animate a single property (such as opacity alone or scale alone). High-production visuals orchestrate three coordinated properties for every entering entity:
+1. **Scale**: $0.88 \to 1.0$ (spatial arrival)
+2. **Opacity**: $0.0 \to 1.0$ (perceptual fade)
+3. **Translation**: $Y: +40\text{px} \to 0\text{px}$ or $X: \pm 60\text{px} \to 0\text{px}$ (directional momentum)
+
+---
+
+## 3. Staggered Entrance Choreography
+Never trigger all elements simultaneously. When rendering cards, list items, or diagram nodes:
+- Stagger siblings by $0.15\text{s} - 0.28\text{s}$ relative to base timestamp.
+- Hierarchy flows from primary anchor $\to$ structural components $\to$ explanatory callouts $\to$ micro-badges.
+
+---
+
+## 4. Asymmetric Timing: Exits Faster Than Entrances
+- **Entrances**: Informative, welcoming, gentle settling ($0.5\text{s} - 0.8\text{s}$ duration).
+- **Exits**: Crisp, decisive, purposeful ($0.2\text{s} - 0.35\text{s}$ duration). Exits must clear the stage without lingering.
+
+---
+
+## 5. Five-Layer Depth Stack
+Every scene must maintain clear atmospheric depth across 5 distinct visual layers:
+- **Layer 1: Ambient Backdrop** — Radial gradients, atmospheric tint, depth falloff.
+- **Layer 2: Environment / Context** — Architectural wainscoting, blueprint grid, floor plane, distant mountain ridges, or starry cosmos.
+- **Layer 3: Primary Visual Entity** — The core subject (doodle character, cutaway engine, split comparison cards, neural insight core, or optical loupe).
+- **Layer 4: Explanatory Callouts & Overlays** — Connecting vector lines, animated pulse packets, telemetry tags, and indicator badges.
+- **Layer 5: Foreground Framing & Vignette** — Subtle radial corner shading, specular glass arcs, or foreground foliage.
+
+---
+
+## 6. Continuous Audio-Driven Camera Progression
+Scenes must never switch camera angles at arbitrary fixed timer intervals. Camera motion is a continuous parametric function of speech duration:
+
+$$p = \frac{t}{\text{DURATION}}$$
+
+- **Dynamic zoom**: $1.0 + p \times 0.08$
+- **Dynamic pan**: Organic Lissajous drift ($\sin(0.4t) \times 6\text{px}$)
+- **Cut synchronization**: Scene cuts occur strictly on spoken sentence boundaries and audio cues.
+
+---
+
+## 7. Continuous Life (Zero Frozen PowerPoint Slides)
+Every frame must contain subtle life. An audience detects static images instantly:
+- Rotating gears ($t \times \omega$)
+- Oscillating telemetry needles and wave pulses
+- Flowing data packets along pipeline tracks
+- Gentle character breathing and foliage sway ($\sin(3t) \times 4\text{px}$)
+
+---
+
+## 8. Hand-Drawn Boil Wobble at 12fps
+When rendering hand-drawn doodle characters and sketch line work, apply authentic 12fps line boil wobble:
+- Quantize step to 12fps: `step = Math.floor(t * 12)`
+- Use seeded deterministic trigonometric noise:
+  `Math.sin(seed * 19.37 + step * 2.41) * 2.4`
+- Never use `Math.random()` inside the render loop.
+
+---
+
+## 9. Regional Typography & HarfBuzz Text Shaping
+Ensure professional typographic hierarchy:
+- Auto-detect script (Malayalam: Manjari / Gayathri / Chilanka; Devanagari: Noto Sans Devanagari; Latin: Inter / Rajdhani / Cinzel).
+- Maintain WCAG AAA contrast ratios against backgrounds.
+- Gate on-screen subtitles: display narration text only when explicitly requested in prompt.
+
+---
+
+## 10. Closed-Loop Visual QA Gate
+Never deliver rendered video blind. The production harness must execute automated quality checks across 4 axes:
+1. **Content Presence**: Non-blank ($> 1.5\%$ foreground variance).
+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/video-pipeline/references/render-contract.md

@@ -0,0 +1,65 @@
+# Render Contract — Deterministic Frame Specification
+
+This document specifies the strict mathematical and runtime contract required for all FrameForge HTML-as-compositor rendering engines.
+
+---
+
+## 1. Pure Mathematical Function of Time: $F(t) \to \text{Pixels}$
+
+Every scene page must behave as a pure, stateless function of time $t$ in seconds:
+
+$$\text{Frame}(t) = \mathcal{R}(\text{SceneState}(t))$$
+
+- **Zero Memory Leaks**: Frame $N$ must never depend on whether Frame $N-1$ was previously rendered.
+- **Out-of-Order Parallelism**: Frames can be rendered out of sequence across multiple worker threads (e.g. Worker 1 renders $t=1.0\text{s}$, Worker 2 renders $t=0.2\text{s}$, Worker 3 renders $t=2.5\text{s}$).
+
+---
+
+## 2. Virtual Clock Interception
+
+The harness injects a virtual clock prior to page script execution (`capture.mjs`):
+
+- **Overridden APIs**:
+  - `window.performance.now()` $\to$ returns $t \times 1000$
+  - `Date.now()` $\to$ returns `virtualEpoch + t * 1000`
+  - `window.Date` constructor $\to$ anchored to `VirtualDate(t)`
+  - `requestAnimationFrame(cb)` $\to$ registered into a synchronized callback queue
+  - `CSS Animations` $\to$ synced via `document.getAnimations().forEach(a => a.currentTime = t * 1000)`
+
+---
+
+## 3. Seeded PRNG Determinism Invariant
+
+Standard `Math.random()` produces divergent frames on repeated renders and breaks cache hashing.
+- **Forbidden**: `Math.random()`
+- **Required**: Seeded PRNG (`sfc32` or deterministic integer hashing).
+- **Time-Synchronized Reseed**:
+  ```javascript
+  let _seed = (0x2F6E2B1 ^ Math.imul(Math.floor(t * 1000), 0x9E3779B9)) | 0;
+  function prng() {
+    _seed = (_seed + 0x6D2B79F5) | 0;
+    let x = Math.imul(_seed ^ (_seed >>> 15), 1 | _seed);
+    x = (x + Math.imul(x ^ (x >>> 7), 61 | x)) ^ x;
+    return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+  }
+  ```
+
+---
+
+## 4. Three-Point Purity Gate (`verify-purity.mjs`)
+
+Every scene must pass the 3-point purity gate prior to full-rate production encoding:
+1. **Repeat Check**: Sampling $t = 1.0\text{s}$ twice in succession must yield identical SHA-256 frame hashes.
+2. **Wander Check**: Seeking forward $0\text{s} \to 2.5\text{s}$ and then jumping back to $1.0\text{s}$ must yield the identical hash as the cold seek.
+3. **Cold Jump Check**: Spawning a fresh browser session and seeking immediately to $1.0\text{s}$ must match the sequential seek.
+
+---
+
+## 5. Master Encoding Contract (`encode.mjs`)
+
+Output MP4s must comply with broadcast and streaming color standards:
+- **Codec**: `libx264` (Profile: High, Level: 4.2)
+- **Pixel Format**: `yuv420p`
+- **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,12 +20,14 @@ 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.8',   code.includes("version: '2.4.8'"));
+check('SERVER_INFO version 2.4.9',   code.includes("version: '2.4.9'"));
 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'));
 check('generate_scene_code tool defined', code.includes('generate_scene_code'));
 check('preview_scene tool defined', code.includes('preview_scene'));
+check('verify_scene_quality tool defined', code.includes('verify_scene_quality'));
+check('plan_video_edit tool defined', code.includes('plan_video_edit'));
 check('video-editor exists', fs.existsSync('./src/video-editor/editor.js'));
 check('voxforge TTS provider', code.includes('voxforge'));
 const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
@@ -287,10 +289,12 @@ check('harness/lib/capture.mjs exists',       fs.existsSync('./src/harness/lib/c
 check('harness/lib/jobs.mjs exists',          fs.existsSync('./src/harness/lib/jobs.mjs'));
 check('harness/lib/sheets.mjs exists',        fs.existsSync('./src/harness/lib/sheets.mjs'));
 check('harness/lib/verify-purity.mjs exists', fs.existsSync('./src/harness/lib/verify-purity.mjs'));
+check('harness/lib/verify-quality.mjs exists', fs.existsSync('./src/harness/lib/verify-quality.mjs'));
 check('harness/lib/pixels.mjs exists',        fs.existsSync('./src/harness/lib/pixels.mjs'));
 check('harness/lib/encode.mjs exists',        fs.existsSync('./src/harness/lib/encode.mjs'));
 check('asset harness.mjs exists',             fs.existsSync(`${engineAssetBase}/scripts/harness.mjs`));
 check('asset verify-purity.mjs exists',       fs.existsSync(`${engineAssetBase}/scripts/verify-purity.mjs`));
+check('asset verify-quality.mjs exists',      fs.existsSync(`${engineAssetBase}/scripts/verify-quality.mjs`));
 
 // ── Cloudflare Worker rate limiting ───────────────────────────────────────
 console.log('\n=== Cloudflare Worker rate limiting ===');
@@ -299,13 +303,15 @@ 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.8',        cfWorker.includes("'2.4.8'"));
+check('cf-worker version 2.4.9',        cfWorker.includes("'2.4.9'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────
 console.log('\n=== Plugin skills ===');
 check('video-pipeline SKILL.md exists', fs.existsSync('./plugins/video-pipeline/skills/video-pipeline/SKILL.md'));
 check('html-renderer SKILL.md exists',  fs.existsSync('./plugins/video-pipeline/skills/html-renderer/SKILL.md'));
+check('motion-craft reference exists', fs.existsSync('./plugins/video-pipeline/skills/html-renderer/references/motion-craft.md'));
+check('render-contract reference exists', fs.existsSync('./plugins/video-pipeline/skills/html-renderer/references/render-contract.md'));
 
 // ── Security: no .kiro references in committed source ────────────────────
 console.log('\n=== No stale .kiro references in source ===');

package/src/harness/bin/harness.mjs

@@ -21,6 +21,7 @@ import { fileURLToPath } from 'url';
 import { doctorBrowser, launchHarnessBrowser } from '../lib/browser.mjs';
 import { openPageWithVirtualClock } from '../lib/capture.mjs';
 import { verifyScenePurity } from '../lib/verify-purity.mjs';
+import { verifySceneQuality } from '../lib/verify-quality.mjs';
 import { renderSheet, renderStrip, renderCrop, renderStoryboard } from '../lib/sheets.mjs';
 import { renderFrameJobs } from '../lib/jobs.mjs';
 import { encodeFramesToMp4 } from '../lib/encode.mjs';
@@ -305,12 +306,40 @@ async function cmdPixels() {
   }
 }
 
+async function cmdQuality() {
+  console.log(`🎯 Running Closed-Loop Visual QA Gate (1–10 Scoring) on: ${HTML_PATH}`);
+  const { browser } = await launchHarnessBrowser();
+  const sheetTarget = path.join(CHECK_DIR, 'sheet.jpg');
+  const res = await verifySceneQuality({
+    browser,
+    htmlPath: HTML_PATH,
+    sheetPath: sheetTarget,
+  });
+  await browser.close();
+
+  console.log(`  Overall Scene Score: ${res.overallScore}/10 [${res.passed ? 'PASSED ✅' : 'FAILED ❌'}]`);
+  console.log(`  Motion Delta: ${(res.motionDelta * 100).toFixed(0)}%`);
+  for (const f of res.sampledFrames) {
+    const issueStr = f.issues.length > 0 ? ` (${f.issues.join(', ')})` : '';
+    console.log(`    t=${f.time.toFixed(2)}s: ${f.score}/10${issueStr}`);
+  }
+
+  const qualityReportPath = path.join(CHECK_DIR, 'quality_report.json');
+  fs.writeFileSync(qualityReportPath, JSON.stringify(res, null, 2), 'utf8');
+  console.log(`  Quality report saved: ${qualityReportPath}`);
+
+  if (!res.passed && !flags['skip-quality']) {
+    throw new Error(`Scene failed closed-loop quality gate (Score: ${res.overallScore}/10). Fix worst frames: ${res.worstFrames.map(w => `${w.time}s`).join(', ')}`);
+  }
+}
+
 async function cmdAll() {
-  console.log('🚀 Running Complete Production Pipeline: Storyboard → Verify → Frames → Encode → Inspect');
+  console.log('🚀 Running Complete Production Pipeline: Storyboard → Verify → Quality → Frames → Encode → Inspect');
   await cmdDoctor();
   await cmdStoryboard();
   await cmdSheet();
   await cmdVerify();
+  await cmdQuality();
   await cmdFrames();
   await cmdEncode();
   console.log('\n✨ Production complete! Output ready at out/film.mp4');
@@ -321,6 +350,7 @@ try {
     case 'doctor':     await cmdDoctor();     break;
     case 'storyboard': await cmdStoryboard(); break;
     case 'verify':     await cmdVerify();     break;
+    case 'quality':    await cmdQuality();    break;
     case 'sheet':      await cmdSheet();      break;
     case 'strip':      await cmdStrip();      break;
     case 'crop':       await cmdCrop();       break;
@@ -329,7 +359,7 @@ try {
     case 'pixels':     await cmdPixels();     break;
     case 'all':        await cmdAll();        break;
     default:
-      console.log(`Usage: harness <doctor|storyboard|verify|sheet|strip|crop|frames|encode|pixels|all> [options]`);
+      console.log(`Usage: harness <doctor|storyboard|verify|quality|sheet|strip|crop|frames|encode|pixels|all> [options]`);
       break;
   }
 } catch (err) {