Mid Cuts v2 read-only viewer (Phase 4 deploy)

.gitattributes

@@ -33,3 +33,13 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp4 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,21 @@
 ---
 title: Mid Cuts
-emoji: 🦀
+emoji: 🎬
 colorFrom: gray
-colorTo: green
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 6.18.0
 app_file: app.py
 pinned: false
+short_description: Voice-narrated video cuts — Small Cuts v2 (read-only viewer)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Mid Cuts — Small Cuts v2 (read-only viewer)
+
+Whole-clip, voice-only cinematic narration (Qwen3-Omni) played with a near-native
+single-clock player. Scenes are produced by the `/v2/narrate` Modal pipeline, written to a
+private Hugging Face bucket, and pushed here via the relay hook (`/small-cuts/hooks/relay-scene`);
+the browser refreshes once from the `/small-cuts/events` SSE event — no polling.
+
+Read-only viewer: media is proxied **same-origin** (Range/206, Safari-seekable) so the private
+bucket is never exposed cross-origin.

app.py

@@ -0,0 +1,111 @@
+"""Hugging Face Space entrypoint for Small Cuts.
+
+Local dev keeps the lazy/mock defaults. On a Space this module refuses unsafe
+CPU local inference and never lets startup failures crash-loop the container:
+
+- ``import spaces`` happens before anything touches torch (ZeroGPU hijack).
+- The narrator loads lazily inside the ``@spaces.GPU`` event handler.
+- TTS runs inside @spaces.GPU workers too (kokoro's torch use poisons
+  worker forks if it ever runs in the main process).
+"""
+
+import os
+import sys
+import warnings
+from pathlib import Path
+
+from starlette.exceptions import StarletteDeprecationWarning
+
+ON_SPACE = bool(os.environ.get("SPACE_ID"))
+if ON_SPACE:
+    # HF Spaces defaults Gradio SSR on; its Node proxy shadows custom FastAPI SSE routes.
+    os.environ["GRADIO_SSR_MODE"] = "False"
+
+import gradio as gr  # noqa: E402
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+warnings.filterwarnings(
+    "ignore",
+    message=r".*HTTP_422_UNPROCESSABLE_ENTITY.*HTTP_422_UNPROCESSABLE_CONTENT.*",
+    category=StarletteDeprecationWarning,
+)
+
+ENGINE_MODE = bool(os.environ.get("SMALL_CUTS_ENGINE_URL", "").strip())
+
+from small_cuts.hf_relay import RELAY_BUCKET_ENV  # noqa: E402
+
+RELAY_MODE = bool(os.environ.get(RELAY_BUCKET_ENV, "").strip())
+MODAL_UPLOAD_MODE = bool(os.environ.get("SMALL_CUTS_MODAL_API_URL", "").strip())
+VIEWER_ONLY_MODE = ENGINE_MODE or RELAY_MODE or MODAL_UPLOAD_MODE
+NEEDS_LOCAL_INFERENCE = not VIEWER_ONLY_MODE
+
+try:
+    import spaces  # noqa: F401  (must precede torch imports for ZeroGPU)
+except ImportError:  # local dev / CI: no ZeroGPU
+    spaces = None
+
+if ON_SPACE and NEEDS_LOCAL_INFERENCE:
+    os.environ.setdefault("SMALL_CUTS_BACKEND", "transformers")
+    os.environ.setdefault("SMALL_CUTS_TTS_BACKEND", "kokoro")
+
+from small_cuts.observability import capture_exception, init_sentry  # noqa: E402
+from small_cuts.space_hooks import install_relay_hooks  # noqa: E402
+from small_cuts.viewer import THEME, build_viewer_app  # noqa: E402
+
+init_sentry()
+
+STARTUP_ERROR: str | None = None
+
+
+def _allow_cpu_inference() -> bool:
+    return os.environ.get("SMALL_CUTS_ALLOW_CPU_INFERENCE", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+
+def _validate_startup_mode() -> None:
+    if ON_SPACE and NEEDS_LOCAL_INFERENCE and spaces is None and not _allow_cpu_inference():
+        raise RuntimeError(
+            "refusing local inference on a Space without ZeroGPU; configure relay, engine, "
+            "or Modal upload mode, or set SMALL_CUTS_ALLOW_CPU_INFERENCE=1 explicitly"
+        )
+
+
+def _degraded_app(message: str) -> gr.Blocks:
+    with gr.Blocks(title="Small Cuts") as degraded:
+        gr.Markdown(
+            f"# Small Cuts is temporarily unavailable\n\nStartup configuration failed: `{message}`"
+        )
+    return degraded
+
+
+def _build_demo() -> gr.Blocks:
+    _validate_startup_mode()
+    # In engine/relay/upload modes the Space is a public reader and upload front door, so it must
+    # not warm local model weights. In local-inference mode, ZeroGPU loads lazily inside the
+    # Gradio handler decorated with @spaces.GPU.
+    app = build_viewer_app()
+    install_relay_hooks(app.app)
+    return app
+
+
+try:
+    demo = _build_demo()
+except Exception as exc:
+    capture_exception(exc)
+    STARTUP_ERROR = str(exc)
+    demo = _degraded_app(STARTUP_ERROR)
+
+
+def launch_demo():
+    return demo.launch(theme=THEME, _app=demo.app)
+
+
+if __name__ == "__main__":
+    launch_demo()

requirements.txt

@@ -0,0 +1,10 @@
+# Hugging Face Space runtime for live-demo viewer mode. Gradio + spaces are
+# platform-managed; inference and TTS run on the Mac Studio engine.
+pillow>=10.0
+pillow-heif>=0.18
+av>=12.0
+httpx>=0.27
+huggingface-hub>=1.19
+itsdangerous>=2.2
+sentry-sdk>=2.0
+soundfile>=0.12

src/small_cuts/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md — `src/small_cuts/` (space / view platform)
+
+Module-local notes for the **Gradio Space + viewer + narration/TTS/title-card** code. Global rules,
+the canonical command list, and the architecture live in the **root `CLAUDE.md`** and the **KB**
+(`10-projects/small-cuts/space/` and `…/architecture/`). Don't restate them here.
+
+## What's here
+- `app.py` (repo root) — HF Space entrypoint. `viewer.py` — the streaming-platform viewer.
+- `ui.py` (local dev UI) · `theme.py` (Off-Brand) · `narrator.py` / `tts.py` / `title_card.py` /
+  `styles.py` / `frames.py` — the narration pipeline pieces (shared with the engine).
+- `demo_seed.py` + `seed_media/` — the hero library (5 real glasses cuts: mp4 + poster + Kokoro mp3).
+- `_icons.py` — generated CSS icon masks (from `small_cuts_icon_set`); regenerate if the set changes.
+
+## Run
+- See root `CLAUDE.md` → `uv run --no-sync python app.py` (bare `uv run` prunes the `tts` extra).
+
+## Backend selection (env)
+- `SMALL_CUTS_BACKEND` = `mock` (default) | `transformers` (`Qwen/Qwen3-VL-8B-Instruct`) | `llama_cpp`.
+- `SMALL_CUTS_TTS_BACKEND` = `mock` (default) | `kokoro`. `get_backend()` / `get_tts_backend()` cache
+  one instance per key — do **not** construct backends per call (re-loads 16 GB on the Space).
+
+## Viewer modes + layout (`viewer.py`)
+- Decided at build time by env:
+  - **Pure relay mode**: `SMALL_CUTS_RELAY_BUCKET` set and upload sandbox unset. This is the current
+    safe development posture for a personal-profile staging Space (`macayaven/*`): viewer-only,
+    CPU Basic, no local model/TTS load, reads a finished-scene manifest + media from a personal HF
+    bucket relay.
+  - **Hybrid relay + upload mode**: `SMALL_CUTS_RELAY_BUCKET` and
+    `SMALL_CUTS_ENABLE_UPLOAD_SANDBOX=1` set. This is the target final submission posture if judges
+    need direct upload verification: relay stays the public library, upload calls Modal for real
+    narration/TTS on demand, and the submitted Space should remain CPU Basic. Prove this first through
+    a personal-profile Space/bucket plus the private Modal app `small-cuts-postcut`; promote to
+    `build-small-hackathon/small-cuts-buffer-poc` only after cold/warm timing, bucket artifact
+    writing, and playback smoke pass.
+  - **Engine mode**: `SMALL_CUTS_ENGINE_URL` set. Polls `GET /v1/scenes` from an engine/read-gate
+    endpoint. Keep this as a local/ops mode unless the current readiness doc explicitly switches back.
+  - **Upload mode**: neither relay nor engine env set. Local "try it" dropzone; useful for development
+    and fallback demos, not the active public relay architecture.
+- **Layout (Review-3 theater):** full-width top bar (Voice-Cut brand mark + upload icon), then a
+  two-column **theater** — left: 9:16 stage (ratio is a hard invariant) + display-only progress bar +
+  control **pill** (rewind/forward = **clip-to-clip**; custom player controls = **play/pause + volume**;
+  like no-count toggle + flag now **inside** the pill); right: the **Library** rail (gallery). Fits one
+  viewport — **no main scrollbar**; a `@media (max-width:860px)` query collapses to one column with a
+  horizontal gallery rail on mobile. Header = auto-title for finished cuts / **"● Happening now"** for
+  live capture, and is the clickable **back-to-live** affordance (the button is hidden, JS-forwarded).
+- **`SMALL_CUTS_SHOW_FEED`** (default off) revives the dropped narrator-chat feed (a future
+  "see transcription" surface for non-live clips).
+- **One playback clock (`PLAYBACK_SYNC_JS`):** media is **decoupled** and the **browser owns each
+  element's clock** — there is **no `gr.Audio`** (it can't be the clock; wavesurfer leaves its
+  `<audio>` unreadable). Narration is a hidden custom `<audio id="sc-voice">` (re-rendered per scene),
+  authoritative when present, else the muted looping `<video>`. The gold pill / progress / captions
+  are painted from **native media events** (`play`/`pause`/`timeupdate`) — **no `setInterval`, no
+  drift correction**; the muted b-roll free-runs. Captions ride `data-sc-cues`/`data-sc-chunks`
+  attributes on the subtitle div. **Boots PAUSED.** (Design-of-record: the 2026-06-17 native
+  single-clock player rewrite, in the KB.)
+
+## ZeroGPU gotchas (hard-won — see KB `…/space/`)
+- **HF deployment safety override (2026-06-15):** do not deploy this viewer, run upload smokes, or
+  write relay artifacts against `build-small-hackathon/*` during development. Use only personal
+  `macayaven/*` Spaces and buckets until the product is fully proven. The reserved org submission
+  Space is `build-small-hackathon/small-cuts-buffer-poc`, currently private/paused by Carlos, to be
+  renamed and made public only at final submission.
+- If a personal Space is paused and restart/rebuild returns `503`, stop all HF Space operations
+  immediately. Do not keep polling, restarting, uploading, changing variables/secrets, creating
+  replacement Spaces, or fetching logs. Verify locally or directly against Modal until Carlos
+  approves one explicit next HF Space action.
+- Current personal dev Space: `macayaven/small-cuts-dev`. It is private, on paid hardware above CPU
+  Basic, and has Dev Mode enabled for careful interactive work from Cursor/VS Code. Do not deploy,
+  restart, poll, mutate variables/secrets, open Dev Mode sessions, or smoke-test it without one
+  explicit approval from Carlos for that exact HF Space action.
+- In relay or engine viewer-only mode, the Space must not warm Qwen/Kokoro and should stay on
+  `cpu-basic`; ZeroGPU is only a fallback if Modal is ruled out and the Space itself performs
+  narration/TTS.
+- Relay refresh is push-triggered, not timer-polled. The publisher calls
+  `/small-cuts/hooks/relay-scene` after a successful bucket sync, and browsers refresh once from
+  the `/small-cuts/events` SSE event through a `gr.HTML(js_on_load=...)` custom event bridge.
+  Do not reintroduce `gr.Timer` relay polling or hidden-button click bridges.
+- `@spaces.GPU` must mark the functions **Gradio binds** (the startup scan walks event handlers);
+  decorating inner helpers → worker dies `No CUDA GPUs are available`.
+- **No torch forward in the main process ever** — TTS runs inside `@spaces.GPU(duration=…)` workers;
+  no main-process pre-warm (kokoro poisons worker forks otherwise).
+- Code is hardware-agnostic (`_gpu` no-ops off-Space): dedicated-GPU swap = one
+  `hf spaces settings --hardware …`. Iterate: `hf upload …`, `hf spaces variables …`, `hf spaces logs --tail`.
+
+## Design invariant
+- The Space is the **view platform + library**, not the capture path. Publishing/visibility happens
+  **only here**, never on the glasses (D10). Make it feel like a reference live-streaming platform.
+- Wearer controls stay product-clean: `Action!` starts a take and `Cut!` finalizes it. Do not add a
+  third publish button. Glasses-origin cuts are published from the already-generated local scene
+  artifacts after `Cut!` and should show a small glasses badge in the Space; browser-uploaded judge
+  cuts use Modal and should not get that badge.

src/small_cuts/__init__.py

@@ -0,0 +1,9 @@
+"""Small Cuts — an omniscient cinematic narrator powered by small open models."""
+
+from pillow_heif import register_heif_opener
+
+# iPhones shoot HEIC by default; registering once here covers every entry
+# point (Gradio app, eval harness) that opens images through PIL.
+register_heif_opener()
+
+__version__ = "0.1.0"

src/small_cuts/_icons.py

@@ -0,0 +1,24 @@
+# ruff: noqa: E501
+"""Generated icon mask-image CSS (from Carlos's small_cuts_icon_set).
+
+Each glyph is a 24x24 SVG rendered as a CSS mask so it inherits `currentColor`
+via `.sc-icbtn` (see VIEWER_CSS). Regenerate from the icon set if it changes.
+"""
+
+ICON_CSS = """
+:root { --sc-ico-glasses-mask: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-glasses-view%22%20fill%3D%22none%22%3E%20%3Ctitle%20id%3D%22title-glasses-view%22%3EGlasses%20view%3C%2Ftitle%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M3.8%2012.5c.3-2.4%201.6-3.7%203.6-3.7h2.1c1.1%200%201.8.8%201.8%201.8v1.9c0%202-1.5%203.7-3.6%203.7S4%2014.6%203.8%2012.5Z%22%2F%3E%20%3Cpath%20d%3D%22M20.2%2012.5c-.3-2.4-1.6-3.7-3.6-3.7h-2.1c-1.1%200-1.8.8-1.8%201.8v1.9c0%202%201.5%203.7%203.6%203.7s3.7-1.6%203.9-3.7Z%22%2F%3E%20%3Cpath%20d%3D%22M11.3%2011h1.4%22%2F%3E%20%3Cpath%20d%3D%22M4.6%209.9%203%208.7M19.4%209.9%2021%208.7%22%2F%3E%20%3Cpath%20d%3D%22M7.1%2010.4h1.8M15.1%2010.4h1.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+:root { --sc-ico-upload-mask: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Ctitle%20id%3D%22title-upload-video%22%3EUpload%20video%3C%2Ftitle%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-glasses { -webkit-mask-image: var(--sc-ico-glasses-mask); mask-image: var(--sc-ico-glasses-mask); }
+.sc-ico-upload { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-rewind { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-rewind%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M11.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L10%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M20.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L19%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-rewind%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M11.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L10%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M20.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L19%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-forward { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-forward%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M12.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L14%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M3.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L5%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-forward%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M12.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L14%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M3.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L5%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-like { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2011.2v7.3H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.5a1.4%201.4%200%200%201%201.4-1.4h2.4Z%22%2F%3E%20%3Cpath%20d%3D%22M7.2%2011.2%2010.8%205c.42-.72%201.5-.48%201.58.35l.18%201.9a4.2%204.2%200%200%201-.53%202.43l-.75%201.32h5.6a2%202%200%200%201%201.95%202.45l-1%204.2a2.4%202.4%200%200%201-2.34%201.85H7.2%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2011.2v7.3H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.5a1.4%201.4%200%200%201%201.4-1.4h2.4Z%22%2F%3E%20%3Cpath%20d%3D%22M7.2%2011.2%2010.8%205c.42-.72%201.5-.48%201.58.35l.18%201.9a4.2%204.2%200%200%201-.53%202.43l-.75%201.32h5.6a2%202%200%200%201%201.95%202.45l-1%204.2a2.4%202.4%200%200%201-2.34%201.85H7.2%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-like-filled { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like-filled%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M7.2%2011.15v7.35H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.55a1.4%201.4%200%200%201%201.4-1.4h2.4Zm1.2%207.35h6.75a2.45%202.45%200%200%200%202.38-1.88l1-4.15A2.02%202.02%200%200%200%2016.57%2010h-3.64l.18-.33a4.35%204.35%200%200%200%20.55-2.52l-.18-1.87c-.16-1.66-2.32-2.1-3.16-.66L8.4%207.93v10.57Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like-filled%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M7.2%2011.15v7.35H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.55a1.4%201.4%200%200%201%201.4-1.4h2.4Zm1.2%207.35h6.75a2.45%202.45%200%200%200%202.38-1.88l1-4.15A2.02%202.02%200%200%200%2016.57%2010h-3.64l.18-.33a4.35%204.35%200%200%200%20.55-2.52l-.18-1.87c-.16-1.66-2.32-2.1-3.16-.66L8.4%207.93v10.57Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-flag { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-flag-filled { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag-filled%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag-filled%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-mark { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-small-cuts-mark%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Crect%20x%3D%225%22%20y%3D%224.5%22%20width%3D%2214%22%20height%3D%2215%22%20rx%3D%222.2%22%2F%3E%20%3Cpath%20d%3D%22M9%204.5v15M15%204.5v15%22%2F%3E%20%3Cpath%20d%3D%22M5%208.5h4M15%208.5h4M5%2015.5h4M15%2015.5h4%22%2F%3E%20%3Cpath%20d%3D%22M8.5%2016.5%2015.8%207.2%22%2F%3E%20%3Cpath%20d%3D%22M10.8%2017.2h4.7%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-small-cuts-mark%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Crect%20x%3D%225%22%20y%3D%224.5%22%20width%3D%2214%22%20height%3D%2215%22%20rx%3D%222.2%22%2F%3E%20%3Cpath%20d%3D%22M9%204.5v15M15%204.5v15%22%2F%3E%20%3Cpath%20d%3D%22M5%208.5h4M15%208.5h4M5%2015.5h4M15%2015.5h4%22%2F%3E%20%3Cpath%20d%3D%22M8.5%2016.5%2015.8%207.2%22%2F%3E%20%3Cpath%20d%3D%22M10.8%2017.2h4.7%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-play { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M8.5%206.7v10.6c0%20.72.78%201.17%201.4.8l8.36-5.3a.95.95%200%200%200%200-1.6L9.9%205.9c-.62-.39-1.4.06-1.4.8Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M8.5%206.7v10.6c0%20.72.78%201.17%201.4.8l8.36-5.3a.95.95%200%200%200%200-1.6L9.9%205.9c-.62-.39-1.4.06-1.4.8Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); }
+.sc-ico-pause { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Crect%20x%3D%227%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3Crect%20x%3D%2213.4%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Crect%20x%3D%227%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3Crect%20x%3D%2213.4%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); }
+.sc-ico-volume { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22M15.2%209.2a4.2%204.2%200%200%201%200%205.6%22%2F%3E%3Cpath%20d%3D%22M17.5%207a7.4%207.4%200%200%201%200%2010%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22M15.2%209.2a4.2%204.2%200%200%201%200%205.6%22%2F%3E%3Cpath%20d%3D%22M17.5%207a7.4%207.4%200%200%201%200%2010%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); }
+.sc-ico-volume-muted { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22m16%209.2%204.2%204.2M20.2%209.2%2016%2013.4%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22m16%209.2%204.2%204.2M20.2%209.2%2016%2013.4%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); }
+"""

src/small_cuts/demo_seed.py

@@ -0,0 +1,81 @@
+"""Seeded 'hero' library — curated VIDEO cuts so the Space loads alive.
+
+Real first-person glasses moments, **muted** (the generated narration is the only
+audio, which also strips any incidental conversation), narrated in the one signature
+deadpan voice. The live "Try it" sandbox runs the real model; this seed just gives a
+first-time visitor a channel with a few finished cuts to scroll. Five short, compressed,
+face-free clips so the Space boots fast and respects bystander privacy.
+"""
+
+from __future__ import annotations
+
+import os
+
+from PIL import Image
+
+STYLE_KEY = "deadpan"
+SEED_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "seed_media")
+
+# (clip, poster, title, narration, visibility) — ordered oldest → newest.
+SEED: list[tuple[str, str, str, str, str]] = [
+    (
+        "desk-laptop.mp4",
+        "desk-laptop.jpg",
+        "Debugging His Own Ambition",
+        "It is late — the specific, self-inflicted late of someone building a thing nobody "
+        "asked for. On the monitor a small game he is making flickers half-finished, its rules "
+        "still being argued into existence. His hands move with the patience of a man debugging "
+        "his own ambition, and the coffee, just off-frame, went cold around the last good idea.",
+        "private",
+    ),
+    (
+        "the-stumble.mp4",
+        "the-stumble.jpg",
+        "He Meant to Do That",
+        "He has stepped out of the bar for air and the small chemical comfort of the vape, and "
+        "the pavement, sensing an opening, tilts very slightly underfoot. He recovers, as one "
+        "does, with the careful dignity of a man who would prefer the record to show he meant to "
+        "do that. The night says nothing. It has seen steadier, and worse.",
+        "private",
+    ),
+    (
+        "street-parked-car.mp4",
+        "street-parked-car.jpg",
+        "Just Five Minutes",
+        "The car is parked with the easy confidence of a driver who said 'just five minutes' and "
+        "meant it the way everyone means it. The street is in no hurry to disagree. Somewhere "
+        "nearby a meter is running, patient and unread.",
+        "public",
+    ),
+    (
+        "night-drive.mp4",
+        "night-drive.jpg",
+        "Photographs Well at Night",
+        "The city slides past at the speed of someone who knows the way and feels no need to "
+        "prove it. Streetlight opens and closes on the windshield; the older facades hold their "
+        "glow a little longer than the new ones. He is driving through the part of town that "
+        "photographs well at night, which is, if one is honest about Barcelona, most of it.",
+        "public",
+    ),
+    (
+        "rayuela.mp4",
+        "rayuela.jpg",
+        "The Stone Almost Never Reaches the Sky",
+        "Through the wire, a hopscotch waits on the schoolyard floor, its chalk gone soft with "
+        "weather. At the bottom is the Earth; at the top, the Sky — and the old difficulty "
+        "between them, that the stone, nudged by the toe of a shoe, almost never reaches the "
+        "Sky. He passes on the far side of the fence now, a grown man in grown shoes, and does "
+        "not stop. The ingredients were always so small: a sidewalk, a stone, the tip of a shoe.",
+        "public",
+    ),
+]
+
+
+def clip_path(name: str) -> str:
+    """Absolute path to a bundled seed clip (served via gr.set_static_paths)."""
+    return os.path.join(SEED_DIR, name)
+
+
+def load_poster(name: str) -> Image.Image:
+    """Load a bundled poster frame (the still shown before the clip plays / in the shelf)."""
+    return Image.open(os.path.join(SEED_DIR, name)).convert("RGB")

