initial commit

.env.example

@@ -0,0 +1,51 @@
+# Reel Studio v2 — API keys
+# Copy this file to .env and fill in what you have.
+# The app starts and degrades gracefully with ONLY the first two set.
+
+# ── REQUIRED ────────────────────────────────────────────────────────────────
+
+# Gemini (LLM — scripts, topics, style). FREE.
+# Sign up: https://aistudio.google.com/apikey
+# IMPORTANT: must be an AI STUDIO key. A Google Cloud Console key tied to a
+# billing project shows free-tier quota 0 and returns 429 immediately.
+#
+# KEY ROTATION: to spread the free-tier rate limit, set several keys. Either
+# put them comma-separated here, or use GEMINI_API_KEYS below. The adapter
+# rotates through them (and drops any that come back invalid/leaked).
+GEMINI_API_KEY=
+# Optional extra keys to rotate (comma-separated). Merged with GEMINI_API_KEY.
+#GEMINI_API_KEYS=key2,key3,key4
+
+# Pexels (stock video clips). FREE.
+# Sign up: https://www.pexels.com/api/
+PEXELS_API_KEY=
+
+# ── RECOMMENDED ─────────────────────────────────────────────────────────────
+
+# YouTube Data API v3 (reference channels: top Shorts, channel lookup). FREE.
+# Enable "YouTube Data API v3" at https://console.cloud.google.com/apis/library
+# then create an API key under Credentials.
+YOUTUBE_API_KEY=
+
+# ── OPTIONAL ────────────────────────────────────────────────────────────────
+
+# Freesound (sound effects). FREE. Skipped cleanly when empty.
+# Sign up: https://freesound.org/apiv2/apply/
+FREESOUND_API_KEY=
+
+# ElevenLabs (premium voices). Paid/free trial. edge-tts is the free default.
+# Sign up: https://elevenlabs.io/
+ELEVENLABS_API_KEY=
+
+# ── ADAPTER SELECTION (defaults shown; change to swap providers) ────────────
+#ADAPTER_LLM=gemini
+#ADAPTER_TTS=edge_tts          # edge_tts | gemini_tts | elevenlabs
+#ADAPTER_STOCK=pexels
+#ADAPTER_SFX=freesound
+#ADAPTER_MUSIC=local
+#ADAPTER_REFDATA=youtube
+#ADAPTER_TRANSCRIPT=youtube
+
+# ── TUNING ──────────────────────────────────────────────────────────────────
+#GEMINI_MODELS=gemini-2.0-flash,gemini-2.5-flash,gemini-flash-latest   # fallback order
+#EDGE_TTS_VOICE=en-US-ChristopherNeural

.gitignore

