vibemovie 0.1.0 → 0.2.0

package/dist/{chunk-JTRTKTPK.js → chunk-DO2IWHL6.js}

@@ -1,5 +1,5 @@
 // src/index.ts
-import { createCascade, createConsentLedger } from "@pooriaarab/vibe-core";
+import { createCascade, createConsentLedger, makeEvent, notify as vibeCoreNotify } from "@pooriaarab/vibe-core";
 import { writeFile } from "fs/promises";
 
 // src/scenes.ts
@@ -687,6 +687,327 @@ function renderHyperframes(scenes, opts = {}) {
 `;
 }
 
+// src/cinematic.ts
+import { execFileSync } from "child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename as basename2, join } from "path";
+var ENGINES = ["hyperframes", "cinematic"];
+var STYLE = "cinematic 1980s film still, warm tungsten light with subtle magenta and cyan neon accents, 35mm film grain, shallow depth of field, night";
+var SET = "the SAME single cozy 1980s home office at night: a wooden desk front and center with a glowing laptop and mechanical keyboard, a steaming mug, sticky notes on the wall behind it, a warm desk lamp on the left, and a bookshelf with a glowing retro radio on the right";
+var DEV = "a young woman software developer in her early twenties, big voluminous curly blonde 80s hair, natural makeup with soft neutral eyeshadow and red lipstick, wearing a VIBRANT colorful 80s outfit: a bold color-blocked cropped jacket in hot pink and electric blue over a bright teal tee, vibrant and colorful";
+var LOCK = "Identical woman and identical office as the reference (same face, big curly blonde hair, natural red-lip makeup, vibrant hot-pink-and-blue cropped jacket, teal tee, same desk/laptop/lamp/sticky-notes/bookshelf). Only change pose and camera.";
+var EYE = "looking at what she is doing, not at the camera";
+function plural2(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function deriveReferencePrompts() {
+  return {
+    hero: `${STYLE}. Wide reference of ${DEV}, settling in to work at ${SET}.`,
+    face: `${STYLE}. Clean sharp front-facing headshot portrait of ${DEV}, looking straight at camera, evenly lit, crisp focus on her face.`
+  };
+}
+function beatFor(scene2) {
+  switch (scene2.kind) {
+    case "title": {
+      const d = scene2.data;
+      const dur = d.totalMinutes > 0 ? `${formatMinutes(d.totalMinutes)} in the flow` : "a session worth replaying";
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Wide establishing shot from across the room: she drops into her desk chair and flips open the glowing laptop, screen light spilling onto her face, ${EYE}. ${STYLE}`,
+        motion: `she sits down at the desk and opens the laptop, the screen wakes and lights her face, smooth settle-in. ${STYLE}`,
+        vo: `[energetically] ${d.sessionName} \u2014 ${dur}. Let's run it back.`
+      };
+    }
+    case "tasks": {
+      const d = scene2.data;
+      const first = d.tasks[0]?.label ?? "the first task";
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Close-up side profile: she types fast on the mechanical keyboard, then reaches up and ticks a sticky note on the wall, mid-action, ${EYE}. ${STYLE}`,
+        motion: `she types quickly, then reaches over and checks off a sticky note, natural working rhythm. ${STYLE}`,
+        vo: d.total === 1 ? `[excited] One task landed, clean \u2014 ${first}.` : `[excited] ${plural2(d.total, "task")} landed, clean \u2014 kicked off by ${first}.`
+      };
+    }
+    case "diff": {
+      const d = scene2.data;
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Over-the-shoulder shot from behind her: she leans into the glowing laptop covered in code, one hand mid-scroll, screen glow catching her hair, ${EYE}. ${STYLE}`,
+        motion: `she scrolls through the diff and leans in closer to the code, subtle continuous motion. ${STYLE}`,
+        vo: `[excited] ${plural2(d.filesChanged, "file")} touched \u2014 plus ${d.additions}, minus ${d.deletions}.`
+      };
+    }
+    case "terminal": {
+      const d = scene2.data;
+      const hasTests = d.lines.some((l) => l.cls === "ok" && l.text.includes("passed"));
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Three-quarter shot from the lamp side: she throws a triumphant fist pump at the glowing screen, mid-cheer, ${EYE}. ${STYLE}`,
+        motion: `she reads the screen, then pumps her fist in celebration, energetic. ${STYLE}`,
+        vo: hasTests ? "[shouting] GREEN! Green across the board \u2014 every test, passing!" : "[excited] The commands tell the story \u2014 clean, top to bottom."
+      };
+    }
+    case "merge": {
+      const d = scene2.data;
+      const vo = d.pr !== null ? d.merged ? `[excited] And there it is \u2014 pull request number ${d.pr}, merged into ${d.branch}! No conflicts, no mercy!` : `[excited] Pull request number ${d.pr} is open on ${d.branch} \u2014 reviews incoming!` : d.merged ? `[excited] Merged into ${d.branch}! No conflicts, no mercy!` : `[excited] The pull request is open on ${d.branch}!`;
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Low-angle shot from the desk surface: she hits the enter key with a flourish and throws both hands up, screen glow flaring, mid-celebration, ${EYE}. ${STYLE}`,
+        motion: `she slams enter, throws both hands up and leans back laughing, joyful release. ${STYLE}`,
+        vo
+      };
+    }
+    case "end": {
+      return {
+        kind: scene2.kind,
+        keyframe: `${LOCK} Wide slightly dutch-angle shot: she closes the laptop and leans back in her chair with a satisfied smile, lamplight warm on the room, ${EYE}. ${STYLE}`,
+        motion: `she gently closes the laptop and leans back, smiling, calm settle. ${STYLE}`,
+        vo: `[warmly] ${scene2.caption} This is vibemovie.`
+      };
+    }
+  }
+}
+function deriveBeats(scenes) {
+  return scenes.map(beatFor);
+}
+function cinematicAvailable(env = process.env) {
+  const key = env["WAVESPEED_API_KEY"];
+  return typeof key === "string" && key.trim().length > 0;
+}
+var defaultExec = (file, args) => {
+  execFileSync(file, [...args], { stdio: "ignore" });
+};
+function ffmpegAvailable(execFn = defaultExec) {
+  try {
+    execFn("ffmpeg", ["-version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var API_BASE = "https://api.wavespeed.ai/api/v3";
+var MODEL_T2I = "bytedance/seedream-v4";
+var MODEL_EDIT = "wavespeed-ai/flux-kontext-max";
+var MODEL_I2V = "kwaivgi/kling-v2.5-turbo-pro/image-to-video";
+var MODEL_FACE_SWAP = "wavespeed-ai/video-face-swap";
+var MODEL_TTS = "elevenlabs/eleven-v3";
+var T2I_SIZE = "1920*1080";
+var CLIP_SECONDS = 5;
+var NEGATIVE_PROMPT = "morphing, warping, distorted face, changing outfit, extra fingers, flicker, duplicated objects, ghosting, double image, cloned furniture";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function renderCinematic(scenes, opts) {
+  const apiKey = opts.apiKey ?? process.env["WAVESPEED_API_KEY"];
+  if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+    throw new Error("cinematic: WAVESPEED_API_KEY is required (set it in the environment or pass opts.apiKey)");
+  }
+  const fetchFn = opts.deps?.fetchFn ?? fetch;
+  const execFn = opts.deps?.execFn ?? defaultExec;
+  const sleepFn = opts.deps?.sleepFn ?? sleep;
+  const log = opts.log ?? ((msg) => process.stderr.write(`${msg}
+`));
+  const voiceId = opts.voiceId ?? "George";
+  const workDir = opts.workDir ?? mkdtempSync(join(tmpdir(), "vibemovie-cinematic-"));
+  mkdirSync(workDir, { recursive: true });
+  const headers = { Authorization: `Bearer ${apiKey}` };
+  const post = async (model, body) => {
+    const res = await fetchFn(`${API_BASE}/${model}`, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const j = await res.json();
+    const id = j.data?.id;
+    if (id === void 0) throw new Error(`cinematic: ${model} did not return a prediction id`);
+    return id;
+  };
+  const poll = async (id, maxTicks = 95, intervalMs = 3e3) => {
+    for (let i = 0; i < maxTicks; i++) {
+      const res = await fetchFn(`${API_BASE}/predictions/${id}/result`, { headers });
+      const j = await res.json();
+      const status = j.data?.status;
+      const out = j.data?.outputs?.[0];
+      if (status === "completed" && out !== void 0) return out;
+      if (status === "failed") throw new Error(`cinematic: prediction ${id} failed`);
+      await sleepFn(intervalMs);
+    }
+    throw new Error(`cinematic: prediction ${id} timed out`);
+  };
+  const download = async (url, path) => {
+    const res = await fetchFn(url);
+    writeFileSync(path, Buffer.from(await res.arrayBuffer()));
+  };
+  const upload = async (path) => {
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(path)]), basename2(path));
+    const res = await fetchFn(`${API_BASE}/media/upload/binary`, { method: "POST", headers, body: form });
+    const j = await res.json();
+    const url = j.data?.download_url;
+    if (url === void 0) throw new Error("cinematic: media upload failed");
+    return url;
+  };
+  const t2i = async (prompt) => poll(await post(MODEL_T2I, { prompt, size: T2I_SIZE }));
+  const edit = async (prompt, image) => poll(await post(MODEL_EDIT, { prompt, image }));
+  const kling = async (first, last, motion) => poll(
+    await post(MODEL_I2V, {
+      image: first,
+      last_image: last,
+      prompt: motion,
+      duration: CLIP_SECONDS,
+      negative_prompt: NEGATIVE_PROMPT
+    })
+  );
+  const tts = async (text) => poll(
+    await post(MODEL_TTS, {
+      text,
+      voice_id: voiceId,
+      stability: 0.3,
+      similarity: 0.75,
+      use_speaker_boost: true
+    }),
+    60,
+    2500
+  );
+  const beats = deriveBeats(scenes);
+  if (beats.length < 2) throw new Error("cinematic: need at least 2 scenes to build a film");
+  log("cinematic: hero + face ref...");
+  const { hero: heroPrompt, face: facePrompt } = deriveReferencePrompts();
+  const [heroUrl, faceUrl] = await Promise.all([t2i(heroPrompt), t2i(facePrompt)]);
+  log(`cinematic: ${beats.length} keyframes (parallel)...`);
+  const kfUrls = await Promise.all(beats.map((b) => edit(b.keyframe, heroUrl)));
+  const lastKfPath = join(workDir, "end.jpg");
+  await download(kfUrls[kfUrls.length - 1], lastKfPath);
+  const clipCount = beats.length - 1;
+  log(`cinematic: ${clipCount} Kling clips (parallel, first+last frame chained)...`);
+  const clipPaths = await Promise.all(
+    beats.slice(0, -1).map(async (b, i) => {
+      const path = join(workDir, `c${i}.mp4`);
+      try {
+        await download(await kling(kfUrls[i], kfUrls[i + 1], b.motion), path);
+        log(`cinematic:  clip ${i}`);
+        return path;
+      } catch (err) {
+        log(`cinematic:  clip ${i} failed (${err instanceof Error ? err.message : String(err)}) \u2014 skipping`);
+        return null;
+      }
+    })
+  );
+  const clips = clipPaths.filter((p) => p !== null && existsSync(p));
+  if (clips.length === 0) throw new Error("cinematic: all Kling clips failed");
+  const segs = [];
+  for (let i = 0; i < clips.length; i++) {
+    const seg = join(workDir, `s${i}.mp4`);
+    execFn("ffmpeg", [
+      "-y",
+      "-i",
+      clips[i],
+      "-an",
+      "-vf",
+      "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720,setsar=1,fps=24",
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      seg
+    ]);
+    segs.push(seg);
+  }
+  const endCard = join(workDir, "end.mp4");
+  execFn("ffmpeg", [
+    "-y",
+    "-i",
+    lastKfPath,
+    "-vf",
+    `zoompan=z='min(zoom+0.0008,1.06)':d=${CLIP_SECONDS * 24}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=1280x720:fps=24,setsar=1`,
+    "-an",
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    endCard
+  ]);
+  segs.push(endCard);
+  const listPath = join(workDir, "list.txt");
+  writeFileSync(listPath, segs.map((s) => `file '${s.replace(/'/g, `'\\''`)}'`).join("\n"));
+  const baseRaw = join(workDir, "base_raw.mp4");
+  execFn("ffmpeg", ["-y", "-f", "concat", "-safe", "0", "-i", listPath, "-an", baseRaw]);
+  log(`cinematic: base cut assembled (${segs.length} segments)`);
+  let base = join(workDir, "base.mp4");
+  try {
+    log("cinematic: face-swap identity lock...");
+    const swapped = await poll(
+      await post(MODEL_FACE_SWAP, { video: await upload(baseRaw), face_image: faceUrl, target_gender: "female" }),
+      140
+    );
+    await download(swapped, base);
+  } catch (err) {
+    log(`cinematic: face-swap failed (${err instanceof Error ? err.message : String(err)}) \u2014 using the raw cut`);
+    copyFileSync(baseRaw, base);
+  }
+  const graded = join(workDir, "base_g.mp4");
+  execFn("ffmpeg", [
+    "-y",
+    "-i",
+    base,
+    "-vf",
+    "eq=contrast=1.06:saturation=1.08:brightness=0.01,colorbalance=rs=0.05:gs=0.01:bs=-0.04:rm=0.03:bm=-0.02,setsar=1",
+    "-an",
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    graded
+  ]);
+  log(`cinematic: ${beats.length} VO lines (parallel)...`);
+  const voPaths = await Promise.all(
+    beats.map(async (b, i) => {
+      const raw = join(workDir, `raw${i}.mp3`);
+      await download(await tts(b.vo), raw);
+      const processed = join(workDir, `r${i}.mp3`);
+      execFn("ffmpeg", [
+        "-y",
+        "-i",
+        raw,
+        "-af",
+        "highpass=f=80,acompressor=threshold=-18dB:ratio=2.5,volume=2dB",
+        processed
+      ]);
+      log(`cinematic:  line ${i} (${voiceId})`);
+      return processed;
+    })
+  );
+  const dur = beats.length * CLIP_SECONDS;
+  const inputs = ["-i", graded];
+  for (const p of voPaths) inputs.push("-i", p);
+  inputs.push("-f", "lavfi", "-i", `anoisesrc=color=pink:d=${dur}:a=0.025`);
+  const hissIdx = 1 + voPaths.length;
+  let fc = "";
+  voPaths.forEach((_, i) => {
+    const d = i * CLIP_SECONDS * 1e3;
+    fc += `[${i + 1}:a]adelay=${d}|${d}[v${i}];`;
+  });
+  fc += `[${hissIdx}:a]highpass=f=300,lowpass=f=3000,volume=0.5[hiss];`;
+  fc += voPaths.map((_, i) => `[v${i}]`).join("") + `[hiss]amix=inputs=${voPaths.length + 1}:duration=longest:dropout_transition=0,volume=1.3[a]`;
+  execFn("ffmpeg", [
+    "-y",
+    ...inputs,
+    "-filter_complex",
+    fc,
+    "-map",
+    "0:v",
+    "-map",
+    "[a]",
+    "-c:v",
+    "copy",
+    "-c:a",
+    "aac",
+    "-shortest",
+    opts.out
+  ]);
+  log(`cinematic: DONE -> ${opts.out}`);
+  return { path: opts.out, beats };
+}
+
 // src/index.ts
 function createHyperframesRunner() {
   return {
@@ -700,6 +1021,30 @@ function createHyperframesRunner() {
 }
 async function renderMovie(events, opts = {}) {
   const scenes = buildScenes(events, opts);
+  const log = opts.log ?? ((msg) => process.stderr.write(`${msg}
+`));
+  const sink = opts.notify ?? vibeCoreNotify;
+  let out = opts.out;
+  if ((opts.engine ?? "hyperframes") === "cinematic") {
+    if (cinematicAvailable() && ffmpegAvailable()) {
+      const cinOut = out ?? "./vibe-recap.mp4";
+      const cinOpts = { out: cinOut, log };
+      if (opts.apiKey !== void 0) cinOpts.apiKey = opts.apiKey;
+      const cin = await renderCinematic(scenes, cinOpts);
+      const result2 = { engine: "cinematic", path: cin.path };
+      notifyRenderDone(sink, result2);
+      return result2;
+    }
+    const why = !cinematicAvailable() ? "WAVESPEED_API_KEY is not set" : "ffmpeg is not on PATH";
+    log(`vibemovie: cinematic engine unavailable (${why}) \u2014 falling back to hyperframes (offline, zero keys)`);
+    if (out !== void 0) {
+      const htmlOut = out.replace(/\.(mp4|mov|webm|mkv)$/i, ".html");
+      if (htmlOut !== out) {
+        log(`vibemovie: writing the hyperframes HTML to ${htmlOut}`);
+        out = htmlOut;
+      }
+    }
+  }
   const cascade = createCascade({
     consent: createConsentLedger(),
     pickLocal: (capability) => Promise.resolve(capability === "video" ? createHyperframesRunner() : null)
@@ -713,11 +1058,26 @@ async function renderMovie(events, opts = {}) {
   if (opts.ratio !== void 0) req.ratio = opts.ratio;
   if (opts.title !== void 0) req.title = opts.title;
   const html = await provider.generate(req);
-  if (opts.out !== void 0) {
-    await writeFile(opts.out, html, "utf8");
-    return { html, path: opts.out };
+  if (out !== void 0) {
+    await writeFile(out, html, "utf8");
+    const result2 = { engine: "hyperframes", html, path: out };
+    notifyRenderDone(sink, result2);
+    return result2;
+  }
+  const result = { engine: "hyperframes", html };
+  notifyRenderDone(sink, result);
+  return result;
+}
+function notifyRenderDone(sink, result) {
+  try {
+    sink(
+      makeEvent("render-done", "vibemovie", process.cwd(), {
+        summary: `rendered ${result.engine} recap${result.path !== void 0 ? ` \u2192 ${result.path}` : ""}`,
+        outputPath: result.path ?? null
+      })
+    );
+  } catch {
   }
-  return { html };
 }
 
 export {
@@ -725,5 +1085,10 @@ export {
   TEMPLATES,
   buildScenes,
   renderHyperframes,
+  ENGINES,
+  deriveReferencePrompts,
+  deriveBeats,
+  cinematicAvailable,
+  renderCinematic,
   renderMovie
 };

package/dist/cinematic-C31_2Fw6.d.ts

@@ -0,0 +1,219 @@
+import { VibeEvent } from '@pooriaarab/vibe-core';
+
+/**
+ * scenes.ts — pure events → scene-list compiler.
+ *
+ * Takes normalized `VibeEvent`s (from vibe-core) or loose `RawEvent`s (anything a
+ * harness/logger might emit) and compiles them into an ordered, fully-described
+ * scene list for the Hyperframes renderer. No IO, no randomness, no clock — the
+ * same events always produce the same scenes, which makes this unit-testable and
+ * the rendered HTML deterministic.
+ */
+
+type Ratio = '16:9' | '9:16' | '1:1';
+type Template = 'documentary' | 'speedrun' | 'meme';
+type Transition = 'fade' | 'slide' | 'scale' | 'rise';
+type SceneKind = 'title' | 'tasks' | 'diff' | 'terminal' | 'merge' | 'end';
+/**
+ * A loosely-shaped event from any source: a harness transcript export, a JSON
+ * log, a hand-written fixture. Any field may be missing; known aliases
+ * (`type`/`timestamp`) are normalized.
+ */
+interface RawEvent {
+    kind?: string;
+    type?: string;
+    ts?: number;
+    timestamp?: number | string;
+    agent?: string;
+    cwd?: string;
+    payload?: Record<string, unknown>;
+}
+interface BuildOptions {
+    /** Accepted for API symmetry with the renderer; layout is a render-time concern. */
+    ratio?: Ratio;
+    /** Caption tone + pacing. Default 'documentary'. */
+    template?: Template;
+    /** Session name for the title card. Default: basename of the events' cwd. */
+    title?: string;
+}
+interface TitleData {
+    sessionName: string;
+    /** Total session length in whole minutes, counted up during the title scene. */
+    totalMinutes: number;
+    subtitle: string;
+}
+interface TaskRow {
+    label: string;
+    durationMin?: number;
+}
+interface TasksData {
+    /** Real number of completed tasks (may exceed `tasks.length`). */
+    total: number;
+    /** Rows actually shown (capped at MAX_TASK_ROWS). */
+    tasks: TaskRow[];
+}
+interface DiffData {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+    /** Up to 4 representative file paths. */
+    files: string[];
+}
+interface TermLine {
+    text: string;
+    cls: 'ok' | '';
+}
+interface TerminalData {
+    lines: TermLine[];
+}
+interface MergeData {
+    pr: number | null;
+    branch: string;
+    reviewers: number | null;
+    merged: boolean;
+}
+interface EndData {
+    tagline: string;
+}
+interface SceneBase {
+    /** DOM id in the rendered page, `scene-<kind>`. */
+    id: string;
+    transition: Transition;
+    /** Milliseconds on the timeline. */
+    duration: number;
+    /** Narrator caption shown while the scene is live. */
+    caption: string;
+}
+type Scene = (SceneBase & {
+    kind: 'title';
+    data: TitleData;
+}) | (SceneBase & {
+    kind: 'tasks';
+    data: TasksData;
+}) | (SceneBase & {
+    kind: 'diff';
+    data: DiffData;
+}) | (SceneBase & {
+    kind: 'terminal';
+    data: TerminalData;
+}) | (SceneBase & {
+    kind: 'merge';
+    data: MergeData;
+}) | (SceneBase & {
+    kind: 'end';
+    data: EndData;
+});
+/**
+ * Compile events into an ordered scene list.
+ *
+ * Always emits a title card and an end card; the middle scenes appear only when
+ * the events carry the data for them (tasks → task ticks, file/diff stats →
+ * animated diff, notable command events → terminal moment, PR event → merge
+ * celebration). Empty input yields `[title, end]`.
+ *
+ * PURE: no IO, no clock, no randomness.
+ */
+declare function buildScenes(events: readonly (VibeEvent | RawEvent)[], opts?: BuildOptions): Scene[];
+
+/**
+ * cinematic.ts — the BYO-key gen-video engine: session scenes → a real mp4.
+ *
+ * Opt-in tier above Hyperframes. Given the scene list from `buildScenes`, it
+ * renders a short cinematic character video of the session via wavespeed.ai
+ * and muxes an ElevenLabs voiceover with ffmpeg:
+ *
+ *   1. derive one beat per scene (~6): keyframe prompt + motion prompt + VO line
+ *   2. `bytedance/seedream-v4` — wide hero + crisp face headshot (parallel)
+ *   3. `wavespeed-ai/flux-kontext-max` — one keyframe per beat, image-conditioned
+ *      on the hero with a LOCK string for character/set consistency (parallel)
+ *   4. `kwaivgi/kling-v2.5-turbo-pro/image-to-video` — chained 5s clips:
+ *      `image` = keyframe N, `last_image` = keyframe N+1, so cuts are seamless
+ *   5. `wavespeed-ai/video-face-swap` — swap the headshot face onto the silent
+ *      cut in one pass (identity lock), then one unified ffmpeg color grade
+ *   6. `elevenlabs/eleven-v3` — one VO line per beat, each delayed to its beat
+ *      (`adelay=i*5000`), mixed over a near-silent pink-noise room-tone bed
+ *
+ * The pipeline (model IDs, params, poll loop, ffmpeg filters) follows the
+ * validated recipe in `launch-video-generation` ("Validated pipeline: cinematic
+ * character video") and the reference scripts it was distilled from.
+ *
+ * Requirements: `WAVESPEED_API_KEY` in the environment (ElevenLabs is reached
+ * through wavespeed, so one key covers both), `ffmpeg` on PATH, node >= 18
+ * (global fetch). Nothing is sent out without a key — callers should check
+ * `cinematicAvailable()` and fall back to Hyperframes when it returns false.
+ */
+
+type Engine = 'hyperframes' | 'cinematic';
+declare const ENGINES: readonly Engine[];
+/** ------------------------------------------------------------------ */
+/** Beat derivation (pure — no IO, no clock, no randomness)             */
+/** ------------------------------------------------------------------ */
+/**
+ * One narrated shot of the film. `keyframe` and `motion` are complete prompts
+ * (LOCK/STYLE baked in) for the image-edit and image-to-video models; `vo` is
+ * the eleven-v3 line for the beat (may carry `[emotion]` tags).
+ */
+interface Beat {
+    kind: SceneKind;
+    /** flux-kontext-max edit prompt: LOCK + shot description + STYLE. */
+    keyframe: string;
+    /** Kling motion prompt: action + STYLE. Unused on the last beat (end card). */
+    motion: string;
+    /** eleven-v3 narration line, played at this beat's 5s mark. */
+    vo: string;
+}
+/**
+ * The two seedream-v4 reference prompts: a wide hero that fixes look/wardrobe/set,
+ * and a crisp front-facing headshot used only as the face-swap anchor later.
+ */
+declare function deriveReferencePrompts(): {
+    hero: string;
+    face: string;
+};
+/**
+ * Compile the scene list into the shot list: one beat per scene, in scene order
+ * (title … end). A full session yields 6 beats; an empty one yields 2 (title +
+ * end cards). PURE: same scenes → same prompts.
+ */
+declare function deriveBeats(scenes: readonly Scene[]): Beat[];
+/** ------------------------------------------------------------------ */
+/** Availability                                                        */
+/** ------------------------------------------------------------------ */
+/** True when a usable wavespeed key is present — the only egress gate. */
+declare function cinematicAvailable(env?: NodeJS.ProcessEnv): boolean;
+type ExecFn = (file: string, args: readonly string[]) => void;
+/** Injectable side-effects so tests can run the whole pipeline without network/ffmpeg. */
+interface CinematicDeps {
+    fetchFn?: typeof fetch;
+    execFn?: ExecFn;
+    sleepFn?: (ms: number) => Promise<void>;
+}
+interface CinematicOptions {
+    /** Where the final mp4 is written. */
+    out: string;
+    /** wavespeed key. Default: `WAVESPEED_API_KEY` from the environment. */
+    apiKey?: string;
+    /** Scratch dir for keyframes/clips/mix parts. Default: a fresh mkdtemp. */
+    workDir?: string;
+    /** eleven-v3 voice. Default 'George'. */
+    voiceId?: string;
+    /** Progress lines. Default: stderr. */
+    log?: (msg: string) => void;
+    /** Test seam: override fetch/ffmpeg/sleep. */
+    deps?: CinematicDeps;
+}
+interface CinematicResult {
+    /** The rendered mp4 (`opts.out`). */
+    path: string;
+    /** The shot list the film was built from. */
+    beats: Beat[];
+}
+/**
+ * Render the scene list as a gen-video mp4. Egresses to wavespeed.ai — the
+ * caller is responsible for the consent gate (`cinematicAvailable`) and the
+ * Hyperframes fallback. Throws on missing key, failed predictions, or ffmpeg
+ * errors; a failed face-swap degrades to the un-swapped cut (logged, not fatal).
+ */
+declare function renderCinematic(scenes: readonly Scene[], opts: CinematicOptions): Promise<CinematicResult>;
+
+export { type BuildOptions as B, type CinematicDeps as C, type DiffData as D, type Engine as E, type MergeData as M, type Ratio as R, type Scene as S, type Template as T, type RawEvent as a, type Beat as b, type CinematicOptions as c, type CinematicResult as d, ENGINES as e, type EndData as f, type SceneKind as g, type TaskRow as h, type TasksData as i, type TermLine as j, type TerminalData as k, type TitleData as l, type Transition as m, buildScenes as n, cinematicAvailable as o, deriveBeats as p, deriveReferencePrompts as q, renderCinematic as r };

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as Ratio, T as Template } from './scenes-CKgKppfK.js';
+import { R as Ratio, T as Template, E as Engine } from './cinematic-C31_2Fw6.js';
 import '@pooriaarab/vibe-core';
 
 /**
@@ -13,12 +13,14 @@ declare const VERSION = "0.1.0";
  * vibemovie CLI — render a session recap from JSON events, or serve MCP.
  *
  *   vibemovie render [file.json] [--ratio 16:9|9:16|1:1] [--template documentary|speedrun|meme]
- *                    [--out recap.html] [--title "my session"]
+ *                    [--engine hyperframes|cinematic] [--out recap.html] [--title "my session"]
  *   vibemovie mcp        start the MCP server on stdio
  *   vibemovie --version  ·  vibemovie --help
  *
- * Events are read from the file argument, or stdin when piped. The recap is
- * rendered by the local Hyperframes tier — offline, zero keys.
+ * Events are read from the file argument, or stdin when piped. The default
+ * engine is the local Hyperframes tier — offline, zero keys. The cinematic
+ * engine is opt-in and BYO-key: it needs WAVESPEED_API_KEY and ffmpeg, and
+ * falls back to Hyperframes when either is missing.
  */
 
 declare class CliError extends Error {
@@ -29,6 +31,7 @@ interface CliArgs {
     file?: string;
     ratio: Ratio;
     template: Template;
+    engine: Engine;
     out: string;
     title?: string;
 }

package/dist/cli.js

@@ -3,14 +3,15 @@ import {
   VERSION
 } from "./chunk-HI6AAJID.js";
 import {
+  ENGINES,
   RATIOS,
   TEMPLATES,
   renderMovie
-} from "./chunk-JTRTKTPK.js";
+} from "./chunk-DO2IWHL6.js";
 
 // src/cli.ts
 import { readFile } from "fs/promises";
-import { pathToFileURL } from "url";
+import "url";
 var CliError = class extends Error {
 };
 var HELP = `vibemovie \u2014 your agent coding session as a short recap video
@@ -24,13 +25,19 @@ Usage:
 Options:
   --ratio 16:9|9:16|1:1                    player aspect ratio (default 16:9)
   --template documentary|speedrun|meme     caption tone + pacing (default documentary)
-  --out <path>                             output HTML file (default ./vibe-recap.html)
+  --engine hyperframes|cinematic           render engine (default hyperframes)
+  --out <path>                             output file (default ./vibe-recap.html,
+                                           or ./vibe-recap.mp4 for cinematic)
   --title <name>                           session name on the title card
 
 Input: a JSON array of events (or { "events": [...] }). Each event:
   { "kind": "task-done", "ts": 1720000000000, "payload": { "label": "..." } }
 
-The recap is rendered on-device by the Hyperframes tier: offline, zero keys.
+Engines:
+  hyperframes  renders on-device: offline, zero keys, no data out.
+  cinematic    real gen-video mp4 via wavespeed.ai (BYO key) + ElevenLabs VO.
+               Needs WAVESPEED_API_KEY in the env and ffmpeg on PATH; falls
+               back to hyperframes when either is missing.
 `;
 function takeValue(argv, i, flag, inline) {
   if (inline !== void 0) {
@@ -43,11 +50,12 @@ function takeValue(argv, i, flag, inline) {
 }
 function parseArgs(argv) {
   if (argv.length === 0) {
-    return { command: "help", ratio: "16:9", template: "documentary", out: "./vibe-recap.html" };
+    return { command: "help", ratio: "16:9", template: "documentary", engine: "hyperframes", out: "./vibe-recap.html" };
   }
-  const args = { command: "render", ratio: "16:9", template: "documentary", out: "./vibe-recap.html" };
+  const args = { command: "render", ratio: "16:9", template: "documentary", engine: "hyperframes", out: "./vibe-recap.html" };
   let sawCommand = false;
   let sawFile = false;
+  let sawOut = false;
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i];
     if (tok === "--help" || tok === "-h") {
@@ -74,7 +82,7 @@ function parseArgs(argv) {
     if (tok.startsWith("--")) {
       const eq = tok.indexOf("=");
       const flag = eq === -1 ? tok : tok.slice(0, eq);
-      if (flag !== "--ratio" && flag !== "--template" && flag !== "--out" && flag !== "--title") {
+      if (flag !== "--ratio" && flag !== "--template" && flag !== "--engine" && flag !== "--out" && flag !== "--title") {
         throw new CliError(`unknown flag: ${flag}`);
       }
       const inline = eq === -1 ? void 0 : tok.slice(eq + 1);
@@ -90,8 +98,14 @@ function parseArgs(argv) {
           throw new CliError(`invalid --template "${value}" (expected ${TEMPLATES.join("|")})`);
         }
         args.template = value;
+      } else if (flag === "--engine") {
+        if (!ENGINES.includes(value)) {
+          throw new CliError(`invalid --engine "${value}" (expected ${ENGINES.join("|")})`);
+        }
+        args.engine = value;
       } else if (flag === "--out") {
         args.out = value;
+        sawOut = true;
       } else if (flag === "--title") {
         args.title = value;
       } else {
@@ -112,6 +126,9 @@ function parseArgs(argv) {
   if (args.command === "mcp" && (args.file !== void 0 || sawFile)) {
     throw new CliError("mcp takes no input file");
   }
+  if (args.engine === "cinematic" && !sawOut) {
+    args.out = "./vibe-recap.mp4";
+  }
   return args;
 }
 async function readStdin() {
@@ -168,14 +185,19 @@ async function main(argv) {
   const result = await renderMovie(events, {
     ratio: args.ratio,
     template: args.template,
+    engine: args.engine,
     out: args.out,
+    log: (msg) => process.stderr.write(`${msg}
+`),
     ...args.title !== void 0 ? { title: args.title } : {}
   });
   process.stdout.write(`\u2713 recap rendered \u2192 ${result.path}
 `);
-  process.stdout.write("  hyperframes \xB7 offline \xB7 zero keys\n");
+  process.stdout.write(
+    result.engine === "cinematic" ? "  cinematic \xB7 wavespeed gen-video + eleven-v3 narration \xB7 BYO key\n" : "  hyperframes \xB7 offline \xB7 zero keys\n"
+  );
 }
-var invokedAsScript = typeof process.argv[1] === "string" && import.meta.url === pathToFileURL(process.argv[1]).href;
+var invokedAsScript = typeof process.argv[1] === "string";
 if (invokedAsScript) {
   main(process.argv.slice(2)).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as Ratio, S as Scene, B as BuildOptions, a as RawEvent } from './scenes-CKgKppfK.js';
-export { D as DiffData, E as EndData, M as MergeData, b as SceneKind, c as TaskRow, d as TasksData, T as Template, e as TermLine, f as TerminalData, g as TitleData, h as Transition, i as buildScenes } from './scenes-CKgKppfK.js';
+import { R as Ratio, S as Scene, B as BuildOptions, E as Engine, a as RawEvent } from './cinematic-C31_2Fw6.js';
+export { b as Beat, C as CinematicDeps, c as CinematicOptions, d as CinematicResult, D as DiffData, e as ENGINES, f as EndData, M as MergeData, g as SceneKind, h as TaskRow, i as TasksData, T as Template, j as TermLine, k as TerminalData, l as TitleData, m as Transition, n as buildScenes, o as cinematicAvailable, p as deriveBeats, q as deriveReferencePrompts, r as renderCinematic } from './cinematic-C31_2Fw6.js';
 import { VibeEvent } from '@pooriaarab/vibe-core';
 export { VibeEvent } from '@pooriaarab/vibe-core';
 
@@ -31,38 +31,64 @@ declare function renderHyperframes(scenes: readonly Scene[], opts?: RenderOption
 /**
  * @pooriaarab/vibemovie — your agent coding session as a short recap video.
  *
- * v0 ships the Hyperframes tier of the vibe-core video cascade: a recap "movie"
- * is a self-contained animated HTML page rendered 100% on-device — no gen-video
- * model, no API key, no network. The cascade seam is real: gen-video providers
- * (Sora, Wavespeed, …) can later be registered as tier-1/2 providers without
- * touching this API; the consent ledger gates their egress.
+ * Two render engines:
+ *
+ * - **hyperframes** (default) — a self-contained animated HTML page rendered
+ *   100% on-device: no gen-video model, no API key, no network.
+ * - **cinematic** (opt-in, BYO key) — a real gen-video mp4 via wavespeed.ai
+ *   (Kling chained clips + face-swap identity lock + ElevenLabs VO). Requires
+ *   `WAVESPEED_API_KEY` and ffmpeg; without them it falls back to Hyperframes
+ *   with a clear message — it never fails hard and never egresses without a key.
  *
  * ```ts
  * import { renderMovie } from '@pooriaarab/vibemovie';
  * const { html, path } = await renderMovie(events, { ratio: '9:16', out: 'recap.html' });
+ * const video = await renderMovie(events, { engine: 'cinematic', out: 'recap.mp4' });
  * ```
  */
 
+/** Sink for milestone notifications. Injectable so tests can capture events. */
+type NotifySink = (event: VibeEvent) => void;
 interface RenderMovieOptions extends BuildOptions, RenderOptions {
-    /** When set, the HTML is also written to this path. */
+    /** When set, the output is also written to this path (HTML or mp4, per engine). */
     out?: string;
+    /** Render engine. Default 'hyperframes' (offline, zero keys). */
+    engine?: Engine;
+    /** wavespeed key for the cinematic engine. Default: `WAVESPEED_API_KEY` from env. */
+    apiKey?: string;
+    /** Status/fallback messages. Default: stderr. */
+    log?: (msg: string) => void;
+    /** Override the notification sink (tests). Defaults to vibe-core's `notify`. */
+    notify?: NotifySink;
 }
 interface RenderMovieResult {
-    /** The self-contained recap HTML (always returned, whether or not `out` was set). */
-    html: string;
-    /** Absolute or relative path the HTML was written to — only when `opts.out` was set. */
+    /** The engine that actually produced the output (cinematic can fall back). */
+    engine: Engine;
+    /** The self-contained recap HTML — present iff `engine` is 'hyperframes'. */
+    html?: string;
+    /** Path the output was written to — when `opts.out` was set (always for cinematic). */
     path?: string;
 }
 /**
- * Compile events → scenes → a self-contained animated HTML recap.
+ * Compile events → scenes → a recap via the selected engine.
+ *
+ * `hyperframes` (default) goes through the vibe-core cascade with egress
+ * disabled and an in-memory consent ledger, so it always resolves to the local
+ * Hyperframes runner — offline with zero keys. `cinematic` is opt-in egress:
+ * it renders only when a wavespeed key is present (and ffmpeg runs); otherwise
+ * it logs why and falls back to the Hyperframes tier — never a hard failure,
+ * never data out without a key.
  *
- * Rendering goes through the vibe-core cascade with egress disabled and an
- * in-memory consent ledger, so it always resolves to the local Hyperframes
- * runner — this call works offline with zero keys. (The cascade is the seam
- * for future gen-video tiers; they are not registered in v0.)
+ * When `opts.out` is set the output is also written to disk. Cinematic output
+ * is always a file (default `./vibe-recap.mp4` when `out` is omitted); if the
+ * cinematic engine falls back, a video-looking `out` extension is rewritten to
+ * `.html` so the artifact matches its contents.
  *
- * When `opts.out` is set the HTML is also written to disk (the only IO here).
+ * A successful render (either engine, including a cinematic → hyperframes
+ * fallback) fires ONE best-effort `render-done` vibenotify event via the
+ * injectable sink (`opts.notify`, default vibe-core's `notify`). A failed
+ * render fires nothing.
  */
 declare function renderMovie(events: readonly (VibeEvent | RawEvent)[], opts?: RenderMovieOptions): Promise<RenderMovieResult>;
 
-export { BuildOptions, Ratio, RawEvent, type RenderMovieOptions, type RenderMovieResult, type RenderOptions, Scene, renderHyperframes, renderMovie };
+export { BuildOptions, Engine, type NotifySink, Ratio, RawEvent, type RenderMovieOptions, type RenderMovieResult, type RenderOptions, Scene, renderHyperframes, renderMovie };

package/dist/index.js

@@ -1,10 +1,20 @@
 import {
+  ENGINES,
   buildScenes,
+  cinematicAvailable,
+  deriveBeats,
+  deriveReferencePrompts,
+  renderCinematic,
   renderHyperframes,
   renderMovie
-} from "./chunk-JTRTKTPK.js";
+} from "./chunk-DO2IWHL6.js";
 export {
+  ENGINES,
   buildScenes,
+  cinematicAvailable,
+  deriveBeats,
+  deriveReferencePrompts,
+  renderCinematic,
   renderHyperframes,
   renderMovie
 };

package/dist/mcp.d.ts

@@ -1,9 +1,11 @@
 /**
  * vibemovie MCP server (stdio) — lets an agent render a session recap.
  *
- * Exposes one tool, `render`: { events, ratio?, template?, out? } → the recap
- * HTML (or the output path when `out` is given). Rendering is the local
- * Hyperframes tier, so the tool works offline with zero keys.
+ * Exposes one tool, `render`: { events, ratio?, template?, engine?, out? } →
+ * the recap HTML (or the output path when `out` is given). The default engine
+ * is the local Hyperframes tier, so the tool works offline with zero keys;
+ * `engine: 'cinematic'` opts into the BYO-key wavespeed gen-video pipeline
+ * (falls back to Hyperframes when no key/ffmpeg is available).
  *
  * Uses the SDK's low-level Server with a plain JSON Schema for input — no
  * schema-library dependency beyond the SDK itself.

package/dist/mcp.js

@@ -2,10 +2,11 @@ import {
   VERSION
 } from "./chunk-HI6AAJID.js";
 import {
+  ENGINES,
   RATIOS,
   TEMPLATES,
   renderMovie
-} from "./chunk-JTRTKTPK.js";
+} from "./chunk-DO2IWHL6.js";
 
 // src/mcp.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -14,7 +15,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { pathToFileURL } from "url";
 var RENDER_TOOL = {
   name: "render",
-  description: 'Render an agent coding session as a recap "movie" \u2014 a self-contained animated HTML page (Hyperframes tier: offline, zero keys, no data out). Returns the HTML, or the output path when `out` is set.',
+  description: 'Render an agent coding session as a recap "movie". Default engine is hyperframes \u2014 a self-contained animated HTML page (offline, zero keys, no data out). Set engine to "cinematic" for a real gen-video mp4 via wavespeed.ai (BYO key: needs WAVESPEED_API_KEY in the server env and ffmpeg on PATH; falls back to hyperframes when unavailable). Returns the HTML, or the output path when `out` is set.',
   inputSchema: {
     type: "object",
     properties: {
@@ -25,8 +26,9 @@ var RENDER_TOOL = {
       },
       ratio: { type: "string", enum: [...RATIOS], description: "Player aspect ratio (default 16:9)." },
       template: { type: "string", enum: [...TEMPLATES], description: "Caption tone + pacing (default documentary)." },
+      engine: { type: "string", enum: [...ENGINES], description: "Render engine (default hyperframes)." },
       title: { type: "string", description: "Session name on the title card." },
-      out: { type: "string", description: "Optional path to write the HTML to." }
+      out: { type: "string", description: "Optional path to write the HTML (or mp4 for cinematic) to." }
     },
     required: ["events"]
   }
@@ -51,6 +53,7 @@ async function startMcpServer() {
     }
     const ratio = enumArg(args["ratio"], "ratio", RATIOS);
     const template = enumArg(args["template"], "template", TEMPLATES);
+    const engine = enumArg(args["engine"], "engine", ENGINES);
     const title = args["title"];
     const out = args["out"];
     if (title !== void 0 && typeof title !== "string") throw new Error('render: "title" must be a string');
@@ -58,10 +61,15 @@ async function startMcpServer() {
     const result = await renderMovie(args["events"], {
       ...ratio !== void 0 ? { ratio } : {},
       ...template !== void 0 ? { template } : {},
+      ...engine !== void 0 ? { engine } : {},
       ...title !== void 0 ? { title } : {},
-      ...out !== void 0 ? { out } : {}
+      ...out !== void 0 ? { out } : {},
+      // stdio transport: anything user-facing must stay off stdout
+      log: (msg) => process.stderr.write(`${msg}
+`)
     });
-    const text = result.path !== void 0 ? `vibemovie recap written to ${result.path} (hyperframes \xB7 offline \xB7 zero keys)` : result.html;
+    const tier = result.engine === "cinematic" ? "cinematic \xB7 wavespeed gen-video + eleven-v3 narration \xB7 BYO key" : "hyperframes \xB7 offline \xB7 zero keys";
+    const text = result.path !== void 0 ? `vibemovie recap written to ${result.path} (${tier})` : result.html ?? "";
     return { content: [{ type: "text", text }] };
   });
   await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibemovie",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Your agent coding session as a short recap video — Hyperframes (HTML/CSS/JS) with zero gen-video keys, or your own video model. For Claude Code, Codex, Gemini, and other agentic CLIs. Local-first.",
   "type": "module",
   "license": "MIT",
@@ -26,8 +26,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pooriaarab/vibe-core": "^0.1.0",
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@pooriaarab/vibe-core": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",

package/dist/scenes-CKgKppfK.d.ts

@@ -1,118 +0,0 @@
-import { VibeEvent } from '@pooriaarab/vibe-core';
-
-/**
- * scenes.ts — pure events → scene-list compiler.
- *
- * Takes normalized `VibeEvent`s (from vibe-core) or loose `RawEvent`s (anything a
- * harness/logger might emit) and compiles them into an ordered, fully-described
- * scene list for the Hyperframes renderer. No IO, no randomness, no clock — the
- * same events always produce the same scenes, which makes this unit-testable and
- * the rendered HTML deterministic.
- */
-
-type Ratio = '16:9' | '9:16' | '1:1';
-type Template = 'documentary' | 'speedrun' | 'meme';
-type Transition = 'fade' | 'slide' | 'scale' | 'rise';
-type SceneKind = 'title' | 'tasks' | 'diff' | 'terminal' | 'merge' | 'end';
-/**
- * A loosely-shaped event from any source: a harness transcript export, a JSON
- * log, a hand-written fixture. Any field may be missing; known aliases
- * (`type`/`timestamp`) are normalized.
- */
-interface RawEvent {
-    kind?: string;
-    type?: string;
-    ts?: number;
-    timestamp?: number | string;
-    agent?: string;
-    cwd?: string;
-    payload?: Record<string, unknown>;
-}
-interface BuildOptions {
-    /** Accepted for API symmetry with the renderer; layout is a render-time concern. */
-    ratio?: Ratio;
-    /** Caption tone + pacing. Default 'documentary'. */
-    template?: Template;
-    /** Session name for the title card. Default: basename of the events' cwd. */
-    title?: string;
-}
-interface TitleData {
-    sessionName: string;
-    /** Total session length in whole minutes, counted up during the title scene. */
-    totalMinutes: number;
-    subtitle: string;
-}
-interface TaskRow {
-    label: string;
-    durationMin?: number;
-}
-interface TasksData {
-    /** Real number of completed tasks (may exceed `tasks.length`). */
-    total: number;
-    /** Rows actually shown (capped at MAX_TASK_ROWS). */
-    tasks: TaskRow[];
-}
-interface DiffData {
-    filesChanged: number;
-    additions: number;
-    deletions: number;
-    /** Up to 4 representative file paths. */
-    files: string[];
-}
-interface TermLine {
-    text: string;
-    cls: 'ok' | '';
-}
-interface TerminalData {
-    lines: TermLine[];
-}
-interface MergeData {
-    pr: number | null;
-    branch: string;
-    reviewers: number | null;
-    merged: boolean;
-}
-interface EndData {
-    tagline: string;
-}
-interface SceneBase {
-    /** DOM id in the rendered page, `scene-<kind>`. */
-    id: string;
-    transition: Transition;
-    /** Milliseconds on the timeline. */
-    duration: number;
-    /** Narrator caption shown while the scene is live. */
-    caption: string;
-}
-type Scene = (SceneBase & {
-    kind: 'title';
-    data: TitleData;
-}) | (SceneBase & {
-    kind: 'tasks';
-    data: TasksData;
-}) | (SceneBase & {
-    kind: 'diff';
-    data: DiffData;
-}) | (SceneBase & {
-    kind: 'terminal';
-    data: TerminalData;
-}) | (SceneBase & {
-    kind: 'merge';
-    data: MergeData;
-}) | (SceneBase & {
-    kind: 'end';
-    data: EndData;
-});
-/**
- * Compile events into an ordered scene list.
- *
- * Always emits a title card and an end card; the middle scenes appear only when
- * the events carry the data for them (tasks → task ticks, file/diff stats →
- * animated diff, notable command events → terminal moment, PR event → merge
- * celebration). Empty input yields `[title, end]`.
- *
- * PURE: no IO, no clock, no randomness.
- */
-declare function buildScenes(events: readonly (VibeEvent | RawEvent)[], opts?: BuildOptions): Scene[];
-
-export { type BuildOptions as B, type DiffData as D, type EndData as E, type MergeData as M, type Ratio as R, type Scene as S, type Template as T, type RawEvent as a, type SceneKind as b, type TaskRow as c, type TasksData as d, type TermLine as e, type TerminalData as f, type TitleData as g, type Transition as h, buildScenes as i };