src/small_cuts/engine/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md — `src/small_cuts/engine/` (inference / home node)
+
+Module-local notes for the **real-time home-node engine**. Global rules + canonical commands are in
+the **root `CLAUDE.md`**; the pipeline design + decisions are in the **KB**
+(`10-projects/small-cuts/inference/` and `…/architecture/`). Contract shapes: `docs/contracts/`.
+
+## What's here
+- `app.py` — FastAPI factory. `session.py` — WS `/v1/session` runner (D8 coalesce-to-newest, one
+  ack per envelope, honest retries). `library.py` — SceneLibrary (sqlite-WAL + media files, in-proc
+  pub/sub, SSE replay). `__main__.py` — uvicorn entry.
+- Endpoints: WS `/v1/session` · `GET /v1/scenes` · SSE `GET /v1/scenes/stream` (Last-Event-ID) ·
+  `PATCH /v1/scenes/{id}` (visibility — the viewer's only write) · `GET /media/{scene}/{file}`.
+
+## Run (needs `uv sync --extra engine`)
+```bash
+SMALL_CUTS_BACKEND=llama_cpp SMALL_CUTS_TTS_BACKEND=kokoro uv run python -m small_cuts.engine  # :8077
+SMALL_CUTS_BACKEND=mock uv run python -m small_cuts.engine                                      # smoke
+```
+- **Warm it first:** cold first moment ≈ 17 s (llama-server spawn + model load); warm e2e ≈ 5.7–6.9 s
+  (≤10 s budget). Send one throwaway moment after start.
+
+## Env
+`SMALL_CUTS_ENGINE_HOST`/`_PORT` (127.0.0.1 / 8077; set host explicitly for LAN/Tailnet) ·
+`_LIBRARY_DIR` (`~/.small-cuts/library`) ·
+`_GGUF_PATH`/`_MMPROJ_PATH` · `_LLAMA_SERVER` (binary) · `_LLAMA_URL` (external server, skips spawn) ·
+`_MODEL_ID` · `_TEMPERATURE` (0.3).
+
+## llama.cpp
+- `brew install llama.cpp` → `llama-server` on PATH; spawns lazily on first moment. **Keep the
+  `--image-max-tokens 1024` floor** (Qwen-VL grounding; portrait glasses frames OOM Metal without it).
+- CI uses an in-process fake OpenAI server — no real model needed.
+
+## Inspect a running engine
+- Loopback: `http://127.0.0.1:8077/v1/scenes` (JSON) ·
+  `curl -N http://127.0.0.1:8077/v1/scenes/stream` (SSE).
+- LAN/Tailnet: set `SMALL_CUTS_ENGINE_HOST=0.0.0.0`, then use the host name, e.g.
+  `http://mac-studio:8077/v1/scenes`.
+- Library files live at `~/.small-cuts/library`. Engine validates every frame against
+  `docs/contracts/`.

src/small_cuts/engine/__init__.py

@@ -0,0 +1,9 @@
+"""Home-node narration engine — mobile-facing WebSocket session (Team Inference).
+
+Optional install: `uv sync --extra engine`. Nothing in the existing app path
+imports this package, so the Space/UI keep working without the extra.
+"""
+
+from .app import build_engine_app
+
+__all__ = ["build_engine_app"]

src/small_cuts/engine/__main__.py

@@ -0,0 +1,33 @@
+"""Run the engine: `uv run python -m small_cuts.engine`."""
+
+import contextlib
+import os
+import signal
+
+import uvicorn
+
+from .app import build_engine_app
+
+
+def main() -> None:
+    from small_cuts import narrator
+
+    def shutdown(signum, frame):  # noqa: ARG001
+        with contextlib.suppress(Exception):
+            backend = narrator.get_backend()
+            close = getattr(backend, "close", None)
+            if close is not None:
+                close()
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, shutdown)
+    uvicorn.run(
+        build_engine_app(),
+        host=os.environ.get("SMALL_CUTS_ENGINE_HOST", "127.0.0.1"),
+        port=int(os.environ.get("SMALL_CUTS_ENGINE_PORT", "8077")),
+        ws_max_size=int(os.environ.get("SMALL_CUTS_ENGINE_WS_MAX_SIZE", str(64 * 1024 * 1024))),
+    )
+
+
+if __name__ == "__main__":
+    main()

src/small_cuts/engine/app.py