@@ -0,0 +1,28 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Secrets — never commit real keys. .env.example IS tracked (it's the template).
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+secrets.json
+
+# Per-project data + outputs
+projects/*
+!projects/.gitkeep
+
+# User-supplied music (keep the folder, not the files)
+assets/music/*
+!assets/music/.gitkeep
+
+# Web
+web/node_modules/
+web/dist/
+
+# OS
+.DS_Store

README.md

@@ -0,0 +1,208 @@
+# Reel Studio v2
+
+An AI short-form video pipeline with a web UI. You define a niche and a few
+reference channels; the app suggests topics from live signals, writes a
+script in the *style of your references*, voices it, gathers stock clips,
+and renders 2–3 draft 9:16 reel variants you can compare, tweak, and
+download. Everything runs locally on free-tier APIs.
+
+There's also a **Clone a reel** flow: paste a YouTube Shorts URL and the app
+extracts its topic and structure, then produces a *fresh* video — original
+wording, different clips, different captions. Source footage, audio, and
+verbatim text are never reused.
+
+---
+
+## Setup (≈10 minutes)
+
+### 1. Prerequisites
+
+- **Python 3.11+** (`python3 --version`)
+- **Node 18+** (`node --version`)
+- **FFmpeg** with ffprobe (`brew install ffmpeg` on macOS)
+
+### 2. Install
+
+```bash
+cd reel-maker-v2
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+cd web && npm install && cd ..
+```
+
+### 3. API keys
+
+```bash
+cp .env.example .env
+# open .env and paste your keys
+```
+
+Only two keys are required — the app degrades gracefully without the rest:
+
+| Key | What it powers | Where to get it (free) |
+|---|---|---|
+| `GEMINI_API_KEY` | scripts, topics, style | https://aistudio.google.com/apikey — **must be an AI Studio key**; a Cloud Console key with billing shows free-tier quota 0 and 429s immediately |
+| `PEXELS_API_KEY` | stock video clips | https://www.pexels.com/api/ |
+| `YOUTUBE_API_KEY` | reference channels (top Shorts, transcripts source) | https://console.cloud.google.com/apis/library → enable *YouTube Data API v3* → Credentials → API key |
+| `FREESOUND_API_KEY` | optional sound effects | https://freesound.org/apiv2/apply/ |
+| `ELEVENLABS_API_KEY` | optional premium voices | https://elevenlabs.io/ |
+
+The free default voice provider is **edge-tts** (no key needed at all).
+
+### 4. Background music (optional, 2 minutes)
+
+Music is mixed from the local `assets/music/` folder only. Download a few
+**royalty-free** tracks from [Pixabay Music](https://pixabay.com/music/) or
+the [YouTube Audio Library](https://studio.youtube.com → Audio Library) and
+drop the MP3s into `assets/music/`. No files there = no background music,
+everything else still works. The app never fetches music from the network —
+only royalty-free files you placed yourself are ever mixed in.
+
+### 5. Run it
+
+Terminal 1 — backend:
+```bash
+.venv/bin/uvicorn server.app:app --port 8000
+```
+
+Terminal 2 — frontend:
+```bash
+cd web && npm run dev
+```
+
+Open **http://localhost:5173** and follow the wizard:
+**Setup → References → Topics → Script → Media → Render → Review.**
+
+---
+
+## Projects and reels
+
+A **project** holds your niche, reference channels, style profile, and topic
+pool — all shared. Within it you create any number of **reels**, each its own
+video (topic → script → voice → media → renders). Switch between reels in the
+left sidebar without losing progress on the others; *+ New reel* starts a
+fresh one. References, the style profile, and topics are built once and reused
+across every reel.
+
+## Editable prompts (QC every AI step)
+
+Every generative step — *Suggest channels*, *Style profile*, *Topics*, and
+*Script* — has a **▸ Show / edit prompt (advanced)** toggle. It reveals the
+exact text sent to the model (with live data already filled in). Edit it to
+steer the output, then run; *↺ Reset to default* restores the original. The
+outputs are editable too: the **style card**, the **topic list** (inline),
+and the **script** (every field). The exact prompt used is saved alongside
+each result for reproducibility.
+
+## How the wizard flows
+
+1. **Setup** — name the project, describe the niche (topic, keywords,
+   subreddits, audience, tone — or hit *✨ Autofill*), pick YouTube Short or
+   Instagram Reel (same 9:16 video, different label).
+2. **References** — add YouTube channels (or *✨ Suggest channels*). Then
+   *Build style profile*: pulls transcripts of each reference's top recent
+   Shorts and distills how they write. Edit the prompt before, the card after.
+3. **Topics** — choose how many, generate, edit inline, then *Create a reel*
+   for the one you pick.
+4. **Script** (per reel) — scene-by-scene script in your references' style.
+   Pick one of 3 hooks, edit any field, regenerate one scene or the whole
+   thing (with prompt editing).
+5. **Media** (per reel) — pick a **voice provider** (Gemini = natural default,
+   ElevenLabs if you add a key, edge-tts = free fallback) and voice, synthesize,
+   then gather clips. Each scene keeps 4 candidates — *Swap* cycles them.
+6. **Render** (per reel) — 2–3 variants with different clips and caption styles.
+7. **Review** (per reel) — side-by-side players, pick one, tweak (swap clip /
+   caption preset) and re-render, then **Download**.
+
+**Clone a reel:** the bar at the top of every step. Paste a Shorts URL → it
+creates a *new reel* with a fresh script on the same topic and opens it at the
+Script step. The source URL is stored for attribution. If the video has no
+obtainable transcript, the app refuses with a clear message.
+
+## CLI (debug path)
+
+The whole pipeline also runs headless, no server needed:
+
+```bash
+.venv/bin/python cli.py init --name "Deep Sea" --niche "deep sea creatures" \
+    --keywords "ocean,marine biology" --subreddits "thalassophobia" \
+    --refs "@NatGeo"
+.venv/bin/python cli.py run-all <project_id>        # everything, end to end
+# …or stage by stage:
+.venv/bin/python cli.py style <project_id>
+.venv/bin/python cli.py topics <project_id> -n 8
+.venv/bin/python cli.py script <project_id> --topic "..."
+.venv/bin/python cli.py voice <project_id>
+.venv/bin/python cli.py media <project_id>
+.venv/bin/python cli.py render <project_id>
+.venv/bin/python cli.py clone <project_id> --url https://www.youtube.com/shorts/XXXX
+```
+
+Outputs land in `projects/<id>/renders/`.
+
+## Tests
+
+Fully offline — the LLM, TTS, stock, and YouTube adapters are mocked with
+local generators, but the real FFmpeg render path runs:
+
+```bash
+.venv/bin/python -m pytest tests/ -q
+```
+
+## Architecture
+
+```
+core/            pure Python pipeline — importable without FastAPI
+  contracts.py   every shared dataclass (the only inter-stage language)
+  adapters/      one interface + registry per external capability
+  stages/        setup, style, topics, script, voice, media, render, clone
+  pipeline.py    the only place stages are wired together
+server/          FastAPI: routes + background job manager (POST → job_id → poll)
+web/             React + Vite wizard (plain CSS)
+assets/music/    your royalty-free tracks
+projects/        per-project JSON + media outputs (gitignored)
+cli.py           headless entry point
+```
+
+Rules the code follows:
+
+- Stages import only `contracts.py` and adapters — never each other.
+- Every network call fails soft: a missing SFX or one failed clip never
+  kills a run; the stage logs, degrades, and continues.
+- All timing downstream of TTS is driven by the **measured** voice-track
+  durations (ffprobe), not by the script's estimates.
+- Captions are rendered as transparent PNGs with Pillow and compiled into
+  a single qtrle overlay track — one overlay pass for the whole video.
+  (FFmpeg `drawtext`/libass are deliberately not used: many builds lack
+  them, and per-word overlay filters are pathologically slow.)
+
+### Adding a provider
+
+1. Create `core/adapters/<capability>_<name>.py`, subclass the interface
+   from `core/adapters/base.py`, call `register("<capability>", "<name>", YourClass)`.
+2. Import the module in `core/adapters/__init__.py`.
+3. Select it with `ADAPTER_<CAPABILITY>=<name>` in `.env`.
+
+Nothing else changes — stages only know the interface.
+
+## Known limitations
+
+- **Instagram references are style-only.** They are never fetched or
+  scraped: scraping violates Instagram's ToS and there is no public
+  content API. Your written notes about the page feed the style prompt
+  as text instead.
+- **Trending audio is not embedded.** Platform-licensed sounds (TikTok /
+  Reels / Shorts trending audio) are licensed for use *inside those apps
+  only*. Add trending audio in the app at posting time; renders here mix
+  only your local royalty-free tracks.
+- **Karaoke captions and the default Gemini voice.** Gemini TTS sounds the
+  most natural of the free options but emits no word timings, so faster-whisper
+  (installed by default) re-transcribes the audio to recover them. Because the
+  karaoke words then come from speech recognition, they can differ slightly
+  from the script wording; the `minimal` caption preset uses the exact script
+  text instead. edge-tts and ElevenLabs provide native timings (no whisper
+  needed). The first whisper run downloads a ~75MB model.
+- **Long-form is not built yet.** The format field reserves it; the
+  render stage is 9:16 only.
+- Free-tier quotas (Gemini, YouTube, Pexels) are generous for a few reels
+  a day but real; the app retries with backoff and falls back where it can.

cli.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Reel Studio v2 CLI — run the whole pipeline headless (the debug path).
+
+Examples:
+    python cli.py init --name "Space Facts" --niche "astronomy facts" \
+        --keywords "space,nasa,astronomy" --subreddits "space,astronomy" \
+        --refs "@besmartchannel,@AstroKobi"
+    python cli.py style <project_id>
+    python cli.py topics <project_id> -n 8
+    python cli.py script <project_id> --topic "Why Venus spins backwards"
+    python cli.py voice <project_id> --voice en-US-GuyNeural
+    python cli.py media <project_id>
+    python cli.py render <project_id>
+    python cli.py clone <project_id> --url https://www.youtube.com/shorts/XXXX
+    python cli.py run-all <project_id> [--topic "..."]
+    python cli.py list
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from core.contracts import NicheProfile, ReferenceEntry, to_dict
+from core.pipeline import Pipeline
+from core.utils import log
+
+
+def _progress(msg: str) -> None:
+    log.info(">> %s", msg)
+
+
+def _load_project(pipe: Pipeline, project_id: str):
+    project = pipe.store.load_project(project_id)
+    if not project:
+        sys.exit(f"No project {project_id!r}. Run `python cli.py list`.")
+    return project
+
+
+def _print(obj) -> None:
+    print(json.dumps(to_dict(obj), indent=2, ensure_ascii=False))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Reel Studio v2 — headless pipeline")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("init", help="create a project")
+    p.add_argument("--name", required=True)
+    p.add_argument("--niche", required=True, help="niche topic, e.g. 'astronomy facts'")
+    p.add_argument("--keywords", default="", help="comma separated")
+    p.add_argument("--subreddits", default="", help="comma separated")
+    p.add_argument("--audience", default="")
+    p.add_argument("--tone", default="")
+    p.add_argument("--format", default="youtube_short",
+                   choices=["youtube_short", "instagram_reel"])
+    p.add_argument("--refs", default="",
+                   help="comma separated YouTube @handles / URLs / names")
+
+    p = sub.add_parser("suggest-refs", help="AI-suggest reference channels")
+    p.add_argument("project_id")
+    p.add_argument("-n", type=int, default=5)
+
+    p = sub.add_parser("style", help="build/refresh the style profile")
+    p.add_argument("project_id")
+
+    p = sub.add_parser("topics", help="generate ranked topics")
+    p.add_argument("project_id")
+    p.add_argument("-n", type=int, default=8)
+
+    p = sub.add_parser("reels", help="list reels in a project")
+    p.add_argument("project_id")
+
+    p = sub.add_parser("script", help="generate the script (creates a new reel unless --reel)")
+    p.add_argument("project_id")
+    p.add_argument("--topic", required=True)
+    p.add_argument("--reel", default=None, help="reel id (default: create a new reel)")
+
+    p = sub.add_parser("voice", help="synthesize the voice track")
+    p.add_argument("project_id")
+    p.add_argument("--reel", default=None, help="reel id (default: latest reel)")
+    p.add_argument("--voice", default="")
+    p.add_argument("--provider", default=None, help="tts provider: gemini_tts|elevenlabs|edge_tts")
+
+    p = sub.add_parser("media", help="gather clips/sfx/music")
+    p.add_argument("project_id")
+    p.add_argument("--reel", default=None, help="reel id (default: latest reel)")
+
+    p = sub.add_parser("render", help="render 2-3 variants")
+    p.add_argument("project_id")
+    p.add_argument("--reel", default=None, help="reel id (default: latest reel)")
+
+    p = sub.add_parser("clone", help="clone a reel from a YouTube Shorts URL (creates a new reel)")
+    p.add_argument("project_id")
+    p.add_argument("--url", required=True)
+
+    p = sub.add_parser("run-all", help="style->topics->script->voice->media->render")
+    p.add_argument("project_id")
+    p.add_argument("--topic", default=None)
+    p.add_argument("--voice", default="")
+
+    sub.add_parser("list", help="list projects")
+
+    args = ap.parse_args()
+    pipe = Pipeline()
+
+    if args.cmd == "init":
+        refs = [
+            ReferenceEntry(kind="youtube", name=r.strip(), url=r.strip() if "/" in r else "")
+            for r in args.refs.split(",") if r.strip()
+        ]
+        niche = NicheProfile(
+            topic=args.niche,
+            keywords=[k.strip() for k in args.keywords.split(",") if k.strip()],
+            subreddits=[s.strip() for s in args.subreddits.split(",") if s.strip()],
+            audience=args.audience,
+            tone=args.tone,
+        )
+        project = pipe.create_project(args.name, niche, args.format, refs)
+        print(f"Created project {project.id}")
+        _print(project)
+        return
+
+    if args.cmd == "list":
+        for proj in pipe.store.list_projects():
+            print(f"{proj.id}  {proj.name}  [{proj.format}]  niche={proj.niche.topic}")
+        return
+
+    project = _load_project(pipe, args.project_id)
+
+    def resolve_reel(create_topic: str | None = None) -> str:
+        """Use --reel, else the latest reel, else (if create_topic) a new one."""
+        if getattr(args, "reel", None):
+            return args.reel
+        reels = pipe.list_reels(project)
+        if reels and create_topic is None:
+            return reels[-1].id
+        reel = pipe.create_reel(project, topic=create_topic or "")
+        print(f"Created reel {reel.id}")
+        return reel.id
+
+    if args.cmd == "suggest-refs":
+        _print(pipe.suggest_references(project, n=args.n))
+    elif args.cmd == "style":
+        _print(pipe.build_style(project, progress=_progress))
+    elif args.cmd == "topics":
+        _print(pipe.generate_topics(project, n=args.n, progress=_progress))
+    elif args.cmd == "reels":
+        for r in pipe.list_reels(project):
+            print(f"{r.id}  {r.name}  topic={r.topic!r}")
+    elif args.cmd == "script":
+        rid = resolve_reel(create_topic=args.topic)
+        _print(pipe.generate_script(project, rid, args.topic))
+    elif args.cmd == "voice":
+        rid = resolve_reel()
+        _print(pipe.synthesize_voice(project, rid, voice=args.voice,
+                                     provider=args.provider, progress=_progress))
+    elif args.cmd == "media":
+        rid = resolve_reel()
+        _print(pipe.gather_media(project, rid, _progress))
+    elif args.cmd == "render":
+        rid = resolve_reel()
+        batch = pipe.render(project, rid, progress=_progress)
+        _print(batch)
+        for r in batch.results:
+            print(f"\n{r.variant}: {r.path}")
+    elif args.cmd == "clone":
+        result = pipe.clone_reel(project, args.url, _progress)
+        print(f"Created reel {result['reel'].id}")
+        _print(result["script"])
+    elif args.cmd == "run-all":
+        batch = pipe.run_all(project, topic=args.topic, voice=args.voice, progress=_progress)
+        for r in batch.results:
+            print(f"{r.variant}: {r.path}")
+
+
+if __name__ == "__main__":
+    main()

core/adapters/__init__.py

@@ -0,0 +1,30 @@
+"""Adapter package. Importing it registers every built-in provider.
+
+To add a provider: create a module here that subclasses the relevant
+interface from ``base`` and calls ``register(capability, name, factory)``,
+then import it below. Select it via ``ADAPTER_<CAPABILITY>`` in .env.
+"""
+
+from core.adapters import (  # noqa: F401  (imports trigger registration)
+    llm_gemini,
+    music_local,
+    refdata_youtube,
+    sfx_freesound,
+    stock_pexels,
+    transcript_youtube,
+    tts_edge,
+    tts_elevenlabs,
+    tts_gemini,
+)
+from core.adapters.base import (  # noqa: F401
+    LLMAdapter,
+    MusicAdapter,
+    ReferenceDataAdapter,
+    SFXAdapter,
+    StockVideoAdapter,
+    TranscriptAdapter,
+    TTSAdapter,
+    get_adapter,
+    register,
+    registered,
+)

core/adapters/alignment.py

@@ -0,0 +1,42 @@
+"""Forced-alignment fallback for word timings.
+
+When a TTS provider returns no word timings, we try faster-whisper (if
+installed) to recover them from the rendered audio. faster-whisper is an
+OPTIONAL dependency — when missing or failing, return None and the render
+stage degrades to static (per-scene) captions instead of karaoke.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from core.contracts import WordTiming
+from core.utils import log
+
+_model = None
+_model_failed = False
+
+
+def align_words(audio_path: str, text: str) -> Optional[list[WordTiming]]:
+    """Best-effort word timings for ``audio_path``. None on any failure."""
+    global _model, _model_failed
+    if _model_failed:
+        return None
+    try:
+        if _model is None:
+            from faster_whisper import WhisperModel  # type: ignore
+
+            _model = WhisperModel("tiny", device="cpu", compute_type="int8")
+        segments, _info = _model.transcribe(audio_path, word_timestamps=True)
+        timings: list[WordTiming] = []
+        for seg in segments:
+            for w in seg.words or []:
+                timings.append(WordTiming(word=w.word.strip(), start=w.start, end=w.end))
+        return timings or None
+    except ImportError:
+        log.info("faster-whisper not installed — captions will be static (pip install faster-whisper to enable karaoke alignment)")
+        _model_failed = True
+        return None
+    except Exception as e:
+        log.warning("Forced alignment failed (%s) — falling back to static captions", e)
+        return None

core/adapters/base.py

@@ -0,0 +1,119 @@
+"""Adapter interfaces and the provider registry.
+
+One abstract interface per external capability. Concrete providers register
+themselves with :func:`register`; stages obtain instances through
+:func:`get_adapter` using names from :class:`core.config.Config`. Adding a
+provider = one new module + one ``register()`` call.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Optional
+
+from core.contracts import ClipCandidate, Topic, WordTiming
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[str, dict[str, Callable[..., Any]]] = {}
+
+
+def register(capability: str, name: str, factory: Callable[..., Any]) -> None:
+    """Register a provider factory under (capability, name).
+
+    ``factory`` receives the :class:`core.config.Config` and returns an
+    adapter instance.
+    """
+    _REGISTRY.setdefault(capability, {})[name] = factory
+
+
+def get_adapter(capability: str, name: str, config: Any) -> Any:
+    """Instantiate the registered provider, or raise with the known names."""
+    providers = _REGISTRY.get(capability, {})
+    if name not in providers:
+        known = ", ".join(sorted(providers)) or "(none registered)"
+        raise KeyError(f"No {capability!r} adapter named {name!r}. Known: {known}")
+    return providers[name](config)
+
+
+def registered(capability: str) -> list[str]:
+    return sorted(_REGISTRY.get(capability, {}))
+
+
+# ---------------------------------------------------------------------------
+# Interfaces
+# ---------------------------------------------------------------------------
+
+
+class LLMAdapter(ABC):
+    """Text + JSON completion with retries and model fallbacks built in."""
+
+    @abstractmethod
+    def complete(self, prompt: str) -> str:
+        """Return the raw text completion."""
+
+    @abstractmethod
+    def complete_json(self, prompt: str) -> Any:
+        """Return parsed JSON (markdown fences stripped, retried on junk)."""
+
+
+class TTSAdapter(ABC):
+    """Text-to-speech. Returns word timings when the provider supplies them."""
+
+    @abstractmethod
+    def synth(self, text: str, out_path: str, voice: str = "") -> Optional[list[WordTiming]]:
+        """Synthesize ``text`` to ``out_path`` (mp3/wav). Return word timings
+        relative to the start of the file, or None if unavailable."""
+
+    @abstractmethod
+    def voices(self) -> list[str]:
+        """Voice names the user can pick from."""
+
+
+class StockVideoAdapter(ABC):
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        orientation: str = "portrait",
+        min_duration: float = 3.0,
+        max_duration: float = 30.0,
+        per_query: int = 4,
+    ) -> list[ClipCandidate]:
+        """Return up to ``per_query`` candidates so the UI can offer alternates."""
+
+    @abstractmethod
+    def download(self, candidate: ClipCandidate, out_path: str) -> str:
+        """Download the candidate, set ``local_path`` and return it."""
+
+
+class SFXAdapter(ABC):
+    @abstractmethod
+    def fetch(self, query: str, out_path: str, max_duration: float = 4.0) -> Optional[str]:
+        """Download one short sound effect; None if unavailable (fail soft)."""
+
+
+class MusicAdapter(ABC):
+    @abstractmethod
+    def pick(self, mood: str = "") -> tuple[str, str]:
+        """Return (path, credit) of a royalty-free background track, or ("", "")."""
+
+
+class ReferenceDataAdapter(ABC):
+    """YouTube Data API v3 only. Instagram entries are never fetched."""
+
+    @abstractmethod
+    def resolve_channel(self, name_or_url: str) -> Optional[dict]:
+        """Return {channel_id, title, url, subscribers} or None."""
+
+    @abstractmethod
+    def top_shorts(self, channel_id: str, n: int = 5, since_days: int = 90) -> list[dict]:
+        """Return [{video_id, title, views, likes, published}] sorted by views."""
+
+
+class TranscriptAdapter(ABC):
+    @abstractmethod
+    def fetch(self, video_id: str) -> Optional[str]:
+        """Plain-text transcript of a YouTube video, or None (fail soft)."""

core/adapters/gemini_keys.py

@@ -0,0 +1,68 @@
+"""Shared Gemini API key rotation + backoff.
+
+Used by the TTS adapter (and available to any Gemini-backed adapter). Spreads
+load across multiple keys: rotate on rate-limit/transient errors, drop a key
+that is refused (401/403), back off only once every live key is rate-limited.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Callable
+
+from core.utils import HardAPIError, log
+
+
+class KeyRejected(Exception):
+    """A single key was refused (401/403) — try another key."""
+
+
+class KeyRotator:
+    def __init__(self, keys: list[str]):
+        self.keys = list(keys)
+        self._i = 0
+        self._lock = threading.Lock()
+
+    def _current(self) -> str:
+        with self._lock:
+            return self.keys[self._i % len(self.keys)]
+
+    def _rotate(self) -> None:
+        with self._lock:
+            self._i = (self._i + 1) % len(self.keys)
+
+    def call(self, do_call: Callable[[str], object], *, label: str,
+             rounds: int = 4, base_delay: float = 2.0):
+        """Run ``do_call(key)`` with rotation + backoff.
+
+        ``do_call`` should raise HardAPIError (abort), KeyRejected (drop this
+        key), or any other exception (treated as retryable → rotate).
+        """
+        rejected: set[str] = set()
+        delay = base_delay
+        last: Exception | None = None
+        for _ in range(rounds):
+            for _ in range(len(self.keys)):
+                key = self._current()
+                if key in rejected:
+                    self._rotate()
+                    continue
+                try:
+                    return do_call(key)
+                except HardAPIError:
+                    raise
+                except KeyRejected as e:
+                    log.warning("%s — dropping key …%s for the run", label, key[-6:])
+                    rejected.add(key)
+                    self._rotate()
+                    last = e
+                except Exception as e:  # 429 / 5xx / network — rotate
+                    last = e
+                    self._rotate()
+            if len(rejected) >= len(self.keys):
+                raise HardAPIError(f"{label}: all Gemini keys were rejected (401/403)")
+            log.warning("%s: all live keys rate-limited — backing off %.0fs", label, delay)
+            time.sleep(delay)
+            delay *= 2
+        raise last or RuntimeError(f"{label}: exhausted retries")

core/adapters/llm_gemini.py

@@ -0,0 +1,166 @@
+"""Gemini LLM adapter (free tier, AI Studio keys) with key rotation.
+
+Behavior hardened by v1 experience:
+- retry with exponential backoff on 429/500/503,
+- ordered model fallbacks (config.gemini_models),
+- markdown fences stripped before JSON parsing.
+
+Key rotation (v2): give it several keys and it spreads load across them.
+- 429/5xx (rate limit / transient): rotate to the next key immediately; only
+  after every key has been tried this round do we back off and sleep. This
+  turns N keys into roughly N× the free-tier throughput.
+- 401/403 (invalid / leaked / permission): that key is dropped for the run;
+  the call retries on the remaining keys. Only when ALL keys are rejected do
+  we hard-fail with a clear message.
+- 404 (model not found): advance to the next model, not the next key.
+- 400 (bad request): hard-fail immediately — not a key or model problem.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any
+
+import requests
+
+from core.adapters.base import LLMAdapter, register
+from core.utils import HardAPIError, extract_json, log
+
+_API = "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent"
+
+
+class _KeyRejected(Exception):
+    """A single key was refused (401/403) — try another key."""
+
+
+class _ModelUnavailable(Exception):
+    """A model was not found (404) — try the next model."""
+
+
+class _AllKeysRejected(Exception):
+    """Every key was refused — no point trying more models."""
+
+
+class GeminiLLM(LLMAdapter):
+    def __init__(self, config):
+        self.keys = list(config.gemini_api_keys)
+        if not self.keys:
+            raise HardAPIError(
+                "No Gemini API key set. Put one in GEMINI_API_KEY (or several, "
+                "comma-separated, in GEMINI_API_KEY / GEMINI_API_KEYS to rotate). "
+                "Free keys: https://aistudio.google.com/apikey — must be AI Studio "
+                "keys; Cloud Console keys show free-tier quota 0 and 429 immediately."
+            )
+        self.models = list(config.gemini_models)
+        self._idx = 0  # rotation cursor, shared across job-manager threads
+        self._lock = threading.Lock()
+
+    # -- key rotation -------------------------------------------------------
+
+    def _current_key(self) -> str:
+        with self._lock:
+            return self.keys[self._idx % len(self.keys)]
+
+    def _rotate(self) -> None:
+        with self._lock:
+            self._idx = (self._idx + 1) % len(self.keys)
+
+    # -- one HTTP call ------------------------------------------------------
+
+    def _call(self, model: str, key: str, prompt: str) -> str:
+        resp = requests.post(
+            _API.format(model=model),
+            params={"key": key},
+            json={"contents": [{"parts": [{"text": prompt}]}]},
+            timeout=120,
+        )
+        code = resp.status_code
+        if code == 400:
+            raise HardAPIError(f"Gemini {model} HTTP 400 (bad request): {resp.text[:300]}")
+        if code in (401, 403):
+            raise _KeyRejected(f"Gemini key …{key[-6:]} HTTP {code}: {resp.text[:200]}")
+        if code == 404:
+            raise _ModelUnavailable(f"Gemini model {model} not found (404)")
+        if code in (429, 500, 503):
+            raise RuntimeError(f"Gemini {model} HTTP {code} (retryable)")
+        resp.raise_for_status()
+        data = resp.json()
+        try:
+            return data["candidates"][0]["content"]["parts"][0]["text"]
+        except (KeyError, IndexError) as e:
+            raise RuntimeError(f"Gemini {model} returned no text: {json.dumps(data)[:300]}") from e
+
+    # -- one model, all keys, with backoff ----------------------------------
+
+    def _complete_model(self, model: str, prompt: str, rejected: set[str]) -> str:
+        n = len(self.keys)
+        delay = 2.0
+        last: Exception | None = None
+        for _round in range(4):  # backoff rounds once all live keys are rate-limited
+            for _ in range(n):
+                key = self._current_key()
+                if key in rejected:  # already known-bad this run
+                    self._rotate()
+                    continue
+                try:
+                    return self._call(model, key, prompt)
+                except HardAPIError:
+                    raise
+                except _ModelUnavailable:
+                    raise
+                except _KeyRejected as e:
+                    log.warning("%s — dropping this key for the run", e)
+                    rejected.add(key)
+                    self._rotate()
+                    last = e
+                except Exception as e:  # 429 / 5xx — rotate to the next key
+                    last = e
+                    self._rotate()
+            live = [k for k in self.keys if k not in rejected]
+            if not live:
+                raise _AllKeysRejected("All Gemini keys were rejected (401/403).")
+            # Every live key is rate-limited right now — wait, then retry.
+            log.warning(
+                "All %d live Gemini key(s) rate-limited on %s — backing off %.0fs",
+                len(live), model, delay,
+            )
+            time.sleep(delay)
+            delay *= 2
+        raise last or RuntimeError(f"Gemini {model} exhausted retries")
+
+    # -- interface ----------------------------------------------------------
+
+    def complete(self, prompt: str) -> str:
+        rejected: set[str] = set()  # keys refused, shared across model attempts
+        errors: list[str] = []
+        for model in self.models:
+            try:
+                return self._complete_model(model, prompt, rejected)
+            except HardAPIError:
+                raise
+            except _AllKeysRejected as e:
+                raise HardAPIError(str(e)) from e
+            except _ModelUnavailable as e:
+                log.warning("%s — trying next model", e)
+                errors.append(str(e))
+            except Exception as e:
+                log.warning("Model %s exhausted retries (%s); falling back", model, e)
+                errors.append(f"{model}: {e}")
+        raise RuntimeError("All Gemini models/keys failed: " + "; ".join(errors))
+
+    def complete_json(self, prompt: str) -> Any:
+        # One extra round trip if the first response isn't valid JSON.
+        text = self.complete(prompt)
+        try:
+            return extract_json(text)
+        except ValueError:
+            log.warning("LLM response was not JSON; asking it to reformat")
+            text = self.complete(
+                "Convert the following into VALID JSON only — no prose, no markdown fences:\n\n" + text
+            )
+            return extract_json(text)
+
+
+register("llm", "gemini", GeminiLLM)

core/adapters/music_local.py

@@ -0,0 +1,37 @@
+"""Local-folder music adapter.
+
+COPYRIGHT RULE: only royalty-free music is ever mixed into a render. The
+user downloads tracks themselves (Pixabay Music, YouTube Audio Library —
+both download-only, no public API) into ``assets/music/``. We never fetch
+arbitrary music from the network.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from core.adapters.base import MusicAdapter, register
+from core.utils import log
+
+_EXTS = {".mp3", ".m4a", ".wav", ".ogg", ".flac"}
+
+
+class LocalMusic(MusicAdapter):
+    def __init__(self, config):
+        self.music_dir = config.music_dir
+
+    def pick(self, mood: str = "") -> tuple[str, str]:
+        tracks = sorted(
+            p for p in self.music_dir.glob("*") if p.suffix.lower() in _EXTS
+        )
+        if not tracks:
+            log.info("No music files in %s — rendering without background music", self.music_dir)
+            return "", ""
+        # Deterministic pick keyed on the mood string so re-renders of the
+        # same project reuse the same track (Date-free, test-friendly).
+        idx = int(hashlib.sha1(mood.encode()).hexdigest(), 16) % len(tracks)
+        track = tracks[idx]
+        return str(track), f"local: {track.name}"
+
+
+register("music", "local", LocalMusic)

core/adapters/refdata_youtube.py

@@ -0,0 +1,143 @@
+"""YouTube Data API v3 reference-data adapter (free key).
+
+This is the ONLY place reference channel data comes from. Instagram
+reference entries are style-only text and are never fetched (ToS + no
+public API) — see core.contracts.ReferenceEntry.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import requests
+
+from core.adapters.base import ReferenceDataAdapter, register
+from core.utils import HardAPIError, log, retry_backoff
+
+_BASE = "https://www.googleapis.com/youtube/v3"
+
+
+class YouTubeRefData(ReferenceDataAdapter):
+    def __init__(self, config):
+        if not config.youtube_api_key:
+            raise HardAPIError(
+                "YOUTUBE_API_KEY is not set. Free key: enable 'YouTube Data API v3' "
+                "at https://console.cloud.google.com/apis/library"
+            )
+        self.key = config.youtube_api_key
+
+    def _get(self, path: str, **params) -> dict:
+        def _call():
+            resp = requests.get(
+                f"{_BASE}/{path}", params={"key": self.key, **params}, timeout=30
+            )
+            if resp.status_code in (400, 401, 403, 404):
+                raise HardAPIError(f"YouTube API {path} HTTP {resp.status_code}: {resp.text[:300]}")
+            resp.raise_for_status()
+            return resp.json()
+
+        return retry_backoff(_call, attempts=3, label=f"youtube:{path}")
+
+    # -- interface ----------------------------------------------------------
+
+    def resolve_channel(self, name_or_url: str) -> Optional[dict]:
+        """Accepts @handles, channel URLs, or plain names."""
+        text = name_or_url.strip()
+        # URL forms: /channel/UC..., /@handle
+        m = re.search(r"youtube\.com/channel/(UC[\w-]+)", text)
+        channel_id = m.group(1) if m else ""
+        handle = ""
+        m = re.search(r"youtube\.com/@([\w.-]+)", text)
+        if m:
+            handle = m.group(1)
+        elif text.startswith("@"):
+            handle = text[1:]
+
+        try:
+            if channel_id:
+                data = self._get("channels", part="snippet,statistics", id=channel_id)
+            elif handle:
+                data = self._get("channels", part="snippet,statistics", forHandle=handle)
+            else:
+                # Plain name: search for the channel, take the top hit.
+                search = self._get("search", part="snippet", q=text, type="channel", maxResults=1)
+                items = search.get("items", [])
+                if not items:
+                    return None
+                channel_id = items[0]["snippet"]["channelId"]
+                data = self._get("channels", part="snippet,statistics", id=channel_id)
+        except HardAPIError:
+            raise
+        except Exception as e:
+            log.warning("resolve_channel(%r) failed: %s", name_or_url, e)
+            return None
+
+        items = data.get("items", [])
+        if not items:
+            return None
+        ch = items[0]
+        return {
+            "channel_id": ch["id"],
+            "title": ch["snippet"]["title"],
+            "url": f"https://www.youtube.com/channel/{ch['id']}",
+            "subscribers": int(ch.get("statistics", {}).get("subscriberCount", 0)),
+        }
+
+    def top_shorts(self, channel_id: str, n: int = 5, since_days: int = 90) -> list[dict]:
+        """Recent videos <= 3.5 min, sorted by views. Uses search + videos."""
+        published_after = (
+            datetime.now(timezone.utc) - timedelta(days=since_days)
+        ).strftime("%Y-%m-%dT%H:%M:%SZ")
+        try:
+            search = self._get(
+                "search",
+                part="id",
+                channelId=channel_id,
+                type="video",
+                order="viewCount",
+                publishedAfter=published_after,
+                maxResults=25,
+            )
+            ids = [it["id"]["videoId"] for it in search.get("items", []) if "videoId" in it.get("id", {})]
+            if not ids:
+                return []
+            vids = self._get(
+                "videos", part="snippet,statistics,contentDetails", id=",".join(ids)
+            )
+        except HardAPIError:
+            raise
+        except Exception as e:
+            log.warning("top_shorts(%s) failed: %s", channel_id, e)
+            return []
+
+        out = []
+        for v in vids.get("items", []):
+            dur = _iso_duration_seconds(v["contentDetails"].get("duration", "PT0S"))
+            if dur == 0 or dur > 210:  # Shorts-length only (<= 3.5 min)
+                continue
+            stats = v.get("statistics", {})
+            out.append(
+                {
+                    "video_id": v["id"],
+                    "title": v["snippet"]["title"],
+                    "views": int(stats.get("viewCount", 0)),
+                    "likes": int(stats.get("likeCount", 0)),
+                    "published": v["snippet"].get("publishedAt", ""),
+                }
+            )
+        out.sort(key=lambda x: x["views"], reverse=True)
+        return out[:n]
+
+
+def _iso_duration_seconds(iso: str) -> int:
+    """PT1M23S -> 83."""
+    m = re.match(r"PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?", iso or "")
+    if not m:
+        return 0
+    h, mi, s = (int(x) if x else 0 for x in m.groups())
+    return h * 3600 + mi * 60 + s
+
+
+register("refdata", "youtube", YouTubeRefData)

core/adapters/sfx_freesound.py

@@ -0,0 +1,59 @@
+"""Freesound SFX adapter (optional free key). Skips cleanly when keyless."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from core.adapters.base import SFXAdapter, register
+from core.utils import log, retry_backoff
+
+_SEARCH = "https://freesound.org/apiv2/search/text/"
+
+
+class FreesoundSFX(SFXAdapter):
+    def __init__(self, config):
+        self.key = config.freesound_api_key  # may be empty — fetch() then no-ops
+
+    def fetch(self, query: str, out_path: str, max_duration: float = 4.0) -> Optional[str]:
+        if not self.key:
+            log.info("Freesound: no key — skipping SFX %r", query)
+            return None
+        try:
+            def _search():
+                resp = requests.get(
+                    _SEARCH,
+                    params={
+                        "query": query,
+                        "token": self.key,
+                        "filter": f"duration:[0.2 TO {max_duration}]",
+                        "fields": "id,name,previews,duration",
+                        "page_size": 5,
+                        "sort": "score",
+                    },
+                    timeout=30,
+                )
+                resp.raise_for_status()
+                return resp.json()
+
+            data = retry_backoff(_search, attempts=2, label=f"freesound:{query!r}")
+            results = data.get("results", [])
+            if not results:
+                return None
+            preview = results[0]["previews"].get("preview-hq-mp3") or results[0]["previews"].get(
+                "preview-lq-mp3"
+            )
+            if not preview:
+                return None
+            with requests.get(preview, timeout=60) as r:
+                r.raise_for_status()
+                with open(out_path, "wb") as f:
+                    f.write(r.content)
+            return out_path
+        except Exception as e:  # SFX is decoration — never kill a run over it
+            log.warning("Freesound fetch failed for %r: %s — skipping", query, e)
+            return None
+
+
+register("sfx", "freesound", FreesoundSFX)

core/adapters/stock_pexels.py

@@ -0,0 +1,87 @@
+"""Pexels stock-video adapter (free API key)."""
+
+from __future__ import annotations
+
+import requests
+
+from core.adapters.base import StockVideoAdapter, register
+from core.contracts import ClipCandidate
+from core.utils import HardAPIError, log, retry_backoff
+
+_SEARCH = "https://api.pexels.com/videos/search"
+
+
+class PexelsStock(StockVideoAdapter):
+    def __init__(self, config):
+        if not config.pexels_api_key:
+            raise HardAPIError(
+                "PEXELS_API_KEY is not set. Free key: https://www.pexels.com/api/"
+            )
+        self.headers = {"Authorization": config.pexels_api_key}
+
+    def search(
+        self,
+        query: str,
+        orientation: str = "portrait",
+        min_duration: float = 3.0,
+        max_duration: float = 30.0,
+        per_query: int = 4,
+    ) -> list[ClipCandidate]:
+        def _call():
+            resp = requests.get(
+                _SEARCH,
+                headers=self.headers,
+                params={"query": query, "orientation": orientation, "per_page": 15},
+                timeout=30,
+            )
+            if resp.status_code in (400, 401, 403):
+                raise HardAPIError(f"Pexels HTTP {resp.status_code}: {resp.text[:200]}")
+            resp.raise_for_status()
+            return resp.json()
+
+        data = retry_backoff(_call, attempts=3, label=f"pexels:{query!r}")
+        out: list[ClipCandidate] = []
+        for video in data.get("videos", []):
+            if not (min_duration <= video.get("duration", 0) <= max_duration * 3):
+                continue
+            files = video.get("video_files", [])
+            # Prefer tall HD files; smallest file that is >= 1080 tall, else tallest.
+            portrait = [f for f in files if f.get("height", 0) >= f.get("width", 0)]
+            pool = portrait or files
+            pool = sorted(pool, key=lambda f: f.get("height", 0))
+            best = next((f for f in pool if f.get("height", 0) >= 1080), pool[-1] if pool else None)
+            if not best:
+                continue
+            out.append(
+                ClipCandidate(
+                    id=str(video["id"]),
+                    source="pexels",
+                    preview_url=video.get("image", ""),
+                    download_url=best["link"],
+                    width=best.get("width", 0),
+                    height=best.get("height", 0),
+                    duration_sec=float(video.get("duration", 0)),
+                    credit=f'{video.get("user", {}).get("name", "Pexels")} / Pexels',
+                )
+            )
+            if len(out) >= per_query:
+                break
+        if not out:
+            log.warning("Pexels: no usable results for %r", query)
+        return out
+
+    def download(self, candidate: ClipCandidate, out_path: str) -> str:
+        def _dl():
+            with requests.get(candidate.download_url, stream=True, timeout=120) as r:
+                r.raise_for_status()
+                with open(out_path, "wb") as f:
+                    for chunk in r.iter_content(chunk_size=1 << 16):
+                        f.write(chunk)
+            return out_path
+
+        retry_backoff(_dl, attempts=3, label=f"pexels-dl:{candidate.id}")
+        candidate.local_path = out_path
+        return out_path
+
+
+register("stock", "pexels", PexelsStock)

core/adapters/transcript_youtube.py

@@ -0,0 +1,72 @@
+"""Transcript adapter: YouTube captions first, yt-dlp + faster-whisper fallback.
+
+Used for two things: style few-shot exemplars and the clone flow. Both fail
+soft — a missing transcript degrades the feature, never crashes a run.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from core.adapters.base import TranscriptAdapter, register
+from core.utils import log
+
+
+class YouTubeTranscript(TranscriptAdapter):
+    def __init__(self, config):
+        self.config = config
+
+    def fetch(self, video_id: str) -> Optional[str]:
+        text = self._via_captions(video_id)
+        if text:
+            return text
+        log.info("No captions for %s — trying audio transcription fallback", video_id)
+        return self._via_whisper(video_id)
+
+    # -- caption API ---------------------------------------------------------
+
+    @staticmethod
+    def _via_captions(video_id: str) -> Optional[str]:
+        try:
+            from youtube_transcript_api import YouTubeTranscriptApi
+
+            api = YouTubeTranscriptApi()
+            fetched = api.fetch(video_id, languages=["en", "en-US", "en-GB"])
+            return " ".join(snippet.text.strip() for snippet in fetched if snippet.text.strip())
+        except Exception as e:
+            log.info("youtube-transcript-api failed for %s: %s", video_id, e)
+            return None
+
+    # -- yt-dlp + faster-whisper fallback -------------------------------------
+
+    @staticmethod
+    def _via_whisper(video_id: str) -> Optional[str]:
+        try:
+            import yt_dlp
+            from faster_whisper import WhisperModel  # optional dep
+        except ImportError as e:
+            log.info("Transcription fallback unavailable (%s) — skipping %s", e, video_id)
+            return None
+        try:
+            with tempfile.TemporaryDirectory() as tmp:
+                out = str(Path(tmp) / "audio.%(ext)s")
+                ydl_opts = {
+                    "format": "bestaudio/best",
+                    "outtmpl": out,
+                    "quiet": True,
+                    "no_warnings": True,
+                }
+                with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                    ydl.download([f"https://www.youtube.com/watch?v={video_id}"])
+                audio = next(Path(tmp).glob("audio.*"))
+                model = WhisperModel("tiny", device="cpu", compute_type="int8")
+                segments, _ = model.transcribe(str(audio))
+                return " ".join(seg.text.strip() for seg in segments) or None
+        except Exception as e:
+            log.warning("Whisper transcription failed for %s: %s", video_id, e)
+            return None
+
+
+register("transcript", "youtube", YouTubeTranscript)

core/adapters/tts_edge.py

@@ -0,0 +1,63 @@
+"""edge-tts adapter — the free default voice provider.
+
+Microsoft Edge's online TTS emits word-boundary events natively, so we get
+karaoke-grade word timings without any alignment step.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+from core.adapters.base import TTSAdapter, register
+from core.contracts import WordTiming
+from core.utils import log, retry_backoff
+
+# A small curated set; edge-tts has hundreds, these are reliable for narration.
+_VOICES = [
+    "en-US-ChristopherNeural",
+    "en-US-GuyNeural",
+    "en-US-JennyNeural",
+    "en-US-AriaNeural",
+    "en-GB-RyanNeural",
+    "en-AU-NatashaNeural",
+]
+
+
+class EdgeTTS(TTSAdapter):
+    def __init__(self, config):
+        self.default_voice = config.edge_voice
+
+    async def _synth_async(self, text: str, out_path: str, voice: str) -> list[WordTiming]:
+        import edge_tts
+
+        # edge-tts >= 7 defaults to sentence boundaries; we need per-word.
+        communicate = edge_tts.Communicate(text, voice, boundary="WordBoundary")
+        timings: list[WordTiming] = []
+        with open(out_path, "wb") as f:
+            async for chunk in communicate.stream():
+                if chunk["type"] == "audio":
+                    f.write(chunk["data"])
+                elif chunk["type"] == "WordBoundary":
+                    start = chunk["offset"] / 10_000_000  # 100-ns ticks -> s
+                    dur = chunk["duration"] / 10_000_000
+                    timings.append(WordTiming(word=chunk["text"], start=start, end=start + dur))
+        return timings
+
+    def synth(self, text: str, out_path: str, voice: str = "") -> Optional[list[WordTiming]]:
+        voice = voice or self.default_voice
+
+        def _run():
+            return asyncio.run(self._synth_async(text, out_path, voice))
+
+        timings = retry_backoff(_run, attempts=3, label="edge-tts")
+        if not timings:
+            log.warning("edge-tts returned no word boundaries for %r", text[:40])
+            return None
+        return timings
+
+    def voices(self) -> list[str]:
+        return list(_VOICES)
+
+
+register("tts", "edge_tts", EdgeTTS)

core/adapters/tts_elevenlabs.py

@@ -0,0 +1,83 @@
+"""ElevenLabs TTS adapter (optional, needs ELEVENLABS_API_KEY).
+
+Uses the with-timestamps endpoint so we get character-level timings and
+aggregate them into word timings — no alignment pass needed.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Optional
+
+import requests
+
+from core.adapters.base import TTSAdapter, register
+from core.contracts import WordTiming
+from core.utils import HardAPIError, log, retry_backoff
+
+_BASE = "https://api.elevenlabs.io/v1"
+
+# name -> voice_id (a few stock voices)
+_VOICES = {
+    "Adam": "pNInz6obpgDQGcFmaJgB",
+    "Rachel": "21m00Tcm4TlvDq8ikWAM",
+    "Antoni": "ErXwobaYiN019PkySvjV",
+    "Bella": "EXAVITQu4vr4xnSDxMaL",
+}
+
+
+class ElevenLabsTTS(TTSAdapter):
+    def __init__(self, config):
+        if not config.elevenlabs_api_key:
+            raise HardAPIError("ELEVENLABS_API_KEY required for elevenlabs adapter")
+        self.key = config.elevenlabs_api_key
+
+    def _call(self, text: str, voice_id: str) -> dict:
+        resp = requests.post(
+            f"{_BASE}/text-to-speech/{voice_id}/with-timestamps",
+            headers={"xi-api-key": self.key},
+            json={"text": text, "model_id": "eleven_turbo_v2_5"},
+            timeout=120,
+        )
+        if resp.status_code in (400, 401, 403, 404):
+            raise HardAPIError(f"ElevenLabs HTTP {resp.status_code}: {resp.text[:300]}")
+        resp.raise_for_status()
+        return resp.json()
+
+    @staticmethod
+    def _chars_to_words(alignment: dict) -> list[WordTiming]:
+        chars = alignment.get("characters", [])
+        starts = alignment.get("character_start_times_seconds", [])
+        ends = alignment.get("character_end_times_seconds", [])
+        words: list[WordTiming] = []
+        cur, w_start, w_end = "", 0.0, 0.0
+        for ch, s, e in zip(chars, starts, ends):
+            if ch.isspace():
+                if cur:
+                    words.append(WordTiming(word=cur, start=w_start, end=w_end))
+                    cur = ""
+                continue
+            if not cur:
+                w_start = s
+            cur += ch
+            w_end = e
+        if cur:
+            words.append(WordTiming(word=cur, start=w_start, end=w_end))
+        return words
+
+    def synth(self, text: str, out_path: str, voice: str = "") -> Optional[list[WordTiming]]:
+        voice_id = _VOICES.get(voice or "Adam", next(iter(_VOICES.values())))
+        data = retry_backoff(lambda: self._call(text, voice_id), attempts=3, label="elevenlabs")
+        with open(out_path, "wb") as f:
+            f.write(base64.b64decode(data["audio_base64"]))
+        timings = self._chars_to_words(data.get("alignment") or {})
+        if not timings:
+            log.warning("ElevenLabs returned no alignment for %r", text[:40])
+            return None
+        return timings
+
+    def voices(self) -> list[str]:
+        return list(_VOICES)
+
+
+register("tts", "elevenlabs", ElevenLabsTTS)

core/adapters/tts_gemini.py

@@ -0,0 +1,80 @@
+"""Gemini TTS adapter (free tier). No native word timings — the voice stage
+recovers them via faster-whisper forced alignment when available."""
+
+from __future__ import annotations
+
+import base64
+import struct
+import wave
+from typing import Optional
+
+import requests
+
+from core.adapters.base import TTSAdapter, register
+from core.adapters.gemini_keys import KeyRejected, KeyRotator
+from core.contracts import WordTiming
+from core.utils import HardAPIError
+
+_API = (
+    "https://generativelanguage.googleapis.com/v1beta/models/"
+    "gemini-2.5-flash-preview-tts:generateContent"
+)
+
+_VOICES = ["Kore", "Puck", "Charon", "Fenrir", "Aoede"]
+
+
+class GeminiTTS(TTSAdapter):
+    def __init__(self, config):
+        if not config.gemini_api_keys:
+            raise HardAPIError("GEMINI_API_KEY required for gemini_tts")
+        # Rotate across all configured keys, same as the LLM adapter.
+        self.rotator = KeyRotator(config.gemini_api_keys)
+
+    def _call(self, key: str, text: str, voice: str) -> bytes:
+        resp = requests.post(
+            _API,
+            params={"key": key},
+            json={
+                "contents": [{"parts": [{"text": text}]}],
+                "generationConfig": {
+                    "responseModalities": ["AUDIO"],
+                    "speechConfig": {
+                        "voiceConfig": {"prebuiltVoiceConfig": {"voiceName": voice}}
+                    },
+                },
+            },
+            timeout=120,
+        )
+        code = resp.status_code
+        if code in (400, 404):
+            raise HardAPIError(f"Gemini TTS HTTP {code}: {resp.text[:300]}")
+        if code in (401, 403):
+            raise KeyRejected(f"Gemini TTS key HTTP {code}")
+        if code in (429, 500, 503):
+            raise RuntimeError(f"Gemini TTS HTTP {code} (retryable)")
+        resp.raise_for_status()
+        data = resp.json()
+        b64 = data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
+        return base64.b64decode(b64)
+
+    def synth(self, text: str, out_path: str, voice: str = "") -> Optional[list[WordTiming]]:
+        voice = voice or _VOICES[0]
+        pcm = self.rotator.call(lambda key: self._call(key, text, voice), label="gemini-tts")
+        # API returns raw 16-bit 24kHz mono PCM; wrap it in a WAV container.
+        wav_path = out_path if out_path.endswith(".wav") else out_path + ".wav"
+        with wave.open(wav_path, "wb") as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(24000)
+            w.writeframes(pcm)
+        if wav_path != out_path:
+            import shutil
+
+            shutil.move(wav_path, out_path)
+        return None  # no native timings — caller runs forced alignment
+
+    def voices(self) -> list[str]:
+        return list(_VOICES)
+
+
+register("tts", "gemini_tts", GeminiTTS)

core/captions.py

@@ -0,0 +1,313 @@
+"""Caption rendering: Pillow PNGs compiled into ONE qtrle overlay track.
+
+v1 lessons baked in:
+- FFmpeg drawtext/libass are NOT available on the target machine's build —
+  captions are rasterized with Pillow instead.
+- One overlay pass for the whole video. Per-word overlay filters are
+  pathologically slow; instead every caption state becomes a transparent
+  PNG frame and the sequence is compiled into a single qtrle .mov with
+  alpha, overlaid once.
+
+Karaoke mode (word timings available): words are grouped into small chunks;
+each word boundary produces a frame with the current word highlighted.
+Static mode (no timings): chunks are spread evenly across each line.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+from core.contracts import VIDEO_HEIGHT, VIDEO_WIDTH, VoiceTrack
+from core.utils import log, run_ffmpeg
+
+# ---------------------------------------------------------------------------
+# Presets
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CaptionPreset:
+    name: str
+    font_size: int
+    y_center_frac: float  # vertical anchor as fraction of video height
+    base_color: tuple
+    highlight_color: tuple
+    stroke_color: tuple
+    stroke_width: int
+    uppercase: bool
+    karaoke: bool  # highlight the current word when timings exist
+    box: bool  # dark rounded box behind text
+    words_per_chunk: int
+
+
+PRESETS: dict[str, CaptionPreset] = {
+    "bold-center-karaoke": CaptionPreset(
+        name="bold-center-karaoke",
+        font_size=88,
+        y_center_frac=0.52,
+        base_color=(255, 255, 255, 255),
+        highlight_color=(255, 214, 10, 255),
+        stroke_color=(0, 0, 0, 255),
+        stroke_width=8,
+        uppercase=True,
+        karaoke=True,
+        box=False,
+        words_per_chunk=3,
+    ),
+    "clean-lower-third": CaptionPreset(
+        name="clean-lower-third",
+        font_size=58,
+        y_center_frac=0.78,
+        base_color=(255, 255, 255, 255),
+        highlight_color=(120, 220, 255, 255),
+        stroke_color=(0, 0, 0, 200),
+        stroke_width=3,
+        uppercase=False,
+        karaoke=True,
+        box=True,
+        words_per_chunk=5,
+    ),
+    "minimal": CaptionPreset(
+        name="minimal",
+        font_size=48,
+        y_center_frac=0.85,
+        base_color=(245, 245, 245, 235),
+        highlight_color=(245, 245, 245, 235),
+        stroke_color=(0, 0, 0, 160),
+        stroke_width=2,
+        uppercase=False,
+        karaoke=False,
+        box=False,
+        words_per_chunk=6,
+    ),
+}
+
+_FONT_CANDIDATES = [
+    "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+    "/System/Library/Fonts/Supplemental/Verdana Bold.ttf",
+    "/System/Library/Fonts/Helvetica.ttc",
+    "/Library/Fonts/Arial Bold.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
+]
+
+
+def _load_font(size: int) -> ImageFont.FreeTypeFont:
+    for path in _FONT_CANDIDATES:
+        if os.path.exists(path):
+            try:
+                return ImageFont.truetype(path, size)
+            except OSError:
+                continue
+    log.warning("No system TTF found — using Pillow default bitmap font")
+    return ImageFont.load_default(size)  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Event timeline
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CaptionEvent:
+    start: float  # absolute seconds in the final video
+    end: float
+    words: list[str]  # the visible chunk
+    highlight: int  # index of the highlighted word, -1 for none
+
+
+def build_events(voice: VoiceTrack, preset: CaptionPreset) -> list[CaptionEvent]:
+    """Turn the voice track into an absolute-time caption event list."""
+    events: list[CaptionEvent] = []
+    offset = 0.0
+    for line in voice.lines:
+        if line.word_timings and preset.karaoke:
+            events.extend(_karaoke_events(line, offset, preset))
+        else:
+            events.extend(_static_events(line, offset, preset))
+        offset += line.duration_sec
+    return events
+
+
+def _karaoke_events(line, offset: float, preset: CaptionPreset) -> list[CaptionEvent]:
+    timings = line.word_timings
+    chunks = [
+        timings[i : i + preset.words_per_chunk]
+        for i in range(0, len(timings), preset.words_per_chunk)
+    ]
+    events: list[CaptionEvent] = []
+    for ci, chunk in enumerate(chunks):
+        words = [t.word for t in chunk]
+        chunk_end_limit = (
+            chunks[ci + 1][0].start if ci + 1 < len(chunks) else line.duration_sec
+        )
+        for wi, t in enumerate(chunk):
+            start = t.start
+            end = chunk[wi + 1].start if wi + 1 < len(chunk) else chunk_end_limit
+            if end <= start:
+                end = start + 0.05
+            events.append(
+                CaptionEvent(
+                    start=offset + start,
+                    end=offset + min(end, line.duration_sec),
+                    words=words,
+                    highlight=wi,
+                )
+            )
+    return events
+
+
+def _static_events(line, offset: float, preset: CaptionPreset) -> list[CaptionEvent]:
+    words = line.text.split()
+    if not words:
+        return []
+    chunks = [
+        words[i : i + preset.words_per_chunk]
+        for i in range(0, len(words), preset.words_per_chunk)
+    ]
+    per = line.duration_sec / len(chunks)
+    return [
+        CaptionEvent(
+            start=offset + i * per,
+            end=offset + (i + 1) * per,
+            words=chunk,
+            highlight=-1,
+        )
+        for i, chunk in enumerate(chunks)
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Frame rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_frame(event: CaptionEvent, preset: CaptionPreset, font) -> Image.Image:
+    img = Image.new("RGBA", (VIDEO_WIDTH, VIDEO_HEIGHT), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(img)
+    words = [w.upper() for w in event.words] if preset.uppercase else list(event.words)
+
+    space_w = draw.textlength(" ", font=font)
+    widths = [draw.textlength(w, font=font) for w in words]
+
+    # Wrap into display lines that fit 90% of the frame width.
+    max_w = VIDEO_WIDTH * 0.9
+    lines: list[list[int]] = [[]]
+    cur_w = 0.0
+    for i, w in enumerate(widths):
+        add = w if not lines[-1] else w + space_w
+        if lines[-1] and cur_w + add > max_w:
+            lines.append([i])
+            cur_w = w
+        else:
+            lines[-1].append(i)
+            cur_w += add
+
+    ascent, descent = font.getmetrics()
+    line_h = (ascent + descent) * 1.15
+    block_h = line_h * len(lines)
+    y = preset.y_center_frac * VIDEO_HEIGHT - block_h / 2
+
+    if preset.box:
+        widest = max(sum(widths[i] for i in ln) + space_w * (len(ln) - 1) for ln in lines)
+        pad = 28
+        box = [
+            (VIDEO_WIDTH - widest) / 2 - pad,
+            y - pad * 0.5,
+            (VIDEO_WIDTH + widest) / 2 + pad,
+            y + block_h + pad * 0.5,
+        ]
+        draw.rounded_rectangle(box, radius=18, fill=(10, 10, 14, 175))
+
+    for ln in lines:
+        total_w = sum(widths[i] for i in ln) + space_w * (len(ln) - 1)
+        x = (VIDEO_WIDTH - total_w) / 2
+        for i in ln:
+            color = (
+                preset.highlight_color
+                if i == event.highlight
+                else preset.base_color
+            )
+            draw.text(
+                (x, y),
+                words[i],
+                font=font,
+                fill=color,
+                stroke_width=preset.stroke_width,
+                stroke_fill=preset.stroke_color,
+            )
+            x += widths[i] + space_w
+        y += line_h
+
+    return img
+
+
+# ---------------------------------------------------------------------------
+# Overlay track compilation
+# ---------------------------------------------------------------------------
+
+
+def build_caption_track(
+    voice: VoiceTrack,
+    preset_name: str,
+    work_dir: str,
+    total_duration: float,
+) -> str:
+    """Render all caption frames and compile ONE qtrle overlay .mov.
+
+    Returns the .mov path, or "" when there is nothing to caption.
+    """
+    preset = PRESETS.get(preset_name) or PRESETS["minimal"]
+    events = build_events(voice, preset)
+    if not events:
+        return ""
+
+    work = Path(work_dir)
+    frames_dir = work / f"captions_{preset.name}"
+    frames_dir.mkdir(parents=True, exist_ok=True)
+    font = _load_font(preset.font_size)
+
+    blank = Image.new("RGBA", (VIDEO_WIDTH, VIDEO_HEIGHT), (0, 0, 0, 0))
+    blank_path = frames_dir / "blank.png"
+    blank.save(blank_path)
+
+    # Build a gap-free ffconcat timeline: blank frames fill silence.
+    entries: list[tuple[str, float]] = []
+    cursor = 0.0
+    for i, ev in enumerate(events):
+        if ev.start > cursor + 0.01:
+            entries.append((str(blank_path), ev.start - cursor))
+        frame_path = frames_dir / f"f{i:04d}.png"
+        _render_frame(ev, preset, font).save(frame_path)
+        end = min(ev.end, total_duration)
+        if end <= ev.start:
+            continue
+        entries.append((str(frame_path), end - ev.start))
+        cursor = end
+    if cursor < total_duration:
+        entries.append((str(blank_path), total_duration - cursor))
+
+    concat_path = work / f"captions_{preset.name}.ffconcat"
+    lines = ["ffconcat version 1.0"]
+    for path, dur in entries:
+        lines.append(f"file '{path}'")
+        lines.append(f"duration {max(dur, 0.034):.3f}")
+    lines.append(f"file '{entries[-1][0]}'")  # concat demuxer needs a final repeat
+    concat_path.write_text("\n".join(lines))
+
+    out_mov = str(work / f"captions_{preset.name}.mov")
+    run_ffmpeg(
+        [
+            "-f", "concat", "-safe", "0", "-i", str(concat_path),
+            "-vf", "fps=30,format=argb",
+            "-c:v", "qtrle",
+            out_mov,
+        ],
+        label="caption track",
+    )
+    log.info("Caption track (%s): %d events -> %s", preset.name, len(events), out_mov)
+    return out_mov

core/config.py

@@ -0,0 +1,107 @@
+"""Configuration: .env loading, API keys, and adapter selection.
+
+Adapter choice is config-driven: set ``ADAPTER_<CAPABILITY>`` in the
+environment (or .env) to the registry name of the provider you want.
+Defaults are the free-tier providers.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PROJECTS_DIR = REPO_ROOT / "projects"
+MUSIC_DIR = REPO_ROOT / "assets" / "music"
+
+load_dotenv(REPO_ROOT / ".env")
+
+
+def env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default).strip()
+
+
+@dataclass
+class Config:
+    """Resolved runtime configuration. Build once via :func:`load_config`."""
+
+    # API keys (only Gemini + Pexels are required for a useful run).
+    # gemini_api_keys holds one or more keys the LLM adapter rotates through
+    # to spread free-tier rate limits; gemini_api_key is the first one (kept
+    # for back-compat and used by the optional Gemini TTS adapter).
+    gemini_api_keys: list[str] = field(default_factory=list)
+    pexels_api_key: str = ""
+    freesound_api_key: str = ""
+    youtube_api_key: str = ""
+    elevenlabs_api_key: str = ""
+
+    # Adapter selection (registry names)
+    llm_adapter: str = "gemini"
+    # Default to Gemini TTS for natural narration (works with the Gemini key).
+    # Word timings come from faster-whisper alignment; edge_tts / elevenlabs
+    # are selectable per-reel in the UI.
+    tts_adapter: str = "gemini_tts"
+    stock_adapter: str = "pexels"
+    sfx_adapter: str = "freesound"
+    music_adapter: str = "local"
+    refdata_adapter: str = "youtube"
+    transcript_adapter: str = "youtube"
+
+    # LLM model fallback chain, tried in order on retryable failures.
+    # gemini-flash-latest is an alias that always resolves to a live flash
+    # model, so it survives Google retiring specific dated versions.
+    gemini_models: list[str] = field(
+        default_factory=lambda: ["gemini-2.0-flash", "gemini-2.5-flash", "gemini-flash-latest"]
+    )
+
+    # TTS
+    edge_voice: str = "en-US-ChristopherNeural"
+
+    projects_dir: Path = PROJECTS_DIR
+    music_dir: Path = MUSIC_DIR
+
+    @property
+    def gemini_api_key(self) -> str:
+        """First Gemini key (back-compat; used by the Gemini TTS adapter)."""
+        return self.gemini_api_keys[0] if self.gemini_api_keys else ""
+
+
+def _parse_keys(*raw: str) -> list[str]:
+    """Split keys on comma / whitespace / newline, dedupe, keep order."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for chunk in raw:
+        for k in chunk.replace("\n", ",").replace(" ", ",").split(","):
+            k = k.strip()
+            if k and k not in seen:
+                seen.add(k)
+                out.append(k)
+    return out
+
+
+def load_config() -> Config:
+    models = env("GEMINI_MODELS")
+    # Accept one key in GEMINI_API_KEY or many in GEMINI_API_KEYS (or several
+    # comma-separated in GEMINI_API_KEY itself). All are merged and rotated.
+    gemini_keys = _parse_keys(env("GEMINI_API_KEY"), env("GEMINI_API_KEYS"))
+    cfg = Config(
+        gemini_api_keys=gemini_keys,
+        pexels_api_key=env("PEXELS_API_KEY"),
+        freesound_api_key=env("FREESOUND_API_KEY"),
+        youtube_api_key=env("YOUTUBE_API_KEY"),
+        elevenlabs_api_key=env("ELEVENLABS_API_KEY"),
+        llm_adapter=env("ADAPTER_LLM", "gemini"),
+        tts_adapter=env("ADAPTER_TTS", "gemini_tts"),
+        stock_adapter=env("ADAPTER_STOCK", "pexels"),
+        sfx_adapter=env("ADAPTER_SFX", "freesound"),
+        music_adapter=env("ADAPTER_MUSIC", "local"),
+        refdata_adapter=env("ADAPTER_REFDATA", "youtube"),
+        transcript_adapter=env("ADAPTER_TRANSCRIPT", "youtube"),
+        edge_voice=env("EDGE_TTS_VOICE", "en-US-ChristopherNeural"),
+    )
+    if models:
+        cfg.gemini_models = [m.strip() for m in models.split(",") if m.strip()]
+    return cfg

core/contracts.py

@@ -0,0 +1,359 @@
+"""Shared data contracts for the Reel Studio v2 pipeline.
+
+Every stage and adapter communicates exclusively through the dataclasses
+defined here. Stages never import each other; they import this module and
+the adapter interfaces only.
+
+All dataclasses are JSON-serializable via :func:`to_dict` / :func:`from_dict`
+helpers so projects persist as plain JSON files on disk.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+
+def to_dict(obj: Any) -> Any:
+    """Recursively convert a dataclass (or container of them) to plain JSON types."""
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return {k: to_dict(v) for k, v in dataclasses.asdict(obj).items()}
+    if isinstance(obj, list):
+        return [to_dict(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: to_dict(v) for k, v in obj.items()}
+    return obj
+
+
+def from_dict(cls: type, data: dict) -> Any:
+    """Build a dataclass instance from a dict, ignoring unknown keys.
+
+    Nested dataclass fields are reconstructed when the field's type
+    annotation is itself a dataclass or a ``list`` of dataclasses
+    (resolved via the ``_NESTED`` map each contract declares as needed).
+    """
+    nested = getattr(cls, "_NESTED", {})
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):
+        if f.name not in data:
+            continue
+        value = data[f.name]
+        if f.name in nested and value is not None:
+            sub_cls, is_list = nested[f.name]
+            if is_list:
+                value = [from_dict(sub_cls, v) for v in value]
+            else:
+                value = from_dict(sub_cls, value)
+        kwargs[f.name] = value
+    return cls(**kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Project setup
+# ---------------------------------------------------------------------------
+
+# Output formats. "youtube_short" and "instagram_reel" are the same 9:16
+# video with a different label. "long_form" is reserved for the future and
+# intentionally not implemented by the render stage.
+FORMATS = ("youtube_short", "instagram_reel", "long_form")
+
+VIDEO_WIDTH = 1080
+VIDEO_HEIGHT = 1920
+VIDEO_FPS = 30
+
+
+@dataclass
+class NicheProfile:
+    """What the project is about. Nothing niche-specific is hardcoded anywhere."""
+
+    topic: str
+    keywords: list[str] = field(default_factory=list)
+    subreddits: list[str] = field(default_factory=list)
+    audience: str = ""
+    tone: str = ""
+
+
+@dataclass
+class ReferenceEntry:
+    """A reference channel/page that informs topics and style.
+
+    ``kind == "youtube"``: a data source (top Shorts stats, transcripts)
+    AND a style source.
+
+    ``kind == "instagram_style"``: style-only. Never fetched or scraped —
+    just a URL plus the user's own notes that feed the style prompt as text
+    (Instagram ToS forbids scraping and there is no public content API).
+    """
+
+    kind: str  # "youtube" | "instagram_style"
+    name: str
+    url: str = ""
+    channel_id: str = ""  # resolved YouTube channel id (youtube kind only)
+    notes: str = ""  # user-written style notes (required for instagram_style)
+
+
+@dataclass
+class Project:
+    id: str
+    name: str
+    niche: NicheProfile
+    format: str = "youtube_short"  # one of FORMATS
+    references: list[ReferenceEntry] = field(default_factory=list)
+    created_at: str = ""
+
+    _NESTED = {
+        "niche": (NicheProfile, False),
+        "references": (ReferenceEntry, True),
+    }
+
+
+@dataclass
+class Reel:
+    """One video within a project.
+
+    References + style profile + the topic pool live at the project level and
+    are shared; each Reel owns its own script, voice, media, and renders, so a
+    user can work on several topics in parallel without losing progress.
+    """
+
+    id: str
+    name: str = ""
+    topic: str = ""
+    created_at: str = ""
+    clone_source: str = ""  # attribution when this reel came from the clone flow
+
+
+# ---------------------------------------------------------------------------
+# Style profile
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StyleProfile:
+    """Distilled writing style of the reference channels.
+
+    ``style_card`` is an LLM-written brief (hook patterns, pacing, sentence
+    length, vocabulary, CTA style). ``exemplars`` keeps 2-3 full transcripts
+    for few-shot injection into script generation.
+    """
+
+    style_card: str = ""
+    exemplars: list[str] = field(default_factory=list)
+    instagram_notes: list[str] = field(default_factory=list)
+    sources: list[str] = field(default_factory=list)  # human-readable provenance
+    built_at: str = ""
+    prompt_used: str = ""  # the exact LLM prompt, for QC / reproducibility
+
+
+# ---------------------------------------------------------------------------
+# Topics
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Topic:
+    title: str
+    reason: str = ""  # one-line why this topic
+    # Supporting signals, one source per item (reference Shorts, news, Reddit
+    # posts). A list, not a string, since each item is its own source.
+    signals: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TopicBatch:
+    topics: list[Topic] = field(default_factory=list)
+    generated_at: str = ""
+    prompt_used: str = ""  # the exact LLM prompt, for QC / reproducibility
+
+    _NESTED = {"topics": (Topic, True)}
+
+
+# ---------------------------------------------------------------------------
+# Script
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Scene:
+    scene: int
+    narration: str
+    visual_query: str  # concrete 3-5 word stock-footage query
+    sfx_query: Optional[str] = None
+    duration_sec: float = 5.0
+
+
+@dataclass
+class Script:
+    title: str
+    hook_options: list[str] = field(default_factory=list)  # exactly 3
+    selected_hook: int = 0  # index into hook_options
+    scenes: list[Scene] = field(default_factory=list)  # <= 6 scenes
+    cta: str = ""
+    total_duration_sec: float = 0.0
+    topic: str = ""  # the topic this script was written for
+    clone_source: str = ""  # attribution when produced by the clone flow
+    prompt_used: str = ""  # the exact LLM prompt, for QC / reproducibility
+
+    _NESTED = {"scenes": (Scene, True)}
+
+    def narration_lines(self) -> list[str]:
+        """Hook + scene narrations + CTA, in spoken order.
+
+        The selected hook replaces nothing — it is spoken first, then each
+        scene, then the CTA. Voice generation iterates this list.
+        """
+        hook = self.hook_options[self.selected_hook] if self.hook_options else ""
+        lines = [hook] if hook else []
+        lines += [s.narration for s in self.scenes]
+        if self.cta:
+            lines.append(self.cta)
+        return lines
+
+
+# ---------------------------------------------------------------------------
+# Voice
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class WordTiming:
+    word: str
+    start: float  # seconds, relative to the line's audio file
+    end: float
+
+
+@dataclass
+class VoiceLine:
+    """One synthesized narration line (hook, a scene, or the CTA)."""
+
+    index: int  # position in Script.narration_lines()
+    text: str
+    audio_path: str
+    duration_sec: float  # true duration from ffprobe — drives ALL timing
+    word_timings: list[WordTiming] = field(default_factory=list)
+
+    _NESTED = {"word_timings": (WordTiming, True)}
+
+
+@dataclass
+class VoiceTrack:
+    lines: list[VoiceLine] = field(default_factory=list)
+    provider: str = ""
+    voice: str = ""
+    total_duration_sec: float = 0.0
+
+    _NESTED = {"lines": (VoiceLine, True)}
+
+
+# ---------------------------------------------------------------------------
+# Media
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ClipCandidate:
+    id: str
+    source: str  # e.g. "pexels"
+    preview_url: str = ""
+    download_url: str = ""
+    width: int = 0
+    height: int = 0
+    duration_sec: float = 0.0
+    credit: str = ""
+    local_path: str = ""  # set once downloaded
+
+
+@dataclass
+class SceneMedia:
+    """Clip candidates for one voice line. ``selected`` indexes candidates."""
+
+    line_index: int
+    query: str
+    candidates: list[ClipCandidate] = field(default_factory=list)
+    selected: int = 0
+    sfx_path: str = ""  # optional sound effect, empty if none
+
+    _NESTED = {"candidates": (ClipCandidate, True)}
+
+
+@dataclass
+class MediaManifest:
+    scenes: list[SceneMedia] = field(default_factory=list)
+    music_path: str = ""  # royalty-free local file only — never fetched music
+    music_credit: str = ""
+
+    _NESTED = {"scenes": (SceneMedia, True)}
+
+
+# ---------------------------------------------------------------------------
+# Render
+# ---------------------------------------------------------------------------
+
+# Caption style presets. Names are part of the contract so the UI can offer
+# them and variant specs can reference them.
+CAPTION_PRESETS = ("bold-center-karaoke", "clean-lower-third", "minimal")
+
+
+@dataclass
+class VariantSpec:
+    """How one render variant differs from the others.
+
+    ``clip_offset`` rotates each scene's clip choice through its alternates
+    (0 = the selected clip, 1 = next candidate, ...). ``caption_preset`` is
+    one of CAPTION_PRESETS.
+    """
+
+    name: str
+    caption_preset: str = "bold-center-karaoke"
+    clip_offset: int = 0
+
+
+DEFAULT_VARIANTS = [
+    VariantSpec(name="Variant A", caption_preset="bold-center-karaoke", clip_offset=0),
+    VariantSpec(name="Variant B", caption_preset="clean-lower-third", clip_offset=1),
+    VariantSpec(name="Variant C", caption_preset="minimal", clip_offset=2),
+]
+
+
+@dataclass
+class RenderResult:
+    variant: str
+    caption_preset: str
+    path: str
+    duration_sec: float = 0.0
+
+
+@dataclass
+class RenderBatch:
+    results: list[RenderResult] = field(default_factory=list)
+    rendered_at: str = ""
+
+    _NESTED = {"results": (RenderResult, True)}
+
+
+# ---------------------------------------------------------------------------
+# Clone flow
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CloneBrief:
+    """Extracted essence of a source Short, used to write a FRESH script.
+
+    The brief carries structure and topic only. The script stage is
+    explicitly instructed to write original wording; source footage, audio
+    and verbatim text are never reused.
+    """
+
+    source_url: str
+    source_title: str = ""
+    source_channel: str = ""
+    topic: str = ""
+    hook_pattern: str = ""
+    structure: str = ""  # e.g. "hook -> 3 escalating facts -> twist -> CTA"
+    style_notes: str = ""

core/pipeline.py

@@ -0,0 +1,387 @@
+"""Pipeline orchestrator — the ONLY place stages are wired together.
+
+Builds adapters from config (lazily, fail-soft for optional ones), hands
+stages their inputs, and persists every artifact through ProjectStore.
+Used identically by cli.py and the FastAPI server.
+
+Project-level (shared): references, style profile, topic pool.
+Reel-level (per video): script, voice, media, renders, clone brief.
+
+Every generative step exposes a prepare_*_prompt() that returns the exact
+assembled prompt, and accepts a ``prompt`` override on the run method so the
+prompt can be QC'd / edited in the UI before it is sent.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import core.adapters  # noqa: F401 — registers all providers
+from core.adapters.base import get_adapter, registered
+from core.config import Config, load_config
+from core.contracts import (
+    CloneBrief,
+    MediaManifest,
+    NicheProfile,
+    Project,
+    Reel,
+    ReferenceEntry,
+    RenderBatch,
+    Script,
+    StyleProfile,
+    TopicBatch,
+    VariantSpec,
+    VoiceTrack,
+)
+from core.stages import clone as clone_stage
+from core.stages import media as media_stage
+from core.stages import render as render_stage
+from core.stages import script as script_stage
+from core.stages import setup as setup_stage
+from core.stages import style as style_stage
+from core.stages import topics as topics_stage
+from core.stages import voice as voice_stage
+from core.store import ProjectStore, now_iso
+from core.utils import log
+
+Progress = Callable[[str], None]
+
+# Which TTS providers need which key (edge_tts is always free/available).
+_TTS_KEY = {"gemini_tts": "gemini_api_key", "elevenlabs": "elevenlabs_api_key", "edge_tts": None}
+
+_STYLE_PREP = "style_prep.json"  # cached transcripts between prompt-prepare and run
+
+
+class Pipeline:
+    def __init__(self, config: Optional[Config] = None, store: Optional[ProjectStore] = None):
+        self.config = config or load_config()
+        self.store = store or ProjectStore(self.config.projects_dir)
+        self._adapters: dict[str, object] = {}
+
+    # -- adapter access (lazy; optional ones fail soft to None) --------------
+
+    def adapter(self, capability: str, name: Optional[str] = None) -> object:
+        """Required adapter. ``name`` overrides the configured provider."""
+        name = name or getattr(self.config, f"{capability}_adapter")
+        key = f"{capability}:{name}"
+        if key not in self._adapters:
+            self._adapters[key] = get_adapter(capability, name, self.config)
+        return self._adapters[key]
+
+    def optional_adapter(self, capability: str, name: Optional[str] = None):
+        try:
+            return self.adapter(capability, name)
+        except Exception as e:
+            log.info("Optional %r adapter unavailable: %s", capability, e)
+            return None
+
+    # -- TTS provider discovery ---------------------------------------------
+
+    def available_tts_providers(self) -> list[str]:
+        """Registered TTS providers whose key (if any) is present."""
+        out = []
+        for name in registered("tts"):
+            key_attr = _TTS_KEY.get(name)
+            if key_attr is None or getattr(self.config, key_attr, ""):
+                out.append(name)
+        return out
+
+    SAMPLE_TEXT = "Hey! This is a quick preview of how I sound. Let's make something great together."
+
+    def voice_sample(self, provider: Optional[str], voice: str) -> str:
+        """Synthesize (once, then cache) a short sample for a provider+voice.
+
+        Returns the path to an mp3. Cached under projects/_voice_samples so
+        repeated previews don't re-spend TTS quota.
+        """
+        from core.utils import run_ffmpeg, slugify
+
+        provider = provider or self.config.tts_adapter
+        if provider not in self.available_tts_providers():
+            raise RuntimeError(f"Voice provider {provider!r} is not available")
+        samples = self.store.root / "_voice_samples"
+        samples.mkdir(parents=True, exist_ok=True)
+        mp3 = samples / f"{slugify(provider)}_{slugify(voice or 'default')}.mp3"
+        if not mp3.exists():
+            raw = samples / f"{mp3.stem}.raw"
+            self.adapter("tts", provider).synth(self.SAMPLE_TEXT, str(raw), voice=voice)
+            # Transcode whatever the provider produced (mp3/wav) to real mp3.
+            run_ffmpeg(["-i", str(raw), str(mp3)], label="voice sample")
+            raw.unlink(missing_ok=True)
+        return str(mp3)
+
+    def voices(self, provider: Optional[str] = None) -> tuple[str, list[str]]:
+        provider = provider or self.config.tts_adapter
+        if provider not in self.available_tts_providers():
+            # Fall back to a usable provider rather than erroring.
+            avail = self.available_tts_providers()
+            provider = avail[0] if avail else "edge_tts"
+        tts = self.adapter("tts", provider)
+        return provider, tts.voices()
+
+    # -- stage 1: setup -------------------------------------------------------
+
+    def create_project(
+        self,
+        name: str,
+        niche: NicheProfile,
+        format: str = "youtube_short",
+        references: Optional[list[ReferenceEntry]] = None,
+    ) -> Project:
+        project = setup_stage.build_project(name, niche, format, references)
+        refdata = self.optional_adapter("refdata")
+        if refdata:
+            for ref in project.references:
+                if ref.kind == "youtube" and not ref.channel_id:
+                    try:
+                        resolved = refdata.resolve_channel(ref.url or ref.name)
+                        if resolved:
+                            ref.channel_id = resolved["channel_id"]
+                            ref.url = ref.url or resolved["url"]
+                            ref.name = resolved["title"]
+                    except Exception as e:
+                        log.warning("Could not resolve %r now: %s", ref.name, e)
+        return self.store.create_project(project)
+
+    def suggest_niche_fields(self, topic: str) -> dict:
+        return setup_stage.suggest_niche_fields(self.adapter("llm"), topic)
+
+    def prepare_suggest_prompt(self, project: Project, n: int = 5) -> str:
+        return setup_stage.build_suggest_channels_prompt(project.niche, n)
+
+    def suggest_references(
+        self, project: Project, n: int = 5, prompt: Optional[str] = None
+    ) -> list[ReferenceEntry]:
+        return setup_stage.suggest_channels(
+            self.adapter("llm"), self.optional_adapter("refdata"), project.niche, n=n, prompt=prompt
+        )
+
+    # -- stage 2: style (project-level) --------------------------------------
+
+    def prepare_style_prompt(self, project: Project, progress: Progress = lambda m: None) -> str:
+        """Fetch transcripts, cache them, and return the assembled style prompt."""
+        collected, ig_notes, sources = style_stage.collect_style_inputs(
+            project, self.optional_adapter("refdata"), self.optional_adapter("transcript"), progress
+        )
+        self.store.save_json(
+            project.id, _STYLE_PREP,
+            {"collected": collected, "ig_notes": ig_notes, "sources": sources},
+        )
+        self.store.save_project(project)  # channel ids may have resolved
+        return style_stage.build_style_prompt(project, collected, ig_notes)
+
+    def build_style(
+        self, project: Project, prompt: Optional[str] = None, progress: Progress = lambda m: None
+    ) -> StyleProfile:
+        prep = self.store.load_json(project.id, _STYLE_PREP) if prompt else None
+        if prep is not None:
+            # Reuse cached transcripts so an edited prompt doesn't re-fetch.
+            collected = [tuple(c) for c in prep["collected"]]
+            ig_notes, sources = prep["ig_notes"], prep["sources"]
+        else:
+            collected, ig_notes, sources = style_stage.collect_style_inputs(
+                project, self.optional_adapter("refdata"), self.optional_adapter("transcript"), progress
+            )
+            self.store.save_project(project)
+        profile = style_stage.assemble_style_profile(
+            self.adapter("llm"), project, collected, ig_notes, sources, prompt=prompt, progress=progress
+        )
+        profile.built_at = now_iso()
+        self.store.save_style(project.id, profile)
+        return profile
+
+    def save_style(self, project: Project, profile: StyleProfile) -> StyleProfile:
+        """Persist a user-edited style profile (editable output)."""
+        profile.built_at = now_iso()
+        self.store.save_style(project.id, profile)
+        return profile
+
+    # -- stage 3: topics (project-level pool) --------------------------------
+
+    def prepare_topics_prompt(
+        self, project: Project, n: int = 8, progress: Progress = lambda m: None
+    ) -> str:
+        signals = topics_stage.collect_topic_signals(project, self.optional_adapter("refdata"), progress)
+        return topics_stage.build_topics_prompt(project, signals, n)
+
+    def generate_topics(
+        self, project: Project, n: int = 8, prompt: Optional[str] = None,
+        progress: Progress = lambda m: None,
+    ) -> TopicBatch:
+        batch = topics_stage.generate_topics(
+            project, self.adapter("llm"), self.optional_adapter("refdata"),
+            n=n, progress=progress, prompt=prompt,
+        )
+        batch.generated_at = now_iso()
+        self.store.save_topics(project.id, batch)
+        return batch
+
+    def save_topics(self, project: Project, batch: TopicBatch) -> TopicBatch:
+        self.store.save_topics(project.id, batch)
+        return batch
+
+    # -- reels ----------------------------------------------------------------
+
+    def create_reel(self, project: Project, name: str = "", topic: str = "") -> Reel:
+        return self.store.create_reel(project.id, name=name, topic=topic)
+
+    def list_reels(self, project: Project) -> list[Reel]:
+        return self.store.list_reels(project.id)
+
+    def delete_reel(self, project: Project, reel_id: str) -> None:
+        self.store.delete_reel(project.id, reel_id)
+
+    def _touch_reel(self, project: Project, reel_id: str, topic: str) -> None:
+        reel = self.store.load_reel(project.id, reel_id)
+        if reel:
+            reel.topic = topic
+            if not reel.name or reel.name == "Untitled reel":
+                reel.name = topic
+            self.store.save_reel(project.id, reel)
+
+    # -- stage 4: script (reel-level) ----------------------------------------
+
+    def prepare_script_prompt(
+        self, project: Project, reel_id: str, topic: str
+    ) -> str:
+        style = self.store.load_style(project.id)
+        clone_brief = self.store.load_clone(project.id, reel_id)
+        use_brief = clone_brief if clone_brief and clone_brief.topic == topic else None
+        return script_stage.build_script_prompt(project, topic, style, use_brief)
+
+    def generate_script(
+        self, project: Project, reel_id: str, topic: str,
+        clone_brief: Optional[CloneBrief] = None, prompt: Optional[str] = None,
+    ) -> Script:
+        style = self.store.load_style(project.id)
+        if clone_brief is None:
+            saved = self.store.load_clone(project.id, reel_id)
+            if saved and saved.topic == topic:
+                clone_brief = saved
+        script = script_stage.generate_script(
+            project, topic, self.adapter("llm"), style=style, clone_brief=clone_brief, prompt=prompt
+        )
+        self.store.save_script(project.id, reel_id, script)
+        self._touch_reel(project, reel_id, topic)
+        return script
+
+    def save_script(self, project: Project, reel_id: str, script: Script) -> Script:
+        self.store.save_script(project.id, reel_id, script)
+        return script
+
+    def regenerate_scene(self, project: Project, reel_id: str, scene_number: int) -> Script:
+        script = self.store.load_script(project.id, reel_id)
+        if not script:
+            raise RuntimeError("No script to regenerate — generate one first")
+        style = self.store.load_style(project.id)
+        script = script_stage.regenerate_scene(
+            project, script, scene_number, self.adapter("llm"), style=style
+        )
+        self.store.save_script(project.id, reel_id, script)
+        return script
+
+    # -- stage 5: voice (reel-level) -----------------------------------------
+
+    def synthesize_voice(
+        self, project: Project, reel_id: str, voice: str = "",
+        provider: Optional[str] = None, progress: Progress = lambda m: None,
+    ) -> VoiceTrack:
+        script = self.store.load_script(project.id, reel_id)
+        if not script:
+            raise RuntimeError("No script — generate one first")
+        provider = provider or self.config.tts_adapter
+        track = voice_stage.synthesize_voice(
+            script,
+            self.adapter("tts", provider),
+            str(self.store.voice_dir(project.id, reel_id)),
+            voice=voice,
+            provider_name=provider,
+            progress=progress,
+        )
+        self.store.save_voice(project.id, reel_id, track)
+        return track
+
+    # -- stage 6: media (reel-level) -----------------------------------------
+
+    def gather_media(self, project: Project, reel_id: str, progress: Progress = lambda m: None) -> MediaManifest:
+        script = self.store.load_script(project.id, reel_id)
+        voice = self.store.load_voice(project.id, reel_id)
+        if not script or not voice:
+            raise RuntimeError("Need a script and a voice track before gathering media")
+        manifest = media_stage.gather_media(
+            script, voice, self.adapter("stock"), self.optional_adapter("sfx"),
+            self.optional_adapter("music"), str(self.store.media_dir(project.id, reel_id)), progress,
+        )
+        self.store.save_media(project.id, reel_id, manifest)
+        return manifest
+
+    def swap_clip(self, project: Project, reel_id: str, line_index: int) -> MediaManifest:
+        manifest = self.store.load_media(project.id, reel_id)
+        if not manifest:
+            raise RuntimeError("No media manifest — gather media first")
+        manifest = media_stage.swap_clip(
+            manifest, line_index, self.adapter("stock"), str(self.store.media_dir(project.id, reel_id))
+        )
+        self.store.save_media(project.id, reel_id, manifest)
+        return manifest
+
+    # -- stage 7: render (reel-level) ----------------------------------------
+
+    def render(
+        self, project: Project, reel_id: str, variants: Optional[list[VariantSpec]] = None,
+        progress: Progress = lambda m: None,
+    ) -> RenderBatch:
+        voice = self.store.load_voice(project.id, reel_id)
+        manifest = self.store.load_media(project.id, reel_id)
+        if not voice or not manifest:
+            raise RuntimeError("Need voice and media before rendering")
+        batch = render_stage.render_variants(
+            voice, manifest, str(self.store.renders_dir(project.id, reel_id)),
+            variants=variants, stock=self.optional_adapter("stock"), progress=progress,
+        )
+        batch.rendered_at = now_iso()
+        self.store.save_renders(project.id, reel_id, batch)
+        return batch
+
+    # -- stage 8: clone (creates a new reel) ---------------------------------
+
+    def clone_reel(self, project: Project, url: str, progress: Progress = lambda m: None) -> dict:
+        """URL -> CloneBrief -> a NEW reel with a fresh script."""
+        transcripts = self.optional_adapter("transcript")
+        if transcripts is None:
+            raise clone_stage.CloneError("Transcript support unavailable on this install.")
+        progress("Fetching source transcript")
+        brief = clone_stage.build_clone_brief(
+            url, self.adapter("llm"), transcripts, self.optional_adapter("refdata")
+        )
+        reel = self.store.create_reel(project.id, name=brief.topic, topic=brief.topic)
+        reel.clone_source = url
+        self.store.save_reel(project.id, reel)
+        self.store.save_clone(project.id, reel.id, brief)
+        progress(f"Writing a fresh script on: {brief.topic}")
+        script = self.generate_script(project, reel.id, brief.topic, clone_brief=brief)
+        return {"reel": reel, "script": script}
+
+    # -- convenience: full headless run --------------------------------------
+
+    def run_all(
+        self, project: Project, topic: Optional[str] = None, voice: str = "",
+        provider: Optional[str] = None, progress: Progress = lambda m: None,
+    ) -> RenderBatch:
+        """Style -> topics -> reel(script -> voice -> media -> render), end to end."""
+        progress("Building style profile")
+        self.build_style(project, progress=progress)
+        if topic is None:
+            progress("Generating topics")
+            batch = self.generate_topics(project, n=5, progress=progress)
+            topic = batch.topics[0].title
+            progress(f"Auto-picked top topic: {topic}")
+        reel = self.create_reel(project, topic=topic)
+        progress("Writing script")
+        self.generate_script(project, reel.id, topic)
+        progress("Synthesizing voice")
+        self.synthesize_voice(project, reel.id, voice=voice, provider=provider, progress=progress)
+        progress("Gathering media")
+        self.gather_media(project, reel.id, progress)
+        progress("Rendering variants")
+        return self.render(project, reel.id, progress=progress)

core/stages/clone.py

@@ -0,0 +1,94 @@
+"""Stage 8 — "Clone a reel".
+
+Given a YouTube Shorts URL: fetch metadata + transcript, have the LLM
+extract the topic / hook pattern / structure, and emit a CloneBrief that
+script.py uses to write a FRESH script.
+
+Content policy (enforced here and in the script prompt): the output is
+transformed original content. The source video's footage, audio, and
+verbatim wording are NEVER reused. If a transcript can't be obtained we
+refuse gracefully with a clear message instead of guessing.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from core.adapters.base import LLMAdapter, ReferenceDataAdapter, TranscriptAdapter
+from core.contracts import CloneBrief
+from core.utils import log
+
+_VIDEO_ID_RE = re.compile(
+    r"(?:youtube\.com/(?:shorts/|watch\?v=)|youtu\.be/)([\w-]{11})"
+)
+
+
+class CloneError(Exception):
+    """User-facing clone failure (bad URL, no transcript, ...)."""
+
+
+def extract_video_id(url: str) -> str:
+    m = _VIDEO_ID_RE.search(url.strip())
+    if not m:
+        raise CloneError(
+            "That doesn't look like a YouTube video URL. "
+            "Paste a link like https://www.youtube.com/shorts/VIDEOID"
+        )
+    return m.group(1)
+
+
+def build_clone_brief(
+    url: str,
+    llm: LLMAdapter,
+    transcripts: TranscriptAdapter,
+    refdata: Optional[ReferenceDataAdapter] = None,
+) -> CloneBrief:
+    video_id = extract_video_id(url)
+
+    transcript = transcripts.fetch(video_id)
+    if not transcript or len(transcript.strip()) < 40:
+        raise CloneError(
+            "Couldn't get a transcript for that video (no captions and audio "
+            "transcription unavailable). Cloning needs the spoken content — "
+            "try a different video."
+        )
+
+    title, channel = "", ""
+    if refdata is not None:
+        try:
+            # videos.list via the refdata adapter's private getter keeps the
+            # YouTube surface in one module.
+            data = refdata._get("videos", part="snippet", id=video_id)  # type: ignore[attr-defined]
+            items = data.get("items", [])
+            if items:
+                title = items[0]["snippet"]["title"]
+                channel = items[0]["snippet"]["channelTitle"]
+        except Exception as e:
+            log.info("Clone metadata lookup failed (%s) — proceeding with transcript only", e)
+
+    prompt = f"""Analyze this short-form video transcript and extract its essence
+so a writer can make an ORIGINAL video on the same topic.
+
+TITLE: {title or "(unknown)"}
+TRANSCRIPT:
+{transcript[:6000]}
+
+Return JSON only:
+{{"topic": "what the video is about, one line",
+  "hook_pattern": "the abstract pattern of its hook (e.g. 'shocking stat then challenge to viewer'), NOT its words",
+  "structure": "beat-by-beat structure (e.g. 'hook -> 3 escalating examples -> twist -> CTA')",
+  "style_notes": "delivery style: pacing, person, tone, devices used"}}"""
+    raw = llm.complete_json(prompt)
+    brief = CloneBrief(
+        source_url=url,
+        source_title=title,
+        source_channel=channel,
+        topic=(raw.get("topic") or "").strip(),
+        hook_pattern=(raw.get("hook_pattern") or "").strip(),
+        structure=(raw.get("structure") or "").strip(),
+        style_notes=(raw.get("style_notes") or "").strip(),
+    )
+    if not brief.topic:
+        raise CloneError("Couldn't extract a usable topic from that video's transcript.")
+    return brief

core/stages/media.py

@@ -0,0 +1,155 @@
+"""Stage 6 — media gathering.
+
+For each voiced narration line: search stock clips (keeping alternates in
+the manifest so the UI can offer swaps), download the selected candidate,
+optionally fetch an SFX, and pick a background music track. Dedupe rule:
+the same clip id is never used twice in one reel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.adapters.base import MusicAdapter, SFXAdapter, StockVideoAdapter
+from core.contracts import MediaManifest, SceneMedia, Script, VoiceTrack
+from core.utils import log
+
+Progress = Callable[[str], None]
+
+
+def _queries_per_line(script: Script) -> list[str]:
+    """Map each narration line (hook + scenes + cta) to a visual query.
+
+    The hook reuses the first scene's visuals; the CTA reuses the last's.
+    """
+    scene_queries = [s.visual_query for s in script.scenes]
+    if not scene_queries:
+        return []
+    queries = []
+    if script.hook_options:
+        queries.append(scene_queries[0])
+    queries.extend(scene_queries)
+    if script.cta:
+        queries.append(scene_queries[-1])
+    return queries
+
+
+def _sfx_per_line(script: Script) -> list[Optional[str]]:
+    sfx = [s.sfx_query for s in script.scenes]
+    out: list[Optional[str]] = []
+    if script.hook_options:
+        out.append(None)
+    out.extend(sfx)
+    if script.cta:
+        out.append(None)
+    return out
+
+
+def gather_media(
+    script: Script,
+    voice: VoiceTrack,
+    stock: StockVideoAdapter,
+    sfx: Optional[SFXAdapter],
+    music: Optional[MusicAdapter],
+    out_dir: str,
+    progress: Progress = lambda m: None,
+) -> MediaManifest:
+    out = Path(out_dir)
+    clips_dir = out / "clips"
+    sfx_dir = out / "sfx"
+    clips_dir.mkdir(parents=True, exist_ok=True)
+    sfx_dir.mkdir(parents=True, exist_ok=True)
+
+    queries = _queries_per_line(script)
+    sfx_queries = _sfx_per_line(script)
+    if len(queries) != len(voice.lines):
+        log.warning(
+            "Query count (%d) != voice line count (%d) — padding with last query",
+            len(queries), len(voice.lines),
+        )
+        while len(queries) < len(voice.lines):
+            queries.append(queries[-1] if queries else script.topic)
+        queries = queries[: len(voice.lines)]
+        sfx_queries = (sfx_queries + [None] * len(voice.lines))[: len(voice.lines)]
+
+    used_clip_ids: set[str] = set()
+    scenes: list[SceneMedia] = []
+
+    for line, query, sfx_query in zip(voice.lines, queries, sfx_queries):
+        progress(f"Searching clips for line {line.index + 1}: {query!r}")
+        try:
+            candidates = stock.search(
+                query,
+                orientation="portrait",
+                min_duration=max(2.0, line.duration_sec * 0.5),
+                max_duration=max(30.0, line.duration_sec * 2),
+                per_query=4,
+            )
+        except Exception as e:
+            log.warning("Stock search failed for %r: %s — line gets no candidates", query, e)
+            candidates = []
+
+        # Dedupe across the whole reel: drop candidates already used elsewhere,
+        # unless that would leave the line with nothing.
+        fresh = [c for c in candidates if c.id not in used_clip_ids]
+        candidates = fresh or candidates
+
+        selected = 0
+        if candidates:
+            try:
+                chosen = candidates[selected]
+                dest = str(clips_dir / f"line{line.index:02d}_{chosen.id}.mp4")
+                progress(f"Downloading clip {chosen.id}")
+                stock.download(chosen, dest)
+                used_clip_ids.add(chosen.id)
+            except Exception as e:
+                log.warning("Clip download failed (%s) — line %d left clipless", e, line.index)
+                candidates = []
+
+        sfx_path = ""
+        if sfx_query and sfx is not None:
+            dest = str(sfx_dir / f"line{line.index:02d}.mp3")
+            got = sfx.fetch(sfx_query, dest)
+            sfx_path = got or ""
+
+        scenes.append(
+            SceneMedia(
+                line_index=line.index,
+                query=query,
+                candidates=candidates,
+                selected=selected,
+                sfx_path=sfx_path,
+            )
+        )
+
+    music_path, music_credit = "", ""
+    if music is not None:
+        try:
+            music_path, music_credit = music.pick(mood=script.topic)
+        except Exception as e:
+            log.warning("Music pick failed: %s — rendering without music", e)
+
+    return MediaManifest(scenes=scenes, music_path=music_path, music_credit=music_credit)
+
+
+def swap_clip(
+    manifest: MediaManifest,
+    line_index: int,
+    stock: StockVideoAdapter,
+    out_dir: str,
+) -> MediaManifest:
+    """Cycle a line's selection to its next downloaded-or-downloadable alternate."""
+    sm = next((s for s in manifest.scenes if s.line_index == line_index), None)
+    if sm is None or len(sm.candidates) < 2:
+        return manifest
+    sm.selected = (sm.selected + 1) % len(sm.candidates)
+    chosen = sm.candidates[sm.selected]
+    if not chosen.local_path:
+        dest = str(Path(out_dir) / "clips" / f"line{line_index:02d}_{chosen.id}.mp4")
+        try:
+            stock.download(chosen, dest)
+        except Exception as e:
+            log.warning("Swap download failed (%s) — reverting selection", e)
+            sm.selected = (sm.selected - 1) % len(sm.candidates)
+    return manifest

core/stages/render.py

@@ -0,0 +1,218 @@
+"""Stage 7 — rendering.
+
+Per voice line: normalize the chosen clip to 1080x1920@30, loop/trim it to
+the TRUE voice duration, and mix voice + optional SFX. Segments are then
+concatenated, the Pillow caption track is overlaid in a single pass, and
+royalty-free music is mixed at low volume.
+
+Produces 2-3 VARIANTS per run (different clip choices via alternates +
+different caption presets) so the user can pick side by side.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.adapters.base import StockVideoAdapter
+from core.captions import build_caption_track
+from core.contracts import (
+    DEFAULT_VARIANTS,
+    VIDEO_FPS,
+    VIDEO_HEIGHT,
+    VIDEO_WIDTH,
+    MediaManifest,
+    RenderBatch,
+    RenderResult,
+    VariantSpec,
+    VoiceTrack,
+)
+from core.utils import ffprobe_duration, log, run_ffmpeg
+
+Progress = Callable[[str], None]
+
+_VID = f"scale={VIDEO_WIDTH}:{VIDEO_HEIGHT}:force_original_aspect_ratio=increase,crop={VIDEO_WIDTH}:{VIDEO_HEIGHT},fps={VIDEO_FPS},setsar=1,format=yuv420p"
+_AUD = "aresample=44100,aformat=sample_fmts=fltp:channel_layouts=stereo"
+_ENC = [
+    "-c:v", "libx264", "-preset", "veryfast", "-crf", "20",
+    "-c:a", "aac", "-b:a", "192k", "-ar", "44100", "-ac", "2",
+]
+_FALLBACK_BG = "color=c=0x16213e:s=%dx%d:r=%d" % (VIDEO_WIDTH, VIDEO_HEIGHT, VIDEO_FPS)
+
+
+def _clip_for_line(scene_media, clip_offset: int, stock: Optional[StockVideoAdapter],
+                   clips_dir: Path) -> str:
+    """Pick this variant's clip for a line, lazily downloading alternates.
+
+    Falls back: offset candidate -> selected candidate -> "" (solid bg).
+    """
+    cands = scene_media.candidates
+    if not cands:
+        return ""
+    order = [(scene_media.selected + clip_offset) % len(cands), scene_media.selected]
+    for idx in order:
+        cand = cands[idx]
+        if cand.local_path and Path(cand.local_path).exists():
+            return cand.local_path
+        if stock is not None:
+            dest = str(clips_dir / f"line{scene_media.line_index:02d}_{cand.id}.mp4")
+            try:
+                stock.download(cand, dest)
+                return dest
+            except Exception as e:
+                log.warning("Alternate download failed (%s) — trying fallback clip", e)
+    return ""
+
+
+def _render_segment(clip_path: str, line, sfx_path: str, out_path: str) -> None:
+    """One normalized 9:16 segment, exactly line.duration_sec long."""
+    dur = max(line.duration_sec, 0.2)
+    args: list[str] = []
+    if clip_path:
+        args += ["-stream_loop", "-1", "-i", clip_path]
+        video_in = "[0:v]"
+        voice_idx, sfx_idx = 1, 2
+    else:
+        args += ["-f", "lavfi", "-i", _FALLBACK_BG]
+        video_in = "[0:v]"
+        voice_idx, sfx_idx = 1, 2
+    args += ["-i", line.audio_path]
+    if sfx_path:
+        args += ["-i", sfx_path]
+
+    filters = [f"{video_in}{_VID}[v]"]
+    if sfx_path:
+        filters.append(f"[{sfx_idx}:a]volume=0.45,{_AUD}[sfx]")
+        filters.append(f"[{voice_idx}:a]{_AUD}[vo]")
+        filters.append("[vo][sfx]amix=inputs=2:duration=first:dropout_transition=0[a]")
+    else:
+        filters.append(f"[{voice_idx}:a]{_AUD}[a]")
+
+    run_ffmpeg(
+        [
+            *args,
+            "-filter_complex", ";".join(filters),
+            "-map", "[v]", "-map", "[a]",
+            "-t", f"{dur:.3f}",
+            *_ENC,
+            out_path,
+        ],
+        label=f"segment line {line.index}",
+    )
+
+
+def render_variants(
+    voice: VoiceTrack,
+    manifest: MediaManifest,
+    out_dir: str,
+    variants: Optional[list[VariantSpec]] = None,
+    stock: Optional[StockVideoAdapter] = None,
+    progress: Progress = lambda m: None,
+) -> RenderBatch:
+    """Render every requested variant; a failed variant is logged and skipped,
+    but at least one must succeed."""
+    variants = variants or list(DEFAULT_VARIANTS)
+    out = Path(out_dir)
+    work = out / "work"
+    work.mkdir(parents=True, exist_ok=True)
+    clips_dir = work / "clips"
+    clips_dir.mkdir(exist_ok=True)
+
+    media_by_line = {s.line_index: s for s in manifest.scenes}
+    results: list[RenderResult] = []
+
+    for vi, spec in enumerate(variants):
+        try:
+            progress(f"Rendering {spec.name} ({spec.caption_preset})")
+            path = _render_one(
+                voice, manifest, media_by_line, spec, work, out, clips_dir, stock, progress
+            )
+            results.append(
+                RenderResult(
+                    variant=spec.name,
+                    caption_preset=spec.caption_preset,
+                    path=path,
+                    duration_sec=ffprobe_duration(path),
+                )
+            )
+        except Exception as e:
+            log.warning("Variant %s failed: %s — continuing with the others", spec.name, e)
+
+    if not results:
+        raise RuntimeError("All render variants failed")
+    return RenderBatch(results=results)
+
+
+def _render_one(
+    voice: VoiceTrack,
+    manifest: MediaManifest,
+    media_by_line: dict,
+    spec: VariantSpec,
+    work: Path,
+    out: Path,
+    clips_dir: Path,
+    stock: Optional[StockVideoAdapter],
+    progress: Progress,
+) -> str:
+    tag = spec.name.lower().replace(" ", "_")
+
+    # 1. Per-line segments (loop/trim clip to the voice line's true duration).
+    seg_paths = []
+    for line in voice.lines:
+        sm = media_by_line.get(line.index)
+        clip = _clip_for_line(sm, spec.clip_offset, stock, clips_dir) if sm else ""
+        sfx = sm.sfx_path if sm and sm.sfx_path and Path(sm.sfx_path).exists() else ""
+        seg = str(work / f"{tag}_seg{line.index:02d}.mp4")
+        progress(f"{spec.name}: segment {line.index + 1}/{len(voice.lines)}")
+        _render_segment(clip, line, sfx, seg)
+        seg_paths.append(seg)
+
+    concat_list = work / f"{tag}_segments.txt"
+    concat_list.write_text("\n".join(f"file '{p}'" for p in seg_paths))
+    total = sum(line.duration_sec for line in voice.lines)
+
+    # 2. Caption overlay track (one qtrle pass for the whole video).
+    progress(f"{spec.name}: rendering captions")
+    captions = build_caption_track(voice, spec.caption_preset, str(work), total)
+
+    # 3. Final pass: concat + caption overlay + low-volume music, one encode.
+    final = str(out / f"{tag}.mp4")
+    args = ["-f", "concat", "-safe", "0", "-i", str(concat_list)]
+    filter_parts = []
+    n_in = 1
+    video_label = "[0:v]"
+    if captions:
+        args += ["-i", captions]
+        filter_parts.append(f"{video_label}[{n_in}:v]overlay=0:0:eof_action=pass[v]")
+        video_label = "[v]"
+        n_in += 1
+
+    audio_label = "[0:a]"
+    music = manifest.music_path if manifest.music_path and Path(manifest.music_path).exists() else ""
+    if music:
+        args += ["-stream_loop", "-1", "-i", music]
+        filter_parts.append(f"[{n_in}:a]volume=0.12,{_AUD}[mus]")
+        filter_parts.append(f"{audio_label}[mus]amix=inputs=2:duration=first:dropout_transition=0[a]")
+        audio_label = "[a]"
+        n_in += 1
+
+    progress(f"{spec.name}: final encode")
+    if filter_parts:
+        run_ffmpeg(
+            [
+                *args,
+                "-filter_complex", ";".join(filter_parts),
+                "-map", video_label, "-map", audio_label,
+                "-t", f"{total:.3f}",
+                *_ENC,
+                "-movflags", "+faststart",
+                final,
+            ],
+            label=f"final {spec.name}",
+        )
+    else:  # no captions, no music — plain concat re-encode
+        run_ffmpeg(
+            [*args, "-t", f"{total:.3f}", *_ENC, "-movflags", "+faststart", final],
+            label=f"final {spec.name}",
+        )
+    return final

core/stages/script.py

@@ -0,0 +1,178 @@
+"""Stage 4 — scene-structured script generation.
+
+Injects the niche profile + style card + exemplar transcripts + topic so
+output mirrors the reference channels rather than generic AI voice.
+Supports full regeneration, single-scene regeneration, and clone briefs.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from core.adapters.base import LLMAdapter
+from core.contracts import CloneBrief, Project, Scene, Script, StyleProfile
+from core.utils import log
+
+MAX_SCENES = 6
+MIN_TOTAL_SEC = 30
+MAX_TOTAL_SEC = 45
+
+_SCHEMA = """{
+  "title": "video title",
+  "hook_options": ["hook 1", "hook 2", "hook 3"],
+  "scenes": [
+    {"scene": 1, "narration": "spoken words", "visual_query": "3-5 word stock footage query",
+     "sfx_query": "short sfx query or null", "duration_sec": 6}
+  ],
+  "cta": "closing call to action",
+  "total_duration_sec": 38
+}"""
+
+
+def _style_block(style: Optional[StyleProfile]) -> str:
+    if not style:
+        return "No style profile available — use a strong default short-form style."
+    parts = [f"STYLE CARD:\n{style.style_card}"]
+    for i, ex in enumerate(style.exemplars[:2], 1):
+        parts.append(f"EXEMPLAR TRANSCRIPT {i} (match this voice, never copy lines):\n{ex[:3000]}")
+    if style.instagram_notes:
+        parts.append("EXTRA STYLE NOTES:\n" + "\n".join(f"- {n}" for n in style.instagram_notes))
+    return "\n\n".join(parts)
+
+
+def generate_script(
+    project: Project,
+    topic: str,
+    llm: LLMAdapter,
+    style: Optional[StyleProfile] = None,
+    clone_brief: Optional[CloneBrief] = None,
+    prompt: Optional[str] = None,
+) -> Script:
+    """Write a complete script for ``topic`` in the references' style.
+
+    ``prompt`` overrides the default assembled prompt (for QC editing).
+    """
+    used_prompt = prompt or build_script_prompt(project, topic, style, clone_brief)
+    raw = llm.complete_json(used_prompt)
+    script = _parse_script(raw, topic)
+    script.prompt_used = used_prompt
+    if clone_brief:
+        script.clone_source = clone_brief.source_url
+    return script
+
+
+def build_script_prompt(
+    project: Project,
+    topic: str,
+    style: Optional[StyleProfile] = None,
+    clone_brief: Optional[CloneBrief] = None,
+) -> str:
+    """The default scriptwriting prompt (exposed for QC/editing)."""
+    clone_block = ""
+    if clone_brief:
+        clone_block = f"""
+THIS IS A CLONE BRIEF. A reference Short exists on this topic. Reuse ONLY its
+abstract structure — write 100% ORIGINAL wording. Never quote or paraphrase
+its lines closely.
+Hook pattern to emulate: {clone_brief.hook_pattern}
+Structure to follow: {clone_brief.structure}
+Style notes: {clone_brief.style_notes}
+"""
+    return f"""You write scripts for 9:16 short-form videos.
+
+NICHE: {project.niche.topic} | Audience: {project.niche.audience or "general"} | Tone: {project.niche.tone or "engaging"}
+TOPIC: {topic}
+
+{_style_block(style)}
+{clone_block}
+HARD RULES:
+- At most {MAX_SCENES} scenes; total spoken duration {MIN_TOTAL_SEC}-{MAX_TOTAL_SEC} seconds.
+- The hook must land inside the first 2 seconds (start mid-action, no warmup).
+- Conversational spoken English — contractions, short sentences, no headings.
+- Provide exactly 3 alternative hook_options (different angles, same topic).
+- visual_query: concrete 3-5 word stock-footage search ("rain on car window"),
+  never abstract ("success concept").
+- sfx_query: a short sound effect cue or null. Use sparingly (0-2 scenes).
+
+Return JSON only, exactly this shape:
+{_SCHEMA}"""
+
+
+def regenerate_scene(
+    project: Project,
+    script: Script,
+    scene_number: int,
+    llm: LLMAdapter,
+    style: Optional[StyleProfile] = None,
+) -> Script:
+    """Rewrite a single scene in place, keeping the rest of the script."""
+    target = next((s for s in script.scenes if s.scene == scene_number), None)
+    if target is None:
+        raise ValueError(f"No scene {scene_number} in script")
+    context = "\n".join(
+        f"Scene {s.scene}: {s.narration}" for s in script.scenes if s.scene != scene_number
+    )
+    prompt = f"""Rewrite ONE scene of a short-form video script.
+
+TOPIC: {script.topic} | NICHE: {project.niche.topic}
+{_style_block(style)}
+
+OTHER SCENES (keep continuity with these):
+{context}
+
+Rewrite scene {scene_number} (currently: "{target.narration}").
+Keep roughly the same duration ({target.duration_sec}s of speech).
+
+Return JSON only:
+{{"narration": "...", "visual_query": "3-5 words", "sfx_query": null, "duration_sec": {target.duration_sec}}}"""
+    raw = llm.complete_json(prompt)
+    target.narration = (raw.get("narration") or target.narration).strip()
+    target.visual_query = (raw.get("visual_query") or target.visual_query).strip()
+    target.sfx_query = raw.get("sfx_query") or None
+    try:
+        target.duration_sec = float(raw.get("duration_sec") or target.duration_sec)
+    except (TypeError, ValueError):
+        pass
+    return script
+
+
+def _parse_script(raw: dict, topic: str) -> Script:
+    scenes = []
+    for i, s in enumerate(raw.get("scenes", [])[:MAX_SCENES], 1):
+        narration = (s.get("narration") or "").strip()
+        if not narration:
+            continue
+        try:
+            duration = float(s.get("duration_sec") or 5.0)
+        except (TypeError, ValueError):
+            duration = 5.0
+        scenes.append(
+            Scene(
+                scene=int(s.get("scene") or i),
+                narration=narration,
+                visual_query=(s.get("visual_query") or topic).strip(),
+                sfx_query=(s.get("sfx_query") or None),
+                duration_sec=duration,
+            )
+        )
+    if not scenes:
+        raise RuntimeError("LLM script had no usable scenes")
+
+    hooks = [h.strip() for h in raw.get("hook_options", []) if isinstance(h, str) and h.strip()]
+    while len(hooks) < 3:  # contract promises 3 options
+        hooks.append(hooks[0] if hooks else f"You won't believe this about {topic}")
+    hooks = hooks[:3]
+
+    total = sum(s.duration_sec for s in scenes)
+    if not (MIN_TOTAL_SEC * 0.5 <= total <= MAX_TOTAL_SEC * 1.5):
+        log.warning("Script total %ss is far from the %s-%ss target", total, MIN_TOTAL_SEC, MAX_TOTAL_SEC)
+
+    return Script(
+        title=(raw.get("title") or topic).strip(),
+        hook_options=hooks,
+        selected_hook=0,
+        scenes=scenes,
+        cta=(raw.get("cta") or "").strip(),
+        total_duration_sec=total,
+        topic=topic,
+    )

core/stages/setup.py

@@ -0,0 +1,146 @@
+"""Stage 1 — project setup: build/validate Project objects and suggest
+reference channels for a niche.
+
+Pure functions over contracts; persistence happens in the orchestrator.
+"""
+
+from __future__ import annotations
+
+from core.adapters.base import LLMAdapter, ReferenceDataAdapter
+from core.contracts import FORMATS, NicheProfile, Project, ReferenceEntry
+from core.utils import log
+
+
+def build_project(
+    name: str,
+    niche: NicheProfile,
+    format: str = "youtube_short",
+    references: list[ReferenceEntry] | None = None,
+) -> Project:
+    """Validate inputs and construct a Project (id assigned on save)."""
+    if format not in FORMATS:
+        raise ValueError(f"format must be one of {FORMATS}, got {format!r}")
+    if format == "long_form":
+        raise ValueError("long_form is a future format and not yet supported")
+    if not niche.topic.strip():
+        raise ValueError("Niche topic is required")
+    for ref in references or []:
+        validate_reference(ref)
+    return Project(id="", name=name.strip() or niche.topic, niche=niche, format=format,
+                   references=list(references or []))
+
+
+def validate_reference(ref: ReferenceEntry) -> None:
+    if ref.kind not in ("youtube", "instagram_style"):
+        raise ValueError(f"Unknown reference kind {ref.kind!r}")
+    if ref.kind == "instagram_style" and not (ref.url or ref.notes):
+        raise ValueError("instagram_style references need a URL or style notes")
+
+
+def suggest_niche_fields(llm: LLMAdapter, topic: str) -> dict:
+    """From a bare niche topic, propose the rest of the setup fields.
+
+    Returns a dict with name/keywords/subreddits/audience/tone. Fails soft:
+    on any LLM error returns an empty dict so the UI can degrade gracefully.
+    The caller decides which fields to actually apply (e.g. only empty ones).
+    """
+    topic = topic.strip()
+    if not topic:
+        return {}
+    prompt = f"""A creator is setting up short-form videos (YouTube Shorts / Reels)
+in this niche: "{topic}".
+
+Propose sensible defaults for the rest of their project setup. Subreddits must
+be REAL, active subreddits relevant to the niche (no "r/" prefix, no guesses at
+dead subs). Keep keywords concrete and searchable.
+
+Return JSON only:
+{{"name": "a short catchy project name",
+  "keywords": ["5-7 search keywords"],
+  "subreddits": ["3-5 real subreddit names"],
+  "audience": "one phrase describing the target viewer",
+  "tone": "2-4 words describing the voice/tone"}}"""
+    try:
+        raw = llm.complete_json(prompt)
+    except Exception as e:
+        log.warning("Niche autofill failed: %s", e)
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        "name": (raw.get("name") or "").strip(),
+        "keywords": [str(k).strip() for k in (raw.get("keywords") or []) if str(k).strip()],
+        "subreddits": [
+            str(s).strip().lstrip("r/").strip("/")
+            for s in (raw.get("subreddits") or [])
+            if str(s).strip()
+        ],
+        "audience": (raw.get("audience") or "").strip(),
+        "tone": (raw.get("tone") or "").strip(),
+    }
+
+
+def build_suggest_channels_prompt(niche: NicheProfile, n: int = 5) -> str:
+    """The default prompt for channel suggestion (exposed for QC/editing)."""
+    return f"""Suggest {n + 3} popular YouTube channels that post SHORT-FORM
+(YouTube Shorts) content in this niche. Prefer channels known for high-view
+Shorts, not just long-form.
+
+Niche: {niche.topic}
+Keywords: {", ".join(niche.keywords) or "-"}
+Audience: {niche.audience or "-"}
+
+Return JSON only: [{{"name": "...", "handle": "@..."}}] — handle may be ""
+if unknown."""
+
+
+def suggest_channels(
+    llm: LLMAdapter,
+    refdata: ReferenceDataAdapter | None,
+    niche: NicheProfile,
+    n: int = 5,
+    prompt: str | None = None,
+) -> list[ReferenceEntry]:
+    """LLM proposes channel names for the niche; each is verified via the
+    YouTube API and unverifiable ones are dropped. Without a refdata
+    adapter (no YOUTUBE_API_KEY) returns unverified suggestions, marked so.
+
+    ``prompt`` overrides the default assembled prompt (for QC editing).
+    """
+    prompt = prompt or build_suggest_channels_prompt(niche, n)
+    try:
+        raw = llm.complete_json(prompt)
+    except Exception as e:
+        log.warning("Channel suggestion LLM call failed: %s", e)
+        return []
+
+    suggestions = raw if isinstance(raw, list) else raw.get("channels", [])
+    out: list[ReferenceEntry] = []
+    for item in suggestions:
+        if len(out) >= n:
+            break
+        name = (item.get("name") or "").strip()
+        handle = (item.get("handle") or "").strip()
+        if not name:
+            continue
+        if refdata is None:
+            out.append(ReferenceEntry(kind="youtube", name=name,
+                                      notes="unverified (no YOUTUBE_API_KEY)"))
+            continue
+        try:
+            resolved = refdata.resolve_channel(handle or name)
+        except Exception as e:
+            log.warning("Verification failed for %r: %s — dropping", name, e)
+            continue
+        if not resolved:
+            log.info("Dropping unverifiable suggested channel %r", name)
+            continue
+        out.append(
+            ReferenceEntry(
+                kind="youtube",
+                name=resolved["title"],
+                url=resolved["url"],
+                channel_id=resolved["channel_id"],
+            )
+        )
+    return out

core/stages/style.py

@@ -0,0 +1,158 @@
+"""Stage 2 — style profile builder.
+
+Pulls transcripts of each YouTube reference's top recent Shorts, distills a
+style card with the LLM, and keeps 2-3 full transcripts as few-shot
+exemplars. Instagram references contribute only their user-written notes.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from core.adapters.base import LLMAdapter, ReferenceDataAdapter, TranscriptAdapter
+from core.contracts import Project, StyleProfile
+from core.utils import log
+
+Progress = Callable[[str], None]
+
+_MAX_TRANSCRIPTS_PER_CHANNEL = 3
+_MAX_EXEMPLARS = 3
+_EXEMPLAR_CHAR_LIMIT = 4000
+
+
+def build_style_profile(
+    project: Project,
+    llm: LLMAdapter,
+    refdata: Optional[ReferenceDataAdapter],
+    transcripts: Optional[TranscriptAdapter],
+    progress: Progress = lambda m: None,
+) -> StyleProfile:
+    """Distill the writing style of the project's references (collect + assemble).
+
+    Every external call fails soft: with no YouTube key or no transcripts
+    the profile is built from whatever is available (worst case: niche
+    fields + Instagram notes only).
+    """
+    collected, ig_notes, sources = collect_style_inputs(project, refdata, transcripts, progress)
+    return assemble_style_profile(llm, project, collected, ig_notes, sources, progress=progress)
+
+
+def collect_style_inputs(
+    project: Project,
+    refdata: Optional[ReferenceDataAdapter],
+    transcripts: Optional[TranscriptAdapter],
+    progress: Progress = lambda m: None,
+) -> tuple[list[tuple[str, str]], list[str], list[str]]:
+    """Fetch transcripts + Instagram notes — the slow part, run once per refresh.
+
+    Returns (collected [(label, transcript)], instagram_notes, sources).
+    """
+    collected: list[tuple[str, str]] = []
+    sources: list[str] = []
+    ig_notes: list[str] = []
+
+    for ref in project.references:
+        if ref.kind == "instagram_style":
+            note = f"{ref.name}: {ref.notes}".strip(": ")
+            if note:
+                ig_notes.append(note)
+                sources.append(f"instagram_style:{ref.name} (notes only, never fetched)")
+            continue
+        if refdata is None or transcripts is None:
+            log.info("Skipping transcript pull for %s (missing YouTube/transcript adapter)", ref.name)
+            continue
+        try:
+            channel_id = ref.channel_id
+            if not channel_id:
+                resolved = refdata.resolve_channel(ref.url or ref.name)
+                if not resolved:
+                    log.warning("Could not resolve reference channel %r — skipping", ref.name)
+                    continue
+                channel_id = resolved["channel_id"]
+                ref.channel_id = channel_id
+            progress(f"Fetching top Shorts of {ref.name}")
+            shorts = refdata.top_shorts(channel_id, n=_MAX_TRANSCRIPTS_PER_CHANNEL + 2)
+        except Exception as e:
+            log.warning("Reference data failed for %s: %s — skipping channel", ref.name, e)
+            continue
+
+        got = 0
+        for short in shorts:
+            if got >= _MAX_TRANSCRIPTS_PER_CHANNEL:
+                break
+            text = transcripts.fetch(short["video_id"])
+            if not text or len(text) < 100:
+                continue
+            collected.append((f'{ref.name} — "{short["title"]}" ({short["views"]:,} views)', text))
+            sources.append(f'youtube:{ref.name}:{short["video_id"]}')
+            got += 1
+        if got:
+            progress(f"Got {got} transcript(s) from {ref.name}")
+
+    return collected, ig_notes, sources
+
+
+def build_style_prompt(
+    project: Project,
+    collected: list[tuple[str, str]],
+    ig_notes: list[str],
+) -> str:
+    """The default style-card distillation prompt (exposed for QC/editing)."""
+    transcript_block = "\n\n".join(
+        f"--- {label} ---\n{text[:2500]}" for label, text in collected[:6]
+    )
+    ig_block = "\n".join(f"- {n}" for n in ig_notes)
+    return f"""You are analyzing the style of successful short-form video channels.
+
+Niche: {project.niche.topic} (audience: {project.niche.audience or "general"};
+tone: {project.niche.tone or "unspecified"})
+
+{"TRANSCRIPTS OF TOP SHORTS:" + chr(10) + transcript_block if transcript_block else "No transcripts available — infer a strong default style for the niche."}
+
+{"INSTAGRAM STYLE NOTES (user-written):" + chr(10) + ig_block if ig_block else ""}
+
+Write a STYLE CARD (max ~250 words) covering:
+- Hook patterns (how the first 2 seconds grab attention)
+- Pacing and sentence length
+- Vocabulary level and signature phrases
+- How facts/claims are delivered
+- CTA style
+
+Plain text, bullet form. This card will steer a scriptwriter."""
+
+
+def assemble_style_profile(
+    llm: LLMAdapter,
+    project: Project,
+    collected: list[tuple[str, str]],
+    ig_notes: list[str],
+    sources: list[str],
+    prompt: Optional[str] = None,
+    progress: Progress = lambda m: None,
+) -> StyleProfile:
+    """Run the distillation LLM call and build the StyleProfile.
+
+    ``prompt`` overrides the default assembled prompt (for QC editing); the
+    exemplars are taken from ``collected`` either way.
+    """
+    used_prompt = prompt or build_style_prompt(project, collected, ig_notes)
+    progress("Distilling style card")
+    try:
+        style_card = llm.complete(used_prompt).strip()
+    except Exception as e:
+        log.warning("Style card distillation failed: %s — using minimal default", e)
+        style_card = (
+            "Default style: punchy hook in the first sentence, short conversational "
+            "sentences, one concrete fact per scene, end with a question CTA."
+        )
+    exemplars = [
+        f"[{label}]\n{text[:_EXEMPLAR_CHAR_LIMIT]}"
+        for label, text in collected[:_MAX_EXEMPLARS]
+    ]
+    return StyleProfile(
+        style_card=style_card,
+        exemplars=exemplars,
+        instagram_notes=ig_notes,
+        sources=sources,
+        prompt_used=used_prompt,
+    )

core/stages/topics.py

@@ -0,0 +1,213 @@
+"""Stage 3 — topic generation.
+
+Blends three signal sources, all fail-soft:
+  (a) titles + stats of the reference channels' top recent Shorts,
+  (b) Google News RSS for the niche keywords,
+  (c) Reddit top-of-day from the niche subreddits (JSON, RSS fallback).
+The LLM ranks them into N topics, each with a one-line reason and a
+popularity-signal note.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from typing import Callable, Optional
+
+import requests
+
+from core.adapters.base import LLMAdapter, ReferenceDataAdapter
+from core.contracts import Project, Topic, TopicBatch
+from core.utils import log
+
+Progress = Callable[[str], None]
+
+_UA = {"User-Agent": "ReelStudio/2.0 (local short-form video research tool)"}
+
+# v1-proven filter: drop megathreads / mod housekeeping / daily threads.
+_REDDIT_NOISE = re.compile(
+    r"megathread|daily (thread|discussion)|weekly (thread|discussion)|"
+    r"open thread|mod ?post|announcement|rules|read first|faq",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Signal collectors (each returns a list of human-readable signal lines)
+# ---------------------------------------------------------------------------
+
+
+def _reference_signals(project: Project, refdata: Optional[ReferenceDataAdapter]) -> list[str]:
+    if refdata is None:
+        return []
+    lines = []
+    for ref in project.references:
+        if ref.kind != "youtube" or not ref.channel_id:
+            continue
+        try:
+            for s in refdata.top_shorts(ref.channel_id, n=5):
+                lines.append(
+                    f'[reference short] {ref.name}: "{s["title"]}" — {s["views"]:,} views'
+                )
+        except Exception as e:
+            log.warning("Reference signals failed for %s: %s", ref.name, e)
+    return lines
+
+
+def _news_signals(project: Project) -> list[str]:
+    """Google News RSS for the niche keywords."""
+    query = " OR ".join([project.niche.topic, *project.niche.keywords[:3]])
+    url = "https://news.google.com/rss/search"
+    try:
+        resp = requests.get(url, params={"q": query, "hl": "en-US"}, headers=_UA, timeout=20)
+        resp.raise_for_status()
+        root = ET.fromstring(resp.content)
+        titles = [item.findtext("title") or "" for item in root.iter("item")]
+        return [f"[news] {t}" for t in titles[:12] if t]
+    except Exception as e:
+        log.warning("Google News RSS failed: %s — continuing without news", e)
+        return []
+
+
+def _reddit_signals(project: Project) -> list[str]:
+    lines: list[str] = []
+    for sub in project.niche.subreddits[:4]:
+        sub = sub.lstrip("r/").strip("/")
+        if not sub:
+            continue
+        posts = _reddit_json(sub)
+        if posts is None:
+            posts = _reddit_rss(sub)
+        for title, score in (posts or [])[:8]:
+            if _REDDIT_NOISE.search(title):
+                continue
+            score_txt = f" ({score:,} upvotes)" if score else ""
+            lines.append(f"[r/{sub}] {title}{score_txt}")
+    return lines
+
+
+def _reddit_json(sub: str) -> Optional[list[tuple[str, int]]]:
+    try:
+        resp = requests.get(
+            f"https://www.reddit.com/r/{sub}/top.json",
+            params={"t": "day", "limit": 15},
+            headers=_UA,
+            timeout=20,
+        )
+        resp.raise_for_status()
+        out = []
+        for child in resp.json().get("data", {}).get("children", []):
+            d = child.get("data", {})
+            if d.get("stickied") or d.get("distinguished"):
+                continue
+            out.append((d.get("title", ""), int(d.get("ups", 0))))
+        return out
+    except Exception as e:
+        log.info("Reddit JSON failed for r/%s (%s) — trying RSS", sub, e)
+        return None
+
+
+def _reddit_rss(sub: str) -> Optional[list[tuple[str, int]]]:
+    try:
+        resp = requests.get(f"https://www.reddit.com/r/{sub}/top/.rss?t=day", headers=_UA, timeout=20)
+        resp.raise_for_status()
+        root = ET.fromstring(resp.content)
+        ns = {"atom": "http://www.w3.org/2005/Atom"}
+        return [(e.findtext("atom:title", "", ns), 0) for e in root.findall("atom:entry", ns)]
+    except Exception as e:
+        log.warning("Reddit RSS failed for r/%s: %s — skipping subreddit", sub, e)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Ranking
+# ---------------------------------------------------------------------------
+
+
+def collect_topic_signals(
+    project: Project,
+    refdata: Optional[ReferenceDataAdapter],
+    progress: Progress = lambda m: None,
+) -> list[str]:
+    """Gather reference / news / Reddit signal lines — the slow part."""
+    progress("Collecting reference channel signals")
+    signals = _reference_signals(project, refdata)
+    progress("Collecting news signals")
+    signals += _news_signals(project)
+    progress("Collecting Reddit signals")
+    signals += _reddit_signals(project)
+    if not signals:
+        log.info("No external signals available — LLM will rely on the niche profile alone")
+    return signals
+
+
+def build_topics_prompt(project: Project, signals: list[str], n: int = 8) -> str:
+    """The default topic-ranking prompt (exposed for QC/editing)."""
+    signal_block = "\n".join(signals[:60]) or "(no external signals available)"
+    return f"""You pick topics for short-form videos (YouTube Shorts / Reels).
+
+NICHE: {project.niche.topic}
+Keywords: {", ".join(project.niche.keywords) or "-"}
+Audience: {project.niche.audience or "general"}
+Tone: {project.niche.tone or "engaging"}
+
+LIVE SIGNALS (reference channels' top Shorts, news, Reddit):
+{signal_block}
+
+Propose exactly {n} video topics ranked best-first. Favor topics supported
+by multiple signals; avoid duplicating a reference Short's exact angle.
+Each topic must work as a 30-45 second vertical video.
+
+Return JSON only:
+[{{"title": "...", "reason": "one line on why now",
+   "signals": ["one supporting source per item", "..."]}}]"""
+
+
+def _coerce_signals(it: dict) -> list[str]:
+    """Read the signals list, tolerating the older single-string field."""
+    sig = it.get("signals")
+    if isinstance(sig, list):
+        return [str(s).strip() for s in sig if str(s).strip()]
+    if isinstance(sig, str) and sig.strip():
+        return [sig.strip()]
+    legacy = it.get("popularity_signal")  # pre-list format
+    if isinstance(legacy, str) and legacy.strip():
+        return [legacy.strip()]
+    return []
+
+
+def _parse_topics(raw, n: int) -> list[Topic]:
+    items = raw if isinstance(raw, list) else raw.get("topics", [])
+    return [
+        Topic(
+            title=(it.get("title") or "").strip(),
+            reason=(it.get("reason") or "").strip(),
+            signals=_coerce_signals(it),
+        )
+        for it in items
+        if (it.get("title") or "").strip()
+    ][:n]
+
+
+def generate_topics(
+    project: Project,
+    llm: LLMAdapter,
+    refdata: Optional[ReferenceDataAdapter],
+    n: int = 8,
+    progress: Progress = lambda m: None,
+    prompt: Optional[str] = None,
+) -> TopicBatch:
+    """Generate N ranked, editable topic candidates.
+
+    ``prompt`` overrides the default; when given we skip signal collection
+    (the user is re-running an edited prompt) and just rank.
+    """
+    if prompt is None:
+        signals = collect_topic_signals(project, refdata, progress)
+        prompt = build_topics_prompt(project, signals, n)
+    progress("Ranking topics with LLM")
+    raw = llm.complete_json(prompt)
+    topics = _parse_topics(raw, n)
+    if not topics:
+        raise RuntimeError("LLM returned no usable topics")
+    return TopicBatch(topics=topics, prompt_used=prompt)

core/stages/voice.py

@@ -0,0 +1,64 @@
+"""Stage 5 — voice synthesis.
+
+One audio file per narration line (hook, scenes, CTA). True durations come
+from ffprobe and drive ALL downstream timing (v1 lesson: never trust the
+script's estimated durations). Word timings come from the TTS provider when
+it emits them, else faster-whisper forced alignment, else None → the render
+stage falls back to static captions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from core.adapters.alignment import align_words
+from core.adapters.base import TTSAdapter
+from core.contracts import Script, VoiceLine, VoiceTrack
+from core.utils import ffprobe_duration, log
+
+Progress = Callable[[str], None]
+
+
+def synthesize_voice(
+    script: Script,
+    tts: TTSAdapter,
+    out_dir: str,
+    voice: str = "",
+    provider_name: str = "",
+    progress: Progress = lambda m: None,
+) -> VoiceTrack:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    lines = script.narration_lines()
+    if not lines:
+        raise ValueError("Script has no narration lines to voice")
+
+    voice_lines: list[VoiceLine] = []
+    for i, text in enumerate(lines):
+        progress(f"Voicing line {i + 1}/{len(lines)}")
+        path = str(out / f"line_{i:02d}.mp3")
+        timings = tts.synth(text, path, voice=voice)
+        if timings is None:
+            timings = align_words(path, text)  # soft fallback, may stay None
+            if timings:
+                log.info("Recovered %d word timings via forced alignment", len(timings))
+        duration = ffprobe_duration(path)
+        voice_lines.append(
+            VoiceLine(
+                index=i,
+                text=text,
+                audio_path=path,
+                duration_sec=duration,
+                word_timings=timings or [],
+            )
+        )
+
+    total = sum(line.duration_sec for line in voice_lines)
+    log.info("Voice track: %d lines, %.1fs total", len(voice_lines), total)
+    return VoiceTrack(
+        lines=voice_lines,
+        provider=provider_name,
+        voice=voice,
+        total_duration_sec=total,
+    )

core/store.py

@@ -0,0 +1,246 @@
+"""JSON-on-disk persistence for projects and their reels.
+
+Layout (everything under projects/<project_id>/):
+    project.json    — Project (niche, format, references)
+    style.json      — StyleProfile        (project-level, shared by all reels)
+    topics.json     — TopicBatch           (project-level topic pool)
+    reels/<reel_id>/
+        reel.json   — Reel metadata
+        script.json — Script
+        voice/      — line_<i>.mp3 + voice.json (VoiceTrack)
+        media/      — clips/ sfx/ + media.json (MediaManifest)
+        renders/    — variant mp4s + renders.json (RenderBatch)
+        clone.json  — CloneBrief (when the reel came from a clone)
+
+References + style profile + the topic pool are shared at the project level;
+each reel owns its own script/voice/media/renders so multiple topics can be
+worked on in parallel. Stage modules stay pure and never touch this layout
+themselves (audio/video files excepted, via paths the orchestrator hands them).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from core.contracts import (
+    CloneBrief,
+    MediaManifest,
+    Project,
+    Reel,
+    RenderBatch,
+    Script,
+    StyleProfile,
+    TopicBatch,
+    VoiceTrack,
+    from_dict,
+    to_dict,
+)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _split_legacy_signal(text: str) -> list[str]:
+    """Split an old single-string signal into sources on '),' boundaries.
+
+    Commas inside the parenthetical quotes (e.g. multiple quoted reactions)
+    are preserved; only the separators between sources split.
+    """
+    import re
+
+    parts = re.split(r"\)\s*,\s*", text)
+    out = []
+    for i, p in enumerate(parts):
+        p = (p + ")" if i < len(parts) - 1 else p).strip()
+        if p:
+            out.append(p)
+    return out
+
+
+class ProjectStore:
+    def __init__(self, projects_dir: Path):
+        self.root = Path(projects_dir)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    # -- paths ---------------------------------------------------------------
+
+    def dir(self, project_id: str) -> Path:
+        return self.root / project_id
+
+    def reels_dir(self, project_id: str) -> Path:
+        return self._ensure(self.dir(project_id) / "reels")
+
+    def reel_dir(self, project_id: str, reel_id: str) -> Path:
+        return self._ensure(self.reels_dir(project_id) / reel_id)
+
+    def voice_dir(self, project_id: str, reel_id: str) -> Path:
+        return self._ensure(self.reel_dir(project_id, reel_id) / "voice")
+
+    def media_dir(self, project_id: str, reel_id: str) -> Path:
+        return self._ensure(self.reel_dir(project_id, reel_id) / "media")
+
+    def renders_dir(self, project_id: str, reel_id: str) -> Path:
+        return self._ensure(self.reel_dir(project_id, reel_id) / "renders")
+
+    @staticmethod
+    def _ensure(p: Path) -> Path:
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    # -- generic json --------------------------------------------------------
+
+    def _save_path(self, path: Path, obj) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(to_dict(obj), indent=2, ensure_ascii=False))
+
+    def _load_path(self, path: Path, cls):
+        if not path.exists():
+            return None
+        return from_dict(cls, json.loads(path.read_text()))
+
+    def _save(self, project_id: str, name: str, obj) -> None:
+        self._save_path(self.dir(project_id) / name, obj)
+
+    def _load(self, project_id: str, name: str, cls):
+        return self._load_path(self.dir(project_id) / name, cls)
+
+    def save_json(self, project_id: str, name: str, data) -> None:
+        """Persist a plain dict/list (used for transient prep caches)."""
+        path = self.dir(project_id) / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2, ensure_ascii=False))
+
+    def load_json(self, project_id: str, name: str):
+        path = self.dir(project_id) / name
+        return json.loads(path.read_text()) if path.exists() else None
+
+    # -- projects ------------------------------------------------------------
+
+    def create_project(self, project: Project) -> Project:
+        if not project.id:
+            project.id = uuid.uuid4().hex[:12]
+        if not project.created_at:
+            project.created_at = now_iso()
+        self.save_project(project)
+        return project
+
+    def save_project(self, project: Project) -> None:
+        self._save(project.id, "project.json", project)
+
+    def load_project(self, project_id: str) -> Optional[Project]:
+        return self._load(project_id, "project.json", Project)  # type: ignore[return-value]
+
+    def list_projects(self) -> list[Project]:
+        out = []
+        for d in sorted(self.root.iterdir()):
+            if d.is_dir() and (d / "project.json").exists():
+                p = self.load_project(d.name)
+                if p:
+                    out.append(p)
+        return out
+
+    def delete_project(self, project_id: str) -> None:
+        d = self.dir(project_id)
+        if d.exists():
+            shutil.rmtree(d)
+
+    # -- reels ---------------------------------------------------------------
+
+    def create_reel(self, project_id: str, name: str = "", topic: str = "") -> Reel:
+        reel = Reel(
+            id=uuid.uuid4().hex[:12],
+            name=name or topic or "Untitled reel",
+            topic=topic,
+            created_at=now_iso(),
+        )
+        self.save_reel(project_id, reel)
+        return reel
+
+    def save_reel(self, project_id: str, reel: Reel) -> None:
+        self._save_path(self.reel_dir(project_id, reel.id) / "reel.json", reel)
+
+    def load_reel(self, project_id: str, reel_id: str) -> Optional[Reel]:
+        return self._load_path(self.reel_dir(project_id, reel_id) / "reel.json", Reel)
+
+    def list_reels(self, project_id: str) -> list[Reel]:
+        rd = self.dir(project_id) / "reels"
+        if not rd.exists():
+            return []
+        out = []
+        for d in sorted(rd.iterdir(), key=lambda p: p.name):
+            reel = self._load_path(d / "reel.json", Reel)
+            if reel:
+                out.append(reel)
+        out.sort(key=lambda r: r.created_at)
+        return out
+
+    def delete_reel(self, project_id: str, reel_id: str) -> None:
+        d = self.reel_dir(project_id, reel_id)
+        if d.exists():
+            shutil.rmtree(d)
+
+    # -- project-level artifacts (shared) ------------------------------------
+
+    def save_style(self, pid: str, s: StyleProfile) -> None:
+        self._save(pid, "style.json", s)
+
+    def load_style(self, pid: str) -> Optional[StyleProfile]:
+        return self._load(pid, "style.json", StyleProfile)  # type: ignore[return-value]
+
+    def save_topics(self, pid: str, t: TopicBatch) -> None:
+        self._save(pid, "topics.json", t)
+
+    def load_topics(self, pid: str) -> Optional[TopicBatch]:
+        raw = self.load_json(pid, "topics.json")
+        if raw is None:
+            return None
+        # Normalize signals: migrate the pre-list field, and split any entry
+        # that still holds a combined "Source (...), Source (...)" string.
+        for t in raw.get("topics", []):
+            sigs = t.get("signals")
+            if not sigs and t.get("popularity_signal"):
+                sigs = [t["popularity_signal"]]
+            if sigs:
+                t["signals"] = [part for s in sigs for part in _split_legacy_signal(str(s))]
+        return from_dict(TopicBatch, raw)
+
+    # -- reel-level artifacts ------------------------------------------------
+
+    def save_script(self, pid: str, rid: str, s: Script) -> None:
+        self._save_path(self.reel_dir(pid, rid) / "script.json", s)
+
+    def load_script(self, pid: str, rid: str) -> Optional[Script]:
+        return self._load_path(self.reel_dir(pid, rid) / "script.json", Script)
+
+    def save_voice(self, pid: str, rid: str, v: VoiceTrack) -> None:
+        self.voice_dir(pid, rid)
+        self._save_path(self.reel_dir(pid, rid) / "voice" / "voice.json", v)
+
+    def load_voice(self, pid: str, rid: str) -> Optional[VoiceTrack]:
+        return self._load_path(self.reel_dir(pid, rid) / "voice" / "voice.json", VoiceTrack)
+
+    def save_media(self, pid: str, rid: str, m: MediaManifest) -> None:
+        self.media_dir(pid, rid)
+        self._save_path(self.reel_dir(pid, rid) / "media" / "media.json", m)
+
+    def load_media(self, pid: str, rid: str) -> Optional[MediaManifest]:
+        return self._load_path(self.reel_dir(pid, rid) / "media" / "media.json", MediaManifest)
+
+    def save_renders(self, pid: str, rid: str, r: RenderBatch) -> None:
+        self.renders_dir(pid, rid)
+        self._save_path(self.reel_dir(pid, rid) / "renders" / "renders.json", r)
+
+    def load_renders(self, pid: str, rid: str) -> Optional[RenderBatch]:
+        return self._load_path(self.reel_dir(pid, rid) / "renders" / "renders.json", RenderBatch)
+
+    def save_clone(self, pid: str, rid: str, c: CloneBrief) -> None:
+        self._save_path(self.reel_dir(pid, rid) / "clone.json", c)
+
+    def load_clone(self, pid: str, rid: str) -> Optional[CloneBrief]:
+        return self._load_path(self.reel_dir(pid, rid) / "clone.json", CloneBrief)

core/utils.py

@@ -0,0 +1,115 @@
+"""Small shared utilities: logging, JSON extraction, retries, ffprobe."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+import time
+from typing import Any, Callable, Optional
+
+log = logging.getLogger("reelstudio")
+if not log.handlers:
+    _h = logging.StreamHandler()
+    _h.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    log.addHandler(_h)
+    log.setLevel(logging.INFO)
+
+
+# ---------------------------------------------------------------------------
+# JSON extraction (LLMs love markdown fences)
+# ---------------------------------------------------------------------------
+
+_FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)```", re.DOTALL)
+
+
+def extract_json(text: str) -> Any:
+    """Parse JSON out of an LLM response, stripping markdown fences.
+
+    Tries, in order: fenced block, the raw text, and the largest
+    {...} / [...] slice. Raises ValueError if nothing parses.
+    """
+    candidates = []
+    m = _FENCE_RE.search(text)
+    if m:
+        candidates.append(m.group(1))
+    candidates.append(text.strip())
+    for opener, closer in (("{", "}"), ("[", "]")):
+        start, end = text.find(opener), text.rfind(closer)
+        if start != -1 and end > start:
+            candidates.append(text[start : end + 1])
+    for c in candidates:
+        try:
+            return json.loads(c)
+        except (json.JSONDecodeError, TypeError):
+            continue
+    raise ValueError(f"No parseable JSON in LLM response: {text[:200]!r}")
+
+
+# ---------------------------------------------------------------------------
+# Retry with exponential backoff
+# ---------------------------------------------------------------------------
+
+
+class HardAPIError(Exception):
+    """Non-retryable API failure (400/401/403/404 class)."""
+
+
+def retry_backoff(
+    fn: Callable[[], Any],
+    attempts: int = 4,
+    base_delay: float = 2.0,
+    retry_on: tuple = (Exception,),
+    label: str = "call",
+) -> Any:
+    """Run ``fn`` with exponential backoff. HardAPIError is never retried."""
+    last: Optional[Exception] = None
+    for i in range(attempts):
+        try:
+            return fn()
+        except HardAPIError:
+            raise
+        except retry_on as e:  # noqa: PERF203
+            last = e
+            delay = base_delay * (2**i)
+            log.warning("%s failed (attempt %d/%d): %s — retrying in %.1fs", label, i + 1, attempts, e, delay)
+            if i < attempts - 1:
+                time.sleep(delay)
+    raise last  # type: ignore[misc]
+
+
+# ---------------------------------------------------------------------------
+# FFmpeg helpers
+# ---------------------------------------------------------------------------
+
+
+def run_ffmpeg(args: list[str], label: str = "ffmpeg") -> None:
+    """Run an ffmpeg command, raising with stderr tail on failure."""
+    cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", *args]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        tail = (proc.stderr or "")[-2000:]
+        raise RuntimeError(f"{label} failed (exit {proc.returncode}): {tail}")
+
+
+def ffprobe_duration(path: str) -> float:
+    """True media duration in seconds via ffprobe."""
+    proc = subprocess.run(
+        [
+            "ffprobe", "-v", "error",
+            "-show_entries", "format=duration",
+            "-of", "default=noprint_wrappers=1:nokey=1",
+            path,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"ffprobe failed for {path}: {proc.stderr[-500:]}")
+    return float(proc.stdout.strip())
+
+
+def slugify(text: str, max_len: int = 40) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return s[:max_len] or "untitled"

requirements.txt

@@ -0,0 +1,21 @@
+# Core
+fastapi>=0.115
+uvicorn[standard]>=0.30
+python-dotenv>=1.0
+requests>=2.32
+Pillow>=10.4
+
+# TTS (free default)
+edge-tts>=6.1
+
+# Reference data / transcripts
+youtube-transcript-api>=0.6.2
+yt-dlp>=2024.8.6
+
+# Word-timing alignment for karaoke captions. Needed by the default Gemini
+# voice (which has no native timings) and as the transcript fallback when a
+# YouTube video has no captions. First use downloads a small (~75MB) model.
+faster-whisper>=1.0
+
+# Tests
+pytest>=8.0

server/app.py

@@ -0,0 +1,551 @@
+"""FastAPI server for Reel Studio v2.
+
+Thin HTTP layer over core.pipeline. Long operations run as background jobs:
+the POST returns {job_id} and the frontend polls GET /api/jobs/{id}.
+
+Structure mirrors the data model:
+- Project-level (shared): references, style profile, topic pool.
+- Reel-level (per video): script, voice, media, renders, clone.
+
+Every generative step has a `/prompt` endpoint returning the exact assembled
+prompt (for QC/editing) and accepts an optional ``prompt`` override on run.
+
+Run:  .venv/bin/uvicorn server.app:app --port 8000
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from core.contracts import (
+    CAPTION_PRESETS,
+    DEFAULT_VARIANTS,
+    NicheProfile,
+    ReferenceEntry,
+    Script,
+    StyleProfile,
+    Topic,
+    TopicBatch,
+    VariantSpec,
+    from_dict,
+    to_dict,
+)
+from core.pipeline import Pipeline
+from core.stages.clone import CloneError
+from server.jobs import JobManager
+
+app = FastAPI(title="Reel Studio v2")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://127.0.0.1:5173",
+                   "http://localhost:5174", "http://127.0.0.1:5174"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+pipeline = Pipeline()
+jobs = JobManager()
+
+app.mount("/files", StaticFiles(directory=str(pipeline.store.root)), name="files")
+
+
+def _url(path: str) -> str:
+    if not path:
+        return ""
+    try:
+        rel = Path(path).resolve().relative_to(pipeline.store.root.resolve())
+    except ValueError:
+        return ""
+    return f"/files/{rel.as_posix()}"
+
+
+def _project_or_404(project_id: str):
+    project = pipeline.store.load_project(project_id)
+    if not project:
+        raise HTTPException(404, f"No project {project_id}")
+    return project
+
+
+def _reel_or_404(project_id: str, reel_id: str):
+    reel = pipeline.store.load_reel(project_id, reel_id)
+    if not reel:
+        raise HTTPException(404, f"No reel {reel_id}")
+    return reel
+
+
+# ---------------------------------------------------------------------------
+# Request models
+# ---------------------------------------------------------------------------
+
+
+class NicheIn(BaseModel):
+    topic: str
+    keywords: list[str] = []
+    subreddits: list[str] = []
+    audience: str = ""
+    tone: str = ""
+
+
+class ReferenceIn(BaseModel):
+    kind: str
+    name: str
+    url: str = ""
+    channel_id: str = ""
+    notes: str = ""
+
+
+class ProjectIn(BaseModel):
+    name: str
+    niche: NicheIn
+    format: str = "youtube_short"
+    references: list[ReferenceIn] = []
+
+
+class NicheSuggestIn(BaseModel):
+    topic: str
+
+
+class SuggestIn(BaseModel):
+    n: int = 5
+    prompt: Optional[str] = None
+
+
+class StyleIn(BaseModel):
+    prompt: Optional[str] = None
+
+
+class TopicsIn(BaseModel):
+    n: int = 8
+    prompt: Optional[str] = None
+
+
+class TopicEditIn(BaseModel):
+    topics: list[dict]
+
+
+class ReelIn(BaseModel):
+    name: str = ""
+    topic: str = ""
+
+
+class ScriptGenIn(BaseModel):
+    topic: str
+    prompt: Optional[str] = None
+
+
+class ScriptPromptIn(BaseModel):
+    topic: str
+
+
+class SceneRegenIn(BaseModel):
+    scene: int
+
+
+class VoiceIn(BaseModel):
+    voice: str = ""
+    provider: Optional[str] = None
+
+
+class SwapIn(BaseModel):
+    line_index: int
+
+
+class RenderIn(BaseModel):
+    variants: Optional[list[dict]] = None
+
+
+class CloneIn(BaseModel):
+    url: str
+
+
+# ---------------------------------------------------------------------------
+# Meta
+# ---------------------------------------------------------------------------
+
+
+@app.get("/api/health")
+def health():
+    cfg = pipeline.config
+    return {
+        "ok": True,
+        "keys": {
+            "gemini": bool(cfg.gemini_api_key),
+            "gemini_key_count": len(cfg.gemini_api_keys),
+            "pexels": bool(cfg.pexels_api_key),
+            "youtube": bool(cfg.youtube_api_key),
+            "freesound": bool(cfg.freesound_api_key),
+            "elevenlabs": bool(cfg.elevenlabs_api_key),
+        },
+        "adapters": {"llm": cfg.llm_adapter, "tts": cfg.tts_adapter, "stock": cfg.stock_adapter},
+        "tts_providers": pipeline.available_tts_providers(),
+        "caption_presets": list(CAPTION_PRESETS),
+    }
+
+
+@app.get("/api/jobs/{job_id}")
+def get_job(job_id: str):
+    job = jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "No such job")
+    return job.to_dict()
+
+
+@app.get("/api/voices")
+def voices(provider: Optional[str] = None):
+    try:
+        used, names = pipeline.voices(provider)
+        return {"provider": used, "voices": names, "providers": pipeline.available_tts_providers()}
+    except Exception as e:
+        raise HTTPException(503, f"TTS adapter unavailable: {e}")
+
+
+class VoiceSampleIn(BaseModel):
+    provider: Optional[str] = None
+    voice: str = ""
+
+
+@app.post("/api/voices/sample")
+def voice_sample(body: VoiceSampleIn):
+    """Synthesize (and cache) a short preview clip for a provider+voice."""
+    try:
+        path = pipeline.voice_sample(body.provider, body.voice)
+        return {"url": _url(path)}
+    except Exception as e:
+        raise HTTPException(503, f"Could not generate sample: {e}")
+
+
+@app.post("/api/niche/suggest")
+def suggest_niche(body: NicheSuggestIn):
+    if not body.topic.strip():
+        raise HTTPException(400, "A niche topic is required")
+    try:
+        return pipeline.suggest_niche_fields(body.topic)
+    except Exception as e:
+        raise HTTPException(503, f"Autofill unavailable: {e}")
+
+
+# ---------------------------------------------------------------------------
+# Projects
+# ---------------------------------------------------------------------------
+
+
+@app.get("/api/projects")
+def list_projects():
+    return [to_dict(p) for p in pipeline.store.list_projects()]
+
+
+@app.post("/api/projects")
+def create_project(body: ProjectIn):
+    try:
+        project = pipeline.create_project(
+            body.name, NicheProfile(**body.niche.model_dump()), body.format,
+            [ReferenceEntry(**r.model_dump()) for r in body.references],
+        )
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+    return to_dict(project)
+
+
+@app.get("/api/projects/{project_id}")
+def get_project(project_id: str):
+    """Project-level data + the list of reels (metadata only)."""
+    project = _project_or_404(project_id)
+    return {
+        "project": to_dict(project),
+        "style": to_dict(pipeline.store.load_style(project_id)),
+        "topics": to_dict(pipeline.store.load_topics(project_id)),
+        "reels": [to_dict(r) for r in pipeline.store.list_reels(project_id)],
+    }
+
+
+@app.patch("/api/projects/{project_id}")
+def update_project(project_id: str, body: ProjectIn):
+    project = _project_or_404(project_id)
+    project.name = body.name or project.name
+    project.niche = NicheProfile(**body.niche.model_dump())
+    project.format = body.format
+    project.references = [ReferenceEntry(**r.model_dump()) for r in body.references]
+    pipeline.store.save_project(project)
+    return to_dict(project)
+
+
+@app.delete("/api/projects/{project_id}")
+def delete_project(project_id: str):
+    _project_or_404(project_id)
+    pipeline.store.delete_project(project_id)
+    return {"ok": True}
+
+
+# ---------------------------------------------------------------------------
+# References / style (project-level)
+# ---------------------------------------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/references/suggest/prompt")
+def suggest_prompt(project_id: str, body: SuggestIn):
+    project = _project_or_404(project_id)
+    return {"prompt": pipeline.prepare_suggest_prompt(project, n=body.n)}
+
+
+@app.post("/api/projects/{project_id}/references/suggest")
+def suggest_references(project_id: str, body: SuggestIn):
+    project = _project_or_404(project_id)
+    job = jobs.submit("suggest", lambda progress: [
+        to_dict(r) for r in pipeline.suggest_references(project, n=body.n, prompt=body.prompt)
+    ])
+    return {"job_id": job.id}
+
+
+@app.post("/api/projects/{project_id}/style/prompt")
+def style_prompt(project_id: str):
+    project = _project_or_404(project_id)
+    job = jobs.submit("style-prompt", lambda progress: {"prompt": pipeline.prepare_style_prompt(project, progress)})
+    return {"job_id": job.id}
+
+
+@app.post("/api/projects/{project_id}/style/refresh")
+def refresh_style(project_id: str, body: StyleIn):
+    project = _project_or_404(project_id)
+    job = jobs.submit("style", lambda progress: to_dict(pipeline.build_style(project, prompt=body.prompt, progress=progress)))
+    return {"job_id": job.id}
+
+
+@app.put("/api/projects/{project_id}/style")
+def save_style(project_id: str, body: dict):
+    """Persist a user-edited style profile (editable output)."""
+    project = _project_or_404(project_id)
+    profile = from_dict(StyleProfile, body)
+    return to_dict(pipeline.save_style(project, profile))
+
+
+# ---------------------------------------------------------------------------
+# Topics (project-level pool)
+# ---------------------------------------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/topics/prompt")
+def topics_prompt(project_id: str, body: TopicsIn):
+    project = _project_or_404(project_id)
+    n = max(1, min(body.n, 20))
+    job = jobs.submit("topics-prompt", lambda progress: {"prompt": pipeline.prepare_topics_prompt(project, n=n, progress=progress)})
+    return {"job_id": job.id}
+
+
+@app.post("/api/projects/{project_id}/topics/generate")
+def generate_topics(project_id: str, body: TopicsIn):
+    project = _project_or_404(project_id)
+    n = max(1, min(body.n, 20))
+    job = jobs.submit("topics", lambda progress: to_dict(
+        pipeline.generate_topics(project, n=n, prompt=body.prompt, progress=progress)
+    ))
+    return {"job_id": job.id}
+
+
+@app.put("/api/projects/{project_id}/topics")
+def edit_topics(project_id: str, body: TopicEditIn):
+    project = _project_or_404(project_id)
+    batch = pipeline.store.load_topics(project_id) or TopicBatch()
+    batch.topics = [from_dict(Topic, t) for t in body.topics]
+    return to_dict(pipeline.save_topics(project, batch))
+
+
+# ---------------------------------------------------------------------------
+# Reels
+# ---------------------------------------------------------------------------
+
+
+def _media_payload(project_id: str, reel_id: str):
+    manifest = pipeline.store.load_media(project_id, reel_id)
+    if not manifest:
+        return None
+    data = to_dict(manifest)
+    data["music_url"] = _url(manifest.music_path)
+    for scene in data["scenes"]:
+        for cand in scene["candidates"]:
+            cand["local_url"] = _url(cand["local_path"])
+    return data
+
+
+def _renders_payload(project_id: str, reel_id: str):
+    batch = pipeline.store.load_renders(project_id, reel_id)
+    if not batch:
+        return None
+    data = to_dict(batch)
+    for r in data["results"]:
+        r["url"] = _url(r["path"])
+    return data
+
+
+def _reel_payload(project_id: str, reel_id: str):
+    reel = _reel_or_404(project_id, reel_id)
+    return {
+        "reel": to_dict(reel),
+        "script": to_dict(pipeline.store.load_script(project_id, reel_id)),
+        "voice": to_dict(pipeline.store.load_voice(project_id, reel_id)),
+        "media": _media_payload(project_id, reel_id),
+        "renders": _renders_payload(project_id, reel_id),
+        "clone": to_dict(pipeline.store.load_clone(project_id, reel_id)),
+    }
+
+
+@app.get("/api/projects/{project_id}/reels")
+def list_reels(project_id: str):
+    _project_or_404(project_id)
+    return [to_dict(r) for r in pipeline.store.list_reels(project_id)]
+
+
+@app.post("/api/projects/{project_id}/reels")
+def create_reel(project_id: str, body: ReelIn):
+    project = _project_or_404(project_id)
+    return to_dict(pipeline.create_reel(project, name=body.name, topic=body.topic))
+
+
+@app.get("/api/projects/{project_id}/reels/{reel_id}")
+def get_reel(project_id: str, reel_id: str):
+    _project_or_404(project_id)
+    return _reel_payload(project_id, reel_id)
+
+
+@app.delete("/api/projects/{project_id}/reels/{reel_id}")
+def delete_reel(project_id: str, reel_id: str):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    pipeline.delete_reel(project, reel_id)
+    return {"ok": True}
+
+
+# -- script (reel-level) -----------------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/script/prompt")
+def script_prompt(project_id: str, reel_id: str, body: ScriptPromptIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    return {"prompt": pipeline.prepare_script_prompt(project, reel_id, body.topic)}
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/script/generate")
+def generate_script(project_id: str, reel_id: str, body: ScriptGenIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    job = jobs.submit("script", lambda progress: to_dict(
+        pipeline.generate_script(project, reel_id, body.topic, prompt=body.prompt)
+    ))
+    return {"job_id": job.id}
+
+
+@app.patch("/api/projects/{project_id}/reels/{reel_id}/script")
+def patch_script(project_id: str, reel_id: str, body: dict):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    script = from_dict(Script, body)
+    if not script.scenes:
+        raise HTTPException(400, "Script must keep at least one scene")
+    return to_dict(pipeline.save_script(project, reel_id, script))
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/script/regenerate-scene")
+def regenerate_scene(project_id: str, reel_id: str, body: SceneRegenIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    job = jobs.submit("scene", lambda progress: to_dict(
+        pipeline.regenerate_scene(project, reel_id, body.scene)
+    ))
+    return {"job_id": job.id}
+
+
+# -- voice / media (reel-level) ----------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/voice")
+def synthesize_voice(project_id: str, reel_id: str, body: VoiceIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    job = jobs.submit("voice", lambda progress: to_dict(
+        pipeline.synthesize_voice(project, reel_id, voice=body.voice, provider=body.provider, progress=progress)
+    ))
+    return {"job_id": job.id}
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/media")
+def gather_media(project_id: str, reel_id: str):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+
+    def run(progress):
+        pipeline.gather_media(project, reel_id, progress)
+        return _media_payload(project_id, reel_id)
+
+    return {"job_id": jobs.submit("media", run).id}
+
+
+@app.get("/api/projects/{project_id}/reels/{reel_id}/media")
+def get_media(project_id: str, reel_id: str):
+    _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    return _media_payload(project_id, reel_id)
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/media/swap")
+def swap_clip(project_id: str, reel_id: str, body: SwapIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    try:
+        pipeline.swap_clip(project, reel_id, body.line_index)
+    except RuntimeError as e:
+        raise HTTPException(400, str(e))
+    return _media_payload(project_id, reel_id)
+
+
+# -- render (reel-level) -----------------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/reels/{reel_id}/render")
+def start_render(project_id: str, reel_id: str, body: RenderIn):
+    project = _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    if body.variants:
+        variants = [from_dict(VariantSpec, v) for v in body.variants]
+        for v in variants:
+            if v.caption_preset not in CAPTION_PRESETS:
+                raise HTTPException(400, f"Unknown caption preset {v.caption_preset!r}")
+    else:
+        variants = list(DEFAULT_VARIANTS)
+
+    def run(progress):
+        pipeline.render(project, reel_id, variants=variants, progress=progress)
+        return _renders_payload(project_id, reel_id)
+
+    return {"job_id": jobs.submit("render", run).id}
+
+
+@app.get("/api/projects/{project_id}/reels/{reel_id}/render")
+def get_renders(project_id: str, reel_id: str):
+    _project_or_404(project_id)
+    _reel_or_404(project_id, reel_id)
+    return _renders_payload(project_id, reel_id)
+
+
+# ---------------------------------------------------------------------------
+# Clone (creates a new reel)
+# ---------------------------------------------------------------------------
+
+
+@app.post("/api/projects/{project_id}/clone")
+def clone_reel(project_id: str, body: CloneIn):
+    project = _project_or_404(project_id)
+
+    def run(progress):
+        try:
+            result = pipeline.clone_reel(project, body.url, progress)
+            return {"reel": to_dict(result["reel"]), "script": to_dict(result["script"])}
+        except CloneError as e:
+            raise RuntimeError(str(e)) from e
+
+    return {"job_id": jobs.submit("clone", run).id}

server/jobs.py

@@ -0,0 +1,71 @@
+"""Background job manager for long pipeline operations.
+
+POST handlers enqueue a callable and return a job_id immediately; the
+frontend polls GET /jobs/{id} for status, per-step progress messages, and
+the result payload. A small thread pool is plenty for a single local user.
+"""
+
+from __future__ import annotations
+
+import threading
+import traceback
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from core.utils import log
+
+
+@dataclass
+class Job:
+    id: str
+    kind: str
+    status: str = "queued"  # queued | running | done | error
+    progress: list[str] = field(default_factory=list)
+    result: Any = None
+    error: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "status": self.status,
+            "progress": list(self.progress),
+            "result": self.result,
+            "error": self.error,
+        }
+
+
+class JobManager:
+    def __init__(self, workers: int = 2):
+        self._pool = ThreadPoolExecutor(max_workers=workers)
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+
+    def submit(self, kind: str, fn: Callable[[Callable[[str], None]], Any]) -> Job:
+        """Run ``fn(progress_callback)`` in the background; return the Job."""
+        job = Job(id=uuid.uuid4().hex[:10], kind=kind)
+        with self._lock:
+            self._jobs[job.id] = job
+
+        def progress(msg: str) -> None:
+            log.info("[job %s] %s", job.id, msg)
+            job.progress.append(msg)
+
+        def run() -> None:
+            job.status = "running"
+            try:
+                job.result = fn(progress)
+                job.status = "done"
+            except Exception as e:
+                log.error("Job %s (%s) failed: %s\n%s", job.id, kind, e, traceback.format_exc())
+                job.error = str(e)
+                job.status = "error"
+
+        self._pool.submit(run)
+        return job
+
+    def get(self, job_id: str) -> Optional[Job]:
+        with self._lock:
+            return self._jobs.get(job_id)

tests/mocks.py

@@ -0,0 +1,213 @@
+"""Offline mock adapters. Registered under the name "mock" per capability.
+
+They synthesize media locally with ffmpeg's lavfi sources, so the whole
+pipeline (including the real render stage) runs with zero network access.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from core.adapters.base import (
+    LLMAdapter,
+    MusicAdapter,
+    ReferenceDataAdapter,
+    SFXAdapter,
+    StockVideoAdapter,
+    TranscriptAdapter,
+    TTSAdapter,
+    register,
+)
+from core.contracts import ClipCandidate, WordTiming
+from core.utils import run_ffmpeg
+
+MOCK_SCRIPT = {
+    "title": "Three wild facts about deep sea creatures",
+    "hook_options": [
+        "This fish hunts with a built-in flashlight.",
+        "The deep sea is weirder than any alien movie.",
+        "Scientists just filmed something impossible down here.",
+    ],
+    "scenes": [
+        {"scene": 1, "narration": "Meet the anglerfish, it lures prey with glowing bait.",
+         "visual_query": "deep sea fish glowing", "sfx_query": "underwater bubble", "duration_sec": 4},
+        {"scene": 2, "narration": "Giant isopods can survive years without a single meal.",
+         "visual_query": "ocean floor creature", "sfx_query": None, "duration_sec": 4},
+        {"scene": 3, "narration": "And the vampire squid turns itself completely inside out.",
+         "visual_query": "squid swimming dark water", "sfx_query": None, "duration_sec": 4},
+    ],
+    "cta": "Follow for more ocean weirdness.",
+    "total_duration_sec": 14,
+}
+
+MOCK_TOPICS = [
+    {"title": f"Mock topic {i}: deep sea discovery #{i}",
+     "reason": "trending in references",
+     "signals": [f"reference Short #{i} >100k views", "r/ocean top post"]}
+    for i in range(1, 9)
+]
+
+MOCK_CLONE = {
+    "topic": "How octopuses edit their own genes",
+    "hook_pattern": "impossible claim then immediate proof",
+    "structure": "hook -> 3 escalating facts -> twist -> CTA",
+    "style_notes": "fast, second person, playful",
+}
+
+MOCK_CHANNELS = [{"name": "Deep Sea Daily", "handle": "@deepseadaily"}]
+
+
+class MockLLM(LLMAdapter):
+    def __init__(self, config=None):
+        self.calls: list[str] = []
+
+    def complete(self, prompt: str) -> str:
+        self.calls.append(prompt)
+        if "STYLE CARD" in prompt:
+            return "- Hook: shocking claim first\n- Pacing: fast\n- CTA: question"
+        return json.dumps(self._route(prompt))
+
+    def complete_json(self, prompt: str):
+        self.calls.append(prompt)
+        return self._route(prompt)
+
+    @staticmethod
+    def _route(prompt: str):
+        if "Rewrite ONE scene" in prompt:
+            return {"narration": "Rewritten: the blobfish only looks sad at the surface.",
+                    "visual_query": "strange fish closeup", "sfx_query": None, "duration_sec": 4}
+        if "Return JSON only, exactly this shape" in prompt:
+            return MOCK_SCRIPT
+        if "extract its essence" in prompt:
+            return MOCK_CLONE
+        if "Propose exactly" in prompt:
+            return MOCK_TOPICS
+        if "Suggest" in prompt and "channels" in prompt:
+            return MOCK_CHANNELS
+        return {"ok": True}
+
+
+class MockTTS(TTSAdapter):
+    """Sine-tone 'speech' with evenly spread word timings."""
+
+    def __init__(self, config=None):
+        pass
+
+    def synth(self, text: str, out_path: str, voice: str = "") -> Optional[list[WordTiming]]:
+        words = text.split()
+        duration = max(0.8, len(words) * 0.28)
+        run_ffmpeg(
+            ["-f", "lavfi", "-i", f"sine=frequency=320:duration={duration:.2f}",
+             "-c:a", "libmp3lame", "-q:a", "7", out_path],
+            label="mock-tts",
+        )
+        per = duration / len(words) if words else duration
+        return [WordTiming(word=w, start=i * per, end=(i + 1) * per) for i, w in enumerate(words)]
+
+    def voices(self) -> list[str]:
+        return ["mock-voice"]
+
+
+_COLORS = ["0x335577", "0x775533", "0x557733", "0x553377", "0x337755"]
+
+
+class MockStock(StockVideoAdapter):
+    def __init__(self, config=None):
+        self.counter = 0
+
+    def search(self, query, orientation="portrait", min_duration=3.0,
+               max_duration=30.0, per_query=4) -> list[ClipCandidate]:
+        out = []
+        for i in range(per_query):
+            self.counter += 1
+            out.append(ClipCandidate(
+                id=f"mock{self.counter}", source="mock",
+                preview_url="", download_url=f"lavfi://{self.counter}",
+                width=608, height=1080, duration_sec=6.0,
+                credit="Mock / lavfi",
+            ))
+        return out
+
+    def download(self, candidate: ClipCandidate, out_path: str) -> str:
+        color = _COLORS[int(candidate.id.removeprefix("mock")) % len(_COLORS)]
+        run_ffmpeg(
+            ["-f", "lavfi", "-i", f"color=c={color}:s=608x1080:r=30:d=6",
+             "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", out_path],
+            label="mock-clip",
+        )
+        candidate.local_path = out_path
+        return out_path
+
+
+class MockSFX(SFXAdapter):
+    def __init__(self, config=None):
+        pass
+
+    def fetch(self, query: str, out_path: str, max_duration: float = 4.0) -> Optional[str]:
+        run_ffmpeg(
+            ["-f", "lavfi", "-i", "sine=frequency=880:duration=0.6",
+             "-c:a", "libmp3lame", "-q:a", "7", out_path],
+            label="mock-sfx",
+        )
+        return out_path
+
+
+class MockMusic(MusicAdapter):
+    """Generates one quiet tone track into the configured music dir."""
+
+    def __init__(self, config):
+        self.music_dir = config.music_dir
+
+    def pick(self, mood: str = "") -> tuple[str, str]:
+        self.music_dir.mkdir(parents=True, exist_ok=True)
+        track = self.music_dir / "mock_track.mp3"
+        if not track.exists():
+            run_ffmpeg(
+                ["-f", "lavfi", "-i", "sine=frequency=110:duration=20",
+                 "-c:a", "libmp3lame", "-q:a", "7", str(track)],
+                label="mock-music",
+            )
+        return str(track), "mock tone"
+
+
+class MockRefData(ReferenceDataAdapter):
+    def __init__(self, config=None):
+        pass
+
+    def resolve_channel(self, name_or_url: str):
+        return {"channel_id": "UCmock123", "title": name_or_url.lstrip("@"),
+                "url": "https://www.youtube.com/channel/UCmock123", "subscribers": 100000}
+
+    def top_shorts(self, channel_id: str, n: int = 5, since_days: int = 90):
+        return [
+            {"video_id": f"vid{i:03d}", "title": f"Wild ocean fact #{i}",
+             "views": 1_000_000 - i * 1000, "likes": 50_000, "published": "2026-06-01T00:00:00Z"}
+            for i in range(n)
+        ]
+
+    def _get(self, path: str, **params):  # used by the clone stage for metadata
+        return {"items": [{"snippet": {"title": "Mock source short",
+                                       "channelTitle": "Mock Channel"}}]}
+
+
+class MockTranscript(TranscriptAdapter):
+    def __init__(self, config=None):
+        pass
+
+    def fetch(self, video_id: str) -> Optional[str]:
+        return (
+            "Did you know the ocean is basically another planet? First, anglerfish "
+            "carry their own lanterns. Second, isopods fast for years. Third, the "
+            "vampire squid does the impossible. Follow for more."
+        ) * 2
+
+
+def register_mocks() -> None:
+    register("llm", "mock", MockLLM)
+    register("tts", "mock", MockTTS)
+    register("stock", "mock", MockStock)
+    register("sfx", "mock", MockSFX)
+    register("music", "mock", MockMusic)
+    register("refdata", "mock", MockRefData)
+    register("transcript", "mock", MockTranscript)

tests/test_server.py

@@ -0,0 +1,180 @@
+"""Server integration test: the full wizard flow over HTTP with mock adapters.
+
+Covers the job lifecycle (submit -> poll -> result), artifact endpoints,
+static file serving of the rendered MP4, and the clone route.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import pytest
+
+# Mock adapters must be selected BEFORE server.app builds its Pipeline.
+os.environ.update(
+    ADAPTER_LLM="mock", ADAPTER_TTS="mock", ADAPTER_STOCK="mock",
+    ADAPTER_SFX="mock", ADAPTER_MUSIC="mock", ADAPTER_REFDATA="mock",
+    ADAPTER_TRANSCRIPT="mock",
+)
+
+from tests.mocks import register_mocks  # noqa: E402
+
+register_mocks()
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from core.stages import topics as topics_stage  # noqa: E402
+from server.app import app  # noqa: E402
+
+client = TestClient(app)
+
+
+def wait_job(job_id: str, timeout: float = 120.0) -> dict:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        job = client.get(f"/api/jobs/{job_id}").json()
+        if job["status"] == "done":
+            return job["result"]
+        if job["status"] == "error":
+            raise AssertionError(f"job {job['kind']} failed: {job['error']}")
+        time.sleep(0.2)
+    raise AssertionError("job timed out")
+
+
+@pytest.fixture(scope="module")
+def project_id(request):
+    resp = client.post("/api/projects", json={
+        "name": "Server Smoke",
+        "niche": {"topic": "deep sea creatures", "keywords": ["ocean"],
+                  "subreddits": ["ocean"], "audience": "everyone", "tone": "fun"},
+        "format": "youtube_short",
+        "references": [
+            {"kind": "youtube", "name": "@deepseadaily"},
+            {"kind": "instagram_style", "name": "oceanreels",
+             "url": "https://instagram.com/oceanreels", "notes": "big captions"},
+        ],
+    })
+    assert resp.status_code == 200, resp.text
+    pid = resp.json()["id"]
+    request.addfinalizer(lambda: client.delete(f"/api/projects/{pid}"))
+    return pid
+
+
+def test_health():
+    body = client.get("/api/health").json()
+    assert body["ok"] and "caption_presets" in body
+    assert "tts_providers" in body
+
+
+def test_wizard_flow(project_id, monkeypatch):
+    monkeypatch.setattr(topics_stage, "_news_signals", lambda p: [])
+    monkeypatch.setattr(topics_stage, "_reddit_signals", lambda p: [])
+
+    # style: prompt prepare (job) then refresh, then edit-and-save the output
+    job = client.post(f"/api/projects/{project_id}/style/prompt").json()
+    assert "STYLE CARD" in wait_job(job["job_id"])["prompt"]
+    job = client.post(f"/api/projects/{project_id}/style/refresh", json={}).json()
+    style = wait_job(job["job_id"])
+    assert style["style_card"] and style["prompt_used"]
+    style["style_card"] = "EDITED style card"
+    assert client.put(f"/api/projects/{project_id}/style", json=style).json()["style_card"] == "EDITED style card"
+
+    # suggest references (job-based)
+    job = client.post(f"/api/projects/{project_id}/references/suggest", json={"n": 3}).json()
+    assert isinstance(wait_job(job["job_id"]), list)
+
+    # topics: prompt prepare + generate + inline edit
+    job = client.post(f"/api/projects/{project_id}/topics/prompt", json={"n": 5}).json()
+    assert wait_job(job["job_id"])["prompt"]
+    job = client.post(f"/api/projects/{project_id}/topics/generate", json={"n": 5}).json()
+    topics = wait_job(job["job_id"])["topics"]
+    assert len(topics) == 5
+    topics[0]["title"] = "Edited topic title"
+    resp = client.put(f"/api/projects/{project_id}/topics", json={"topics": topics})
+    assert resp.json()["topics"][0]["title"] == "Edited topic title"
+
+    # create a reel for the chosen topic
+    reel = client.post(f"/api/projects/{project_id}/reels",
+                       json={"topic": "Edited topic title"}).json()
+    rid = reel["id"]
+    base = f"/api/projects/{project_id}/reels/{rid}"
+
+    # script: prompt prepare + generate + patch + scene regen
+    assert "scripts" in client.post(f"{base}/script/prompt", json={"topic": "Edited topic title"}).json()["prompt"].lower()
+    job = client.post(f"{base}/script/generate", json={"topic": "Edited topic title"}).json()
+    script = wait_job(job["job_id"])
+    assert len(script["hook_options"]) == 3 and script["prompt_used"]
+    script["selected_hook"] = 1
+    assert client.patch(f"{base}/script", json=script).json()["selected_hook"] == 1
+    job = client.post(f"{base}/script/regenerate-scene", json={"scene": 1}).json()
+    assert "Rewritten" in wait_job(job["job_id"])["scenes"][0]["narration"]
+
+    # voices listing (with providers) + voice synthesis
+    vinfo = client.get("/api/voices").json()
+    assert vinfo["voices"] and "providers" in vinfo
+    job = client.post(f"{base}/voice", json={"voice": "", "provider": "mock"}).json()
+    assert wait_job(job["job_id"])["total_duration_sec"] > 3
+
+    # media + swap
+    job = client.post(f"{base}/media").json()
+    media = wait_job(job["job_id"])
+    assert media["scenes"] and media["scenes"][0]["candidates"]
+    before = media["scenes"][0]["selected"]
+    swapped = client.post(f"{base}/media/swap", json={"line_index": 0}).json()
+    assert swapped["scenes"][0]["selected"] != before
+
+    # render one variant, then fetch the file over HTTP
+    job = client.post(f"{base}/render", json={
+        "variants": [{"name": "Variant A", "caption_preset": "bold-center-karaoke", "clip_offset": 0}],
+    }).json()
+    renders = wait_job(job["job_id"], timeout=300)
+    assert renders["results"]
+    url = renders["results"][0]["url"]
+    assert url.startswith("/files/")
+    video = client.get(url)
+    assert video.status_code == 200 and len(video.content) > 50_000
+
+    # reel payload includes everything
+    payload = client.get(base).json()
+    assert payload["script"] and payload["voice"] and payload["media"] and payload["renders"]
+    # project payload lists the reel
+    proj = client.get(f"/api/projects/{project_id}").json()
+    assert any(r["id"] == rid for r in proj["reels"])
+
+
+def test_multiple_reels_via_api(project_id):
+    r1 = client.post(f"/api/projects/{project_id}/reels", json={"topic": "alpha"}).json()
+    r2 = client.post(f"/api/projects/{project_id}/reels", json={"topic": "beta"}).json()
+    reels = client.get(f"/api/projects/{project_id}/reels").json()
+    ids = {r["id"] for r in reels}
+    assert {r1["id"], r2["id"]} <= ids
+    assert client.delete(f"/api/projects/{project_id}/reels/{r1['id']}").json()["ok"]
+    remaining = {r["id"] for r in client.get(f"/api/projects/{project_id}/reels").json()}
+    assert r1["id"] not in remaining and r2["id"] in remaining
+
+
+def test_clone_route(project_id):
+    job = client.post(f"/api/projects/{project_id}/clone",
+                      json={"url": "https://www.youtube.com/shorts/abcdefghijk"}).json()
+    result = wait_job(job["job_id"])
+    assert result["reel"]["clone_source"].endswith("abcdefghijk")
+    assert result["script"]["clone_source"].endswith("abcdefghijk")
+
+    job = client.post(f"/api/projects/{project_id}/clone",
+                      json={"url": "https://example.com/nope"}).json()
+    status = None
+    for _ in range(50):
+        status = client.get(f"/api/jobs/{job['job_id']}").json()
+        if status["status"] in ("done", "error"):
+            break
+        time.sleep(0.1)
+    assert status["status"] == "error" and "YouTube" in status["error"]
+
+
+def test_bad_render_preset(project_id):
+    reel = client.post(f"/api/projects/{project_id}/reels", json={"topic": "x"}).json()
+    resp = client.post(f"/api/projects/{project_id}/reels/{reel['id']}/render", json={
+        "variants": [{"name": "X", "caption_preset": "nope", "clip_offset": 0}],
+    })
+    assert resp.status_code == 400

tests/test_smoke.py

@@ -0,0 +1,199 @@
+"""Offline end-to-end smoke test.
+
+Runs the REAL pipeline and render stage with mock (lavfi-backed) adapters:
+no network, no API keys. Asserts at least one 9:16 MP4 variant lands on
+disk with sane duration.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from core.config import Config
+from core.contracts import DEFAULT_VARIANTS, NicheProfile, ReferenceEntry
+from core.pipeline import Pipeline
+from core.stages import topics as topics_stage
+from core.store import ProjectStore
+from tests.mocks import register_mocks
+
+register_mocks()
+
+
+@pytest.fixture()
+def pipe(tmp_path: Path) -> Pipeline:
+    cfg = Config(
+        llm_adapter="mock",
+        tts_adapter="mock",
+        stock_adapter="mock",
+        sfx_adapter="mock",
+        music_adapter="mock",
+        refdata_adapter="mock",
+        transcript_adapter="mock",
+        projects_dir=tmp_path / "projects",
+        music_dir=tmp_path / "music",
+    )
+    return Pipeline(config=cfg, store=ProjectStore(cfg.projects_dir))
+
+
+@pytest.fixture()
+def project(pipe: Pipeline):
+    niche = NicheProfile(
+        topic="deep sea creatures",
+        keywords=["ocean", "marine biology"],
+        subreddits=["thalassophobia"],
+        audience="curious adults",
+        tone="playful",
+    )
+    refs = [
+        ReferenceEntry(kind="youtube", name="@deepseadaily"),
+        ReferenceEntry(kind="instagram_style", name="oceanreels",
+                       url="https://instagram.com/oceanreels",
+                       notes="moody color grade, big captions"),
+    ]
+    return pipe.create_project("Deep Sea", niche, "youtube_short", refs)
+
+
+def _ffprobe(path: str, entries: str) -> str:
+    return subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "v:0",
+         "-show_entries", entries, "-of", "csv=p=0", path],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+
+def test_full_pipeline_offline(pipe: Pipeline, project, monkeypatch):
+    # Keep the topics stage offline: external trend sources are stubbed out.
+    monkeypatch.setattr(topics_stage, "_news_signals", lambda p: ["[news] mock headline"])
+    monkeypatch.setattr(topics_stage, "_reddit_signals", lambda p: ["[r/mock] mock post"])
+
+    # Stage 2: style (project-level) — prompt captured for QC
+    style = pipe.build_style(project)
+    assert style.style_card
+    assert style.exemplars, "transcripts should become exemplars"
+    assert style.instagram_notes, "IG notes must flow into the style profile"
+    assert style.prompt_used, "the assembled prompt is stored for QC"
+
+    # Stage 3: topics (project-level pool)
+    batch = pipe.generate_topics(project, n=6)
+    assert len(batch.topics) == 6
+    assert batch.prompt_used
+
+    # A reel owns the script -> voice -> media -> render chain
+    reel = pipe.create_reel(project, topic=batch.topics[0].title)
+
+    # Stage 4: script
+    script = pipe.generate_script(project, reel.id, batch.topics[0].title)
+    assert len(script.hook_options) == 3
+    assert 1 <= len(script.scenes) <= 6
+    assert script.narration_lines()[0] == script.hook_options[0]
+    assert script.prompt_used
+
+    # Stage 5: voice — true ffprobe durations drive timing
+    voice = pipe.synthesize_voice(project, reel.id)
+    assert len(voice.lines) == len(script.narration_lines())
+    for line in voice.lines:
+        assert line.duration_sec > 0.2
+        assert line.word_timings, "mock TTS emits timings"
+
+    # Stage 6: media — alternates kept, dedupe enforced
+    manifest = pipe.gather_media(project, reel.id)
+    assert len(manifest.scenes) == len(voice.lines)
+    used = [s.candidates[s.selected].id for s in manifest.scenes if s.candidates]
+    assert len(used) == len(set(used)), "the same clip must never appear twice"
+    assert any(len(s.candidates) > 1 for s in manifest.scenes), "alternates kept for the UI"
+    assert manifest.music_path, "mock music track picked"
+
+    # Stage 7: render — at least 2 variants, 9:16, duration matches voice
+    batch = pipe.render(project, reel.id, variants=DEFAULT_VARIANTS[:2])
+    assert len(batch.results) >= 1
+    for r in batch.results:
+        assert Path(r.path).exists()
+        w, h = _ffprobe(r.path, "stream=width,height").split(",")
+        assert (w, h) == ("1080", "1920")
+        assert abs(r.duration_sec - voice.total_duration_sec) < 1.5
+
+    # Artifacts persisted: project-level + reel-level
+    pdir = pipe.store.dir(project.id)
+    for name in ["project.json", "style.json", "topics.json"]:
+        assert (pdir / name).exists(), f"missing project artifact {name}"
+    rdir = pipe.store.reel_dir(project.id, reel.id)
+    for name in ["reel.json", "script.json", "voice/voice.json",
+                 "media/media.json", "renders/renders.json"]:
+        assert (rdir / name).exists(), f"missing reel artifact {name}"
+    assert json.loads((rdir / "script.json").read_text())["title"]
+
+
+def test_multiple_reels_independent(pipe: Pipeline, project):
+    """Two reels in one project keep separate scripts."""
+    r1 = pipe.create_reel(project, topic="topic one")
+    r2 = pipe.create_reel(project, topic="topic two")
+    pipe.generate_script(project, r1.id, "topic one")
+    pipe.generate_script(project, r2.id, "topic two")
+    assert {r.id for r in pipe.list_reels(project)} >= {r1.id, r2.id}
+    s1 = pipe.store.load_script(project.id, r1.id)
+    s2 = pipe.store.load_script(project.id, r2.id)
+    assert s1.topic == "topic one" and s2.topic == "topic two"
+    # Deleting one leaves the other intact
+    pipe.delete_reel(project, r1.id)
+    assert pipe.store.load_script(project.id, r1.id) is None
+    assert pipe.store.load_script(project.id, r2.id) is not None
+
+
+def test_prompt_override_used(pipe: Pipeline, project):
+    """An edited prompt is passed through and recorded."""
+    reel = pipe.create_reel(project, topic="x")
+    custom = "CUSTOM PROMPT — return the mock script JSON. Return JSON only, exactly this shape: {}"
+    script = pipe.generate_script(project, reel.id, "x", prompt=custom)
+    assert script.prompt_used == custom
+
+
+def test_prepare_prompts(pipe: Pipeline, project, monkeypatch):
+    monkeypatch.setattr(topics_stage, "_news_signals", lambda p: [])
+    monkeypatch.setattr(topics_stage, "_reddit_signals", lambda p: [])
+    assert "Niche" in pipe.prepare_suggest_prompt(project)
+    assert "STYLE CARD" in pipe.prepare_style_prompt(project)
+    assert "topics" in pipe.prepare_topics_prompt(project, n=5).lower()
+    reel = pipe.create_reel(project, topic="t")
+    assert "scripts" in pipe.prepare_script_prompt(project, reel.id, "t").lower()
+
+
+def test_clone_flow_offline(pipe: Pipeline, project):
+    result = pipe.clone_reel(project, "https://www.youtube.com/shorts/abcdefghijk")
+    reel, script = result["reel"], result["script"]
+    assert reel.clone_source == "https://www.youtube.com/shorts/abcdefghijk"
+    assert script.clone_source == "https://www.youtube.com/shorts/abcdefghijk"
+    assert script.scenes
+    brief = pipe.store.load_clone(project.id, reel.id)
+    assert brief and brief.topic and brief.structure
+
+
+def test_clone_rejects_bad_url(pipe: Pipeline, project):
+    from core.stages.clone import CloneError
+
+    with pytest.raises(CloneError):
+        pipe.clone_reel(project, "https://example.com/not-youtube")
+
+
+def test_scene_regeneration(pipe: Pipeline, project):
+    reel = pipe.create_reel(project, topic="test topic")
+    pipe.generate_script(project, reel.id, "test topic")
+    script = pipe.regenerate_scene(project, reel.id, scene_number=2)
+    assert "Rewritten" in script.scenes[1].narration
+    assert "Rewritten" not in script.scenes[0].narration
+
+
+def test_static_captions_when_no_timings(pipe: Pipeline, project, tmp_path):
+    """No word timings -> static captions, render still succeeds."""
+    reel = pipe.create_reel(project, topic="test topic")
+    pipe.generate_script(project, reel.id, "test topic")
+    voice = pipe.synthesize_voice(project, reel.id)
+    for line in voice.lines:
+        line.word_timings = []
+    pipe.store.save_voice(project.id, reel.id, voice)
+    pipe.gather_media(project, reel.id)
+    batch = pipe.render(project, reel.id, variants=[DEFAULT_VARIANTS[0]])
+    assert batch.results and Path(batch.results[0].path).exists()

web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Reel Studio v2</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

web/package-lock.json

@@ -0,0 +1,1680 @@
+{
+  "name": "reel-studio-web",
+  "version": "2.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "reel-studio-web",
+      "version": "2.0.0",
+      "dependencies": {
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1"
+      },
+      "devDependencies": {
+        "@vitejs/plugin-react": "^4.3.1",
+        "vite": "^5.4.8"
+      }
+    },
+    "node_modules/@babel/code-frame": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz",
+      "integrity": "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-validator-identifier": "^7.29.7",
+        "js-tokens": "^4.0.0",
+        "picocolors": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/compat-data": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.7.tgz",
+      "integrity": "sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/core": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.7.tgz",
+      "integrity": "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/generator": "^7.29.7",
+        "@babel/helper-compilation-targets": "^7.29.7",
+        "@babel/helper-module-transforms": "^7.29.7",
+        "@babel/helpers": "^7.29.7",
+        "@babel/parser": "^7.29.7",
+        "@babel/template": "^7.29.7",
+        "@babel/traverse": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "@jridgewell/remapping": "^2.3.5",
+        "convert-source-map": "^2.0.0",
+        "debug": "^4.1.0",
+        "gensync": "^1.0.0-beta.2",
+        "json5": "^2.2.3",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/babel"
+      }
+    },
+    "node_modules/@babel/generator": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.7.tgz",
+      "integrity": "sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "@jridgewell/gen-mapping": "^0.3.12",
+        "@jridgewell/trace-mapping": "^0.3.28",
+        "jsesc": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.29.7.tgz",
+      "integrity": "sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/compat-data": "^7.29.7",
+        "@babel/helper-validator-option": "^7.29.7",
+        "browserslist": "^4.24.0",
+        "lru-cache": "^5.1.1",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-globals": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.29.7.tgz",
+      "integrity": "sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-imports": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz",
+      "integrity": "sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/traverse": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-transforms": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.29.7.tgz",
+      "integrity": "sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-module-imports": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7",
+        "@babel/traverse": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0"
+      }
+    },
+    "node_modules/@babel/helper-plugin-utils": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.29.7.tgz",
+      "integrity": "sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
+      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
+      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-option": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.29.7.tgz",
+      "integrity": "sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helpers": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.7.tgz",
+      "integrity": "sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/template": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.7.tgz",
+      "integrity": "sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.7"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-self": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.29.7.tgz",
+      "integrity": "sha512-TL0hMc9xzy86VD31nUiwzd5otRAcyEPcsegCxolO0PvcXuH1v0kECe/UIznYFihpkvU5wg/jk4v0TTEFfm53fw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-source": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.29.7.tgz",
+      "integrity": "sha512-06IyK09H3wi4cGbhDBwp5gUGo0IKtnYa8tyTiephirPCK6fbobVGiXMMI5zLQ4aKEYP3wZ3ArU44o+8KMrSG/Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/template": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz",
+      "integrity": "sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/parser": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/traverse": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.7.tgz",
+      "integrity": "sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/generator": "^7.29.7",
+        "@babel/helper-globals": "^7.29.7",
+        "@babel/parser": "^7.29.7",
+        "@babel/template": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "debug": "^4.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.7.tgz",
+      "integrity": "sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-beta.27",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
+      "integrity": "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.61.1.tgz",
+      "integrity": "sha512-JnBB8MdXj45cajvTuO5FmPlvFVJRQgvrz1uSEl3NwqFnReAPGwb8EanbGi4z2nRaqLzjJSv5/JmycoTKlRZxHA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.61.1.tgz",
+      "integrity": "sha512-Jx2g7iSjw4AOT0HDPHM9RV3GNjRXwybWtSFZiZAYUTjUwjVrYIwq3kBf+LnhqJlzXFAqTAh2F7IGI+O568exPw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.61.1.tgz",
+      "integrity": "sha512-0F1L/Z3Eqv8mT2n3dCpeO8GcTvHvVqkP5/t6DMsn0KzhYVcg+s7Ncl5DS8qjKYEeio6Az0Gt6nyBORay5qIlCA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.61.1.tgz",
+      "integrity": "sha512-qLttcH871ujY4YcVfUSShhOw+CsoTatYz8gRbHO7Bb92QH059/P0y5do1KMs41fY0BpD2x4AJH/gID0zFiqVKQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.61.1.tgz",
+      "integrity": "sha512-fUI4RapGE0Oh3mb8mgfvC1O2nU1RpDZUKnDQm3xB1Ipg7C2wTs5Kstz7G2uWK99a8S2yTMq8/P4uycwNa0nJyw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.61.1.tgz",
+      "integrity": "sha512-H5YrdvJaDtI/U9/emrD4b++xkvp3y/JvOe4rizHbxvkyMfRS/CiRYdji+Pl8D0brEaNFWUh1drQxgAGIl6Xudw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.61.1.tgz",
+      "integrity": "sha512-Q8CBCCQtDFrYtXoeUXSrnFXKOnyUhx6bz+SkL6A0E7V8kAiCJ5pamq1WtbfpVGhR5TSpXY6ak3avmDc5fHTyJA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.61.1.tgz",
+      "integrity": "sha512-nwnhk1581l0FBVellGcVCAT0Oi06onEA3WB53sf01VO3I0UPBkMH9sXONYME2K0ovXcNayJfNtHfm6mpJElatQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.61.1.tgz",
+      "integrity": "sha512-x5Xr49hwt3hdW75UOZm3395YwwzPyauktslv29KpWL/T+vVAzoT3azLcTWv0eMciBNrx+DYjH4paehHoLpPvpg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.61.1.tgz",
+      "integrity": "sha512-unMS3H73DpaoPyyEVPjGKleM/s0mkmsauTENpw4INQY8y4+IuLNjkueQ5QCtC0D3N38Y38yhAU8OoZ20S2Tm6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.61.1.tgz",
+      "integrity": "sha512-zNZzGRnAhwjFEYmvphJRV5XaQGjs62cCmeYYHUT//NbvEnHauw+I85nGG+SiVg5ld4GX8D1IbKIX+ozITQnhMQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.61.1.tgz",
+      "integrity": "sha512-LdpWGL8X209B2SIvWjqlc8VZgM6PKfontSerGepuldQmHYrAOtnMCXeJkxXGbC+PPZVOuu5czJo7fNV6aeW8rQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.61.1.tgz",
+      "integrity": "sha512-EC5kTtNaNGOmbMGqar8dvJy6y/hg99GAwjfBz++pxZhQATXGcRjd6c5en5wcbru0vkRmiMGsQKdMJOOf6sza4g==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.61.1.tgz",
+      "integrity": "sha512-8hiwp6D4acEcNK78I4rP0/XtS1sknWIAMJBPdR4l6zUtyTm5KiTDr5bXmWt4foY7nAN7AThDHgkLIEZOWKbzWw==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.61.1.tgz",
+      "integrity": "sha512-10dh/h/BqA7DuMPWSxkR8uks18FRwnwOEqr5zOTEl+NOwP/OMzKX8OFR/Of9xxDA7D5qef1Nzar5WDD2kCCr1g==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.61.1.tgz",
+      "integrity": "sha512-YKJ5lg35DP17gcAOggnihe+APw9HLyj1Xn7gsmGumBJAUDa6NGXNixJzmkWLhcK9TOuuyQjdamzvJefkO7qHZQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.61.1.tgz",
+      "integrity": "sha512-Mlil5G2Jj6a7B3LWGctg+XPL9vdXYuzCtNXfxOQ0nPjc2m6ueUktocPGH9bnAM0bNRKb/bAWTujUU7IJQdQA+g==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.61.1.tgz",
+      "integrity": "sha512-bVWIOIk6pV01p4CdUbPP7CJ/434z+OooYjDuFcR+44N35YvKUC66G8MGnvcWx5mWKW3g61J+t74l3Kj15Kwn2Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.61.1.tgz",
+      "integrity": "sha512-qy5pBvZbqNFheBz61R1rzsezjm0J7O2oNGoWtGoY89SZYLUfxAJTBAqDChqAIdB4rCiIbi9nF7yZ83GnNiLwSw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.61.1.tgz",
+      "integrity": "sha512-E83TXjI4zm0+5f2qO+UOudaCYIhYwpJ5jq6YCZNIZ+6CbfhKrkAGezeiASBL9ElxAxFsRS9ZhESv8mfnj6TKeg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.61.1.tgz",
+      "integrity": "sha512-fbWnKqVkjrJN38vNe3ahkbk6iejS/3b0Nt7EEtPpE6RBacZcGXNKbzfHN3GUUlXOPghUg0j6XUGrtjX9z1sIvA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.61.1.tgz",
+      "integrity": "sha512-ArMl38iVAbk0New1ogihQNY6iphLi4ZaRsa037gUzv5yeKPY8TD3Dmy4x2RNC1VztU/uqm+G+/RwFrSka3Oy2g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.61.1.tgz",
+      "integrity": "sha512-0mYtjHS9ucAbcATycCNK9IGBk/cCe/ma7EmSLGZdsxnOA8cjRIyU04wDpVAD9NiOfLUR9KTxdiO53uOkherqjQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.61.1.tgz",
+      "integrity": "sha512-gK1iCEPfpoSG9wfBihXxvBMi8ZfcWffYkEsC/Eih+iFENTaewvNcrEQ69lIOWYO5pePHKLHHO7nq5AILGO/HQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.61.1.tgz",
+      "integrity": "sha512-X+zaP2x+j4RXGfbp/seSoRHWnPxzApilDszisZxbYH5C/jTxFhCtDNdPGZb9lJyYPs24wGxruPF7Y+sIXt9Gzw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@types/babel__core": {
+      "version": "7.20.5",
+      "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
+      "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.20.7",
+        "@babel/types": "^7.20.7",
+        "@types/babel__generator": "*",
+        "@types/babel__template": "*",
+        "@types/babel__traverse": "*"
+      }
+    },
+    "node_modules/@types/babel__generator": {
+      "version": "7.27.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz",
+      "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__template": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz",
+      "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.1.0",
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__traverse": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz",
+      "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.28.2"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz",
+      "integrity": "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.28.0",
+        "@babel/plugin-transform-react-jsx-self": "^7.27.1",
+        "@babel/plugin-transform-react-jsx-source": "^7.27.1",
+        "@rolldown/pluginutils": "1.0.0-beta.27",
+        "@types/babel__core": "^7.20.5",
+        "react-refresh": "^0.17.0"
+      },
+      "engines": {
+        "node": "^14.18.0 || >=16.0.0"
+      },
+      "peerDependencies": {
+        "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
+      }
+    },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.10.37",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.37.tgz",
+      "integrity": "sha512-girxaJ7WZssDOFhzCGZTDKoTa1gk6A1TbflaYTpykLJ4UU9Fz9kx1aREM8JCuoVHbL8X8T/mJg7w2oYSq72Oig==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.cjs"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/browserslist": {
+      "version": "4.28.2",
+      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz",
+      "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "baseline-browser-mapping": "^2.10.12",
+        "caniuse-lite": "^1.0.30001782",
+        "electron-to-chromium": "^1.5.328",
+        "node-releases": "^2.0.36",
+        "update-browserslist-db": "^1.2.3"
+      },
+      "bin": {
+        "browserslist": "cli.js"
+      },
+      "engines": {
+        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+      }
+    },
+    "node_modules/caniuse-lite": {
+      "version": "1.0.30001799",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001799.tgz",
+      "integrity": "sha512-hG1bReV+OUU+MOqK4t/ZWI0tZOyz3rqS9XuhOUz1cIcbwBKjOyJEJuw9ER5JuNyqxNk8u/JUVbGibBOL1yrjFw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "CC-BY-4.0"
+    },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/electron-to-chromium": {
+      "version": "1.5.372",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.372.tgz",
+      "integrity": "sha512-M3yhbAlilnwqC8D21t28UCDGHyitShTmmLRU/H+b74P6Ski16Nb9HONYEaVpMj/pwC7BEo5B95FpjODLCWbtfA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gensync": {
+      "version": "1.0.0-beta.2",
+      "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
+      "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "license": "MIT"
+    },
+    "node_modules/jsesc": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
+      "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "jsesc": "bin/jsesc"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/json5": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
+      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "json5": "lib/cli.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
+    "node_modules/lru-cache": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+      "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^3.0.2"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/node-releases": {
+      "version": "2.0.47",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.47.tgz",
+      "integrity": "sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/postcss": {
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/react": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0",
+        "scheduler": "^0.23.2"
+      },
+      "peerDependencies": {
+        "react": "^18.3.1"
+      }
+    },
+    "node_modules/react-refresh": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",
+      "integrity": "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.61.1",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.61.1.tgz",
+      "integrity": "sha512-I4KW6iuRpuu2uHBLraZ1wNZe0DP7lnRha+VJ9tNaYVaVgKhW0aI3h4RYnoRPeql0flHm/Co55b7snEDcOfOJrA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.9"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.61.1",
+        "@rollup/rollup-android-arm64": "4.61.1",
+        "@rollup/rollup-darwin-arm64": "4.61.1",
+        "@rollup/rollup-darwin-x64": "4.61.1",
+        "@rollup/rollup-freebsd-arm64": "4.61.1",
+        "@rollup/rollup-freebsd-x64": "4.61.1",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.61.1",
+        "@rollup/rollup-linux-arm-musleabihf": "4.61.1",
+        "@rollup/rollup-linux-arm64-gnu": "4.61.1",
+        "@rollup/rollup-linux-arm64-musl": "4.61.1",
+        "@rollup/rollup-linux-loong64-gnu": "4.61.1",
+        "@rollup/rollup-linux-loong64-musl": "4.61.1",
+        "@rollup/rollup-linux-ppc64-gnu": "4.61.1",
+        "@rollup/rollup-linux-ppc64-musl": "4.61.1",
+        "@rollup/rollup-linux-riscv64-gnu": "4.61.1",
+        "@rollup/rollup-linux-riscv64-musl": "4.61.1",
+        "@rollup/rollup-linux-s390x-gnu": "4.61.1",
+        "@rollup/rollup-linux-x64-gnu": "4.61.1",
+        "@rollup/rollup-linux-x64-musl": "4.61.1",
+        "@rollup/rollup-openbsd-x64": "4.61.1",
+        "@rollup/rollup-openharmony-arm64": "4.61.1",
+        "@rollup/rollup-win32-arm64-msvc": "4.61.1",
+        "@rollup/rollup-win32-ia32-msvc": "4.61.1",
+        "@rollup/rollup-win32-x64-gnu": "4.61.1",
+        "@rollup/rollup-win32-x64-msvc": "4.61.1",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      }
+    },
+    "node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/update-browserslist-db": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
+      "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "escalade": "^3.2.0",
+        "picocolors": "^1.1.1"
+      },
+      "bin": {
+        "update-browserslist-db": "cli.js"
+      },
+      "peerDependencies": {
+        "browserslist": ">= 4.21.0"
+      }
+    },
+    "node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/yallist": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+      "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+      "dev": true,
+      "license": "ISC"
+    }
+  }
+}

web/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "reel-studio-web",
+  "private": true,
+  "version": "2.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.1",
+    "vite": "^5.4.8"
+  }
+}

web/src/App.jsx

@@ -0,0 +1,184 @@
+import { useCallback, useEffect, useState } from 'react'
+import { api } from './api'
+import { ErrorBox } from './hooks'
+import Stepper from './components/Stepper'
+import ReelBar from './components/ReelBar'
+import CloneBar from './components/CloneBar'
+import SetupStep from './steps/SetupStep'
+import ReferencesStep from './steps/ReferencesStep'
+import TopicsStep from './steps/TopicsStep'
+import ScriptStep from './steps/ScriptStep'
+import MediaStep from './steps/MediaStep'
+import RenderStep from './steps/RenderStep'
+import ReviewStep from './steps/ReviewStep'
+
+export const STEPS = ['Setup', 'References', 'Topics', 'Script', 'Media', 'Render', 'Review']
+const REEL_STEP_START = 3 // steps >= this operate on the selected reel
+
+export default function App() {
+  const [projects, setProjects] = useState(null)
+  const [projectId, setProjectId] = useState(null)
+  const [data, setData] = useState(null) // project-level: {project, style, topics, reels}
+  const [reelId, setReelId] = useState(null)
+  const [reelData, setReelData] = useState(null) // {reel, script, voice, media, renders, clone}
+  const [step, setStep] = useState(0)
+  const [error, setError] = useState('')
+
+  const loadProjects = useCallback(() => {
+    api.get('/api/projects').then(setProjects).catch((e) => setError(e.message))
+  }, [])
+
+  const refreshProject = useCallback(async () => {
+    if (!projectId) return null
+    try {
+      const d = await api.get(`/api/projects/${projectId}`)
+      setData(d)
+      return d
+    } catch (e) {
+      setError(e.message)
+      return null
+    }
+  }, [projectId])
+
+  const refreshReel = useCallback(async () => {
+    if (!projectId || !reelId) { setReelData(null); return null }
+    try {
+      const d = await api.get(`/api/projects/${projectId}/reels/${reelId}`)
+      setReelData(d)
+      return d
+    } catch (e) {
+      setError(e.message)
+      return null
+    }
+  }, [projectId, reelId])
+
+  useEffect(loadProjects, [loadProjects])
+  useEffect(() => { setData(null); setReelId(null); setReelData(null); refreshProject() }, [projectId, refreshProject])
+  useEffect(() => { refreshReel() }, [reelId, refreshReel])
+
+  const selectReel = (id) => { setReelId(id); setStep(REEL_STEP_START) }
+
+  const newReel = async () => {
+    const reel = await api.post(`/api/projects/${projectId}/reels`, {}).catch((e) => { setError(e.message) })
+    if (reel) { await refreshProject(); selectReel(reel.id) }
+  }
+
+  const deleteReel = async (id) => {
+    if (!window.confirm('Delete this reel and all its media?')) return
+    await api.del(`/api/projects/${projectId}/reels/${id}`).catch((e) => setError(e.message))
+    if (id === reelId) { setReelId(null); setStep(2) }
+    await refreshProject()
+  }
+
+  const canEnter = (i) => {
+    if (!data) return i === 0
+    if (i < REEL_STEP_START) return true
+    if (!reelId) return false
+    if (i === 3) return true                       // Script (offers generate)
+    if (i === 4) return !!reelData?.script         // Media
+    if (i === 5) return !!reelData?.voice && !!reelData?.media // Render
+    if (i === 6) return !!(reelData?.renders?.results?.length) // Review
+    return false
+  }
+
+  if (!projectId) {
+    return (
+      <Home
+        projects={projects}
+        error={error}
+        onOpen={(id) => { setProjectId(id); setStep(1) }}
+        onCreate={(project) => { setProjectId(project.id); setStep(1); loadProjects() }}
+        onDelete={async (id) => {
+          if (!window.confirm('Delete this project and all its reels?')) return
+          await api.del(`/api/projects/${id}`).catch((e) => setError(e.message))
+          loadProjects()
+        }}
+      />
+    )
+  }
+
+  // Props shared with every step.
+  const shared = {
+    projectId, data, refreshProject,
+    reelId, reelData, refreshReel, selectReel, setReelId,
+    setStep,
+  }
+
+  return (
+    <div className="layout">
+      <div className="sidebar">
+        <h1>Reel <span>Studio</span> v2</h1>
+        <button className="home-link" onClick={() => { setProjectId(null); loadProjects() }}>
+          ← All projects
+        </button>
+        {data && <div className="project-name" title={data.project.name}>{data.project.name}</div>}
+        <Stepper steps={STEPS} current={step} canEnter={canEnter} onSelect={setStep} />
+        {data && (
+          <ReelBar
+            reels={data.reels || []}
+            reelId={reelId}
+            onSelect={selectReel}
+            onNew={newReel}
+            onDelete={deleteReel}
+          />
+        )}
+      </div>
+      <div className="main">
+        <ErrorBox error={error} onRetry={() => { setError(''); refreshProject() }} />
+        {!data && !error && <p className="muted"><span className="spinner" />Loading project…</p>}
+        {data && (
+          <>
+            <CloneBar
+              projectId={projectId}
+              onCloned={async (reel) => { await refreshProject(); selectReel(reel.id) }}
+            />
+            {step === 0 && <SetupStep {...shared} mode="edit" />}
+            {step === 1 && <ReferencesStep {...shared} />}
+            {step === 2 && <TopicsStep {...shared} />}
+            {step === 3 && <ScriptStep {...shared} />}
+            {step === 4 && <MediaStep {...shared} />}
+            {step === 5 && <RenderStep {...shared} />}
+            {step === 6 && <ReviewStep {...shared} />}
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function Home({ projects, error, onOpen, onCreate, onDelete }) {
+  const [creating, setCreating] = useState(false)
+  return (
+    <div className="layout">
+      <div className="main" style={{ margin: '0 auto' }}>
+        <h2>Reel Studio v2</h2>
+        <p className="subtitle">AI short-form video pipeline — pick a project or start a new one.</p>
+        <ErrorBox error={error} />
+        {creating ? (
+          <SetupStep mode="create" onCreated={onCreate} onCancel={() => setCreating(false)} />
+        ) : (
+          <>
+            <button className="btn" onClick={() => setCreating(true)}>+ New project</button>
+            <div className="spacer" />
+            {projects === null && <p className="muted"><span className="spinner" />Loading…</p>}
+            {projects?.length === 0 && <p className="muted">No projects yet.</p>}
+            {projects?.map((p) => (
+              <div key={p.id} className="project-tile" onClick={() => onOpen(p.id)}>
+                <div>
+                  <strong>{p.name}</strong>
+                  <div className="muted">{p.niche.topic} · {p.format.replace('_', ' ')}</div>
+                </div>
+                <button
+                  className="btn small danger"
+                  onClick={(e) => { e.stopPropagation(); onDelete(p.id) }}
+                >
+                  Delete
+                </button>
+              </div>
+            ))}
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

web/src/api.js

@@ -0,0 +1,42 @@
+// Thin fetch wrapper + job polling for the FastAPI backend.
+
+async function request(path, options = {}) {
+  const res = await fetch(path, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+  })
+  if (!res.ok) {
+    let detail = res.statusText
+    try {
+      const body = await res.json()
+      detail = body.detail || JSON.stringify(body)
+    } catch { /* keep statusText */ }
+    throw new Error(detail)
+  }
+  return res.json()
+}
+
+export const api = {
+  get: (path) => request(path),
+  post: (path, body) => request(path, { method: 'POST', body: JSON.stringify(body ?? {}) }),
+  put: (path, body) => request(path, { method: 'PUT', body: JSON.stringify(body) }),
+  patch: (path, body) => request(path, { method: 'PATCH', body: JSON.stringify(body) }),
+  del: (path) => request(path, { method: 'DELETE' }),
+}
+
+// Poll a job until done/error. onProgress receives the list of messages.
+export async function pollJob(jobId, onProgress, intervalMs = 1200) {
+  for (;;) {
+    const job = await api.get(`/api/jobs/${jobId}`)
+    if (onProgress) onProgress(job.progress || [])
+    if (job.status === 'done') return job.result
+    if (job.status === 'error') throw new Error(job.error || 'Job failed')
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+}
+
+// Convenience: POST that returns {job_id}, then poll it.
+export async function runJob(path, body, onProgress) {
+  const { job_id } = await api.post(path, body)
+  return pollJob(job_id, onProgress)
+}

web/src/components/CloneBar.jsx

@@ -0,0 +1,41 @@
+import { useState } from 'react'
+import { useJob, ProgressBox, ErrorBox } from '../hooks'
+
+// Paste a YouTube Shorts URL -> backend builds a clone brief and writes a
+// FRESH script -> the wizard jumps to the Script step.
+export default function CloneBar({ projectId, onCloned }) {
+  const [url, setUrl] = useState('')
+  const { running, progress, error, setError, start } = useJob()
+
+  const submit = async () => {
+    if (!url.trim()) return
+    try {
+      const result = await start(`/api/projects/${projectId}/clone`, { url: url.trim() })
+      setUrl('')
+      onCloned(result.reel) // {reel, script} — select the new reel
+    } catch { /* error already shown */ }
+  }
+
+  return (
+    <div className="card">
+      <div className="row">
+        <input
+          type="text"
+          className="grow"
+          placeholder="Clone a reel: paste a YouTube Shorts URL — a fresh script on the same topic, never the same footage or wording"
+          value={url}
+          disabled={running}
+          onChange={(e) => setUrl(e.target.value)}
+          onKeyDown={(e) => e.key === 'Enter' && submit()}
+        />
+        <button className="btn secondary" onClick={submit} disabled={running || !url.trim()}>
+          {running ? 'Cloning…' : 'Clone'}
+        </button>
+      </div>
+      {running && <div style={{ marginTop: 10 }}><ProgressBox progress={progress.length ? progress : ['Starting…']} /></div>}
+      <div style={{ marginTop: error ? 10 : 0 }}>
+        <ErrorBox error={error} onRetry={() => { setError(''); submit() }} />
+      </div>
+    </div>
+  )
+}

web/src/components/PromptPanel.jsx

@@ -0,0 +1,63 @@
+import { useState } from 'react'
+
+// Collapsible "view / edit the exact prompt before it runs" panel.
+//
+// `value` is the current prompt text (null = use the backend default).
+// `fetchPrompt` is an async () => string that assembles the default prompt
+// (some steps fetch live data to build it, so it may take a moment).
+// When the user edits the box, value diverges from the default — the run
+// button sends `value`; if the panel was never opened, value stays null and
+// the backend assembles the default itself.
+export default function PromptPanel({ fetchPrompt, value, setValue, disabled, label = 'prompt' }) {
+  const [open, setOpen] = useState(false)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState('')
+  const [original, setOriginal] = useState(null)
+
+  const load = async () => {
+    setLoading(true)
+    setError('')
+    try {
+      const p = await fetchPrompt()
+      setValue(p)
+      setOriginal(p)
+    } catch (e) {
+      setError(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const toggle = async () => {
+    if (!open && value == null) await load()
+    setOpen(!open)
+  }
+
+  const edited = value != null && original != null && value !== original
+
+  return (
+    <div className="prompt-panel">
+      <button className="prompt-toggle" onClick={toggle} disabled={disabled}>
+        {open ? '▾ Hide' : '▸ Show / edit'} the {label} prompt (advanced)
+        {edited && <span className="edited-badge">● edited</span>}
+      </button>
+      {open && (
+        <div>
+          <p className="prompt-hint">
+            This is the exact text sent to the model. Edit it to QC the output, then run. Your edits are used as-is.
+          </p>
+          {loading ? (
+            <p className="muted"><span className="spinner" />Assembling prompt…</p>
+          ) : error ? (
+            <div className="error-box">{error}</div>
+          ) : (
+            <textarea className="prompt-area" value={value || ''} onChange={(e) => setValue(e.target.value)} />
+          )}
+          <button className="btn small secondary" onClick={load} disabled={loading}>
+            ↺ Reset to default
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}