@viralspin/mcp 0.2.0 → 0.2.2

package/BUNDLE_LOCAL_SPEC.md

@@ -1,133 +0,0 @@
-# Bundle-Local Spec — `@viralspin/mcp` local video-assembly
-
-Status: proposed. Owner: Allen. Last updated: 2026-05-24.
-
-## 1. Goal
-
-Let any ViralSpin user produce a polished vertical short from **their own local files**
-(local A-roll + local B-roll folders) and/or Google Photos, with **zero key management**
-and a **one-time ~10-minute install** — driven entirely by natural language.
-
-Target UX (the literal command from day one of this work):
-
-> "Create a video with A-roll `E:\...\test.mp4`, B-roll from `E:\PickedByCarissa` and my Google Photos."
-
-The agent recognizes the local paths, realizes the cloud connector can't read local disk,
-offers a one-time local install (~10 min, with consent), then runs the assembly. Gemini /
-AI cost runs on **ViralSpin's** key server-side and is metered as **credits**. The user
-never sees or pastes an API key.
-
-## 2. Current state (2026-05-24)
-
-- **Engine** (`E:\AI test\carissa bot\assembly-engine\`) — Node orchestrator (`assemble.mjs`)
-  + Python Gemini scripts (`transcribe.py`, `analyze.py`, `edit.py`, `albums.py`, `style.py`)
-  + parameterized Remotion composition (`src/Assembly.tsx` / `Root.tsx`). Produces the
-  cindyzhu-style edit (captions + hook + keyword pops + fast focal-anchored cuts).
-  **Not in the repo**; referenced by `VIRALSPIN_ASSEMBLY_DIR` (defaults to the carissa path).
-- **MCP** (`mcp/`, this package) — stdio server. `create_video_assembly` + `start_photo_picker`
-  shell out to the engine. **Merged to main (PR #93)** but the engine is still external.
-- **Backend** — `/v1/assembly/picker` (POST create picker session, GET poll → re-host picks to
-  public `narrative` bucket URLs) is **live**. Hosted `viralspin_create_video_assembly`
-  (URL-only, older pipeline) is unchanged.
-- **Two credentials today** (both need to disappear from the user's view):
-  1. `VITE_GEMINI_API_KEY` — engine calls Gemini directly from a local `.env`. **Blocker for
-     distribution** (would be baked into shipped code).
-  2. `vs_…` token — per-user ViralSpin auth, currently hand-pasted into the MCP config env.
-
-## 3. Target architecture
-
-```
-natural-language command
-        │
-        ▼
-  Agent (Claude Code / Desktop, local shell)
-        │  detects local E:\ paths → cloud can't read disk
-        │  one-time consent → installs local helper (.mcpb / npx)  ── §4F
-        ▼
-  Local @viralspin/mcp (stdio, self-contained: Node + ffmpeg-static + Remotion/Chromium) ── §4B
-        │  transcribe / analyze / edit / style  ── all Node ── §4A
-        │  AI calls → ViralSpin backend proxy (no Gemini key locally) ── §4C
-        │  auth via login-provisioned token (no pasted vs_) ── §4D
-        │  persistent analysis cache (path+size+mtime) ── §4E
-        ▼
-  Remotion render (local CPU) → out.mp4 → publish_now / schedule_post
-```
-
-## 4. Workstreams
-
-### A. Port Python → Node (remove the Python dependency)
-Reimplement `transcribe.py`, `analyze.py`, `edit.py`, `albums.py`, `style.py` in TypeScript.
-- Keep the exact contracts (focal `{subject,focal_x,focal_y,secondary,desc,keywords}`;
-  editorial output `{hook,pops,cuts}`; album weights; style `{format,captions,hook,pops,pace,coverage}`).
-- Preserve the hard-won Gemini settings: `thinkingConfig.thinkingBudget=0` +
-  `responseMimeType:application/json` (gemini-2.5-flash is a thinking model — without this it
-  burns the token budget on hidden thinking and returns empty text).
-- Keep "transcribe FIRST → drives album ranking + B-roll selection + captions" ordering.
-
-### B. Bundle the runtime into the package
-- `ffmpeg-static` (transcode A-roll, stage B-roll, extract audio, mid-frame for video analysis).
-- Remotion + its headless Chromium (the ~hundreds-of-MB download → the bulk of the 10 min).
-- Vendor the composition (`Assembly.tsx`/`Root.tsx`) inside the package.
-- Result: `@viralspin/mcp` runs with only Node present; no external engine dir,
-  no system ffmpeg, no Python.
-
-### C. Proxy AI through the backend (credits, no user Gemini key)  ← enables distribution
-- New backend endpoints (X-API-Key / token authed) that wrap the Gemini calls the engine makes:
-  transcription, per-asset vision analysis, editorial pass, style inference.
-- Server holds the Gemini key. Each call **debits credits** against the user's account.
-- Local engine calls these instead of Gemini directly → no key ships to clients.
-- Decide credit pricing per render (≈ #assets analyzed + 1 transcript + 1 editorial + optional style).
-
-### D. Token provisioning via login (no pasted `vs_`)
-- A connect/login flow writes the user's token into the MCP config automatically
-  (or the helper fetches it post-login). User funds credits; never handles a key.
-- Token identifies whose credits to charge and whose Google account the picker uses.
-
-### E. Persistent analysis cache
-- Key each analyzed asset by `path + size + mtime` (and a content hash for URLs).
-- A 1000-item folder is indexed **once**; re-runs / edits skip re-analysis (huge cost + time win).
-- Cache lives under the package's data dir; survives across renders.
-
-### F. Packaging, distribution, auto-install
-- Primary: **`.mcpb` Claude Desktop extension** — double-click install, bundles Node.
-- Secondary: `npx @viralspin/mcp` / install script for Claude Code (`claude mcp add`).
-- **Client-side auto-install trigger**: the agent (not the cloud connector — it has no disk
-  access) detects local paths in the request and offers the one-time setup **with explicit
-  consent**. Never install silently.
-- Note the **reconnect seam**: adding a stdio server still requires the client to spawn it;
-  today that means "restart once" after first install. (`/mcp` reconnect re-attaches to the
-  existing child — it does NOT pick up a freshly installed/rebuilt server.)
-
-### G. Adjustment tools (post-MVP)
-On a persisted "project" (editData + cached candidate pool + transcript), conversational edits:
-`suggest_clips(cut)` → ranked alternatives w/ thumbnails, `swap_clip(cut,choice)` → re-render
-(~1 min local), plus remove / add / reframe / set_hook / edit_caption / set_pace.
-
-### H. Optional server-side render (zero-install fallback)
-For users who can't/won't install: render on ViralSpin infra (your compute → more credits).
-Trade-off: no local-file capability (must upload), but truly zero-setup.
-
-## 5. End-to-end UX (target)
-
-1. User signs in to ViralSpin, funds credits (one time). Token provisioned silently.
-2. Adds the ViralSpin connector — enough on its own for URL / Google-Photos → server-side render.
-3. Types a command referencing local files. Agent: *"This needs a one-time ~10-min local setup
-   to use your local files — install it?"* → installs the `.mcpb` → restart once.
-4. Thereafter, local-file commands "just work": transcribe → AI picks B-roll by context
-   (local folders + Google Photos pooled) → render locally → publish. AI cost = credits; no keys shown.
-
-## 6. Open questions / caveats
-
-- **Render on user hardware** — slow on weak machines. §4H is the escape hatch.
-- **Baseline prereqs** — OS + disk space even with a bundle; confirm Node bundling in `.mcpb`.
-- **Reconnect seam** — see §4F; need "restart once" UX until clients hot-load MCP servers.
-- **Credit metering granularity** — per-asset analysis vs per-render flat fee.
-- **Cache invalidation** — mtime is good enough locally; URLs need a content hash.
-
-## 7. Suggested sequencing
-
-1. **C + D** (Gemini→backend proxy + token-via-login) — unblocks distribution; do first.
-2. **A** (Python→Node) — removes the Python prereq.
-3. **B + E** (bundle runtime + analysis cache) — the actual "10-min install, then fast" payoff.
-4. **F** (.mcpb + client-side auto-install with consent).
-5. **G** (adjustment tools), **H** (server-side render) — after the local MVP ships.

package/engine/assemble.mjs

@@ -1,476 +0,0 @@
-#!/usr/bin/env node
-/**
- * Local video-assembly engine (Node-only — no Python, bundled ffmpeg).
- *   node assemble.mjs --aroll <path|url> [--broll <path|url|folder> ...] [--prompt] [--style-ref]
- *                     [--format 9x16|1x1|16x9] [--out]
- *   node assemble.mjs --suggest <cutIdx>           (rank alternatives for a cut)
- *   node assemble.mjs --swap <cutIdx> <assetName>  (swap a cut + re-render)
- * Pipeline: stage A-roll -> transcribe -> rank albums -> album-weighted B-roll -> analyze ->
- * (rotate) -> editorial -> captions -> face-aware Remotion render. Prints "RESULT:<mp4>".
- */
-import { execFileSync, spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import fs from "node:fs";
-import path from "node:path";
-import ffmpegStatic from "ffmpeg-static";
-import ffprobeStatic from "ffprobe-static";
-import { transcribe, analyzeFrame, rankAlbums, inferStyle, editTimeline, getDirectorDecisions, inferCaptionStyle } from "./gemini.mjs";
-import os from "node:os";
-
-const FFMPEG = ffmpegStatic;
-const FFPROBE = ffprobeStatic.path;
-const EXPLAINER_INDEX_ID = process.env.EXPLAINER_INDEX_ID || "";
-const TL_KEY = process.env.TWELVE_LABS_API_KEY || "";
-const TL_BASE = "https://api.twelvelabs.io/v1.2";
-const LONG_VIDEO_SECS = 120;
-
-// Read the Twelve Labs video cache written by index_explainer_sources.
-const VIRALSPIN_HOME = path.join(os.homedir(), ".viralspin");
-const EXPLAINER_CACHE_FILE = path.join(VIRALSPIN_HOME, "explainer_cache.json");
-function readExplainerCache() {
-  try { return JSON.parse(fs.readFileSync(EXPLAINER_CACHE_FILE, "utf8")); } catch { return { videos: {} }; }
-}
-function localPathFromVideoId(videoId, cache) {
-  for (const [key, v] of Object.entries(cache.videos || {})) {
-    if (v.video_id === videoId) return key.split("|")[0];
-  }
-  return null;
-}
-
-async function tlSearch(query, indexId) {
-  try {
-    const r = await fetch(`${TL_BASE}/search`, {
-      method: "POST",
-      headers: { "x-api-key": TL_KEY, "Content-Type": "application/json" },
-      body: JSON.stringify({ index_id: indexId, query_text: query, options: ["visual", "conversation", "text_in_video"] }),
-    });
-    if (!r.ok) return [];
-    const data = await r.json();
-    return (data.data || []).slice(0, 3);
-  } catch { return []; }
-}
-const ENGINE = path.dirname(fileURLToPath(import.meta.url));
-const PUBLIC = path.join(ENGINE, "public");
-const BROLL = path.join(PUBLIC, "broll");
-const RUN = path.join(ENGINE, "_run");
-const CACHE = path.join(ENGINE, "cache");
-const IMG = new Set([".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif"]);
-const VID = new Set([".mp4", ".mov", ".webm", ".m4v", ".avi", ".mkv", ".wmv"]);
-const SKIP_DIR = /^(porno|logo|inventory|test)$/i;
-const IMG_BUDGET = 24, VID_BUDGET = 16;
-const MAX_COVER = 2.8; // skip B-roll needing >2.8x upscale to fill the frame (would pixellate)
-
-const argv = process.argv.slice(2);
-const one = (f, d) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
-const many = (f) => { const o = []; for (let i = 0; i < argv.length; i++) if (argv[i] === f) { let j = i + 1; while (j < argv.length && !argv[j].startsWith("--")) o.push(argv[j++]); } return o; };
-const aroll = one("--aroll");
-const brollIn = many("--broll");
-const prompt = one("--prompt", "");
-const format = one("--format", "9x16");
-const styleRef = one("--style-ref", "");
-const captionStyleArg = one("--caption-style", "auto"); // "auto" → AI picks; override with e.g. "hormozi"
-const suggestIdx = one("--suggest", null);
-const swapArgs = many("--swap");
-const captionStyleSwapMode = argv.includes("--swap-caption-style");
-const out = path.resolve(one("--out", path.join(ENGINE, "out", "assembly.mp4")));
-const adjustMode = suggestIdx !== null || swapArgs.length >= 2 || captionStyleSwapMode;
-if (!aroll && !adjustMode) { console.error("ERROR: --aroll is required"); process.exit(1); }
-
-const isUrl = (s) => /^https?:\/\//i.test(s);
-const extOf = (f) => (isUrl(f) ? path.extname(new URL(f).pathname) : path.extname(f)).toLowerCase();
-const log = (...a) => console.error("[assemble]", ...a);
-const ff = (args) => execFileSync(FFMPEG, args, { stdio: ["ignore", "ignore", "ignore"] });
-async function download(url, dest) { const r = await fetch(url); if (!r.ok) throw new Error(`download ${r.status} ${url}`); fs.writeFileSync(dest, Buffer.from(await r.arrayBuffer())); }
-function evenSample(arr, n) { if (arr.length <= n) return arr.slice(); const step = arr.length / n, o = []; for (let i = 0; i < n; i++) o.push(arr[Math.floor(i * step)]); return o; }
-function probeDuration(file) { try { return parseFloat(execFileSync(FFPROBE, ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", file]).toString().trim()) || 0; } catch { return 0; } }
-function probeDims(file) {
-  try {
-    const o = execFileSync(FFPROBE, ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height", "-of", "csv=p=0:s=x", file]).toString().trim();
-    const [w, h] = o.split("x").map(Number);
-    return [w || 0, h || 0];
-  } catch { return [0, 0]; }
-}
-function render() {
-  // pass the entry explicitly — when the engine lives inside another package (mcp/engine),
-  // Remotion would otherwise pick that package's src/index.ts as the entry.
-  const entry = path.join(ENGINE, "src", "index.ts");
-  // --public-dir: when nested in another package, Remotion picks the outer root's public/ by
-  // default; point it at the engine's own public/ so staticFile() assets resolve.
-  const r = spawnSync(`npx remotion render "${entry}" Assembly "${out}" "--props=${path.join(PUBLIC, "editData.json")}" "--public-dir=${PUBLIC}"`, { cwd: ENGINE, shell: true, stdio: "inherit" });
-  if (r.status !== 0) throw new Error(`remotion render failed (${r.status})`);
-}
-
-// prep dirs — skip destructive cleanup in swap/adjust modes so staged files survive
-if (!adjustMode) {
-  fs.rmSync(BROLL, { recursive: true, force: true });
-  fs.rmSync(path.join(PUBLIC, "aroll.mp4"), { force: true });
-}
-fs.mkdirSync(BROLL, { recursive: true });
-fs.mkdirSync(RUN, { recursive: true });
-fs.mkdirSync(CACHE, { recursive: true });
-fs.mkdirSync(path.dirname(out), { recursive: true });
-
-async function stageAroll() {
-  let src = aroll;
-  if (isUrl(aroll)) { src = path.join(RUN, "aroll_src"); await download(aroll, src); }
-  else if (!fs.existsSync(src)) throw new Error(`A-roll not found: ${src}`);
-  log("transcoding A-roll…");
-  ff(["-y", "-i", src, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-movflags", "+faststart", path.join(PUBLIC, "aroll.mp4")]);
-}
-
-function listAlbums(dir) {
-  const albums = {};
-  const add = (name, fp) => {
-    const e = path.extname(fp).toLowerCase();
-    if (!IMG.has(e) && !VID.has(e)) return;
-    (albums[name] ??= { imgs: [], vids: [] })[IMG.has(e) ? "imgs" : "vids"].push(fp);
-  };
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const e of entries) if (e.isFile()) add("(root)", path.join(dir, e.name));
-  for (const e of entries) if (e.isDirectory() && !SKIP_DIR.test(e.name)) {
-    const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).forEach((x) => {
-      const fp = path.join(d, x.name);
-      if (x.isDirectory()) { if (!SKIP_DIR.test(x.name)) walk(fp); } else add(e.name, fp);
-    });
-    walk(path.join(dir, e.name));
-  }
-  return albums;
-}
-
-async function stageBroll(transcriptText, segments = []) {
-  const albums = {};
-  const merge = (name, v) => { albums[name] ??= { imgs: [], vids: [] }; albums[name].imgs.push(...v.imgs); albums[name].vids.push(...v.vids); };
-  const urls = [];
-  // Long-form videos queued for Twelve Labs temporal search (only when index is available).
-  const longFormQueue = [];
-  for (const p of brollIn) {
-    if (isUrl(p)) { urls.push(p); continue; }
-    const st = fs.statSync(p, { throwIfNoEntry: false });
-    if (!st) { log("skip (missing):", p); continue; }
-    if (st.isDirectory()) {
-      // Walk directory; intercept long videos.
-      const walked = listAlbums(p);
-      for (const [k, v] of Object.entries(walked)) {
-        const shortVids = [], longVids = [];
-        for (const vf of v.vids) {
-          if (EXPLAINER_INDEX_ID && TL_KEY && probeDuration(vf) > LONG_VIDEO_SECS) longVids.push(vf);
-          else shortVids.push(vf);
-        }
-        longFormQueue.push(...longVids);
-        merge(k, { imgs: v.imgs, vids: shortVids });
-      }
-    } else {
-      const e = extOf(p);
-      if (VID.has(e) && EXPLAINER_INDEX_ID && TL_KEY && probeDuration(p) > LONG_VIDEO_SECS) {
-        log(`long-form video (${probeDuration(p).toFixed(0)}s), queuing for Twelve Labs search: ${path.basename(p)}`);
-        longFormQueue.push(p);
-      } else {
-        merge("(loose)", { imgs: IMG.has(e) ? [p] : [], vids: VID.has(e) ? [p] : [] });
-      }
-    }
-  }
-  const names = Object.keys(albums);
-
-  // rank albums by name vs transcript
-  let weights = Object.fromEntries(names.map((n) => [n, 0.5]));
-  if (names.length > 1) {
-    try {
-      const r = await rankAlbums(transcriptText, names.map((n) => ({ name: n, count: albums[n].imgs.length + albums[n].vids.length })));
-      weights = r.weights;
-      log("album weights:", JSON.stringify(weights));
-    } catch (e) { log("album ranking failed (even weights):", e.message); }
-  }
-
-  const pick = (key, budget) => {
-    const avail = names.filter((n) => albums[n][key].length);
-    const sumW = avail.reduce((a, n) => a + (weights[n] ?? 0.3), 0) || 1;
-    let chosen = [];
-    for (const n of avail) chosen.push(...evenSample(albums[n][key], Math.max(1, Math.round(budget * (weights[n] ?? 0.3) / sumW))));
-    return evenSample(chosen, budget);
-  };
-  const files = [...pick("imgs", IMG_BUDGET), ...pick("vids", VID_BUDGET), ...urls];
-
-  const srcmap = {};
-  const keyOf = (f) => { try { const s = fs.statSync(f); return `${path.resolve(f)}|${s.size}|${Math.round(s.mtimeMs)}`; } catch { return `path:${f}`; } };
-  const [TW, TH] = format === "1x1" ? [1080, 1080] : format === "16x9" ? [1920, 1080] : [1080, 1920];
-  let img = 0, vid = 0;
-  for (const f of files) {
-    let src = f;
-    try {
-      if (isUrl(f)) { src = path.join(RUN, "dl_" + (img + vid)); await download(f, src); }
-      const [dw, dh] = probeDims(src);
-      if (dw && dh && Math.max(TW / dw, TH / dh) > MAX_COVER) { log("skip (low-res):", path.basename(String(f))); continue; }
-      let name;
-      if (VID.has(extOf(f))) {
-        name = `v${String(vid).padStart(2, "0")}.mp4`;
-        ff(["-y", "-i", src, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-t", "6", "-vf", "scale='min(1280,iw)':-2", path.join(BROLL, name)]);
-        vid++;
-      } else {
-        name = `${String(img).padStart(2, "0")}.jpg`;
-        ff(["-y", "-i", src, "-vf", "scale='min(2048,iw)':-2", path.join(BROLL, name)]);
-        img++;
-      }
-      srcmap[name] = isUrl(f) ? `url:${f}` : keyOf(f);
-    } catch { log("skip (convert failed):", path.basename(String(f))); }
-  }
-  // Twelve Labs temporal search for long-form recordings.
-  if (longFormQueue.length > 0 && EXPLAINER_INDEX_ID && TL_KEY) {
-    log(`director pass: ${longFormQueue.length} long-form video(s) → Twelve Labs search (index: ${EXPLAINER_INDEX_ID})`);
-    const cache = readExplainerCache();
-    let decisions = [];
-    try { decisions = await getDirectorDecisions(segments); } catch { /* use transcript keywords as fallback */ }
-
-    if (decisions.length === 0) {
-      // Fallback: use the whole transcript as one search query.
-      decisions = [{ search_query: transcriptText.slice(0, 200), layout: "interrupt", first_mention_ms: 0 }];
-    }
-
-    for (const decision of decisions) {
-      log(`  searching: "${decision.search_query}"`);
-      const results = await tlSearch(decision.search_query, EXPLAINER_INDEX_ID);
-      if (!results.length) { log("  no results for:", decision.search_query); continue; }
-
-      const top = results[0];
-      const localPath = localPathFromVideoId(top.video_id, cache);
-      if (!localPath || !fs.existsSync(localPath)) {
-        log(`  video_id ${top.video_id} not found in local cache — re-run index_explainer_sources`);
-        continue;
-      }
-
-      const startSec = typeof top.start === "number" ? top.start : 0;
-      const endSec = typeof top.end === "number" ? top.end : startSec + 10;
-      const dur = Math.min(endSec - startSec, 30);
-      const clipName = `v${String(vid).padStart(2, "0")}.mp4`;
-      const clipPath = path.join(BROLL, clipName);
-      try {
-        ff(["-y", "-ss", String(startSec), "-t", String(dur), "-i", localPath,
-            "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac",
-            "-vf", "scale='min(1280,iw)':-2", clipPath]);
-        srcmap[clipName] = `tl:${top.video_id}:${startSec}`;
-        vid++;
-        log(`  ✓ extracted ${path.basename(localPath)} @ ${startSec.toFixed(1)}s-${(startSec + dur).toFixed(1)}s → ${clipName}`);
-      } catch (e) { log(`  ✗ clip extraction failed: ${e.message}`); }
-    }
-  }
-
-  fs.writeFileSync(path.join(RUN, "srcmap.json"), JSON.stringify(srcmap));
-  log(`B-roll: ${img} images + ${vid} videos staged (from ${names.length} albums${longFormQueue.length ? ` + ${longFormQueue.length} long-form via Twelve Labs` : ""})`);
-  return img + vid;
-}
-
-// analyze every staged B-roll (cached by source identity → index once)
-async function analyzeBroll() {
-  const srcmap = fs.existsSync(path.join(RUN, "srcmap.json")) ? JSON.parse(fs.readFileSync(path.join(RUN, "srcmap.json"))) : {};
-  const cacheFile = path.join(CACHE, "analysis.json");
-  const cache = fs.existsSync(cacheFile) ? JSON.parse(fs.readFileSync(cacheFile)) : {};
-  const res = {};
-  for (const name of fs.readdirSync(BROLL).sort()) {
-    const ext = path.extname(name).toLowerCase();
-    const kind = IMG.has(ext) ? "image" : VID.has(ext) ? "video" : null;
-    if (!kind) continue;
-    const key = srcmap[name];
-    if (key && cache[key]) { res[name] = cache[key]; log(`${name} (cached)`); continue; }
-    let frame = path.join(BROLL, name);
-    if (kind === "video") {
-      frame = path.join(RUN, "f_" + name + ".jpg");
-      const d = probeDuration(path.join(BROLL, name)) || 1;
-      try { ff(["-y", "-ss", String(Math.max(0.1, d / 2)), "-i", path.join(BROLL, name), "-frames:v", "1", "-vf", "scale=640:-1", frame]); } catch {}
-    }
-    try { res[name] = await analyzeFrame(frame, kind); if (key) cache[key] = res[name]; log(`${name} ${kind} ${res[name].subject} (${res[name].focal})`); }
-    catch (e) { res[name] = { kind, rotate: 0, focal: [0.5, 0.45], secondary: null, subject: "scenery", desc: "", keywords: [] }; log(`${name} analyze error: ${e.message}`); }
-  }
-  fs.writeFileSync(cacheFile, JSON.stringify(cache));
-  fs.writeFileSync(path.join(RUN, "analysis.json"), JSON.stringify(res, null, 2));
-  return res;
-}
-
-async function inferStyleFromRef(refPath) {
-  const [w, h] = probeDims(refPath); const dur = probeDuration(refPath);
-  const fmt = w === h ? "1x1" : w > h ? "16x9" : "9x16";
-  let cuts = 0;
-  try { const r = spawnSync(FFMPEG, ["-i", refPath, "-vf", "select='gt(scene,0.35)',showinfo", "-an", "-f", "null", "-"], { encoding: "utf8" }); cuts = (String(r.stderr).match(/showinfo/g) || []).length; } catch {}
-  const frames = [];
-  for (let i = 0; i < 8; i++) {
-    const t = dur ? Math.max(0.3, (dur * (i + 0.5)) / 8) : 1;
-    const fp = path.join(RUN, `sref_${i}.jpg`);
-    try { ff(["-y", "-ss", String(t), "-i", refPath, "-frames:v", "1", "-vf", "scale=320:-1", fp]); if (fs.existsSync(fp)) frames.push(fp); } catch {}
-  }
-  const style = await inferStyle(frames, { fmt, dur: Math.round(dur), cps: dur ? (cuts / dur).toFixed(2) : "0" });
-  log("inferred style:", JSON.stringify(style));
-  return style;
-}
-
-// ── adjustment modes ──────────────────────────────────────────────────
-function beatTextAt(transcript, fromF, durF, fps) {
-  const a = (fromF / fps) * 1000, b = ((fromF + durF) / fps) * 1000;
-  return transcript.filter((s) => (s.end_ms ?? 0) >= a && (s.start_ms ?? 0) <= b).map((s) => s.text).join(" ");
-}
-function rankCandidates(analysis, beat, usedFiles) {
-  const words = new Set(String(beat).toLowerCase().split(/\W+/).filter((w) => w.length > 3));
-  const scored = [];
-  for (const [name, a] of Object.entries(analysis)) {
-    if (usedFiles.has(name)) continue;
-    const kws = [...(a.keywords || []), ...String(a.desc || "").toLowerCase().split(/\W+/)];
-    let score = kws.reduce((s, k) => s + (words.has(String(k).toLowerCase()) ? 1 : 0), 0);
-    if (a.kind === "video") score += 0.5;
-    scored.push({ name, score, desc: a.desc, kind: a.kind });
-  }
-  return scored.sort((x, y) => y.score - x.score).slice(0, 6);
-}
-function suggestMode(idx) {
-  const editData = JSON.parse(fs.readFileSync(path.join(PUBLIC, "editData.json")));
-  const analysis = JSON.parse(fs.readFileSync(path.join(RUN, "analysis.json")));
-  const transcript = JSON.parse(fs.readFileSync(path.join(RUN, "transcript.json"))).segments || [];
-  const cut = editData.cuts[idx];
-  if (!cut) throw new Error(`no cut #${idx} (have ${editData.cuts.length})`);
-  const used = new Set(editData.cuts.map((c) => path.basename(c.file)));
-  const beat = beatTextAt(transcript, cut.from, cut.dur, editData.fps);
-  const sg = path.join(ENGINE, "suggest"); fs.rmSync(sg, { recursive: true, force: true }); fs.mkdirSync(sg, { recursive: true });
-  const options = [];
-  for (const t of rankCandidates(analysis, beat, used)) {
-    const thumb = path.join(sg, t.name.replace(/\.[^.]+$/, "") + ".jpg");
-    try { ff(["-y", "-ss", "0.5", "-i", path.join(BROLL, t.name), "-frames:v", "1", "-vf", "scale=240:-1", thumb]); } catch {}
-    options.push({ asset: t.name, kind: t.kind, desc: t.desc, thumb });
-  }
-  console.log("SUGGEST:" + JSON.stringify({ cut: idx, beat, current: path.basename(cut.file), options }));
-}
-function swapMode(idx, asset) {
-  const editData = JSON.parse(fs.readFileSync(path.join(PUBLIC, "editData.json")));
-  const analysis = JSON.parse(fs.readFileSync(path.join(RUN, "analysis.json")));
-  const a = analysis[asset]; if (!a) throw new Error(`unknown asset ${asset}`);
-  const cut = editData.cuts[idx]; if (!cut) throw new Error(`no cut #${idx}`);
-  const [w, h] = probeDims(path.join(BROLL, asset));
-  Object.assign(cut, { file: "broll/" + asset, focal: a.focal, secondary: a.secondary || null, video: a.kind === "video", srcW: w, srcH: h });
-  fs.writeFileSync(path.join(PUBLIC, "editData.json"), JSON.stringify(editData, null, 2));
-  render();
-  console.log("RESULT:" + out);
-}
-
-function swapCaptionStyleMode(styleId) {
-  const VALID = ["default", "hormozi", "glow_neon", "minimalist", "whiteboard"];
-  if (!VALID.includes(styleId)) throw new Error(`unknown caption style "${styleId}". Choose one of: ${VALID.join(", ")}`);
-  const editData = JSON.parse(fs.readFileSync(path.join(PUBLIC, "editData.json")));
-  editData.captionStyle = styleId;
-  fs.writeFileSync(path.join(PUBLIC, "editData.json"), JSON.stringify(editData, null, 2));
-  log(`caption style swapped to: ${styleId}`);
-  render();
-  console.log("RESULT:" + out);
-}
-
-async function main() {
-  if (suggestIdx !== null) return suggestMode(parseInt(suggestIdx, 10));
-  if (swapArgs.length >= 2) return swapMode(parseInt(swapArgs[0], 10), swapArgs[1]);
-  if (captionStyleSwapMode) return swapCaptionStyleMode(captionStyleArg !== "auto" ? captionStyleArg : "default");
-
-  await stageAroll();
-  const dur = probeDuration(path.join(PUBLIC, "aroll.mp4"));
-  const fps = 30, totalFrames = Math.max(1, Math.round(dur * fps)), totalMs = Math.round(dur * 1000);
-  log(`A-roll ${dur.toFixed(2)}s → ${totalFrames} frames`);
-
-  // transcribe
-  log("transcribing (Gemini)…");
-  ff(["-y", "-i", path.join(PUBLIC, "aroll.mp4"), "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le", path.join(RUN, "aroll.wav")]);
-  const segments = await transcribe(path.join(RUN, "aroll.wav"));
-  fs.writeFileSync(path.join(RUN, "transcript.json"), JSON.stringify({ segments }, null, 2));
-  const transcriptText = segments.map((s) => s.text).join(" ");
-  log(`transcript: ${segments.length} segments`);
-
-  // style
-  let style = null;
-  if (styleRef) {
-    log("inferring style from reference…");
-    let sref = styleRef;
-    if (isUrl(styleRef)) { sref = path.join(RUN, "styleref"); await download(styleRef, sref); }
-    try { style = await inferStyleFromRef(sref); } catch (e) { log("style inference failed (defaults):", e.message); }
-  }
-  const effFormat = style?.format || format;
-  const wantCaptions = !style || style.captions !== false;
-
-  // caption style — user override > style_ref inference > AI transcript analysis
-  let captionStyle = "default";
-  if (captionStyleArg && captionStyleArg !== "auto") {
-    captionStyle = captionStyleArg;
-    log(`caption style: ${captionStyle} (user-specified)`);
-  } else if (style?.caption_style) {
-    captionStyle = style.caption_style;
-    log(`caption style: ${captionStyle} (inferred from style_ref)`);
-  } else {
-    log("inferring caption style from transcript…");
-    try { captionStyle = await inferCaptionStyle(transcriptText); } catch { captionStyle = "default"; }
-    log(`caption style: ${captionStyle} (AI-inferred)`);
-  }
-
-  const nBroll = await stageBroll(transcriptText, segments);
-
-  let cuts = [], pops = [], hook = null, analysis = {};
-  if (nBroll > 0) {
-    log("analysing B-roll (Gemini vision)…");
-    analysis = await analyzeBroll();
-    // correct sideways B-roll
-    for (const [name, a] of Object.entries(analysis)) {
-      const rot = a.rotate || 0;
-      if (rot !== 90 && rot !== 180 && rot !== 270) continue;
-      const file = path.join(BROLL, name);
-      const isVid = name.toLowerCase().endsWith(".mp4");
-      const tmp = file + (isVid ? ".rot.mp4" : ".rot.jpg");
-      const tp = rot === 90 ? "transpose=1" : rot === 270 ? "transpose=2" : "transpose=1,transpose=1";
-      try { ff(["-y", "-i", file, "-vf", tp, ...(isVid ? ["-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac"] : []), tmp]); fs.renameSync(tmp, file); log(`rotated ${name} ${rot}°`); } catch { log("rotate failed:", name); }
-    }
-    log("editorial pass (Gemini)…");
-    const edit = await editTimeline(segments, analysis, totalMs, prompt, style);
-    cuts = edit.cuts; pops = edit.pops; hook = edit.hook;
-  }
-
-  // captions
-  const capsMs = [];
-  for (const s of (wantCaptions ? segments : [])) {
-    const raw = String(s.text || "").trim();
-    if (/^\(.*\)$/.test(raw)) continue;
-    const words = raw.split(/\s+/).filter(Boolean);
-    if (!words.length) continue;
-    const span = Math.max(600, (s.end_ms || 0) - (s.start_ms || 0));
-    const chunks = []; for (let i = 0; i < words.length; i += 3) chunks.push(words.slice(i, i + 3).join(" "));
-    const totChars = chunks.reduce((a, c) => a + c.length, 0) || 1;
-    let t = s.start_ms || 0;
-    for (const c of chunks) { const d = Math.max(380, Math.round(span * (c.length / totChars))); capsMs.push({ from_ms: t, dur_ms: d, text: c }); t += d; }
-  }
-
-  // build editData
-  const f2 = (ms) => Math.round((ms / 1000) * fps);
-  let built = [];
-  for (const c of cuts) {
-    const a = analysis[c.broll_id]; if (!a) continue;
-    const from = Math.max(0, f2(c.from_ms)), d = Math.max(8, f2(c.dur_ms));
-    if (from + d > totalFrames) continue;
-    const [srcW, srcH] = probeDims(path.join(BROLL, c.broll_id));
-    built.push({ from, dur: d, file: "broll/" + c.broll_id, video: a.kind === "video", dir: c.dir ? 1 : 0, focal: a.focal, secondary: a.secondary || null, srcW, srcH });
-  }
-  built.sort((x, y) => x.from - y.from);
-  const cleaned = []; let last = -1;
-  for (const c of built) if (c.from >= last) { cleaned.push(c); last = c.from + c.dur; }
-
-  const popsF = pops.map((p) => ({ from: f2(p.from_ms), dur: 27, text: String(p.text).toUpperCase() })).filter((p) => p.from >= 0 && p.from + p.dur <= totalFrames);
-
-  const AROLL_FY = 0.38;
-  const captionY = (from, durF) => {
-    const mid = from + durF / 2;
-    const cut = cleaned.find((c) => mid >= c.from && mid < c.from + c.dur);
-    const focalY = cut ? cut.focal[1] : AROLL_FY;
-    let y = 0.58;
-    if (Math.abs(focalY - y) < 0.16) y = focalY < 0.5 ? Math.min(0.82, focalY + 0.3) : Math.max(0.2, focalY - 0.3);
-    if (popsF.some((p) => mid >= p.from - 4 && mid < p.from + p.dur + 4)) y = 0.84;
-    return Math.max(0.16, Math.min(0.86, y));
-  };
-  const captions = capsMs
-    .map((c) => ({ from: f2(c.from_ms), dur: Math.max(8, f2(c.dur_ms)), text: c.text }))
-    .filter((c) => c.from < totalFrames)
-    .map((c) => { const durF = Math.min(c.dur, totalFrames - c.from); return { ...c, dur: durF, y: captionY(c.from, durF) }; });
-  const hookF = hook && hook.text ? { from: 0, dur: Math.min(110, totalFrames), text: hook.text, keyword: hook.keyword || "" } : null;
-
-  const editData = { format: effFormat, fps, totalFrames, aroll: "aroll.mp4", arollFocal: [0.5, 0.38], cuts: cleaned, captions, pops: popsF, hook: hookF, captionStyle };
-  fs.writeFileSync(path.join(PUBLIC, "editData.json"), JSON.stringify(editData, null, 2));
-  log(`${cleaned.length} cutaways, ${captions.length} captions, ${popsF.length} pops, hook=${hookF ? "yes" : "no"}, captionStyle=${captionStyle} → rendering…`);
-  render();
-  console.log("RESULT:" + out);
-}
-main().catch((e) => { console.error("[assemble] FATAL:", e.message); process.exit(1); });