@@ -0,0 +1,152 @@
+"""App factory for the home-node narration engine (Team Inference).
+
+One WebSocket per wearing session (`/v1/session`), plus the viewer-facing
+side of docs/contracts: the scene library REST API (D6) and the live SSE
+scene stream with Last-Event-ID resume (D7).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any, Literal
+
+from fastapi import FastAPI, HTTPException, Query, Request, WebSocket
+from fastapi.responses import FileResponse, StreamingResponse
+from pydantic import BaseModel
+
+from .library import SceneLibrary
+from .session import EngineState, SceneSink, SessionRunner
+
+SSE_HEARTBEAT_S = 15.0
+
+Visibility = Literal["private", "shared", "public"]
+
+
+class VisibilityPatch(BaseModel):
+    visibility: Visibility
+
+
+def _sse_event(event: dict[str, Any]) -> str:
+    data = f"data: {json.dumps(event)}\n\n"
+    seq = event.get("seq")
+    # No seq -> ephemeral event (error frames): no id line, so it never becomes
+    # a Last-Event-ID resume cursor and is never expected in replay.
+    return data if seq is None else f"id: {seq}\n{data}"
+
+
+def _last_event_id(raw: str | None) -> int | None:
+    """SSE resume cursor; absent or unparsable means a fresh connect, live only."""
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+async def scene_event_stream(
+    library: SceneLibrary, last_event_id: int | None, heartbeat_s: float
+) -> AsyncIterator[str]:
+    """SSE body: replay seq > Last-Event-ID, then live events; pings while idle.
+
+    Live events without a seq (pipeline errors) pass straight through —
+    they are ephemeral and never part of replay.
+    """
+    queue = library.subscribe()
+    try:
+        last_seq = -1
+        if last_event_id is not None:
+            last_seq = last_event_id
+            for scene in library.scenes_since(last_event_id):
+                last_seq = scene["seq"]
+                yield _sse_event(scene)
+        while True:
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=heartbeat_s)
+            except asyncio.TimeoutError:
+                yield ": ping\n\n"
+                continue
+            # Invariant: the library publishes each seq exactly once, so live
+            # events never need dedupe against each other. `last_seq` stays
+            # frozen at the replay boundary — it only filters scenes that were
+            # both replayed and queued (stored before replay, published after
+            # subscribe). It must NOT advance here: store() commits seq under
+            # the lock in a worker thread but publishes later on the loop, so
+            # concurrent sessions can publish out of seq order, and a moving
+            # cursor would drop the lower seq forever.
+            seq = event.get("seq")
+            if seq is not None and seq <= last_seq:
+                continue
+            yield _sse_event(event)
+    finally:
+        library.unsubscribe(queue)
+
+
+def build_engine_app(
+    scene_sink: SceneSink | None = None,
+    library: SceneLibrary | None = None,
+    sse_heartbeat_s: float = SSE_HEARTBEAT_S,
+) -> FastAPI:
+    """Engine app: session socket + scene library + SSE stream, per docs/contracts.
+
+    By default scenes are persisted to a `SceneLibrary` (root from
+    `SMALL_CUTS_LIBRARY_DIR`); pass `library` to inject one, or `scene_sink`
+    to replace the sink entirely (tests).
+    """
+    lib = library if library is not None else SceneLibrary()
+    sink = scene_sink if scene_sink is not None else lib
+    # Errors fan out to the viewer stream too (D9): the timeline shows failures.
+    state = EngineState(sink=sink, error_sink=lib.publish_event)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        try:
+            yield
+        finally:
+            close = getattr(app.state.library, "close", None)
+            if close is not None:
+                close()
+
+    app = FastAPI(title="small-cuts engine", lifespan=lifespan)
+    app.state.library = lib
+
+    @app.websocket("/v1/session")
+    async def session(websocket: WebSocket) -> None:
+        await websocket.accept()
+        await SessionRunner(websocket, state).run()
+
+    @app.get("/v1/scenes")
+    def list_scenes(
+        session: str | None = None,
+        visibility: Visibility | None = None,
+        limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+    ) -> dict[str, list[dict[str, Any]]]:
+        return {"scenes": lib.list_scenes(session_id=session, visibility=visibility, limit=limit)}
+
+    @app.get("/v1/scenes/stream")
+    async def stream_scenes(request: Request) -> StreamingResponse:
+        resume_from = _last_event_id(request.headers.get("last-event-id"))
+        return StreamingResponse(
+            scene_event_stream(lib, resume_from, sse_heartbeat_s),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache"},
+        )
+
+    @app.patch("/v1/scenes/{scene_id}")
+    def set_visibility(scene_id: str, patch: VisibilityPatch) -> dict[str, Any]:
+        scene = lib.set_visibility(scene_id, patch.visibility)
+        if scene is None:
+            raise HTTPException(status_code=404, detail=f"unknown scene {scene_id}")
+        return scene
+
+    @app.get("/media/{scene_id}/{filename}")
+    def media(scene_id: str, filename: str) -> FileResponse:
+        path = lib.media_path(scene_id, filename)
+        if path is None:  # unknown name, traversal attempt, or missing file
+            raise HTTPException(status_code=404, detail="no such media")
+        return FileResponse(path)
+
+    return app

src/small_cuts/engine/library.py

@@ -0,0 +1,377 @@
+"""Engine-side scene library: filesystem media + sqlite index (D6).
+
+The real `SceneSink`. Every successful narration is persisted — frame JPEG,
+title card, voice WAV, one sqlite row — and fanned out to live SSE
+subscribers (D7). Blocking writes run in a worker thread via
+`asyncio.to_thread`; the publish happens back on the event loop. Stored
+entries and live events share the same NarratedScene shape, per
+docs/contracts/narrated-scene.schema.json.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import sqlite3
+import sys
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from small_cuts import narrator, tts
+from small_cuts.frames import pick_key_frame
+from small_cuts.title_card import TITLE_MAX_LEN, derive_title, render_title_card
+
+from .session import CONTRACT_VERSION, _wav_bytes
+
+DEFAULT_ROOT = "~/.small-cuts/library"
+OWNER = "carlos"  # v1 engines are single-user; the field is reserved for multi-user
+VISIBILITIES = ("private", "shared", "public")
+MEDIA_FILES = ("frame.jpg", "card.webp", "voice.wav", "clip.mp4")
+STORAGE_TIMEOUT_S = 30.0
+SUBSCRIBER_QUEUE_MAX = 256
+CLIP_MP4_FPS = 12
+CLIP_BLEND_STEPS = 1
+H264_MIN_DIMENSION = 2
+POSTER_JPEG_QUALITY = 90
+RGB_MODE = "RGB"
+VIDEO_PIXEL_FORMAT = "yuv420p"
+PRIMARY_VIDEO_CODEC = "libx264"
+FALLBACK_VIDEO_CODEC = "h264"
+
+_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS scenes (
+    scene_id    TEXT PRIMARY KEY,
+    seq         INTEGER NOT NULL UNIQUE,
+    moment_id   TEXT NOT NULL,
+    session_id  TEXT NOT NULL,
+    captured_at TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    style_key   TEXT NOT NULL,
+    title       TEXT NOT NULL,
+    narration   TEXT NOT NULL,
+    visibility  TEXT NOT NULL DEFAULT 'private',
+    owner       TEXT NOT NULL,
+    engine      TEXT NOT NULL
+)"""
+
+_INSERT = """\
+INSERT INTO scenes (scene_id, seq, moment_id, session_id, captured_at, created_at,
+                    style_key, title, narration, visibility, owner, engine)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"""
+
+
+class SceneLibrary:
+    """Scene store + in-process pub/sub. The instance itself is the async SceneSink.
+
+    Layout: `<root>/library.sqlite3` + `<root>/media/<scene_id>/{frame.jpg,
+    card.webp, voice.wav}`. One sqlite connection, guarded by a lock: the
+    sink writes from worker threads, queries come from request handlers.
+    """
+
+    def __init__(self, root: str | Path | None = None) -> None:
+        base = root or os.environ.get("SMALL_CUTS_LIBRARY_DIR") or DEFAULT_ROOT
+        self.root = Path(base).expanduser().resolve()
+        self.media_dir = self.root / "media"
+        self.media_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()  # guards the connection and seq allocation
+        self._db = sqlite3.connect(self.root / "library.sqlite3", check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        with self._lock, self._db:
+            # WAL + busy_timeout: viewer reads don't block sink writes, and a
+            # briefly locked database waits instead of raising immediately.
+            self._db.execute("PRAGMA journal_mode=WAL")
+            self._db.execute("PRAGMA busy_timeout=5000")
+            self._db.execute(_SCHEMA)
+        self._subscribers: list[asyncio.Queue[dict[str, Any]]] = []
+
+    # -- the sink -----------------------------------------------------------------
+
+    async def __call__(self, scene: dict[str, Any]) -> None:
+        """SceneSink entry point: persist off the event loop, then publish.
+
+        A failed store (disk full, sqlite error) must not be silent data loss:
+        the mobile client already received its SceneAudio, so log to stderr and
+        fan an error ControlFrame to the viewer stream — the timeline stays
+        honest. `_hand_to_sink`'s suppression remains the last-resort backstop.
+        """
+        try:
+            narrated = await asyncio.wait_for(
+                asyncio.to_thread(self.store, scene), timeout=STORAGE_TIMEOUT_S
+            )
+        except (Exception, asyncio.TimeoutError) as exc:
+            print(
+                f"small_cuts.engine: library write failed for scene {scene['scene_id']}: {exc!r}",
+                file=sys.stderr,
+            )
+            self.publish_event(
+                {
+                    "contract_version": CONTRACT_VERSION,
+                    "kind": "error",
+                    "moment_id": scene["moment_id"],
+                    "error": {
+                        "stage": "storage",
+                        "code": "library_write_failed",
+                        "message": str(exc)[:300],
+                        "retryable": False,
+                    },
+                }
+            )
+            return
+        self.publish_event(narrated)
+
+    def publish_event(self, payload: dict[str, Any]) -> None:
+        """Fan any event (stored scene or ControlFrame error) to live subscribers.
+
+        Events without a seq (errors) are EPHEMERAL: not persisted, not in Last-Event-ID replay.
+        """
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                self.unsubscribe(queue)
+
+    def store(self, scene: dict[str, Any]) -> dict[str, Any]:
+        """Persist media + index row (blocking); returns the stored NarratedScene."""
+        scene_id: str = scene["scene_id"]
+        narration: str = scene["narration"]
+        style_key: str = scene["style_key"]
+        title = _stored_title(scene.get("title"), narration)
+
+        scene_dir = self.media_dir / scene_id
+        scene_dir.mkdir(parents=True, exist_ok=True)
+        clip_frames = scene.get("clip_frames") or []
+        poster = pick_key_frame(clip_frames) if clip_frames else scene["image"]
+        poster.convert(RGB_MODE).save(scene_dir / "frame.jpg", "JPEG", quality=POSTER_JPEG_QUALITY)
+        if len(clip_frames) >= 2:
+            try:
+                _write_clip_mp4(scene_dir / "clip.mp4", clip_frames)
+            except Exception as exc:
+                print(
+                    f"small_cuts.engine: clip write failed for scene {scene_id}: {exc!r}",
+                    file=sys.stderr,
+                )
+        render_title_card(title, style_key).save(scene_dir / "card.webp", "WEBP")
+        (scene_dir / "voice.wav").write_bytes(_wav_bytes(scene["audio"], scene["sample_rate"]))
+
+        narrator_backend = narrator.get_backend()
+        tts_backend = tts.get_tts_backend()
+        engine = {
+            "narrator_model": narrator_backend.model_id,
+            "narrator_backend": narrator_backend.name,
+            "tts_model": tts_backend.model_id,
+            "latency_ms": scene["latency_ms"],
+        }
+        with self._lock, self._db:
+            # max+1 under the lock: monotonic across the process AND across restarts.
+            seq = self._db.execute("SELECT COALESCE(MAX(seq), -1) + 1 FROM scenes").fetchone()[0]
+            self._db.execute(
+                _INSERT,
+                (
+                    scene_id,
+                    seq,
+                    scene["moment_id"],
+                    scene["session_id"],
+                    _normalize_datetime(scene["captured_at"]),
+                    _normalize_datetime(scene["created_at"]),
+                    style_key,
+                    title,
+                    narration,
+                    "private",
+                    _owner(),
+                    json.dumps(engine),
+                ),
+            )
+        stored = self.get(scene_id)
+        if stored is None:
+            raise RuntimeError(f"scene {scene_id} missing immediately after insert")
+        return stored
+
+    # -- queries ---------------------------------------------------------------------
+
+    def to_narrated_scene(self, row: sqlite3.Row) -> dict[str, Any]:
+        """Contract-valid NarratedScene (1.1.0) for one stored row."""
+        scene_id = row["scene_id"]
+        media = {
+            "frame_url": f"/media/{scene_id}/frame.jpg",
+            "card_url": f"/media/{scene_id}/card.webp",
+            "audio_url": f"/media/{scene_id}/voice.wav",
+        }
+        if (self.media_dir / scene_id / "clip.mp4").is_file():
+            media["clip_url"] = f"/media/{scene_id}/clip.mp4"
+        return {
+            "contract_version": CONTRACT_VERSION,
+            "scene_id": scene_id,
+            "moment_id": row["moment_id"],
+            "session_id": row["session_id"],
+            "captured_at": row["captured_at"],
+            "created_at": row["created_at"],
+            "style_key": row["style_key"],
+            "title": row["title"],
+            "narration": row["narration"],
+            "visibility": row["visibility"],
+            "seq": row["seq"],
+            "owner": row["owner"],
+            "media": media,
+            "engine": json.loads(row["engine"]),
+        }
+
+    def list_scenes(
+        self,
+        session_id: str | None = None,
+        visibility: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Newest bounded window, returned in scene chronology for the viewer."""
+        clauses, params = [], []
+        if session_id is not None:
+            clauses.append("session_id = ?")
+            params.append(session_id)
+        if visibility is not None:
+            clauses.append("visibility = ?")
+            params.append(visibility)
+        where = f" WHERE {' AND '.join(clauses)}" if clauses else ""
+        query = (
+            "SELECT * FROM ("
+            f"SELECT * FROM scenes{where} ORDER BY seq DESC LIMIT ?"
+            ") ORDER BY captured_at, seq"
+        )
+        with self._lock:
+            rows = self._db.execute(query, (*params, limit)).fetchall()
+        return [self.to_narrated_scene(row) for row in rows]
+
+    def get(self, scene_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            row = self._db.execute(
+                "SELECT * FROM scenes WHERE scene_id = ?", (scene_id,)
+            ).fetchone()
+        return self.to_narrated_scene(row) if row is not None else None
+
+    def set_visibility(self, scene_id: str, visibility: str) -> dict[str, Any] | None:
+        """The viewer's only write (D7). Returns the updated scene, or None if unknown."""
+        if visibility not in VISIBILITIES:
+            raise ValueError(f"Unknown visibility {visibility!r}; expected one of {VISIBILITIES}")
+        with self._lock, self._db:
+            updated = self._db.execute(
+                "UPDATE scenes SET visibility = ? WHERE scene_id = ?", (visibility, scene_id)
+            ).rowcount
+        return self.get(scene_id) if updated else None
+
+    def scenes_since(self, seq: int) -> list[dict[str, Any]]:
+        """Scenes with seq > `seq`, ordered by seq — the SSE Last-Event-ID replay."""
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT * FROM scenes WHERE seq > ? ORDER BY seq", (seq,)
+            ).fetchall()
+        return [self.to_narrated_scene(row) for row in rows]
+
+    def media_path(self, scene_id: str, filename: str) -> Path | None:
+        """Resolve a media file, or None: unknown name, traversal, or missing file."""
+        if filename not in MEDIA_FILES:
+            return None
+        path = (self.media_dir / scene_id / filename).resolve()
+        if not path.is_relative_to(self.media_dir):  # traversal via scene_id
+            return None
+        return path if path.is_file() else None
+
+    # -- pub/sub ----------------------------------------------------------------------
+
+    def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        """New-scene feed for one SSE connection; pair with `unsubscribe`."""
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=SUBSCRIBER_QUEUE_MAX)
+        self._subscribers.append(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        with contextlib.suppress(ValueError):
+            self._subscribers.remove(queue)
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+
+def _write_clip_mp4(
+    path: Path,
+    frames: list[Image.Image],
+    fps: int = CLIP_MP4_FPS,
+    blend_steps: int = CLIP_BLEND_STEPS,
+) -> None:
+    """Render a small browser-playable MP4 from sampled POV frames."""
+    import av
+
+    rgb_frames = [frame.convert(RGB_MODE) for frame in frames]
+    width, height = rgb_frames[0].size
+    # H.264/yuv420p expects even dimensions. Preserve portrait aspect and only
+    # shave one pixel if needed; capture frames are already downscaled upstream.
+    width = max(H264_MIN_DIMENSION, width - (width % 2))
+    height = max(H264_MIN_DIMENSION, height - (height % 2))
+    encode_frames = _smooth_clip_frames(rgb_frames, blend_steps=blend_steps, size=(width, height))
+
+    container = av.open(str(path), "w")
+    try:
+        try:
+            stream = container.add_stream(PRIMARY_VIDEO_CODEC, rate=fps)
+        except Exception:
+            stream = container.add_stream(FALLBACK_VIDEO_CODEC, rate=fps)
+        stream.width = width
+        stream.height = height
+        stream.pix_fmt = VIDEO_PIXEL_FORMAT
+
+        for image in encode_frames:
+            frame = av.VideoFrame.from_image(image)
+            for packet in stream.encode(frame):
+                container.mux(packet)
+        for packet in stream.encode():
+            container.mux(packet)
+    finally:
+        container.close()
+
+
+def _smooth_clip_frames(
+    frames: list[Image.Image],
+    blend_steps: int = CLIP_BLEND_STEPS,
+    size: tuple[int, int] | None = None,
+) -> list[Image.Image]:
+    """Insert tiny cross-dissolve frames so sampled POV clips do not hard-cut."""
+    if not frames:
+        return []
+    prepared = []
+    for image in frames:
+        image = image.convert(RGB_MODE)
+        if size is not None and image.size != size:
+            image = image.resize(size, Image.Resampling.LANCZOS)
+        prepared.append(image)
+    if blend_steps <= 0 or len(prepared) < 2:
+        return prepared
+
+    smoothed = [prepared[0]]
+    for previous, current in zip(prepared, prepared[1:], strict=False):
+        for step in range(1, blend_steps + 1):
+            alpha = step / (blend_steps + 1)
+            smoothed.append(Image.blend(previous, current, alpha))
+        smoothed.append(current)
+    return smoothed
+
+
+def _stored_title(raw_title: object, narration: str) -> str:
+    if isinstance(raw_title, str) and raw_title.strip():
+        return derive_title(raw_title, max_len=TITLE_MAX_LEN)
+    return derive_title(narration, max_len=TITLE_MAX_LEN)
+
+
+def _owner() -> str:
+    return os.environ.get("SMALL_CUTS_ENGINE_OWNER", OWNER)
+
+
+def _normalize_datetime(value: str) -> str:
+    raw = value.replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(raw)
+    if parsed.tzinfo is None:
+        raise ValueError(f"timestamp must include timezone: {value}")
+    return parsed.astimezone(timezone.utc).isoformat()

src/small_cuts/engine/read_gate.py

@@ -0,0 +1,108 @@
+"""Read-only public gate for the live-demo engine surface.
+
+The capture/write socket stays private on Tailnet. This app is the origin behind the public
+Cloudflare Tunnel hostname and only proxies viewer/library reads through to the local engine.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.responses import PlainTextResponse, Response, StreamingResponse
+
+ORIGIN_ENV = "SMALL_CUTS_ORIGIN_ENGINE_URL"
+DEFAULT_ORIGIN = "http://127.0.0.1:8077"
+READ_TIMEOUT = httpx.Timeout(connect=5.0, read=30.0, write=5.0, pool=5.0)
+STREAM_TIMEOUT = httpx.Timeout(connect=5.0, read=None, write=5.0, pool=5.0)
+BLOCKED_TEXT = "small-cuts public endpoint is read-only\n"
+HOP_BY_HOP_HEADERS = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
+
+
+def is_public_read_allowed(method: str, path: str) -> bool:
+    if method.upper() != "GET":
+        return False
+    return path in ("/v1/scenes", "/v1/scenes/stream") or path.startswith("/media/")
+
+
+def _forward_headers(headers: httpx.Headers | dict[str, str]) -> dict[str, str]:
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() not in HOP_BY_HOP_HEADERS and key.lower() != "host"
+    }
+
+
+def _origin_url(origin_url: str, request: Request) -> str:
+    url = f"{origin_url.rstrip('/')}{request.url.path}"
+    return f"{url}?{request.url.query}" if request.url.query else url
+
+
+def _timeout_for_path(path: str) -> httpx.Timeout:
+    return STREAM_TIMEOUT if path == "/v1/scenes/stream" else READ_TIMEOUT
+
+
+async def _proxy_body(upstream: httpx.Response) -> AsyncIterator[bytes]:
+    try:
+        async for chunk in upstream.aiter_raw():
+            yield chunk
+    finally:
+        await upstream.aclose()
+
+
+def build_read_gate_app(origin_url: str | None = None) -> FastAPI:
+    origin = (origin_url or os.environ.get(ORIGIN_ENV) or DEFAULT_ORIGIN).rstrip("/")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.client = httpx.AsyncClient()
+        try:
+            yield
+        finally:
+            await app.state.client.aclose()
+
+    app = FastAPI(title="small-cuts public read gate", lifespan=lifespan)
+
+    @app.api_route(
+        "/{path:path}",
+        methods=["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+        response_model=None,
+    )
+    async def public_gate(path: str, request: Request) -> Response:
+        if not is_public_read_allowed(request.method, request.url.path):
+            return PlainTextResponse(BLOCKED_TEXT, status_code=403)
+
+        client: httpx.AsyncClient = request.app.state.client
+        upstream = await client.send(
+            client.build_request(
+                "GET",
+                _origin_url(origin, request),
+                headers=_forward_headers(request.headers),
+                timeout=_timeout_for_path(request.url.path),
+            ),
+            stream=True,
+        )
+
+        return StreamingResponse(
+            _proxy_body(upstream),
+            status_code=upstream.status_code,
+            headers=_forward_headers(upstream.headers),
+            media_type=upstream.headers.get("content-type"),
+        )
+
+    return app
+
+
+app = build_read_gate_app()

src/small_cuts/engine/session.py

@@ -0,0 +1,470 @@
+"""Mobile-facing WebSocket session for the narration engine.
+
+MomentEnvelope in, ControlFrame + SceneAudio out, per docs/contracts.
+Backpressure is D8 (queue depth <= 1, coalesce-to-newest); freshness is D9
+(`play_by` = created_at + 60 s). Pipeline failures become error frames —
+the socket itself never crashes on a bad moment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import inspect
+import io
+import json
+import os
+import sys
+import time
+import uuid
+import wave
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import numpy as np
+from fastapi import WebSocket, WebSocketDisconnect
+from PIL import Image
+
+from small_cuts import narrator, tts
+from small_cuts.styles import DEFAULT_STYLE_KEY
+
+CONTRACT_VERSION = "1.1.0"
+PLAY_BY_SECONDS = 60
+MAX_FRAME_SIDE = 1024  # contract cap: decoded longest side <= 1024 px (moment.schema.json)
+SEEN_MOMENTS_CAP = 4096  # a day of moments is far less
+CONTRACTS_DIR_ENV = "SMALL_CUTS_CONTRACTS_DIR"
+_SOURCE_CONTRACTS = Path(__file__).resolve().parents[3] / "docs" / "contracts"
+
+SceneSink = Callable[[dict[str, Any]], Any]
+"""Receives every successful scene; Task 2 plugs the library/SSE fan-out here."""
+
+
+def _contract_text(name: str) -> str:
+    configured = os.environ.get(CONTRACTS_DIR_ENV)
+    if configured:
+        return (Path(configured) / name).read_text()
+    source_contract = _SOURCE_CONTRACTS / name
+    if source_contract.exists():
+        return source_contract.read_text()
+    return (resources.files("small_cuts") / "contracts" / name).read_text()
+
+
+def _validator(name: str) -> jsonschema.Draft202012Validator:
+    return jsonschema.Draft202012Validator(json.loads(_contract_text(name)))
+
+
+_MOMENT = _validator("moment.schema.json")
+_SCENE_AUDIO = _validator("scene-audio.schema.json")
+_BACKGROUND_STORAGE_TASKS: set[asyncio.Task[None]] = set()
+
+
+def _noop_sink(scene: dict[str, Any]) -> None:
+    return None
+
+
+class MomentIdLRU:
+    """Bounded dedupe set: insertion-ordered, oldest ids evicted past `cap`."""
+
+    def __init__(self, cap: int = SEEN_MOMENTS_CAP) -> None:
+        self._cap = cap
+        self._ids: OrderedDict[str, None] = OrderedDict()
+
+    def __contains__(self, moment_id: object) -> bool:
+        return moment_id in self._ids
+
+    def add(self, moment_id: str) -> None:
+        self._ids[moment_id] = None
+        self._ids.move_to_end(moment_id)
+        while len(self._ids) > self._cap:
+            self._ids.popitem(last=False)
+
+    def discard(self, moment_id: str) -> None:
+        self._ids.pop(moment_id, None)
+
+
+@dataclass
+class EngineState:
+    """Process-lifetime state shared across session sockets."""
+
+    sink: SceneSink = _noop_sink
+    error_sink: SceneSink | None = None  # receives every error ControlFrame (viewer fan-out, D9)
+    seen_moment_ids: MomentIdLRU = field(default_factory=MomentIdLRU)
+
+
+@dataclass
+class _Queued:
+    envelope: dict[str, Any]
+    queued_at: float
+
+
+class _ValidationFailure(Exception):
+    """Post-admission validation failure (undecodable or over-cap frame); never retryable."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _log_worker_failure(task: asyncio.Task) -> None:
+    """A drain-task bug must fail loudly, not strand moments as unretrieved exceptions."""
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        print(f"small_cuts.engine: session worker task crashed: {exc!r}", file=sys.stderr)
+
+
+def _retain_background_storage(task: asyncio.Task[None]) -> None:
+    """Keep shielded scene storage alive after the client WebSocket is gone."""
+    _BACKGROUND_STORAGE_TASKS.add(task)
+    task.add_done_callback(_BACKGROUND_STORAGE_TASKS.discard)
+
+
+class SessionRunner:
+    """One connected capture app: admission, the single queue slot, the pipeline."""
+
+    def __init__(self, ws: WebSocket, state: EngineState) -> None:
+        self._ws = ws
+        self._state = state
+        self._send_lock = asyncio.Lock()
+        self._pending: _Queued | None = None
+        self._worker: asyncio.Task | None = None
+        self._processing = False
+        self._last_status: tuple[bool, int] | None = None
+
+    async def run(self) -> None:
+        try:
+            while True:
+                message = await self._ws.receive()
+                if message["type"] == "websocket.disconnect":
+                    break
+                text = message.get("text")
+                if text is None:  # binary frame: not in the contract, but don't drop the socket
+                    await self._send_ack(None, "rejected", "binary frames not supported")
+                    continue
+                await self._admit(text)
+        except WebSocketDisconnect:
+            pass
+        finally:
+            if self._worker is not None:
+                self._worker.cancel()
+
+    # -- admission (every envelope gets exactly one ack) ----------------------
+
+    async def _admit(self, raw: str) -> None:
+        try:
+            envelope = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            await self._send_ack(None, "rejected", f"invalid JSON: {exc}")
+            return
+        moment_id = envelope.get("moment_id") if isinstance(envelope, dict) else None
+        if not isinstance(moment_id, str):
+            moment_id = None
+        error = jsonschema.exceptions.best_match(_MOMENT.iter_errors(envelope))
+        if error is not None:
+            await self._send_ack(moment_id, "rejected", error.message)
+            return
+        dedupe_key = _moment_dedupe_key(envelope)
+        if dedupe_key in self._state.seen_moment_ids:
+            await self._send_ack(moment_id, "duplicate")
+            return
+        self._state.seen_moment_ids.add(dedupe_key)
+
+        queued = _Queued(envelope, time.perf_counter())
+        if not self._processing:
+            self._processing = True
+            await self._send_ack(moment_id, "accepted")
+            self._worker = asyncio.create_task(self._drain(queued))
+            self._worker.add_done_callback(_log_worker_failure)
+        elif self._pending is None:
+            self._pending = queued
+            await self._send_ack(moment_id, "accepted")
+        else:  # D8: replace the un-started moment; stale narration is worse than none
+            dropped = self._pending
+            self._pending = queued
+            await self._send_ack(dropped.envelope["moment_id"], "dropped_coalesced")
+            await self._send_ack(moment_id, "accepted")
+        await self._emit_status()
+
+    # -- processing ------------------------------------------------------------
+
+    async def _drain(self, queued: _Queued) -> None:
+        current: _Queued | None = queued
+        try:
+            while current is not None:
+                await self._process(current)
+                current, self._pending = self._pending, None
+                await self._emit_status()
+        finally:
+            self._processing = False
+        await self._emit_status()  # skipped on cancellation: the socket is gone
+
+    async def _process(self, item: _Queued) -> None:
+        envelope = item.envelope
+        moment_id: str = envelope["moment_id"]
+        context = envelope.get("context") or {}
+        style_key = context.get("style_key") or DEFAULT_STYLE_KEY
+        started = time.perf_counter()
+        queue_ms = _ms(started - item.queued_at)
+        stage = "narration"
+        try:
+            image, narration = await asyncio.to_thread(
+                _decode_and_narrate,
+                envelope,
+                style_key,
+                context.get("user_hint", ""),
+            )
+            narration_ms = _ms(time.perf_counter() - started)
+            stage = "tts"
+            tts_started = time.perf_counter()
+            speech = await asyncio.to_thread(tts.speak, narration.text)
+            audio_b64 = base64.b64encode(_wav_bytes(speech.audio, speech.sample_rate)).decode()
+            tts_ms = _ms(time.perf_counter() - tts_started)
+
+            stage = "storage"  # the outgoing SceneAudio is the engine's stored artifact
+            created_at = datetime.now(timezone.utc)
+            payload = {
+                "contract_version": CONTRACT_VERSION,
+                "scene_id": str(uuid.uuid4()),
+                "moment_id": moment_id,
+                "created_at": created_at.isoformat(),
+                "play_by": (created_at + timedelta(seconds=PLAY_BY_SECONDS)).isoformat(),
+                "format": "wav_complete",
+                "audio_b64": audio_b64,
+                "sample_rate": speech.sample_rate,
+                "narration": narration.text,
+            }
+            _SCENE_AUDIO.validate(payload)  # outgoing drift becomes an error frame, never silence
+            await self._send_json(payload)
+        except _ValidationFailure as exc:
+            # The resend would fail the same way, but dedupe only what produced a scene.
+            self._state.seen_moment_ids.discard(_moment_dedupe_key(envelope))
+            await self._send_error(moment_id, "validation", exc, code=exc.code, retryable=False)
+            return
+        except Exception as exc:
+            # Drop the id so a client resend is genuinely re-processed (honest retryable).
+            self._state.seen_moment_ids.discard(_moment_dedupe_key(envelope))
+            retryable = stage in ("narration", "tts")
+            code = "scene_audio_schema_drift" if stage == "storage" else None
+            await self._send_error(moment_id, stage, exc, code=code, retryable=retryable)
+            return
+
+        storage_task = asyncio.create_task(
+            self._finish_scene_storage(
+                envelope=envelope,
+                image=image,
+                scene_audio=payload,
+                narration_text=narration.text,
+                title=narration.title,
+                speech=speech,
+                style_key=style_key,
+                queue_ms=queue_ms,
+                narration_ms=narration_ms,
+                tts_ms=tts_ms,
+            )
+        )
+        _retain_background_storage(storage_task)
+        try:
+            await asyncio.shield(storage_task)
+        except asyncio.CancelledError:
+            storage_task.add_done_callback(_log_worker_failure)
+            raise
+
+    async def _finish_scene_storage(
+        self,
+        *,
+        envelope: dict[str, Any],
+        image: Image.Image,
+        scene_audio: dict[str, Any],
+        narration_text: str,
+        title: str,
+        speech: tts.Speech,
+        style_key: str,
+        queue_ms: int,
+        narration_ms: int,
+        tts_ms: int,
+    ) -> None:
+        clip_frames = await asyncio.to_thread(
+            _decode_clip_frames_for_storage, envelope, image, scene_audio["scene_id"]
+        )
+        await self._hand_to_sink(
+            self._state.sink,
+            {
+                "scene_id": scene_audio["scene_id"],
+                "moment_id": envelope["moment_id"],
+                "session_id": envelope["session_id"],
+                "captured_at": envelope["captured_at"],
+                "created_at": scene_audio["created_at"],
+                "style_key": style_key,
+                "title": title,
+                "narration": narration_text,
+                "image": image,
+                "clip_frames": clip_frames,
+                "audio": speech.audio,
+                "sample_rate": speech.sample_rate,
+                "latency_ms": {
+                    "queue": queue_ms,
+                    "narration": narration_ms,
+                    "tts": tts_ms,
+                    "total": queue_ms + narration_ms + tts_ms,
+                },
+            },
+        )
+
+    async def _hand_to_sink(self, sink: SceneSink | None, payload: dict[str, Any]) -> None:
+        if sink is None:
+            return
+        with contextlib.suppress(Exception):  # a sink bug must not kill the session
+            result = sink(payload)
+            if inspect.isawaitable(result):
+                await result
+
+    # -- outbound frames ---------------------------------------------------------
+
+    async def _send_ack(self, moment_id: str | None, result: str, detail: str = "") -> None:
+        ack: dict[str, Any] = {"result": result}
+        if detail:
+            ack["detail"] = detail[:200]
+        await self._send_json(
+            {
+                "contract_version": CONTRACT_VERSION,
+                "kind": "ack",
+                "moment_id": moment_id,
+                "ack": ack,
+            }
+        )
+
+    async def _send_error(
+        self,
+        moment_id: str,
+        stage: str,
+        exc: Exception,
+        *,
+        retryable: bool,
+        code: str | None = None,
+    ) -> None:
+        frame = {
+            "contract_version": CONTRACT_VERSION,
+            "kind": "error",
+            "moment_id": moment_id,
+            "error": {
+                "stage": stage,
+                "code": (code or type(exc).__name__)[:60],
+                "message": str(exc)[:300],
+                "retryable": retryable,
+            },
+        }
+        await self._send_json(frame)
+        # D9 honest timeline: the same failure fans out to the viewer stream.
+        await self._hand_to_sink(self._state.error_sink, frame)
+
+    async def _emit_status(self) -> None:
+        snapshot = (self._processing, int(self._pending is not None))
+        if snapshot == self._last_status:
+            return
+        self._last_status = snapshot
+        await self._send_json(
+            {
+                "contract_version": CONTRACT_VERSION,
+                "kind": "status",
+                "moment_id": None,
+                "status": {"busy": snapshot[0], "queue_depth": snapshot[1]},
+            }
+        )
+
+    async def _send_json(self, payload: dict[str, Any]) -> None:
+        text = json.dumps(payload)  # serialization bugs must surface, not be swallowed
+        async with self._send_lock:
+            with contextlib.suppress(Exception):  # client gone mid-send; run() closes out
+                await self._ws.send_text(text)
+
+
+def _decode_and_narrate(
+    envelope: dict[str, Any], style_key: str, scene_hint: str
+) -> tuple[Image.Image, narrator.Narration]:
+    """Decode the selected frame + narrate it in one worker-thread hop."""
+    try:
+        selected = _decode_frame(envelope["frames"][0])
+        _validate_frame_size(selected)
+    except _ValidationFailure:
+        raise
+    except Exception as exc:
+        raise _ValidationFailure("frame_decode_failed", f"undecodable frame: {exc}") from exc
+    return (
+        selected,
+        narrator.narrate(selected, style_key=style_key, scene_hint=scene_hint),
+    )
+
+
+def _decode_frame(frame: dict[str, Any]) -> Image.Image:
+    data = base64.b64decode(frame["jpeg_b64"])
+    image = Image.open(io.BytesIO(data))
+    image.load()
+    return image
+
+
+def _moment_dedupe_key(envelope: dict[str, Any]) -> str:
+    return f"{envelope['session_id']}:{envelope['moment_id']}"
+
+
+def _validate_frame_size(image: Image.Image) -> None:
+    longest = max(image.size)
+    if longest > MAX_FRAME_SIDE:
+        raise _ValidationFailure(
+            "frame_exceeds_cap",
+            f"decoded longest side {longest} px exceeds the {MAX_FRAME_SIDE} px contract cap",
+        )
+
+
+def _decode_clip_frames(envelope: dict[str, Any], selected: Image.Image) -> list[Image.Image]:
+    decoded: list[tuple[int, int, Image.Image]] = [
+        (int(envelope["frames"][0].get("ts_offset_ms", 0)), 0, selected)
+    ]
+    for index, frame in enumerate(envelope["frames"][1:], start=1):
+        image = _decode_frame(frame)
+        _validate_frame_size(image)
+        decoded.append((int(frame.get("ts_offset_ms", index)), index, image))
+    return [image for _, _, image in sorted(decoded, key=lambda item: (item[0], item[1]))]
+
+
+def _decode_clip_frames_for_storage(
+    envelope: dict[str, Any], selected: Image.Image, scene_id: str
+) -> list[Image.Image]:
+    """Decode viewer-only supplemental frames after SceneAudio is already sent."""
+    if len(envelope["frames"]) < 2:
+        return [selected]
+    try:
+        return _decode_clip_frames(envelope, selected)
+    except Exception as exc:
+        print(
+            f"small_cuts.engine: clip frame decode failed for scene {scene_id}: {exc!r}",
+            file=sys.stderr,
+        )
+        return [selected]
+
+
+def _wav_bytes(audio: np.ndarray, sample_rate: int) -> bytes:
+    buffer = io.BytesIO()
+    try:
+        import soundfile
+
+        soundfile.write(buffer, audio, sample_rate, format="WAV", subtype="PCM_16")
+    except ImportError:
+        pcm = (np.clip(audio, -1.0, 1.0) * 32767.0).astype("<i2")
+        with wave.open(buffer, "wb") as wav:
+            wav.setnchannels(1)
+            wav.setsampwidth(2)
+            wav.setframerate(sample_rate)
+            wav.writeframes(pcm.tobytes())
+    return buffer.getvalue()
+
+
+def _ms(seconds: float) -> int:
+    return max(0, round(seconds * 1000))

src/small_cuts/eval.py

@@ -0,0 +1,162 @@
+"""M1 model-evaluation harness: candidate VLMs × images × styles → markdown report.
+
+Designed to run on a CUDA box (DGX Spark) so results transfer to ZeroGPU:
+
+    uv sync --extra local
+    uv run python -m small_cuts.eval --images ~/eval-photos --out eval-report.md
+
+Smoke test anywhere (no weights):
+
+    uv run python -m small_cuts.eval --images ~/eval-photos --backend mock
+"""
+
+from __future__ import annotations
+
+import argparse
+import tempfile
+import time
+from pathlib import Path
+
+from PIL import Image
+
+from .narrator import MockBackend, Narration, TransformersBackend, narrate
+
+CANDIDATE_MODELS = [
+    "HuggingFaceTB/SmolVLM2-2.2B-Instruct",
+    "Qwen/Qwen2.5-VL-3B-Instruct",
+    "Qwen/Qwen2.5-VL-7B-Instruct",
+    "google/gemma-3-4b-it",
+]
+
+EVAL_STYLES = ["deadpan", "noir", "nature_doc"]
+
+# .heic/.heif (iPhone default) decode via pillow-heif, registered in small_cuts/__init__.py
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif"}
+
+# Real Small Cuts input is video (Ray-Ban / phone clips). When a directory holds
+# videos, we sample frames so the model eval runs on representative stills.
+VIDEO_SUFFIXES = {".mov", ".mp4", ".m4v", ".webm", ".avi", ".mkv"}
+
+RUBRIC = (
+    "Score each cell 1-5 on: **S**pecificity (names real visible things), "
+    "**G**roundedness (no invented objects/people), **V**oice (style lands). "
+    "A model needs S>=4 and G>=4 on most images to be the pick."
+)
+
+
+def _sample_video_frames(
+    video: Path,
+    every_n_seconds: float = 3.0,
+    output_dir: Path | None = None,
+) -> list[Path]:
+    """Extract frames from a video into an output directory; return their paths."""
+    from .frames import sample_frames
+
+    images = sample_frames(video, every_n_seconds=every_n_seconds)
+    output = output_dir or Path(tempfile.mkdtemp(prefix="small-cuts-eval-frames-"))
+    output.mkdir(parents=True, exist_ok=True)
+    out_paths: list[Path] = []
+    for i, img in enumerate(images):
+        out = output / f"{video.stem}_frame{i:06d}.jpg"
+        img.save(out)
+        out_paths.append(out)
+    return out_paths
+
+
+def load_images(images_dir: Path, frame_dir: Path | None = None) -> list[Path]:
+    if not images_dir.exists():
+        raise SystemExit(f"Directory does not exist: {images_dir}")
+    entries = sorted(p for p in images_dir.iterdir() if p.is_file())
+    paths = [p for p in entries if p.suffix.lower() in IMAGE_SUFFIXES]
+    videos = [p for p in entries if p.suffix.lower() in VIDEO_SUFFIXES]
+    for video in videos:
+        print(f"Sampling frames from {video.name}")
+        paths.extend(_sample_video_frames(video, output_dir=frame_dir))
+    if not paths:
+        listing = "\n".join(f"  {p.name}" for p in entries) or "  (directory is empty)"
+        raise SystemExit(
+            f"No images or videos found in {images_dir}.\n"
+            f"Directory contains:\n{listing}\n"
+            f"Recognized image suffixes: {sorted(IMAGE_SUFFIXES)}\n"
+            f"Recognized video suffixes: {sorted(VIDEO_SUFFIXES)}"
+        )
+    return sorted(paths)
+
+
+def run_model(
+    model_id: str, image_paths: list[Path], styles: list[str], backend_name: str
+) -> dict[tuple[str, str], Narration]:
+    backend = MockBackend() if backend_name == "mock" else TransformersBackend(model_id=model_id)
+    results: dict[tuple[str, str], Narration] = {}
+    for path in image_paths:
+        image = Image.open(path).convert("RGB")
+        for style in styles:
+            result = narrate(image, style_key=style, backend=backend)
+            results[(path.name, style)] = result
+            print(f"  {model_id} | {path.name} | {style} | {result.latency_s:.1f}s")
+    return results
+
+
+def render_report(
+    all_results: dict[str, dict[tuple[str, str], Narration]],
+    image_paths: list[Path],
+    styles: list[str],
+) -> str:
+    lines = [
+        "# Small Cuts — M1 Narrator Model Eval",
+        "",
+        f"Generated {time.strftime('%Y-%m-%d %H:%M:%S')}.",
+        "",
+        RUBRIC,
+        "",
+    ]
+    for path in image_paths:
+        lines.append(f"## {path.name}")
+        lines.append("")
+        lines.append("| Model | Style | Narration | Latency | S | G | V |")
+        lines.append("|---|---|---|---|---|---|---|")
+        for model_id, results in all_results.items():
+            for style in styles:
+                narration = results.get((path.name, style))
+                if narration is None:
+                    lines.append(f"| {model_id} | {style} | (failed) | - |  |  |  |")
+                    continue
+                text = narration.text.replace("\n", " ").replace("|", "\\|")
+                lines.append(
+                    f"| {model_id} | {style} | {text} | {narration.latency_s:.1f}s |  |  |  |"
+                )
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--images", type=Path, required=True, help="Directory of eval photos")
+    parser.add_argument("--models", nargs="*", default=CANDIDATE_MODELS)
+    parser.add_argument("--styles", nargs="*", default=EVAL_STYLES)
+    parser.add_argument("--out", type=Path, default=Path("eval-report.md"))
+    parser.add_argument("--backend", choices=["transformers", "mock"], default="transformers")
+    args = parser.parse_args(argv)
+
+    with tempfile.TemporaryDirectory(prefix="small-cuts-eval-frames-") as frame_dir:
+        image_paths = load_images(args.images, frame_dir=Path(frame_dir))
+        models = args.models if args.backend == "transformers" else ["mock"]
+        all_results = {}
+        failures = []
+        for model_id in models:
+            try:
+                all_results[model_id] = run_model(model_id, image_paths, args.styles, args.backend)
+            except Exception as exc:  # one gated/broken model must not kill the eval
+                failures.append(f"{model_id}: {type(exc).__name__}: {exc}")
+                print(f"  FAILED {model_id}: {exc}")
+        if not all_results:
+            raise SystemExit("All models failed:\n" + "\n".join(failures))
+        report = render_report(all_results, image_paths, args.styles)
+        if failures:
+            report += "\n## Failed models\n\n" + "\n".join(f"- {f}" for f in failures) + "\n"
+        args.out.write_text(report)
+    print(f"\nReport written to {args.out}")
+
+
+if __name__ == "__main__":
+    main()

src/small_cuts/frames.py

@@ -0,0 +1,82 @@
+"""Video frame sampling utilities for Small Cuts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageFilter, ImageStat
+
+
+def sample_frames(
+    path: str | Path,
+    every_n_seconds: float = 3.0,
+    max_frames: int | None = None,
+) -> list[Image.Image]:
+    """Decode *path* with PyAV and return a list of RGB PIL Images.
+
+    Every ``int(fps * every_n_seconds)``-th frame is kept (indices 0, step,
+    2*step, …).  No files are written.  Decoding stops as soon as
+    *max_frames* images have been collected (when *max_frames* is not None).
+    """
+    import av  # PyAV — ffmpeg-backed, reliable ARM64 wheels
+
+    kept: list[Image.Image] = []
+    container = av.open(str(path))
+    try:
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate or stream.guessed_rate or 30)
+        step = max(1, int(fps * every_n_seconds))
+        for i, frame in enumerate(container.decode(stream)):
+            if i % step == 0:
+                img = frame.to_image().convert("RGB")
+                kept.append(img)
+                if max_frames is not None and len(kept) >= max_frames:
+                    break
+    finally:
+        container.close()
+    return kept
+
+
+def pick_frame(frames: list[Image.Image]) -> Image.Image:
+    """Return the middle frame (``frames[len(frames) // 2]``).
+
+    Raises ``ValueError`` when *frames* is empty.
+    """
+    if not frames:
+        raise ValueError("frames list is empty")
+    return frames[len(frames) // 2]
+
+
+def pick_key_frame(frames: list[Image.Image]) -> Image.Image:
+    """Return the most useful library/poster frame from sampled video frames.
+
+    The score is intentionally deterministic and dependency-light: prefer frames
+    that are exposed near mid-brightness, have contrast, and have visible edges.
+    A centrality bonus breaks near-ties toward the middle of the clip, which is
+    usually more representative than the capture start or the trailing frame.
+    """
+    if not frames:
+        raise ValueError("frames list is empty")
+    middle = (len(frames) - 1) / 2
+    best_index, _best_score = max(
+        enumerate(frames),
+        key=lambda item: (_frame_quality(item[1]) + _centrality(item[0], middle), -item[0]),
+    )
+    return frames[best_index]
+
+
+def _frame_quality(frame: Image.Image) -> float:
+    gray = frame.convert("L")
+    gray.thumbnail((160, 160), Image.Resampling.LANCZOS)
+    stats = ImageStat.Stat(gray)
+    brightness = stats.mean[0] / 255.0
+    contrast = min(stats.stddev[0] / 96.0, 1.0)
+    exposure = 1.0 - min(abs(brightness - 0.5) / 0.5, 1.0)
+    edges = ImageStat.Stat(gray.filter(ImageFilter.FIND_EDGES)).mean[0] / 255.0
+    return exposure * 0.45 + contrast * 0.35 + min(edges * 3.0, 1.0) * 0.20
+
+
+def _centrality(index: int, middle: float) -> float:
+    if middle <= 0:
+        return 0.0
+    return (1.0 - min(abs(index - middle) / middle, 1.0)) * 0.08

src/small_cuts/hf_relay.py

@@ -0,0 +1,469 @@
+"""Hugging Face bucket relay for finished Small Cuts scenes.
+
+The Space uses this as a read-only scene source. The private engine or a local
+publisher writes finished scene manifests + media into an HF bucket; the Space
+downloads those files into a temp cache and serves them through Gradio.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.parse import quote, urlparse
+
+import httpx
+
+from .persistence import bucket_mount_path
+
+RELAY_BUCKET_ENV = "SMALL_CUTS_RELAY_BUCKET"
+RELAY_PREFIX_ENV = "SMALL_CUTS_RELAY_PREFIX"
+RELAY_DIRECT_MEDIA_URLS_ENV = "SMALL_CUTS_RELAY_DIRECT_MEDIA_URLS"
+RELAY_READ_TOKEN_ENV = "SMALL_CUTS_RELAY_READ_TOKEN"
+RELAY_BUCKET_PRIVATE_ENV = "SMALL_CUTS_RELAY_BUCKET_PRIVATE"
+DEFAULT_RELAY_PREFIX = "relay"
+RELAY_MANIFEST = "manifest.json"
+RELAY_CACHE_DIR = Path(tempfile.gettempdir()) / "small-cuts-hf-relay"
+GRADIO_FILE_ROUTE = "/gradio_api/file="
+DEFAULT_SCENE_LIMIT = 60
+MEDIA_KEYS = ("frame_url", "card_url", "audio_url", "clip_url")
+SHELF_MEDIA_KEYS = ("frame_url", "card_url")
+PUBLISH_VISIBILITIES = frozenset({"shared", "public"})
+HTTP_TIMEOUT_S = 20.0
+MANIFEST_CACHE_TTL_S = 5.0
+RELAY_CACHE_MAX_BYTES = 512 * 1024 * 1024
+
+_MISSING_SHELF_MEDIA_SVG = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180">'
+    '<rect width="320" height="180" fill="#101014"/>'
+    '<rect x="20" y="20" width="280" height="140" rx="10" fill="none" '
+    'stroke="#2f2f38" stroke-width="2" stroke-dasharray="8 8"/>'
+    '<text x="160" y="92" fill="#d4af37" font-family="monospace" '
+    'font-size="18" text-anchor="middle">ROLLING</text>'
+    '<text x="160" y="118" fill="#8a8894" font-family="monospace" '
+    'font-size="12" text-anchor="middle">media still landing</text>'
+    "</svg>"
+)
+MISSING_SHELF_MEDIA_PLACEHOLDER = f"data:image/svg+xml,{quote(_MISSING_SHELF_MEDIA_SVG, safe='')}"
+
+
+class BucketFileSystem(Protocol):
+    def cat(self, path: str) -> bytes: ...
+
+
+class BucketRelayError(RuntimeError):
+    """Raised when the bucket relay cannot read or hydrate its manifest."""
+
+
+@dataclass(frozen=True)
+class RelaySnapshot:
+    path: Path
+    scene_count: int
+    manifest_path: Path
+
+
+def gradio_file_url(path: str | Path) -> str:
+    return f"{GRADIO_FILE_ROUTE}{quote(str(path))}"
+
+
+def _normalize_prefix(prefix: str) -> str:
+    return prefix.strip().strip("/")
+
+
+def _safe_bucket_slug(bucket_id: str) -> str:
+    return bucket_id.replace("/", "__")
+
+
+class BucketSceneClient:
+    """Read finished NarratedScene payloads from a Hugging Face bucket manifest."""
+
+    base_url = ""
+    readonly = True
+
+    def __init__(
+        self,
+        bucket_id: str,
+        *,
+        prefix: str = DEFAULT_RELAY_PREFIX,
+        fs: BucketFileSystem | None = None,
+        cache_dir: str | Path | None = None,
+        register_static_paths: Any | None = None,
+        manifest_cache_ttl_s: float = MANIFEST_CACHE_TTL_S,
+        cache_max_bytes: int = RELAY_CACHE_MAX_BYTES,
+        direct_media_urls: bool | None = None,
+    ) -> None:
+        self.bucket_id = bucket_id.strip()
+        if not self.bucket_id:
+            raise ValueError("bucket_id is required")
+        self.prefix = _normalize_prefix(prefix)
+        self.root = f"hf://buckets/{self.bucket_id}"
+        if self.prefix:
+            self.root = f"{self.root}/{self.prefix}"
+        self._fs = fs
+        mount = bucket_mount_path()
+        self.bucket_mount_path = mount.expanduser().resolve() if mount is not None else None
+        self.mounted_root = (
+            self.bucket_mount_path / self.prefix
+            if self.bucket_mount_path is not None and self.prefix
+            else self.bucket_mount_path
+        )
+        self.cache_dir = (
+            Path(cache_dir)
+            if cache_dir is not None
+            else (RELAY_CACHE_DIR / _safe_bucket_slug(self.bucket_id))
+        )
+        if cache_dir is None and self.prefix:
+            self.cache_dir = self.cache_dir / self.prefix
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        if register_static_paths is not None:
+            static_paths = [self.cache_dir]
+            if self.bucket_mount_path is not None:
+                static_paths.append(self.bucket_mount_path)
+            register_static_paths(static_paths)
+        self.manifest_cache_ttl_s = manifest_cache_ttl_s
+        self.cache_max_bytes = cache_max_bytes
+        self.direct_media_urls = (
+            _default_direct_media_urls() if direct_media_urls is None else bool(direct_media_urls)
+        )
+        self._read_token = os.environ.get(RELAY_READ_TOKEN_ENV, "").strip() or None
+        self.bucket_private = _env_flag(RELAY_BUCKET_PRIVATE_ENV)
+        if self.bucket_private and self.direct_media_urls:
+            raise BucketRelayError(
+                f"refusing to start: direct-media (resolve) URLs against private bucket "
+                f"{self.bucket_id} would 404 for anonymous clients and leak the bucket path "
+                f"into client HTML; set {RELAY_DIRECT_MEDIA_URLS_ENV}=0 to serve same-origin"
+            )
+        self._manifest_lock = threading.Lock()
+        self._media_lock = threading.Lock()
+        self._manifest_cache: tuple[float, list[dict[str, Any]]] | None = None
+        self._prune_cache()
+
+    @property
+    def fs(self) -> BucketFileSystem:
+        if self._fs is None:
+            from huggingface_hub import HfFileSystem
+
+            self._fs = HfFileSystem(token=self._read_token)
+        return self._fs
+
+    def list_scenes(self, limit: int = DEFAULT_SCENE_LIMIT) -> list[dict[str, Any]]:
+        with self._manifest_lock:
+            now = time.monotonic()
+            if (
+                self._manifest_cache is not None
+                and now - self._manifest_cache[0] < self.manifest_cache_ttl_s
+            ):
+                return copy.deepcopy(self._manifest_cache[1][-limit:])
+            try:
+                raw = self._read_manifest()
+                scenes = self._manifest_scenes(raw) if raw is not None else []
+                hydrated = []
+                for scene in scenes:
+                    try:
+                        hydrated.append(self._hydrate_scene(scene, keys=self._list_media_keys()))
+                    except FileNotFoundError:
+                        continue
+                uploaded = self._uploaded_scenes()
+                hydrated = _merge_bucket_scenes(hydrated, uploaded)
+                self._manifest_cache = (now, hydrated)
+                return copy.deepcopy(hydrated[-limit:])
+            except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+                raise BucketRelayError(
+                    f"could not read relay bucket {self.bucket_id}: {exc}"
+                ) from exc
+
+    def invalidate_cache(self) -> None:
+        """Drop the cached scene list so the next ``list_scenes`` re-reads the bucket.
+
+        The relay-scene push path calls this so a freshly published cut is visible immediately, even
+        within ``MANIFEST_CACHE_TTL_S`` of a prior read; non-push reads keep using the cache.
+        """
+        with self._manifest_lock:
+            self._manifest_cache = None
+
+    def _manifest_scenes(self, raw: bytes) -> list[dict[str, Any]]:
+        manifest = json.loads(raw.decode("utf-8"))
+        scenes = manifest.get("scenes", [])
+        if not isinstance(scenes, list):
+            raise ValueError("relay manifest scenes must be a list")
+        return scenes
+
+    def _read_manifest(self) -> bytes | None:
+        local_manifest = self._mounted_file(RELAY_MANIFEST)
+        if local_manifest is not None and local_manifest.is_file():
+            return local_manifest.read_bytes()
+        try:
+            return self.fs.cat(f"{self.root}/{RELAY_MANIFEST}")
+        except FileNotFoundError:
+            return None
+
+    def _uploaded_scenes(self) -> list[dict[str, Any]]:
+        mounted_paths = self._mounted_upload_scene_paths()
+        if mounted_paths is not None:
+            uploaded = []
+            for scene_path in mounted_paths:
+                scene = json.loads(scene_path.read_bytes().decode("utf-8"))
+                if isinstance(scene, dict):
+                    uploaded.append(self._hydrate_scene(scene, keys=self._list_media_keys()))
+            return uploaded
+        glob = getattr(self.fs, "glob", None)
+        if glob is None:
+            return []
+        try:
+            scene_paths = glob(f"{self.root}/uploads/*/scene.json")
+        except FileNotFoundError:
+            return []
+        uploaded = []
+        for scene_path in sorted(str(path) for path in scene_paths):
+            try:
+                raw = self.fs.cat(scene_path)
+                scene = json.loads(raw.decode("utf-8"))
+                if isinstance(scene, dict):
+                    uploaded.append(self._hydrate_scene(scene, keys=self._list_media_keys()))
+            except FileNotFoundError:
+                continue
+        return uploaded
+
+    def media_url(self, path: str | None) -> str | None:
+        if not path:
+            return None
+        if path.startswith(("http://", "https://", "data:", GRADIO_FILE_ROUTE)):
+            return path
+        relative = self._relative_media_path(path)
+        if self.direct_media_urls:
+            return self._hf_resolve_url(relative)
+        mounted = self._mounted_file(relative)
+        if mounted is not None and mounted.is_file():
+            return gradio_file_url(mounted)
+        target = self.cache_dir / relative
+        with self._media_lock:
+            if not target.exists():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                tmp = target.with_name(f".{target.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+                try:
+                    tmp.write_bytes(self.fs.cat(f"{self.root}/{relative.as_posix()}"))
+                    tmp.replace(target)
+                finally:
+                    tmp.unlink(missing_ok=True)
+                self._prune_cache(protected=target)
+        return gradio_file_url(target)
+
+    def _hf_resolve_url(self, relative: str | Path) -> str:
+        path = Path(relative).as_posix()
+        if self.prefix:
+            path = f"{self.prefix}/{path}"
+        return (
+            f"https://huggingface.co/buckets/{quote(self.bucket_id, safe='/')}"
+            f"/resolve/{quote(path, safe='/')}"
+        )
+
+    def _hydrate_scene(
+        self, scene: dict[str, Any], *, keys: tuple[str, ...] = MEDIA_KEYS
+    ) -> dict[str, Any]:
+        hydrated = copy.deepcopy(scene)
+        media = hydrated.get("media")
+        if not isinstance(media, dict):
+            hydrated["media"] = {}
+            return hydrated
+        for key in keys:
+            try:
+                media[key] = self.media_url(media.get(key))
+            except FileNotFoundError:
+                media[key] = self._missing_media_url(key)
+        return hydrated
+
+    def _missing_media_url(self, key: str) -> str | None:
+        if key in SHELF_MEDIA_KEYS:
+            return MISSING_SHELF_MEDIA_PLACEHOLDER
+        return None
+
+    def _list_media_keys(self) -> tuple[str, ...]:
+        # A private bucket is proxied entirely same-origin (clip + audio too, not just the
+        # shelf thumbnails) so Safari can load and seek the video; existing engine/upload
+        # proxy modes keep serving only the shelf keys (media arrives via a mount).
+        if self.direct_media_urls or self.bucket_private:
+            return MEDIA_KEYS
+        return SHELF_MEDIA_KEYS
+
+    def _relative_media_path(self, path: str) -> Path:
+        value = path.strip().lstrip("/")
+        if self.prefix and value.startswith(f"{self.prefix}/"):
+            value = value[len(self.prefix) + 1 :]
+        relative = Path(value)
+        if relative.is_absolute() or ".." in relative.parts:
+            raise ValueError(f"unsafe bucket media path: {path}")
+        return relative
+
+    def _mounted_file(self, relative: str | Path) -> Path | None:
+        if self.mounted_root is None:
+            return None
+        path = self.mounted_root / Path(relative)
+        if path.is_absolute() and self.mounted_root not in [path, *path.parents]:
+            raise ValueError(f"unsafe mounted bucket path: {relative}")
+        return path
+
+    def _mounted_upload_scene_paths(self) -> list[Path] | None:
+        if self.mounted_root is None or not self.mounted_root.exists():
+            return None
+        uploads_dir = self.mounted_root / "uploads"
+        if not uploads_dir.exists():
+            return []
+        return sorted(uploads_dir.glob("*/scene.json"))
+
+    def _prune_cache(self, protected: Path | None = None) -> None:
+        if self.cache_max_bytes <= 0 or not self.cache_dir.exists():
+            return
+        protected_resolved = protected.resolve() if protected is not None else None
+        files = [path for path in self.cache_dir.rglob("*") if path.is_file()]
+        total = sum(path.stat().st_size for path in files)
+        if total <= self.cache_max_bytes:
+            return
+        for path in sorted(files, key=lambda item: item.stat().st_mtime):
+            if protected_resolved is not None and path.resolve() == protected_resolved:
+                continue
+            size = path.stat().st_size
+            path.unlink(missing_ok=True)
+            total -= size
+            if total <= self.cache_max_bytes:
+                break
+
+
+def prepare_relay_snapshot(
+    engine_url: str,
+    output_dir: str | Path,
+    *,
+    limit: int = DEFAULT_SCENE_LIMIT,
+    include_private: bool = False,
+    source: str | None = None,
+    client: httpx.Client | None = None,
+) -> RelaySnapshot:
+    """Stage a bucket-ready manifest + media snapshot from the private engine."""
+    base_url = engine_url.rstrip("/")
+    output = Path(output_dir)
+    media_root = output / "media"
+    output.mkdir(parents=True, exist_ok=True)
+    media_root.mkdir(parents=True, exist_ok=True)
+    close_client = client is None
+    http = client or httpx.Client(timeout=HTTP_TIMEOUT_S)
+    try:
+        response = http.get(f"{base_url}/v1/scenes")
+        response.raise_for_status()
+        scenes = response.json().get("scenes", [])[-limit:]
+        published = [
+            _stage_scene_media(base_url, output, scene, http, source=source)
+            for scene in scenes
+            if _should_publish_scene(scene, include_private=include_private)
+        ]
+    finally:
+        if close_client:
+            http.close()
+    manifest = {
+        "contract_version": "1.1.0",
+        "published_at": datetime.now(timezone.utc).isoformat(),
+        "source_engine": base_url,
+        "scenes": published,
+    }
+    manifest_path = output / RELAY_MANIFEST
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
+    return RelaySnapshot(output, len(published), manifest_path)
+
+
+def _should_publish_scene(scene: dict[str, Any], *, include_private: bool) -> bool:
+    if include_private:
+        return True
+    return scene.get("visibility") in PUBLISH_VISIBILITIES
+
+
+def _stage_scene_media(
+    engine_url: str,
+    output_dir: Path,
+    scene: dict[str, Any],
+    client: httpx.Client,
+    *,
+    source: str | None = None,
+) -> dict[str, Any]:
+    staged = copy.deepcopy(scene)
+    if source:
+        staged["source"] = source
+        staged["source_icon"] = source
+    media = staged.get("media")
+    if not isinstance(media, dict):
+        staged["media"] = {}
+        return staged
+    scene_dir = _safe_path_segment(str(staged.get("scene_id") or "scene"))
+    for key in MEDIA_KEYS:
+        media[key] = _download_media(engine_url, output_dir, scene_dir, media.get(key), client)
+    return staged
+
+
+def _download_media(
+    engine_url: str,
+    output_dir: Path,
+    scene_dir: str,
+    url: str | None,
+    client: httpx.Client,
+) -> str | None:
+    if not url:
+        return None
+    if url.startswith(("data:", GRADIO_FILE_ROUTE)):
+        return None
+    absolute = url if url.startswith(("http://", "https://")) else f"{engine_url}/{url.lstrip('/')}"
+    relative = _relay_media_path(url, scene_dir)
+    target = output_dir / relative
+    target.parent.mkdir(parents=True, exist_ok=True)
+    response = client.get(absolute)
+    response.raise_for_status()
+    target.write_bytes(response.content)
+    return relative.as_posix()
+
+
+def _relay_media_path(url: str, scene_dir: str) -> Path:
+    parsed = urlparse(url)
+    source_path = (parsed.path if parsed.scheme else url.split("?", 1)[0]).lstrip("/")
+    if source_path.startswith("media/"):
+        relative = Path(source_path)
+    else:
+        filename = _safe_path_segment(Path(source_path).name or "media.bin")
+        relative = Path("media") / scene_dir / filename
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError(f"unsafe relay media path: {url}")
+    return relative
+
+
+def _safe_path_segment(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in ("-", "_", ".") else "-" for ch in value)
+    return cleaned.strip(".-") or "item"
+
+
+def _merge_bucket_scenes(
+    manifest_scenes: list[dict[str, Any]], uploaded_scenes: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    by_id: dict[str, dict[str, Any]] = {}
+    for scene in [*manifest_scenes, *uploaded_scenes]:
+        scene_id = str(scene.get("scene_id") or "")
+        if scene_id:
+            by_id[scene_id] = scene
+    return sorted(
+        by_id.values(),
+        key=lambda scene: (str(scene.get("created_at") or ""), str(scene.get("scene_id") or "")),
+    )
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _default_direct_media_urls() -> bool:
+    configured = os.environ.get(RELAY_DIRECT_MEDIA_URLS_ENV)
+    if configured is not None and configured.strip():
+        return _env_flag(RELAY_DIRECT_MEDIA_URLS_ENV)
+    return bool(
+        os.environ.get("SPACE_ID", "").strip() and os.environ.get(RELAY_BUCKET_ENV, "").strip()
+    )

src/small_cuts/modal_upload.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class ModalUploadError(RuntimeError):
+    """Raised when hosted post-cut inference fails."""
+
+
+DEFAULT_UPLOAD_SOURCE_ID = "public-demo"
+MAX_ERROR_DETAIL_CHARS = 240
+
+
+def _safe_modal_detail(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        return _truncate_detail(response.text.strip() or response.reason_phrase)
+
+    detail = payload.get("detail") if isinstance(payload, dict) else payload
+    return _truncate_detail(_normalize_modal_detail(detail) or response.reason_phrase)
+
+
+def _normalize_modal_detail(detail: Any) -> str:
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, dict):
+        for key in ("msg", "message", "error"):
+            value = detail.get(key)
+            if isinstance(value, str) and value:
+                return value
+        return str(detail)
+    if isinstance(detail, list):
+        messages = [_normalize_modal_detail(item) for item in detail[:3]]
+        return "; ".join(message for message in messages if message)
+    return str(detail) if detail is not None else ""
+
+
+def _truncate_detail(detail: str) -> str:
+    normalized = " ".join(detail.split())
+    if len(normalized) <= MAX_ERROR_DETAIL_CHARS:
+        return normalized
+    return f"{normalized[: MAX_ERROR_DETAIL_CHARS - 1]}..."
+
+
+def _raise_for_modal_status(response: httpx.Response, action: str) -> None:
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError:
+        detail = _safe_modal_detail(response)
+        raise ModalUploadError(
+            f"Modal upload {action} failed ({response.status_code}): {detail}"
+        ) from None
+
+
+@dataclass
+class ModalUploadClient:
+    base_url: str
+    token: str
+    http_client: httpx.Client | None = None
+    poll_interval_s: float = 1.0
+    timeout_s: float = 900.0
+
+    def submit_video(
+        self,
+        video_path: str | Path,
+        *,
+        style_key: str = "deadpan",
+        scene_hint: str = "",
+    ) -> dict[str, Any]:
+        close = self.http_client is None
+        client = self.http_client or httpx.Client(timeout=30.0, follow_redirects=True)
+        try:
+            try:
+                job_id = self._submit(
+                    client,
+                    Path(video_path),
+                    DEFAULT_UPLOAD_SOURCE_ID,
+                    style_key,
+                    scene_hint,
+                )
+            except ModalUploadError:
+                raise
+            except httpx.HTTPError as exc:
+                raise ModalUploadError(
+                    f"Modal upload request failed: {type(exc).__name__}"
+                ) from None
+            try:
+                return self._poll(client, job_id)
+            except ModalUploadError:
+                raise
+            except httpx.HTTPError as exc:
+                raise ModalUploadError(
+                    f"Modal upload status failed: {type(exc).__name__}"
+                ) from None
+        finally:
+            if close:
+                client.close()
+
+    def _submit(
+        self,
+        client: httpx.Client,
+        video_path: Path,
+        source_id: str,
+        style_key: str,
+        scene_hint: str,
+    ) -> str:
+        with video_path.open("rb") as handle:
+            response = client.post(
+                f"{self.base_url.rstrip('/')}/v1/cuts",
+                headers={"Authorization": f"Bearer {self.token}"},
+                data={
+                    "style_key": style_key,
+                    "scene_hint": scene_hint,
+                    "uploader_id": source_id,
+                },
+                files={"video": (video_path.name, handle, "video/mp4")},
+            )
+        _raise_for_modal_status(response, "request")
+        job_id = response.json().get("job_id")
+        if not isinstance(job_id, str) or not job_id:
+            raise ModalUploadError("Modal did not return a job_id")
+        return job_id
+
+    def _poll(self, client: httpx.Client, job_id: str) -> dict[str, Any]:
+        deadline = time.monotonic() + self.timeout_s
+        while time.monotonic() < deadline:
+            response = client.get(
+                f"{self.base_url.rstrip('/')}/v1/cuts/{job_id}",
+                headers={"Authorization": f"Bearer {self.token}"},
+            )
+            if response.status_code == 202:
+                time.sleep(self.poll_interval_s)
+                continue
+            _raise_for_modal_status(response, "status")
+            payload = response.json()
+            scene = payload.get("scene")
+            if not isinstance(scene, dict):
+                raise ModalUploadError("Modal completed without a scene payload")
+            return scene
+        raise ModalUploadError("Modal upload timed out")

src/small_cuts/narrate_v2.py

@@ -0,0 +1,227 @@
+"""Greenfield narration writer for the v2 ``/v2/narrate`` pipeline (Mid Cuts).
+
+This is the importable, GPU-free core that the Modal app depends on: build a contract-valid
+``NarratedScene`` and publish it to the private ``macayaven/mid-cuts`` bucket with atomic
+ordering. Keeping it here (not in ``modal_app/``) makes it unit-testable — ``modal`` is not in
+the CI venv. The model-bearing Omni backend lives in the Modal app; this module only defines the
+swappable backend interface plus a GPU-free mock.
+
+Fixes baked in (DESIGN §7): real ``uuid`` ``scene_id`` (#4); no schema-violating top-level keys,
+provenance under ``engine{}`` (#3); media uploaded before ``scene.json`` (#6). The write token is
+the caller's concern — it passes an ``uploader`` bound to ``HfApi(token=WRITE_TOKEN)`` (#1).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+from uuid import uuid4
+
+CONTRACT_VERSION = "1.2.0"
+TITLE_MAX = 80
+NARRATION_MAX = 2000
+RELAY_HOOK_TIMEOUT_S = 5.0
+
+# (local file, remote bucket-relative path) -> None. The Modal app binds this to a token-scoped
+# bucket writer; tests bind it to a recorder.
+Uploader = Callable[[Path, str], None]
+
+
+def build_narrated_scene(
+    *,
+    narration: str,
+    title: str,
+    style_key: str,
+    media: dict[str, str],
+    captured_at: str,
+    created_at: str,
+    session_id: str = "upload",
+    seq: int = 0,
+    visibility: str = "public",
+    engine: dict[str, Any] | None = None,
+    timed_captions: list[dict[str, Any]] | None = None,
+    duration: float | None = None,
+    keyframe_time: float | None = None,
+    scene_id: str | None = None,
+    moment_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a NarratedScene that validates against narrated-scene.schema.json by construction.
+
+    Only schema keys are emitted (``additionalProperties: false``); provenance goes under
+    ``engine{}``. ``scene_id``/``moment_id`` default to real uuids. ``duration`` is the playback
+    (narration-audio) length in seconds; ``keyframe_time`` is the poster frame's offset in the clip.
+    """
+    scene: dict[str, Any] = {
+        "contract_version": CONTRACT_VERSION,
+        "scene_id": scene_id or str(uuid4()),
+        "moment_id": moment_id or str(uuid4()),
+        "session_id": session_id,
+        "seq": seq,
+        "captured_at": captured_at,
+        "created_at": created_at,
+        "style_key": style_key,
+        "title": title[:TITLE_MAX],
+        "narration": narration[:NARRATION_MAX],
+        "visibility": visibility,
+        "media": media,
+    }
+    if engine is not None:
+        scene["engine"] = engine
+    if duration is not None:
+        scene["duration"] = duration
+    if keyframe_time is not None:
+        scene["keyframe_time"] = keyframe_time
+    if timed_captions is not None:
+        scene["timed_captions"] = timed_captions
+    return scene
+
+
+def _norm(text: str) -> str:
+    return re.sub(r"[^0-9a-záéíóúñü]", "", text.lower())
+
+
+def carrier_cut_index(words: list[dict[str, Any]], carrier: str) -> tuple[float, int]:
+    """Find where the spoken warm-up carrier ends in the aligned word list.
+
+    Accumulates normalized characters of the aligned words until they cover the carrier's
+    normalized length; returns (carrier_end_time, last_carrier_word_index). Robust to the
+    aligner's word/punctuation segmentation and to minor paraphrase (do_sample varies duration).
+    """
+    target = _norm(carrier)
+    accumulated = ""
+    for index, word in enumerate(words):
+        accumulated += _norm(word["word"])
+        if len(accumulated) >= len(target):
+            return float(word["t_end"]), index
+    return (float(words[-1]["t_end"]), len(words) - 1) if words else (0.0, -1)
+
+
+def cues_from_words(
+    words: list[dict[str, Any]],
+    *,
+    start_index: int = 0,
+    t_offset: float = 0.0,
+    max_words: int = 5,
+) -> list[dict[str, Any]]:
+    """Group aligned words (from start_index on) into ~max_words caption cues, rebased so times are
+    relative to the trimmed audio (subtract t_offset, clamp >= 0). Drops the carrier words."""
+    real = words[start_index:]
+    cues: list[dict[str, Any]] = []
+    for start in range(0, len(real), max_words):
+        group = real[start : start + max_words]
+        if not group:
+            continue
+        cues.append(
+            {
+                "t_start": max(0.0, round(float(group[0]["t_start"]) - t_offset, 3)),
+                "t_end": max(0.0, round(float(group[-1]["t_end"]) - t_offset, 3)),
+                "text": " ".join(w["word"] for w in group).strip(),
+            }
+        )
+    return cues
+
+
+def publish_scene(
+    uploader: Uploader,
+    *,
+    prefix: str,
+    scene: dict[str, Any],
+    media_files: dict[str, Path],
+    work_dir: Path,
+) -> dict[str, str]:
+    """Publish a scene under ``<prefix>/uploads/<scene_id>/`` with media-before-scene ordering.
+
+    Uploads every media file first, then ``scene.json`` last, so a relay reading
+    ``uploads/*/scene.json`` never sees a scene whose media has not landed yet (§7 #6). The relay
+    discovers uploads by globbing scene.json, so no manifest mutation is needed.
+    """
+    scene_id = scene["scene_id"]
+    base = f"{prefix.strip('/')}/uploads/{scene_id}"
+    for name, path in media_files.items():
+        uploader(Path(path), f"{base}/media/{name}")
+    scene_path = Path(work_dir) / "scene.json"
+    scene_path.write_text(json.dumps(scene, indent=2) + "\n")
+    uploader(scene_path, f"{base}/scene.json")
+    return {"scene_id": scene_id, "remote_prefix": base}
+
+
+def notify_relay_hook(
+    hook_url: str | None,
+    hook_token: str | None,
+    *,
+    scene_id: str,
+    seq: int,
+    post: Callable[..., Any] | None = None,
+) -> bool:
+    """Best-effort one-shot push to the Space relay hook after a scene is published (push-not-poll).
+
+    POSTs the pointer ``{scene_id, seq}`` with the shared Bearer; the Space re-reads the bucket and
+    emits the scene on its SSE stream so open browsers refresh once. Returns ``True`` only when the
+    hook accepts the push (HTTP 2xx). NEVER raises: the scene is already durably in the bucket, so a
+    hook outage (Space paused/503, network) must not fail the publish — it is logged and swallowed.
+    A no-op returning ``False`` when unconfigured (missing url or token): the bucket stays the
+    source of truth and the headless poll endpoint remains the fallback. ``post`` is injectable
+    (defaults to ``httpx.post``), mirroring this module's ``Uploader`` seam for unit tests.
+    """
+    url = (hook_url or "").strip()
+    token = (hook_token or "").strip()
+    if not (url and token):
+        return False
+    try:
+        if post is None:
+            import httpx  # inside the try so even a missing-httpx env degrades to a no-op
+
+            post = httpx.post
+        response = post(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+            json={"scene_id": scene_id, "seq": seq},
+            timeout=RELAY_HOOK_TIMEOUT_S,
+        )
+        response.raise_for_status()
+        return True
+    except Exception as exc:  # best-effort: the scene is already published; never fail on the hook
+        print(f"narrate_v2: relay hook notify failed: {exc!r}", file=sys.stderr, flush=True)
+        return False
+
+
+@dataclass(frozen=True)
+class NarrationResult:
+    """One narration pass: text + speech + provenance (matches the contract's engine enum)."""
+
+    text: str
+    audio: Any  # samples — numpy array from real backends; a plain list from the mock
+    sample_rate: int
+    narrator_model: str
+    tts_model: str
+    narrator_backend: str  # contract enum: "llama_cpp" | "transformers" | "mock"
+    title: str = ""
+
+
+class NarrationBackend(Protocol):
+    """Swappable narration backend — the modular seam the design requires."""
+
+    def narrate(self, clip_path: Path, *, style_key: str, language: str) -> NarrationResult: ...
+
+
+class MockNarrationBackend:
+    """GPU-free backend for CI and local end-to-end tests (no model load)."""
+
+    def narrate(
+        self, clip_path: Path, *, style_key: str = "deadpan", language: str = "English"
+    ) -> NarrationResult:
+        stem = Path(clip_path).stem
+        return NarrationResult(
+            text=f"[mock {language}] a flat description of {stem}.",
+            audio=[0.0] * 2400,  # 0.1 s @ 24 kHz placeholder
+            sample_rate=24_000,
+            narrator_model="mock",
+            tts_model="mock",
+            narrator_backend="mock",
+            title=stem.replace("-", " ").title()[:TITLE_MAX],
+        )

src/small_cuts/narrator.py

@@ -0,0 +1,491 @@
+"""Narration pipeline with pluggable model backends.
+
+Backend selection is controlled by the SMALL_CUTS_BACKEND env var:
+
+- ``mock``         deterministic, no model weights — CI, tests, UI development
+- ``transformers`` small vision-language model via Hugging Face transformers
+- ``llama_cpp``    GGUF model via llama.cpp (CPU fallback / Llama Champion quest)
+
+All backends are local: no cloud APIs (Off the Grid quest).
+"""
+
+from __future__ import annotations
+
+import atexit
+import base64
+import io
+import json
+import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+from typing import Protocol
+
+import httpx
+from PIL import Image
+
+from .styles import DEFAULT_STYLE_KEY, STYLES, build_messages, clean_scene_hint
+from .title_card import TITLE_MAX_LEN, derive_title
+
+# M1 final pick (docs/eval/run-006-scored.md): beats Qwen2.5-VL-7B head-to-head
+# for BOTH judges (Codex 7/10 vs 0/10, Gemini 9/10 vs 0/10 images passing).
+DEFAULT_MODEL_ID = "Qwen/Qwen3-VL-8B-Instruct"
+LLAMA_REPO_ID = "Qwen/Qwen3-VL-8B-Instruct-GGUF"
+LLAMA_GGUF_FILENAME = "Qwen3VL-8B-Instruct-Q4_K_M.gguf"
+LLAMA_MMPROJ_FILENAME = "mmproj-Qwen3VL-8B-Instruct-F16.gguf"
+LLAMA_TIMEOUT_S = 120.0
+DEFAULT_MAX_NEW_TOKENS = 160
+
+
+@dataclass(frozen=True)
+class Narration:
+    text: str
+    style_key: str
+    backend: str
+    model_id: str
+    latency_s: float
+    title: str = ""
+
+
+class Backend(Protocol):
+    name: str
+    model_id: str
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str: ...
+
+
+class MockBackend:
+    """Deterministic narrator used in CI and UI development.
+
+    Derives a few real features from the image (dimensions, brightness,
+    dominant hue) so the output visibly depends on the input without any
+    model weights.
+    """
+
+    name = "mock"
+    model_id = "mock-narrator-0"
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        style = STYLES[style_key]
+        r, g, b = image.convert("RGB").resize((1, 1)).getpixel((0, 0))
+        brightness = (r + g + b) / 3
+        light = "well-lit" if brightness > 127 else "dimly lit"
+        shape = "wide" if image.width >= image.height else "tall"
+        clean_hint = clean_scene_hint(scene_hint)
+        hint = f" {clean_hint}" if clean_hint else ""
+        narration = (
+            f"[{style.label}] The frame is {shape} and {light}, and the narrator has "
+            f"seen it all before.{hint} What happens next was, frankly, inevitable."
+        )
+        return json.dumps({"title": derive_title(narration), "narration": narration})
+
+
+class TransformersBackend:
+    """Small VLM via transformers. Lazily loads on first use.
+
+    On a ZeroGPU Space, decorate the hot path with ``spaces.GPU`` (handled in
+    app.py so this module stays importable without the ``spaces`` package).
+    """
+
+    name = "transformers"
+
+    def __init__(self, model_id: str | None = None) -> None:
+        self.model_id = model_id or os.environ.get("SMALL_CUTS_MODEL_ID", DEFAULT_MODEL_ID)
+        self._pipe = None
+        self._load_lock = threading.Lock()
+
+    def _load(self):
+        with self._load_lock:
+            if self._pipe is None:
+                import torch
+                from transformers import AutoModelForImageTextToText, AutoProcessor
+
+                self._processor = AutoProcessor.from_pretrained(self.model_id)
+                if torch.cuda.is_available():
+                    # Explicit .to("cuda") — ZeroGPU packs weights on this call;
+                    # accelerate's device_map dispatch would fight it.
+                    self._model = AutoModelForImageTextToText.from_pretrained(
+                        self.model_id, torch_dtype=torch.bfloat16
+                    ).to("cuda")
+                else:
+                    self._model = AutoModelForImageTextToText.from_pretrained(
+                        self.model_id, torch_dtype=torch.float32, device_map="auto"
+                    )
+                self._pipe = True
+        return self._processor, self._model
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        processor, model = self._load()
+        image = _downscale(image)
+        messages = build_messages(style_key, scene_hint)
+        # Attach the image to the user turn in the chat-template format.
+        chat = [
+            {"role": "system", "content": [{"type": "text", "text": messages[0]["content"]}]},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": messages[1]["content"]},
+                ],
+            },
+        ]
+        inputs = processor.apply_chat_template(
+            chat,
+            add_generation_prompt=True,
+            tokenize=True,
+            return_dict=True,
+            return_tensors="pt",
+        ).to(model.device)
+        # Low temperature: judged eval showed small VLMs confabulate; sampling
+        # heat feeds it. Overridable per-run for eval sweeps.
+        temperature = _temperature()
+        output = model.generate(
+            **inputs,
+            max_new_tokens=_max_output_tokens(),
+            do_sample=temperature > 0,
+            temperature=temperature,
+        )
+        text = processor.batch_decode(
+            output[:, inputs["input_ids"].shape[1] :], skip_special_tokens=True
+        )[0]
+        return text.strip()
+
+
+def _downscale(image: Image.Image, max_side: int = 1024) -> Image.Image:
+    """Return a copy whose longest side is at most max_side."""
+    if max(image.size) <= max_side:
+        return image
+    resized = image.copy()
+    resized.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+    return resized
+
+
+class LlamaCppBackend:
+    """GGUF vision model via llama.cpp — CPU fallback and Llama Champion quest."""
+
+    name = "llama_cpp"
+
+    def __init__(self, gguf_path: str | None = None, mmproj_path: str | None = None) -> None:
+        self._external_url = os.environ.get("SMALL_CUTS_LLAMA_URL", "").rstrip("/")
+        self._gguf_path = gguf_path or os.environ.get("SMALL_CUTS_GGUF_PATH", "")
+        self._mmproj_path = mmproj_path or os.environ.get("SMALL_CUTS_MMPROJ_PATH", "")
+        self.model_id = Path(self._gguf_path).name if self._gguf_path else LLAMA_REPO_ID
+        self._server_url = ""
+        self._process: subprocess.Popen | None = None
+        self._stderr_fh = None
+        self._cleanup_registered = False
+        self._spawn_lock = threading.Lock()
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        if self._external_url:
+            server_url = self._external_url
+        else:
+            with self._spawn_lock:  # Gradio handlers are threaded; spawn once
+                server_url = self._ensure_server()
+        body = self._build_request(image, style_key, scene_hint)
+        try:
+            response = httpx.post(
+                f"{server_url}/v1/chat/completions",
+                json=body,
+                timeout=LLAMA_TIMEOUT_S,
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(
+                f"llama-server at {server_url} returned HTTP "
+                f"{exc.response.status_code} for chat completion."
+            ) from exc
+        except httpx.RequestError as exc:
+            raise RuntimeError(f"Could not reach llama-server at {server_url}: {exc}") from exc
+
+        try:
+            content = response.json()["choices"][0]["message"]["content"]
+        except (ValueError, KeyError, IndexError, TypeError) as exc:
+            raise RuntimeError(
+                f"Unexpected llama-server response from {server_url}; expected "
+                "choices[0].message.content."
+            ) from exc
+        if not isinstance(content, str):
+            raise RuntimeError(
+                f"Unexpected llama-server response from {server_url}; message content was not text."
+            )
+        return content.strip()
+
+    def close(self) -> None:
+        process = self._process
+        if process is not None and process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=10)
+        self._process = None
+        self._server_url = ""
+        if self._stderr_fh is not None and not self._stderr_fh.closed:
+            self._stderr_fh.close()
+
+    def _build_request(self, image: Image.Image, style_key: str, scene_hint: str) -> dict:
+        messages = build_messages(style_key, scene_hint)
+        data_uri = _image_data_uri(_downscale(image))
+        return {
+            "messages": [
+                {"role": "system", "content": messages[0]["content"]},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image_url", "image_url": {"url": data_uri}},
+                        {"type": "text", "text": messages[1]["content"]},
+                    ],
+                },
+            ],
+            "temperature": _temperature(),
+            "max_tokens": _max_output_tokens(),
+        }
+
+    def _ensure_server(self) -> str:
+        if self._server_url and self._process is not None and self._process.poll() is None:
+            return self._server_url
+        if self._process is not None and self._process.poll() is not None:
+            self._process = None
+            self._server_url = ""
+
+        binary = _llama_server_binary()
+        gguf_path, mmproj_path = self._model_paths()
+        port = _free_port()
+        self._server_url = f"http://127.0.0.1:{port}"
+        command = [
+            binary,
+            "-m",
+            gguf_path,
+            "--mmproj",
+            mmproj_path,
+            "--port",
+            str(port),
+            "-c",
+            "8192",
+            "--image-max-tokens",
+            "1024",
+            "--host",
+            "127.0.0.1",
+        ]
+        try:
+            self._process = subprocess.Popen(
+                command,
+                stdout=subprocess.DEVNULL,
+                stderr=self._stderr_file(),
+            )
+        except OSError as exc:
+            self._server_url = ""
+            raise RuntimeError(
+                f"Could not start llama-server with {binary!r}. Install llama.cpp "
+                "with `brew install llama.cpp`, set SMALL_CUTS_LLAMA_SERVER to the "
+                "binary path, or point SMALL_CUTS_LLAMA_URL at an already-running server."
+            ) from exc
+
+        if not self._cleanup_registered:
+            atexit.register(self.close)
+            self._cleanup_registered = True
+        self._wait_for_health(self._server_url)
+        return self._server_url
+
+    def _model_paths(self) -> tuple[str, str]:
+        gguf_path = self._gguf_path
+        mmproj_path = self._mmproj_path
+        if gguf_path and mmproj_path:
+            return gguf_path, mmproj_path
+
+        try:
+            from huggingface_hub import hf_hub_download
+        except ImportError as exc:
+            raise RuntimeError(
+                "huggingface_hub is required to resolve the default llama.cpp model. "
+                "Install the local dependencies, or set SMALL_CUTS_GGUF_PATH and "
+                "SMALL_CUTS_MMPROJ_PATH to local files."
+            ) from exc
+
+        if not gguf_path:
+            gguf_path = hf_hub_download(LLAMA_REPO_ID, LLAMA_GGUF_FILENAME)
+        if not mmproj_path:
+            mmproj_path = hf_hub_download(LLAMA_REPO_ID, LLAMA_MMPROJ_FILENAME)
+        return gguf_path, mmproj_path
+
+    def _stderr_file(self):
+        import tempfile
+
+        if self._stderr_fh is not None and not self._stderr_fh.closed:
+            self._stderr_fh.close()
+        self._stderr_path = Path(tempfile.gettempdir()) / f"llama-server-{os.getpid()}.err"
+        self._stderr_fh = self._stderr_path.open("w")
+        return self._stderr_fh
+
+    def _stderr_tail(self, lines: int = 5) -> str:
+        path = getattr(self, "_stderr_path", None)
+        if not path or not Path(path).exists():
+            return ""
+        tail = Path(path).read_text().splitlines()[-lines:]
+        return (" Last stderr lines: " + " | ".join(tail)) if tail else ""
+
+    def _wait_for_health(self, server_url: str) -> None:
+        deadline = time.monotonic() + LLAMA_TIMEOUT_S
+        while time.monotonic() < deadline:
+            if self._process is not None and self._process.poll() is not None:
+                raise RuntimeError(
+                    f"llama-server exited before becoming healthy at {server_url} "
+                    f"(a port conflict is possible).{self._stderr_tail()} "
+                    "Check the GGUF/mmproj paths and llama.cpp installation."
+                )
+            try:
+                response = httpx.get(f"{server_url}/health", timeout=2.0)
+                if response.status_code == 200:
+                    return
+            except httpx.RequestError:
+                pass
+            time.sleep(0.5)
+
+        self.close()
+        raise RuntimeError(
+            f"Timed out waiting for llama-server at {server_url}/health after "
+            f"{int(LLAMA_TIMEOUT_S)} seconds. Check model load time, GGUF/mmproj paths, "
+            "or use SMALL_CUTS_LLAMA_URL to point at a server you started manually."
+        )
+
+
+def _image_data_uri(image: Image.Image) -> str:
+    buffer = io.BytesIO()
+    image.convert("RGB").save(buffer, format="JPEG", quality=90)
+    encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
+    return f"data:image/jpeg;base64,{encoded}"
+
+
+def _temperature() -> float:
+    try:
+        return float(os.environ.get("SMALL_CUTS_TEMPERATURE", "0.3"))
+    except ValueError as exc:
+        raise RuntimeError("SMALL_CUTS_TEMPERATURE must be a floating-point number.") from exc
+
+
+def _max_output_tokens() -> int:
+    raw = os.environ.get("SMALL_CUTS_MAX_NEW_TOKENS", "").strip()
+    if not raw:
+        return DEFAULT_MAX_NEW_TOKENS
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise RuntimeError("SMALL_CUTS_MAX_NEW_TOKENS must be an integer.") from exc
+    if value < 1:
+        raise RuntimeError("SMALL_CUTS_MAX_NEW_TOKENS must be greater than zero.")
+    return value
+
+
+def _llama_server_binary() -> str:
+    configured = os.environ.get("SMALL_CUTS_LLAMA_SERVER", "")
+    binary = configured or shutil.which("llama-server")
+    if binary and _is_executable(binary):
+        return binary
+    raise RuntimeError(
+        "llama.cpp backend needs a llama-server binary. Install it with "
+        "`brew install llama.cpp`, set SMALL_CUTS_LLAMA_SERVER to the binary path, "
+        "or set SMALL_CUTS_LLAMA_URL to an already-running llama-server."
+    )
+
+
+def _is_executable(path: str) -> bool:
+    resolved = path if os.path.sep in path else shutil.which(path)
+    return bool(resolved and Path(resolved).is_file() and os.access(resolved, os.X_OK))
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+_BACKENDS = {
+    "mock": MockBackend,
+    "transformers": TransformersBackend,
+    "llama_cpp": LlamaCppBackend,
+}
+
+
+@cache
+def _backend_instance(key: str) -> Backend:
+    return _BACKENDS[key]()
+
+
+def get_backend(name: str | None = None) -> Backend:
+    key = (name or os.environ.get("SMALL_CUTS_BACKEND", "mock")).lower()
+    if key not in _BACKENDS:
+        raise ValueError(f"Unknown backend {key!r}; expected one of {sorted(_BACKENDS)}")
+    # One instance per backend: model weights load once per process, not per call.
+    return _backend_instance(key)
+
+
+def narrate(
+    image: Image.Image,
+    style_key: str = DEFAULT_STYLE_KEY,
+    scene_hint: str = "",
+    backend: Backend | None = None,
+) -> Narration:
+    """Narrate a single moment. The one entry point the UI calls."""
+    if style_key not in STYLES:
+        raise ValueError(f"Unknown style {style_key!r}")
+    backend = backend or get_backend()
+    start = time.perf_counter()
+    raw = backend.generate(image, style_key, scene_hint)
+    title, text = _parse_generation(raw)
+    return Narration(
+        text=text,
+        style_key=style_key,
+        backend=backend.name,
+        model_id=backend.model_id,
+        latency_s=time.perf_counter() - start,
+        title=title,
+    )
+
+
+def _parse_generation(raw: str) -> tuple[str, str]:
+    """Return (title, narration), tolerating legacy plain-text model output."""
+    text = raw.strip()
+    if not text:
+        return "Untitled Scene", ""
+    parsed = _json_object_from_model(text)
+    if parsed is not None:
+        narration = str(parsed.get("narration", "")).strip()
+        title = _clean_title(str(parsed.get("title", "")).strip(), fallback=narration)
+        if narration:
+            return title, narration
+    return derive_title(text), text
+
+
+def _json_object_from_model(text: str) -> dict | None:
+    candidates = [text]
+    if text.startswith("```"):
+        stripped = text.strip("`").strip()
+        if stripped.lower().startswith("json"):
+            stripped = stripped[4:].strip()
+        candidates.append(stripped)
+    first = text.find("{")
+    last = text.rfind("}")
+    if first != -1 and last > first:
+        candidates.append(text[first : last + 1])
+    for candidate in candidates:
+        try:
+            value = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict):
+            return value
+    return None
+
+
+def _clean_title(title: str, fallback: str) -> str:
+    title = " ".join(title.replace("\n", " ").split())
+    if not title:
+        return derive_title(fallback)
+    return derive_title(title, max_len=TITLE_MAX_LEN)

src/small_cuts/observability.py

@@ -0,0 +1,74 @@
+"""Optional Sentry observability for demo/runtime failures.
+
+No Sentry traffic is sent unless ``SENTRY_DSN`` is configured. Payload scrubbing
+keeps frames, audio, cookies, and auth headers out of events.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+SENTRY_DSN_ENV = "SENTRY_DSN"
+SENTRY_ENV_ENV = "SENTRY_ENVIRONMENT"
+SENTRY_RELEASE_ENV = "SENTRY_RELEASE"
+SENSITIVE_HEADERS = {"authorization", "cookie", "x-api-key", "x-forwarded-for"}
+
+_INITIALIZED = False
+
+
+def init_sentry(dsn: str | None = None, *, sdk: Any | None = None) -> bool:
+    global _INITIALIZED
+    dsn = dsn if dsn is not None else os.environ.get(SENTRY_DSN_ENV, "").strip()
+    if not dsn:
+        return False
+    if _INITIALIZED:
+        return True
+    sdk = sdk or _import_sentry_sdk()
+    if sdk is None:
+        return False
+    sdk.init(
+        dsn=dsn,
+        environment=os.environ.get(SENTRY_ENV_ENV) or os.environ.get("SPACE_ID") or "local",
+        release=os.environ.get(SENTRY_RELEASE_ENV) or os.environ.get("SPACE_COMMIT_SHA"),
+        send_default_pii=False,
+        attach_stacktrace=True,
+        traces_sample_rate=0.0,
+        before_send=_scrub_event,
+    )
+    _INITIALIZED = True
+    return True
+
+
+def capture_exception(exc: BaseException, *, sdk: Any | None = None) -> None:
+    if not _INITIALIZED and not init_sentry(sdk=sdk):
+        return
+    sdk = sdk or _import_sentry_sdk()
+    if sdk is not None:
+        sdk.capture_exception(exc)
+
+
+def _import_sentry_sdk() -> Any | None:
+    try:
+        import sentry_sdk
+    except ImportError:
+        return None
+    return sentry_sdk
+
+
+def _scrub_event(event: dict[str, Any], _hint: dict[str, Any]) -> dict[str, Any]:
+    request = event.get("request")
+    if isinstance(request, dict):
+        request.pop("data", None)
+        request.pop("cookies", None)
+        headers = request.get("headers")
+        if isinstance(headers, dict):
+            request["headers"] = {
+                key: value for key, value in headers.items() if key.lower() not in SENSITIVE_HEADERS
+            }
+    return event
+
+
+def reset_for_tests() -> None:
+    global _INITIALIZED
+    _INITIALIZED = False

src/small_cuts/persistence.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+BUCKET_MOUNT_PATH_ENV = "SMALL_CUTS_BUCKET_MOUNT_PATH"
+
+
+def bucket_mount_path() -> Path | None:
+    raw = os.environ.get(BUCKET_MOUNT_PATH_ENV, "").strip()
+    if not raw:
+        return None
+    return Path(raw).expanduser()
+
+
+def persistent_path(*parts: str) -> Path | None:
+    mount = bucket_mount_path()
+    if mount is None:
+        return None
+    return mount.joinpath("space", *parts)

src/small_cuts/seed_media/desk-laptop.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c50d9aef2c2b3b591b37d28eb24eb1207ee1c1bbd67fd2c387b2de5ed0733480
+size 257229

src/small_cuts/seed_media/desk-laptop.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c6d9e22a67888f755c03d70de70c45ccc2d8b853e0c2f7b6bf00ae58e2f472be
+size 2537344

src/small_cuts/seed_media/night-drive.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8dc4b2d254d62e571e57fba1df98f87e233b75d78426841a864ea135a033040
+size 246573

src/small_cuts/seed_media/night-drive.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06c1866c429bb5a47333e38a56f57ae536b5eb806e6cfedbbb201aea225e26f2
+size 3427164

src/small_cuts/seed_media/rayuela.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dfd85e684c1c231aa0301c47949d427e31646e750ab01d7f52a72b961add1010
+size 294957

src/small_cuts/seed_media/rayuela.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3878bd95d642e3befdc767d2b54d4c4acce8cb43ffef46d1c232ba793cebed01
+size 4268710

src/small_cuts/seed_media/street-parked-car.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7b15be641666c6e99a4038d94fd09f47bce3dada55fa66d10f63c80c6af76b5
+size 169965

src/small_cuts/seed_media/street-parked-car.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d8444745071aab9dc208e77753328b248f472eac11861a920e77e7e607bee8e
+size 4136123

src/small_cuts/seed_media/the-stumble.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ddd9eab9ae92d64c90a94b98759db0f4aa31ccc9cd79ca89c9ef6ea9184e3c2e
+size 233901

src/small_cuts/seed_media/the-stumble.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f8c6ba5d9c32717da065e2a1c923e9c1e96e7830aa5e00038a0e88d367d19baf
+size 3395323

src/small_cuts/space_hooks.py

@@ -0,0 +1,113 @@
+"""Push hooks for relay-scene updates in the Gradio Space.
+
+The Space should not poll Hugging Face control-plane APIs or repeatedly poll the
+relay bucket. The local publisher calls the protected hook after it writes a new
+manifest; browser clients keep one SSE connection open and refresh once per
+hook event.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import os
+from collections.abc import AsyncIterator
+from typing import Annotated, Any
+
+from fastapi import Body, FastAPI, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+RELAY_HOOK_TOKEN_ENV = "SMALL_CUTS_RELAY_HOOK_TOKEN"
+RELAY_HOOK_PATH = "/small-cuts/hooks/relay-scene"
+RELAY_EVENTS_PATH = "/small-cuts/events"
+SSE_HEARTBEAT_S = 15.0
+
+
+class RelayEventHub:
+    def __init__(self) -> None:
+        self._next_id = 0
+        self._subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
+
+    def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=8)
+        self._subscribers.add(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        self._subscribers.discard(queue)
+
+    async def publish(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._next_id += 1
+        event = {"id": self._next_id, "payload": payload or {}}
+        stale: list[asyncio.Queue[dict[str, Any]]] = []
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                stale.append(queue)
+        for queue in stale:
+            self.unsubscribe(queue)
+        return event
+
+
+def install_relay_hooks(app: FastAPI, *, hub: RelayEventHub | None = None) -> RelayEventHub:
+    if getattr(app.state, "small_cuts_relay_hooks_installed", False):
+        return app.state.small_cuts_relay_event_hub
+
+    event_hub = hub or RelayEventHub()
+    app.state.small_cuts_relay_hooks_installed = True
+    app.state.small_cuts_relay_event_hub = event_hub
+
+    @app.post(RELAY_HOOK_PATH, status_code=202)
+    async def relay_scene_hook(
+        payload: Annotated[dict[str, Any] | None, Body()] = None,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, Any]:
+        _require_hook_authorization(authorization)
+        event = await event_hub.publish(payload or {})
+        return {"status": "accepted", "event_id": event["id"]}
+
+    @app.get(RELAY_EVENTS_PATH)
+    async def relay_events(request: Request) -> StreamingResponse:
+        return StreamingResponse(
+            relay_event_stream(event_hub, request, heartbeat_s=SSE_HEARTBEAT_S),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    return event_hub
+
+
+async def relay_event_stream(
+    event_hub: RelayEventHub,
+    request: Request,
+    *,
+    heartbeat_s: float = SSE_HEARTBEAT_S,
+) -> AsyncIterator[str]:
+    queue = event_hub.subscribe()
+    try:
+        yield _sse("ready", {"status": "connected"})
+        while True:
+            if await request.is_disconnected():
+                break
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=heartbeat_s)
+            except asyncio.TimeoutError:
+                yield ": ping\n\n"
+                continue
+            yield _sse("relay-scene", event)
+    finally:
+        event_hub.unsubscribe(queue)
+
+
+def _require_hook_authorization(authorization: str | None) -> None:
+    expected = os.environ.get(RELAY_HOOK_TOKEN_ENV, "").strip()
+    if not expected:
+        raise HTTPException(status_code=503, detail="relay hook is not configured")
+    if not authorization or not hmac.compare_digest(authorization, f"Bearer {expected}"):
+        raise HTTPException(status_code=401, detail="unauthorized")
+
+
+def _sse(event: str, data: dict[str, Any]) -> str:
+    return f"event: {event}\ndata: {json.dumps(data, separators=(',', ':'))}\n\n"

src/small_cuts/styles.py

@@ -0,0 +1,146 @@
+"""Director style presets and prompt construction for the narrator."""
+
+from dataclasses import dataclass
+
+# v3 — evidence-based rebalance. The judged A/B (docs/eval/prompt-ab-comparison.md)
+# showed v2's "find the story" license cost gemma -0.77 S and -0.67 G with zero V
+# gain. v3 restores v1's hard grounding and moves all voice into tone, not facts.
+SYSTEM_PROMPT = (
+    "You are the omniscient narrator of this person's life, in the spirit of the "
+    "narrators in 'The Invention of Lying': you can only say what is true, you see "
+    "the scene exactly as it is, and you describe it with cinematic certainty. "
+    "Narrate ONLY what is visible or directly inferable from the image. Never invent "
+    "objects, people, actions, weather, or sounds. If you are not certain something "
+    "is in the image, leave it out. Quote text on signs only when it is clearly "
+    "legible. Pick the one or two most telling visible details and build the "
+    "narration on them — the director's style changes the TONE of your sentences, "
+    "never the facts. Write 2 to 4 sentences, present tense, third person. "
+    "Also write a short movie-title style title grounded in the same visible facts. "
+    "Output only a compact JSON object with exactly two string keys: "
+    "`title` and `narration`. No markdown, no commentary, no emoji."
+)
+
+
+@dataclass(frozen=True)
+class DirectorStyle:
+    """A narration style, presented to users as a director's cut."""
+
+    key: str
+    label: str
+    direction: str
+    example: str  # one-shot example narration to anchor the voice
+
+
+STYLES: dict[str, DirectorStyle] = {
+    style.key: style
+    for style in (
+        DirectorStyle(
+            key="deadpan",
+            label="Deadpan Omniscient (the classic)",
+            direction=(
+                "Flat, matter-of-fact omniscience. Gentle comic timing comes from "
+                "stating slightly-too-honest truths plainly, the way the narrators "
+                "in 'The Invention of Lying' would."
+            ),
+            example=(
+                "He stirs the coffee for the fourth time, though nothing about it "
+                "has changed. It is, and will remain, slightly too bitter. He "
+                "drinks it anyway, because the mug was a gift and he is sentimental."
+            ),
+        ),
+        DirectorStyle(
+            key="noir",
+            label="Noir Detective",
+            direction=(
+                "Hard-boiled 1940s noir voiceover. Shadows, rain, cigarettes that "
+                "aren't there. World-weary metaphors grounded in what's actually visible."
+            ),
+            example=(
+                "The desk lamp threw its light like an accusation. Somewhere in "
+                "that pile of cables was an answer, and answers in this town never "
+                "came cheap."
+            ),
+        ),
+        DirectorStyle(
+            key="nature_doc",
+            label="Nature Documentary",
+            direction=(
+                "Hushed, reverent wildlife-documentary narration. Treat the subject "
+                "as a fascinating specimen observed in its natural habitat."
+            ),
+            example=(
+                "Here, in the fluorescent clearing of the open-plan office, the "
+                "adult male attempts a ritual as old as the species itself: the "
+                "fourth coffee before noon."
+            ),
+        ),
+        DirectorStyle(
+            key="trailer",
+            label="Epic Trailer Voice",
+            direction=(
+                "Booming movie-trailer gravitas. Short punchy sentences. 'In a "
+                "world...' energy applied to a completely ordinary moment."
+            ),
+            example=("One man. One sandwich. This summer, lunch... changes everything."),
+        ),
+        DirectorStyle(
+            key="telenovela",
+            label="Telenovela",
+            direction=(
+                "Breathless melodrama. Every glance is betrayal, every object holds "
+                "a secret. Spanish-telenovela emotional stakes for mundane scenes."
+            ),
+            example=(
+                "She looks at the empty fridge — the same fridge that promised her "
+                "so much on Sunday. Inside, only mustard remains. Mustard... and lies."
+            ),
+        ),
+        DirectorStyle(
+            key="symmetrist",
+            label="Wes Anderson Symmetrist",
+            direction=(
+                "Precise, whimsical, faux-naive storybook narration. Note colors, "
+                "symmetry, and small formal details. Affectionate melancholy."
+            ),
+            example=(
+                "The bicycle is mustard yellow, which is also the color of the "
+                "third button on his cardigan. He parked it at exactly the angle "
+                "his father would have disapproved of, which is why he did."
+            ),
+        ),
+    )
+}
+
+DEFAULT_STYLE_KEY = "deadpan"
+MAX_SCENE_HINT_CHARS = 280
+
+
+def clean_scene_hint(scene_hint: str) -> str:
+    return scene_hint.strip()[:MAX_SCENE_HINT_CHARS]
+
+
+def style_choices() -> list[tuple[str, str]]:
+    """(label, key) pairs for UI dropdowns."""
+    return [(style.label, style.key) for style in STYLES.values()]
+
+
+def build_messages(style_key: str, scene_hint: str = "") -> list[dict]:
+    """Build the chat messages (minus the image, attached by the backend)."""
+    style = STYLES[style_key]
+    hint = clean_scene_hint(scene_hint)
+    user_text = (
+        f"Director's cut: {style.label}.\n"
+        f"Style direction: {style.direction}\n"
+        f"Example of the voice (different scene): {style.example}\n"
+    )
+    if hint:
+        user_text += f"Context offered by the person living this moment: {hint}\n"
+    user_text += (
+        "Now title and narrate the attached moment as JSON, for example: "
+        '{"title":"The Fourth Coffee","narration":"He stirs the coffee again. '
+        'Nothing about it improves."}'
+    )
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user_text},
+    ]

src/small_cuts/theme.py

@@ -0,0 +1,73 @@
+"""Off-Brand Gradio theme for Small Cuts."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from .title_card import STYLE_CARDS
+
+CANVAS = STYLE_CARDS["trailer"][0]
+MARQUEE_GOLD = STYLE_CARDS["trailer"][1]
+BONE_WHITE = STYLE_CARDS["noir"][1]
+LIFTED_CANVAS = "#16161C"
+BORDER = "#2A292F"
+
+
+class OffBrand(gr.themes.Base):
+    """Dark cinematic Gradio theme using the Small Cuts house palette."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            font=[gr.themes.GoogleFont("Spectral"), "serif"],
+            font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "monospace"],
+        )
+        self.set(
+            body_background_fill=CANVAS,
+            body_background_fill_dark=CANVAS,
+            body_text_color=BONE_WHITE,
+            body_text_color_dark=BONE_WHITE,
+            background_fill_primary=CANVAS,
+            background_fill_primary_dark=CANVAS,
+            background_fill_secondary=LIFTED_CANVAS,
+            background_fill_secondary_dark=LIFTED_CANVAS,
+            block_background_fill=LIFTED_CANVAS,
+            block_background_fill_dark=LIFTED_CANVAS,
+            block_border_color=BORDER,
+            block_border_color_dark=BORDER,
+            block_title_text_color=MARQUEE_GOLD,
+            block_title_text_color_dark=MARQUEE_GOLD,
+            border_color_primary=BORDER,
+            border_color_primary_dark=BORDER,
+            input_background_fill=STYLE_CARDS["noir"][0],
+            input_background_fill_dark=STYLE_CARDS["noir"][0],
+            input_background_fill_focus=CANVAS,
+            input_background_fill_focus_dark=CANVAS,
+            input_border_color=BORDER,
+            input_border_color_dark=BORDER,
+            link_text_color=MARQUEE_GOLD,
+            link_text_color_dark=MARQUEE_GOLD,
+            button_primary_background_fill=MARQUEE_GOLD,
+            button_primary_background_fill_dark=MARQUEE_GOLD,
+            button_primary_border_color=MARQUEE_GOLD,
+            button_primary_border_color_dark=MARQUEE_GOLD,
+            button_primary_text_color=CANVAS,
+            button_primary_text_color_dark=CANVAS,
+            button_secondary_background_fill=LIFTED_CANVAS,
+            button_secondary_background_fill_dark=LIFTED_CANVAS,
+            button_secondary_text_color=BONE_WHITE,
+            button_secondary_text_color_dark=BONE_WHITE,
+            button_secondary_border_color=BORDER,
+            button_secondary_border_color_dark=BORDER,
+            # P0 contrast fixes (#28): code chips rendered near-white-on-white
+            # and the in-block labels were too dim on the charcoal canvas.
+            code_background_fill=STYLE_CARDS["noir"][0],
+            code_background_fill_dark=STYLE_CARDS["noir"][0],
+            block_label_text_color=MARQUEE_GOLD,
+            block_label_text_color_dark=MARQUEE_GOLD,
+            block_label_background_fill=LIFTED_CANVAS,
+            block_label_background_fill_dark=LIFTED_CANVAS,
+        )
+
+
+def build_theme() -> gr.themes.Base:
+    return OffBrand()

src/small_cuts/title_card.py

@@ -0,0 +1,183 @@
+"""Deterministic movie-style title cards for Small Cuts."""
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .styles import STYLES
+
+TITLE_MAX_LEN = 60
+
+STYLE_CARDS = {
+    "deadpan": ("#F2EFE6", "#1A1A1A", "rules"),
+    "noir": ("#0D0D0F", "#E8E4D8", "hard_frame"),
+    "nature_doc": ("#0E2A1B", "#F0E9D2", "double_frame"),
+    "trailer": ("#101014", "#D4AF37", "spaced"),
+    "telenovela": ("#5C0A14", "#FFE9EC", "ornament"),
+    "symmetrist": ("#F7D6C9", "#5B3A29", "thin_frame"),
+}
+
+
+def derive_title(text: str, max_len: int = TITLE_MAX_LEN) -> str:
+    value = text.strip()
+    if value.startswith("["):
+        tag_end = value.find("]")
+        if tag_end != -1:
+            value = value[tag_end + 1 :].strip()
+    if not value:
+        return "Untitled Scene"
+    title = _first_clause(value).strip()
+    if not title:
+        return "Untitled Scene"
+    return _truncate_title(title, max_len)
+
+
+def render_title_card(
+    title: str,
+    style_key: str,
+    size: tuple[int, int] = (1280, 720),
+) -> Image.Image:
+    style = STYLES[style_key]
+    bg, fg, treatment = STYLE_CARDS[style_key]
+    width, height = size
+    image = Image.new("RGB", size, bg)
+    draw = ImageDraw.Draw(image)
+    if treatment == "hard_frame":
+        inset = max(8, min(width, height) // 22)
+        box = (inset, inset, width - inset - 1, height - inset - 1)
+        draw.rectangle(box, outline=fg, width=2)
+    elif treatment == "double_frame":
+        inset = max(8, min(width, height) // 24)
+        for offset in (inset, inset + max(4, inset // 3)):
+            box = (offset, offset, width - offset - 1, height - offset - 1)
+            draw.rectangle(box, outline=fg)
+    elif treatment == "thin_frame":
+        draw.rectangle((8, 8, width - 9, height - 9), outline=fg)
+    margin = max(12, width // 9)
+    content_width = max(1, width - margin * 2)
+    max_title_height = max(24, int(height * 0.42))
+    spaced = treatment == "spaced"
+    for size_px in range(max(12, int(height * 0.12)), 5, -2):
+        title_font = _font(size_px)
+        lines = _wrap(draw, title.strip().upper(), title_font, content_width, spaced)
+        block_width, block_height = _block(draw, lines, title_font)
+        if block_width <= content_width and block_height <= max_title_height:
+            break
+    else:
+        title_font = _font(6)
+        lines = _wrap(draw, title.strip().upper(), title_font, content_width, spaced)
+        _, block_height = _block(draw, lines, title_font)
+    kicker_font = _font(max(10, int(height * 0.04)))
+    subtitle_font = _font(max(10, int(height * 0.035)))
+    _center(draw, "A SMALL CUTS PICTURE", width, int(height * 0.17), kicker_font, fg)
+    if lines:
+        title_top = max(int(height * 0.28), (height - block_height) // 2)
+        title_size = getattr(title_font, "size", 12)
+        if treatment == "rules":
+            top_rule = max(8, title_top - title_size // 2)
+            bottom_rule = min(height - 8, title_top + block_height + title_size // 2)
+            draw.line((margin, top_rule, width - margin, top_rule), fill=fg)
+            draw.line((margin, bottom_rule, width - margin, bottom_rule), fill=fg)
+        line_height = _measure(draw, "Ag", title_font)[1]
+        y = title_top
+        for line in lines:
+            _center(draw, line, width, y, title_font, fg)
+            y += line_height
+        if treatment == "ornament":
+            _center(draw, "♦ ─── ♦", width, y + max(8, title_size // 4), subtitle_font, fg)
+    subtitle_y = min(height - getattr(subtitle_font, "size", 10) * 2, int(height * 0.78))
+    _center(draw, style.label.upper(), width, subtitle_y, subtitle_font, fg)
+    return image
+
+
+def _first_clause(text: str) -> str:
+    index = 0
+    while index < len(text):
+        if text.startswith("...", index):
+            if _ellipsis_ends_clause(text, index, 3):
+                return text[:index]
+            index += 3
+            continue
+        if text[index] == "…":
+            if _ellipsis_ends_clause(text, index, 1):
+                return text[:index]
+        elif text[index] in ".!?;—":
+            return text[:index]
+        index += 1
+    return text
+
+
+def _ellipsis_ends_clause(text: str, index: int, width: int) -> bool:
+    if len(text[:index].split()) < 3:
+        return False
+    next_index = index + width
+    if next_index >= len(text) or not text[next_index].isspace():
+        return False
+    while next_index < len(text) and text[next_index].isspace():
+        next_index += 1
+    return next_index < len(text) and text[next_index].isupper()
+
+
+def _truncate_title(title: str, max_len: int) -> str:
+    if max_len < 1:
+        return ""
+    if len(title) <= max_len:
+        return title
+    if max_len == 1:
+        return "…"
+    cut = -1
+    for index, char in enumerate(title[:max_len]):
+        if char.isspace():
+            cut = index
+    if cut <= 0:
+        return "…"
+    return f"{title[:cut].rstrip()}…"
+
+
+def _font(size):
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:
+        return ImageFont.load_default()
+
+
+def _wrap(draw, text, font, max_width, spaced):
+    def show(value):
+        return " ".join(value) if spaced else value
+
+    def fits(value):
+        return _measure(draw, show(value), font)[0] <= max_width
+
+    lines = []
+    current = ""
+    for word in text.split():
+        candidate = f"{current} {word}".strip()
+        if fits(candidate):
+            current = candidate
+            continue
+        if current:
+            lines.append(show(current))
+        current = word
+        while len(current) > 1 and not fits(current):
+            split = 1
+            while split < len(current) and fits(current[: split + 1]):
+                split += 1
+            lines.append(show(current[:split]))
+            current = current[split:]
+    if current:
+        lines.append(show(current))
+    return lines
+
+
+def _block(draw, lines, font):
+    line_height = _measure(draw, "Ag", font)[1]
+    widths = [_measure(draw, line, font)[0] for line in lines]
+    return max(widths, default=0), len(lines) * line_height
+
+
+def _center(draw, text, width, y, font, fill):
+    x = (width - _measure(draw, text, font)[0]) / 2
+    draw.text((x, y), text, font=font, fill=fill)
+
+
+def _measure(draw, text, font):
+    left, top, right, bottom = draw.textbbox((0, 0), text, font=font)
+    return right - left, bottom - top

src/small_cuts/tts.py

@@ -0,0 +1,133 @@
+"""Text-to-speech pipeline with pluggable local backends."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from dataclasses import dataclass
+from functools import cache
+from typing import Protocol
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Speech:
+    sample_rate: int
+    audio: np.ndarray
+    backend: str
+    model_id: str
+    latency_s: float
+
+
+class TTSBackend(Protocol):
+    name: str
+    model_id: str
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]: ...
+
+
+class MockTTSBackend:
+    name = "mock"
+    model_id = "mock-tts-0"
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]:
+        sample_rate = 24_000
+        duration_s = min(2.0, max(0.2, len(text) / 40))
+        encoded = text.encode("utf-8")
+        frequency = 220 + sum((i + 1) * byte for i, byte in enumerate(encoded)) % 220
+        samples = int(sample_rate * duration_s)
+        t = np.arange(samples, dtype=np.float32) / sample_rate
+        audio = 0.25 * np.sin(2 * np.pi * frequency * t)
+        return sample_rate, audio.astype(np.float32, copy=False)
+
+
+class KokoroBackend:
+    name = "kokoro"
+    model_id = "hexgrad/Kokoro-82M"
+
+    def __init__(self) -> None:
+        self._pipeline = None
+        self._load_lock = threading.Lock()
+
+    def _load(self):
+        with self._load_lock:
+            if self._pipeline is None:
+                try:
+                    from kokoro import KPipeline
+                except ImportError as exc:
+                    raise RuntimeError(
+                        "Kokoro TTS is not installed. Run `uv sync --extra tts` to enable it."
+                    ) from exc
+                # Pin to CPU: on ZeroGPU the hijacked CUDA is only usable inside
+                # @spaces.GPU, and the speak path runs outside it. Forcing
+                # map_location keeps torch.load from initializing CUDA in the
+                # main process while restoring the checkpoint — that cuInit
+                # poisons every later ZeroGPU worker fork ("No CUDA GPUs are
+                # available").
+                import torch
+
+                device = os.environ.get("SMALL_CUTS_TTS_DEVICE", "cpu")
+                original_load = torch.load
+
+                def _cpu_load(*args, **kwargs):
+                    kwargs["map_location"] = "cpu"
+                    return original_load(*args, **kwargs)
+
+                torch.load = _cpu_load
+                try:
+                    self._pipeline = KPipeline(lang_code="a", device=device)
+                finally:
+                    torch.load = original_load
+        return self._pipeline
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]:
+        pipeline = self._load()
+        voice = os.environ.get("SMALL_CUTS_TTS_VOICE", "af_heart")
+        segments = []
+        for _, _, audio in pipeline(text, voice=voice):
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            segment = np.asarray(audio, dtype=np.float32).reshape(-1)
+            segments.append(segment)
+        if not segments:
+            return 24_000, np.zeros(0, dtype=np.float32)
+        return 24_000, np.clip(np.concatenate(segments), -1.0, 1.0).astype(np.float32, copy=False)
+
+
+_BACKENDS = {
+    "mock": MockTTSBackend,
+    "kokoro": KokoroBackend,
+}
+
+
+@cache
+def _backend_instance(key: str) -> TTSBackend:
+    return _BACKENDS[key]()
+
+
+def get_tts_backend(name: str | None = None) -> TTSBackend:
+    key = (name or os.environ.get("SMALL_CUTS_TTS_BACKEND", "mock")).lower()
+    if key not in _BACKENDS:
+        raise ValueError(f"Unknown TTS backend {key!r}; expected one of {sorted(_BACKENDS)}")
+    # One instance per backend: the Kokoro pipeline loads once per process.
+    return _backend_instance(key)
+
+
+def speak(text: str, backend: TTSBackend | None = None) -> Speech:
+    text = text.strip()
+    if not text:
+        raise ValueError("Cannot synthesize empty text")
+    backend = backend or get_tts_backend()
+    start = time.perf_counter()
+    sample_rate, audio = backend.synthesize(text)
+    audio = np.asarray(audio, dtype=np.float32).reshape(-1)
+    audio = np.clip(audio, -1.0, 1.0).astype(np.float32, copy=False)
+    return Speech(
+        sample_rate=sample_rate,
+        audio=audio,
+        backend=backend.name,
+        model_id=backend.model_id,
+        latency_s=time.perf_counter() - start,
+    )

src/small_cuts/ui.py

@@ -0,0 +1,126 @@
+"""Gradio UI for Small Cuts."""
+
+from __future__ import annotations
+
+import gradio as gr
+import numpy as np
+from PIL import Image
+
+from .frames import pick_key_frame, sample_frames
+from .narrator import get_backend, narrate
+from .styles import DEFAULT_STYLE_KEY, style_choices
+from .theme import build_theme
+from .title_card import derive_title, render_title_card
+from .tts import speak
+
+TITLE = "🎬 Small Cuts"
+TAGLINE = (
+    "Your life, narrated. Drop in a moment — from your phone, webcam, or "
+    "smart-glasses footage — pick a director, and hear what scene you're really in. "
+    "Every model under 32B. Everything runs in this Space."
+)
+
+# Off-Brand cinematic theme for the M2 custom UI quest.
+THEME = build_theme()
+
+
+def _gpu(duration: int = 90):
+    """Mark an event handler for ZeroGPU. No-op off-Space.
+
+    ZeroGPU's startup scan looks for the GPU mark on the functions Gradio
+    binds — decorating an inner helper instead leaves requests unscheduled
+    (worker dies with "No CUDA GPUs are available"). TTS is marked too:
+    any torch forward in the main process poisons later worker forks.
+    """
+
+    def deco(fn):
+        try:
+            import spaces
+        except ImportError:
+            return fn
+        return spaces.GPU(duration=duration)(fn)
+
+    return deco
+
+
+def _narrate_core(
+    image: Image.Image | None, style_key: str, scene_hint: str, empty_text: str
+) -> tuple[Image.Image, str]:
+    if image is None:
+        text = empty_text
+    else:
+        result = narrate(image, style_key=style_key, scene_hint=scene_hint or "")
+        text = result.text
+    return render_title_card(derive_title(text), style_key), text
+
+
+@_gpu()
+def _narrate_handler(
+    image: Image.Image | None, style_key: str, scene_hint: str
+) -> tuple[Image.Image, str]:
+    return _narrate_core(
+        image,
+        style_key,
+        scene_hint,
+        "The narrator clears his throat, looks at the empty screen, and waits. "
+        "Some scenes, after all, require a scene.",
+    )
+
+
+@_gpu()
+def _narrate_video_handler(
+    video_path: str | None, style_key: str, scene_hint: str
+) -> tuple[Image.Image, str]:
+    frame = pick_key_frame(sample_frames(video_path)) if video_path else None
+    return _narrate_core(
+        frame,
+        style_key,
+        scene_hint,
+        "The narrator squints at the projector. Nothing. He has narrated "
+        "blank screens before, but never by choice.",
+    )
+
+
+@_gpu(duration=30)
+def _speak_handler(text: str) -> tuple[int, np.ndarray] | None:
+    if not text.strip():
+        return None
+    speech = speak(text)
+    return speech.sample_rate, speech.audio
+
+
+def build_app() -> gr.Blocks:
+    backend = get_backend()
+    with gr.Blocks(title=TITLE) as demo:
+        gr.Markdown(f"# {TITLE}\n{TAGLINE}")
+        with gr.Row():
+            with gr.Column(scale=1):
+                image = gr.Image(label="Your moment", type="pil", sources=["upload", "webcam"])
+                video = gr.Video(
+                    label="…or a clip (glasses or phone, narrates the middle of the scene)",
+                    sources=["upload"],
+                )
+                style = gr.Dropdown(
+                    choices=style_choices(),
+                    value=DEFAULT_STYLE_KEY,
+                    label="Director's cut",
+                )
+                hint = gr.Textbox(
+                    label="Anything the narrator should know? (optional)",
+                    placeholder="e.g. this is my third coffee today",
+                )
+                go = gr.Button("🎬 Roll narration", variant="primary")
+            with gr.Column(scale=1):
+                card = gr.Image(label="Title card", interactive=False)
+                narration = gr.Textbox(label="The narrator says…", lines=8)
+                speak_btn = gr.Button("🔊 Read it to me", variant="secondary")
+                audio = gr.Audio(label="The narrator speaks…", interactive=False)
+                gr.Markdown(
+                    f"<sub>backend: `{backend.name}` · model: `{backend.model_id}` · "
+                    "no cloud APIs — Off the Grid 🏕️</sub>"
+                )
+        go.click(_narrate_handler, inputs=[image, style, hint], outputs=[card, narration])
+        image.change(_narrate_handler, inputs=[image, style, hint], outputs=[card, narration])
+        video.change(_narrate_video_handler, inputs=[video, style, hint], outputs=[card, narration])
+        speak_btn.click(_speak_handler, inputs=[narration], outputs=[audio])
+    return demo

src/small_cuts/upload_budget.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .persistence import persistent_path
+
+UPLOAD_BUDGET_DB_ENV = "SMALL_CUTS_UPLOAD_BUDGET_DB"
+DAILY_GPU_BUDGET_SECONDS_ENV = "SMALL_CUTS_DAILY_GPU_BUDGET_SECONDS"
+GPU_RESERVATION_SECONDS_ENV = "SMALL_CUTS_GPU_SECONDS_PER_UPLOAD_RESERVATION"
+UPLOAD_RESERVATION_TTL_SECONDS_ENV = "SMALL_CUTS_UPLOAD_RESERVATION_TTL_SECONDS"
+DEFAULT_BUDGET_DB = "~/.small-cuts/upload-budget.sqlite3"
+DEFAULT_DAILY_LIMIT_S = 20 * 60
+DEFAULT_RESERVE_S = 60
+DEFAULT_RESERVATION_TTL_S = 30 * 60
+
+_DAILY_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS upload_daily_budget (
+    day TEXT PRIMARY KEY,
+    used_s REAL NOT NULL DEFAULT 0,
+    reserved_s REAL NOT NULL DEFAULT 0,
+    updated_at TEXT NOT NULL
+)"""
+_RESERVATIONS_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS upload_reservations (
+    reservation_id TEXT PRIMARY KEY,
+    day TEXT NOT NULL,
+    reserved_s REAL NOT NULL,
+    created_at_s REAL NOT NULL,
+    expires_at_s REAL NOT NULL
+)"""
+_RESERVATIONS_INDEX = """\
+CREATE INDEX IF NOT EXISTS idx_upload_reservations_day_expiry
+ON upload_reservations(day, expires_at_s)
+"""
+_NO_EXPIRY_S = 1.0e20
+
+
+@dataclass(frozen=True)
+class BudgetDecision:
+    allowed: bool
+    token: dict[str, Any] | None = None
+    message: str = ""
+    remaining_s: float = 0.0
+
+
+class DailyProcessingBudget:
+    """Global daily upload-processing budget.
+
+    The budget is intentionally identity-free. It protects demo GPU credits by tracking committed
+    processing seconds for the current UTC day. A preflight reservation counts against the limit
+    immediately, so queued concurrent requests cannot all pass the same remaining-capacity check.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path | None = None,
+        *,
+        daily_limit_s: float | None = None,
+        reserve_s: float | None = None,
+        reservation_ttl_s: float | None = None,
+        now_fn: Callable[[], float] | None = None,
+    ) -> None:
+        self.db_path = Path(
+            db_path
+            or os.environ.get(UPLOAD_BUDGET_DB_ENV)
+            or persistent_path("upload-budget.sqlite3")
+            or DEFAULT_BUDGET_DB
+        )
+        self.db_path = self.db_path.expanduser().resolve()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.daily_limit_s = float(
+            daily_limit_s
+            if daily_limit_s is not None
+            else os.environ.get(DAILY_GPU_BUDGET_SECONDS_ENV, DEFAULT_DAILY_LIMIT_S)
+        )
+        self.reserve_s = float(
+            reserve_s
+            if reserve_s is not None
+            else os.environ.get(GPU_RESERVATION_SECONDS_ENV, DEFAULT_RESERVE_S)
+        )
+        self.reservation_ttl_s = float(
+            reservation_ttl_s
+            if reservation_ttl_s is not None
+            else os.environ.get(UPLOAD_RESERVATION_TTL_SECONDS_ENV, DEFAULT_RESERVATION_TTL_S)
+        )
+        self._now = now_fn or time.time
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(self.db_path, check_same_thread=False, isolation_level=None)
+        self._db.execute("PRAGMA busy_timeout = 5000")
+        self._db.execute(_DAILY_SCHEMA)
+        self._db.execute(_RESERVATIONS_SCHEMA)
+        self._db.execute(_RESERVATIONS_INDEX)
+        self._migrate_legacy_reserved_seconds()
+
+    @classmethod
+    def from_env(cls) -> DailyProcessingBudget:
+        return cls()
+
+    def try_reserve(self, reserve_s: float | None = None) -> BudgetDecision:
+        reserve = max(0.0, float(self.reserve_s if reserve_s is None else reserve_s))
+        day = self._day_key()
+        with self._lock:
+            with self._transaction():
+                self._ensure_day(day)
+                self._expire_stale_reservations(day)
+                used_s, reserved_s = self._totals(day)
+                committed_s = used_s + reserved_s
+                remaining_s = max(0.0, self.daily_limit_s - committed_s)
+                if reserve > remaining_s:
+                    return BudgetDecision(
+                        allowed=False,
+                        message="Demo daily GPU budget reached. Uploads reopen tomorrow.",
+                        remaining_s=remaining_s,
+                    )
+                reservation_id = uuid.uuid4().hex
+                now_s = self._now()
+                expires_at_s = (
+                    now_s + self.reservation_ttl_s if self.reservation_ttl_s > 0 else _NO_EXPIRY_S
+                )
+                self._db.execute(
+                    """
+                    INSERT INTO upload_reservations
+                        (reservation_id, day, reserved_s, created_at_s, expires_at_s)
+                    VALUES (?, ?, ?, ?, ?)
+                    """,
+                    (reservation_id, day, reserve, now_s, expires_at_s),
+                )
+                self._db.execute(
+                    "UPDATE upload_daily_budget SET updated_at = ? WHERE day = ?",
+                    (self._now_iso(), day),
+                )
+            return BudgetDecision(
+                allowed=True,
+                token={"day": day, "reservation_id": reservation_id, "reserved_s": reserve},
+                remaining_s=max(0.0, remaining_s - reserve),
+            )
+
+    def finish(self, token: Any, elapsed_s: float) -> None:
+        if not isinstance(token, dict):
+            return
+        day = str(token.get("day") or "")
+        if not day:
+            return
+        reserved_s = max(0.0, float(token.get("reserved_s") or 0.0))
+        elapsed = max(0.0, float(elapsed_s or 0.0))
+        reservation_id = str(token.get("reservation_id") or "")
+        with self._lock, self._transaction():
+            self._ensure_day(day)
+            if reservation_id:
+                self._db.execute(
+                    """
+                    DELETE FROM upload_reservations
+                    WHERE day = ? AND reservation_id = ?
+                    """,
+                    (day, reservation_id),
+                )
+            elif reserved_s > 0:
+                self._release_reserved_seconds(day, reserved_s)
+            self._db.execute(
+                """
+                UPDATE upload_daily_budget
+                SET used_s = used_s + ?, reserved_s = 0, updated_at = ?
+                WHERE day = ?
+                """,
+                (elapsed, self._now_iso(), day),
+            )
+
+    def seconds_used_today(self) -> float:
+        with self._lock:
+            day = self._day_key()
+            with self._transaction():
+                self._ensure_day(day)
+                used_s, _ = self._totals(day)
+        return used_s
+
+    def seconds_committed_today(self) -> float:
+        with self._lock:
+            day = self._day_key()
+            with self._transaction():
+                self._ensure_day(day)
+                self._expire_stale_reservations(day)
+                used_s, reserved_s = self._totals(day)
+        return used_s + reserved_s
+
+    def close(self) -> None:
+        self._db.close()
+
+    def _day_key(self) -> str:
+        return datetime.fromtimestamp(self._now(), tz=timezone.utc).date().isoformat()
+
+    def _now_iso(self) -> str:
+        return datetime.fromtimestamp(self._now(), tz=timezone.utc).isoformat()
+
+    def _ensure_day(self, day: str) -> None:
+        self._db.execute(
+            """
+            INSERT OR IGNORE INTO upload_daily_budget (day, used_s, reserved_s, updated_at)
+            VALUES (?, 0, 0, ?)
+            """,
+            (day, self._now_iso()),
+        )
+
+    def _totals(self, day: str) -> tuple[float, float]:
+        row = self._db.execute(
+            "SELECT used_s FROM upload_daily_budget WHERE day = ?", (day,)
+        ).fetchone()
+        if row is None:
+            return 0.0, 0.0
+        reserved = self._db.execute(
+            "SELECT COALESCE(SUM(reserved_s), 0) FROM upload_reservations WHERE day = ?",
+            (day,),
+        ).fetchone()
+        return float(row[0]), float(reserved[0] if reserved is not None else 0.0)
+
+    def _expire_stale_reservations(self, day: str) -> None:
+        if self.reservation_ttl_s <= 0:
+            return
+        self._db.execute(
+            "DELETE FROM upload_reservations WHERE day = ? AND expires_at_s <= ?",
+            (day, self._now()),
+        )
+
+    def _release_reserved_seconds(self, day: str, reserved_s: float) -> None:
+        remaining = reserved_s
+        rows = self._db.execute(
+            """
+            SELECT reservation_id, reserved_s
+            FROM upload_reservations
+            WHERE day = ?
+            ORDER BY created_at_s ASC, reservation_id ASC
+            """,
+            (day,),
+        ).fetchall()
+        for reservation_id, row_reserved_s in rows:
+            if remaining <= 0:
+                break
+            row_reserved = float(row_reserved_s)
+            if row_reserved <= remaining:
+                self._db.execute(
+                    "DELETE FROM upload_reservations WHERE reservation_id = ?",
+                    (reservation_id,),
+                )
+                remaining -= row_reserved
+            else:
+                self._db.execute(
+                    """
+                    UPDATE upload_reservations
+                    SET reserved_s = ?
+                    WHERE reservation_id = ?
+                    """,
+                    (row_reserved - remaining, reservation_id),
+                )
+                remaining = 0
+
+    def _migrate_legacy_reserved_seconds(self) -> None:
+        with self._transaction():
+            rows = self._db.execute(
+                """
+                SELECT day, reserved_s, updated_at
+                FROM upload_daily_budget
+                WHERE reserved_s > 0
+                """
+            ).fetchall()
+            now_s = self._now()
+            for day, reserved_s, updated_at in rows:
+                reserved = float(reserved_s)
+                if reserved <= 0:
+                    continue
+                parsed = _parse_updated_at(str(updated_at))
+                created_at_s = parsed.timestamp() if parsed is not None else now_s
+                if self.reservation_ttl_s > 0 and now_s - created_at_s > self.reservation_ttl_s:
+                    continue
+                self._db.execute(
+                    """
+                    INSERT OR IGNORE INTO upload_reservations
+                        (reservation_id, day, reserved_s, created_at_s, expires_at_s)
+                    VALUES (?, ?, ?, ?, ?)
+                    """,
+                    (
+                        f"legacy-{day}",
+                        str(day),
+                        reserved,
+                        created_at_s,
+                        created_at_s + self.reservation_ttl_s
+                        if self.reservation_ttl_s > 0
+                        else _NO_EXPIRY_S,
+                    ),
+                )
+            self._db.execute("UPDATE upload_daily_budget SET reserved_s = 0 WHERE reserved_s > 0")
+
+    @contextmanager
+    def _transaction(self):
+        self._db.execute("BEGIN IMMEDIATE")
+        try:
+            yield
+        except BaseException:
+            self._db.execute("ROLLBACK")
+            raise
+        else:
+            self._db.execute("COMMIT")
+
+
+def _parse_updated_at(value: str) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)

src/small_cuts/upload_library.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import base64
+import copy
+import json
+import os
+import re
+import shutil
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+from PIL import Image
+
+from .hf_relay import GRADIO_FILE_ROUTE, gradio_file_url
+from .persistence import persistent_path
+
+UPLOAD_LIBRARY_DIR_ENV = "SMALL_CUTS_UPLOAD_LIBRARY_DIR"
+DEFAULT_UPLOAD_LIBRARY_DIR = "~/.small-cuts/uploads"
+SOURCE = "upload"
+
+_DATA_URI_RE = re.compile(r"^data:(?P<mime>[-\w./+]+);base64,(?P<body>.*)$", re.DOTALL)
+_MEDIA_FILENAMES = {
+    "frame_url": "frame.jpg",
+    "card_url": "card.webp",
+    "audio_url": "voice.wav",
+    "clip_url": "clip.mp4",
+}
+_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS upload_scenes (
+    scene_id TEXT PRIMARY KEY,
+    created_at TEXT NOT NULL,
+    stored_at TEXT NOT NULL,
+    payload TEXT NOT NULL
+)"""
+
+
+class LocalUploadLibrary:
+    """Persistent upload shelf backed by SQLite plus stable media files."""
+
+    def __init__(self, root: str | Path | None = None) -> None:
+        base = (
+            root
+            or os.environ.get(UPLOAD_LIBRARY_DIR_ENV)
+            or persistent_path("upload-library")
+            or DEFAULT_UPLOAD_LIBRARY_DIR
+        )
+        self.root = Path(base).expanduser().resolve()
+        self.media_dir = self.root / "media"
+        self.media_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(self.root / "uploads.sqlite3", check_same_thread=False)
+        self._db.execute(_SCHEMA)
+        self._db.commit()
+
+    @classmethod
+    def from_env(cls) -> LocalUploadLibrary:
+        return cls()
+
+    def save_scene(
+        self,
+        scene: dict[str, Any],
+        *,
+        source_video_path: str | Path | None = None,
+    ) -> dict[str, Any]:
+        payload = _json_safe_scene(scene)
+        scene_id = _safe_path_segment(str(payload.get("scene_id") or "upload-scene"))
+        scene_dir = self.media_dir / scene_id
+        scene_dir.mkdir(parents=True, exist_ok=True)
+
+        media = payload.get("media") if isinstance(payload.get("media"), dict) else {}
+        payload["media"] = dict(media)
+        for key, filename in _MEDIA_FILENAMES.items():
+            value = payload["media"].get(key)
+            if isinstance(value, str):
+                payload["media"][key] = self._materialize_value(value, scene_dir, filename)
+
+        frame_src = payload.pop("frame_src", None)
+        if isinstance(frame_src, str):
+            payload["media"]["frame_url"] = self._materialize_value(
+                frame_src, scene_dir, "frame.jpg"
+            )
+
+        audio_src = payload.pop("audio_src", None)
+        if isinstance(audio_src, str):
+            payload["media"]["audio_url"] = self._materialize_value(
+                audio_src, scene_dir, "voice.wav"
+            )
+
+        clip_src = payload.pop("clip_src", None)
+        if source_video_path:
+            clip_name = f"clip{Path(source_video_path).suffix or '.mp4'}"
+            payload["media"]["clip_url"] = self._copy_file(
+                Path(source_video_path), scene_dir, clip_name
+            )
+        elif isinstance(clip_src, str):
+            payload["media"]["clip_url"] = self._materialize_value(clip_src, scene_dir, "clip.mp4")
+
+        card_thumb = scene.get("card_thumb")
+        if isinstance(card_thumb, Image.Image):
+            card_path = scene_dir / "card.webp"
+            card_thumb.save(card_path, "WEBP")
+            payload["media"]["card_url"] = gradio_file_url(card_path)
+
+        payload.pop("card_thumb", None)
+        payload.setdefault("scene_id", scene_id)
+        payload.setdefault("created_at", _now_iso())
+        payload.setdefault("visibility", "private")
+        payload["source"] = SOURCE
+        payload["source_icon"] = SOURCE
+
+        stored_at = _now_iso()
+        with self._lock, self._db:
+            self._db.execute(
+                """
+                INSERT INTO upload_scenes (scene_id, created_at, stored_at, payload)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(scene_id) DO UPDATE SET
+                    created_at = excluded.created_at,
+                    stored_at = excluded.stored_at,
+                    payload = excluded.payload
+                """,
+                (
+                    str(payload["scene_id"]),
+                    str(payload["created_at"]),
+                    stored_at,
+                    json.dumps(payload, sort_keys=True),
+                ),
+            )
+        return copy.deepcopy(payload)
+
+    def list_scenes(self, limit: int = 60) -> list[dict[str, Any]]:
+        with self._lock:
+            rows = self._db.execute(
+                """
+                SELECT payload FROM (
+                    SELECT created_at, scene_id, payload
+                    FROM upload_scenes
+                    ORDER BY created_at DESC, scene_id DESC
+                    LIMIT ?
+                )
+                ORDER BY created_at ASC, scene_id ASC
+                """,
+                (int(limit),),
+            ).fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+    def static_paths(self) -> list[Path]:
+        return [self.root]
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+    def _materialize_value(self, value: str, scene_dir: Path, filename: str) -> str:
+        if value.startswith(("http://", "https://")):
+            return value
+        data = _decode_data_uri(value)
+        if data is not None:
+            target = scene_dir / filename
+            target.write_bytes(data)
+            return gradio_file_url(target)
+        source = _local_path_from_url(value)
+        if source is not None and source.is_file():
+            return self._copy_file(source, scene_dir, filename)
+        return value
+
+    def _copy_file(self, source: Path, scene_dir: Path, filename: str) -> str:
+        target = scene_dir / _safe_path_segment(filename)
+        if source.resolve() != target.resolve():
+            shutil.copy2(source, target)
+        return gradio_file_url(target)
+
+
+def _json_safe_scene(scene: dict[str, Any]) -> dict[str, Any]:
+    clone = {key: value for key, value in scene.items() if key != "card_thumb"}
+    return json.loads(json.dumps(clone, default=str))
+
+
+def _decode_data_uri(value: str) -> bytes | None:
+    match = _DATA_URI_RE.match(value)
+    if not match:
+        return None
+    return base64.b64decode(match.group("body"), validate=False)
+
+
+def _local_path_from_url(value: str) -> Path | None:
+    if value.startswith(GRADIO_FILE_ROUTE):
+        return Path(unquote(value[len(GRADIO_FILE_ROUTE) :]))
+    path = Path(value)
+    return path if path.is_absolute() else None
+
+
+def _safe_path_segment(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in ("-", "_", ".") else "-" for ch in value)
+    return cleaned.strip(".-") or "item"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()