Deploy hybrid Modal upload

README.md

@@ -1,5 +1,5 @@
 ---
-title: Small Cuts Live
+title: Small Cuts
 emoji: 🎬
 colorFrom: indigo
 colorTo: purple
@@ -17,7 +17,7 @@ tags:
   - achievement:fieldnotes
 ---
 
-# Small Cuts Live 🎬
+# Small Cuts 🎬
 
 > *"And that was the moment Carlos realized the coffee had been decaf all along."*
 
@@ -36,7 +36,7 @@ This is the **challenger submission** for the
 **June 15, 2026, 23:59 UTC**), the strategic successor to the original
 *Director's Cut* project.
 
-## The soul of it — the live loop
+## The soul of it — the Action-to-Cut loop
 
 Small Cuts was born wearing glasses. The intended experience is a **live loop**:
 
@@ -46,14 +46,15 @@ Ray-Ban Meta glasses  ──image frames──▶  home engine (small VLM + TTS)
                                               └──── finished cuts ────▶  the Space (watch · library)
 ```
 
-You walk through a moment; the narrator watches a selected first-person frame and speaks
-one grounded, deadpan line back in your ear while the moment is still *recent past*. The
-finished cut then lands in the Space as a short POV clip with synced captions, title, voice,
-and library thumbnail.
+You walk through a moment, tap **Action!**, then tap **Cut!** when the scene has a readable
+beat. The narrator watches a selected first-person frame and speaks one grounded, deadpan line
+back in your ear while the moment is still *recent past*. The finished cut then lands in the
+Space as a short POV clip with synced captions, title, voice, and library thumbnail.
 
-**One pipeline, two surfaces:** the narration returns *in your ear* during capture, and lands
-in the **Space** below as a finished cut you can re-watch — with film-style subtitles that
-crawl in sync with the voice — and publish to a library.
+**One completed-cut experience, multiple inputs:** from the Space's point of view, glasses cuts
+and authenticated browser uploads resolve to the same artifact shape: a finished video, generated
+title, generated narration, Kokoro voice, synced captions, and a library tile. Glasses remain the
+private wearer path; browser uploads are a judge-verifiable path with no glasses or iOS required.
 
 ## What's in this Space
 
@@ -66,7 +67,8 @@ The Space is the **view platform + library** half of the loop — a small stream
 - **A public library** of real Ray-Ban Meta glasses moments, generated through the same local
   engine path so the channel is never empty. The source clips and mark points are curated; the
   visible titles, narration, voice, thumbnails, and clips are produced by Small Cuts.
-- **"Try it"** — a tucked-away sandbox (open only on request) to narrate your *own* short video.
+- **"Try it"** — a tucked-away, HF-login upload drawer that sends your short video to a private
+  Modal post-cut service, then replays the generated cut in the same theater.
 
 ## How it was built
 
@@ -74,7 +76,8 @@ The Space is the **view platform + library** half of the loop — a small stream
 |---|---|---|
 | Narrator (VLM) | `Qwen/Qwen3-VL-8B-Instruct` | Strong grounded captioning at 8B — well under 32B |
 | Voice (TTS) | **Kokoro** (24 kHz) | Tiny, expressive, open; one signature deadpan delivery |
-| Space runtime | Gradio 6 on CPU, viewer-only for live demo | The judged canvas: public theater + library |
+| Space runtime | Gradio 6 on CPU | Public theater + library; uploads call Modal instead of warming models |
+| Judge upload service | Modal GPU app (`small-cuts-postcut`) | Finished-video verification path with real Qwen + Kokoro output |
 | Local live engine | FastAPI WS home node, **llama.cpp** | The in-ear loop + demo video; no cloud LLM/TTS API |
 | Capture | iOS app for Ray-Ban Meta glasses (`ios/SmallCuts/`) | First-person moments, the way it's meant to be lived |
 
@@ -117,6 +120,13 @@ SMALL_CUTS_BACKEND=transformers uv run --no-sync python app.py
 # run the real-time engine (needs `brew install llama.cpp`)
 SMALL_CUTS_BACKEND=llama_cpp SMALL_CUTS_TTS_BACKEND=kokoro uv run python -m small_cuts.engine
 
+# run the hybrid relay + Modal upload Space locally (token comes from your local secret env)
+SMALL_CUTS_RELAY_BUCKET=build-small-hackathon/small-cuts-scenes \
+SMALL_CUTS_RELAY_PREFIX=relay \
+SMALL_CUTS_ENABLE_UPLOAD_SANDBOX=1 \
+SMALL_CUTS_MODAL_API_URL=https://macayaven--small-cuts-postcut-api.modal.run \
+uv run --no-sync python app.py
+
 # the gate (mirrors CI exactly)
 uv run ruff check . && uv run ruff format --check . && uv run pytest
 ```

app.py

@@ -34,14 +34,16 @@ 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())
-VIEWER_ONLY_MODE = ENGINE_MODE or RELAY_MODE
+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 not VIEWER_ONLY_MODE:
+if ON_SPACE and NEEDS_LOCAL_INFERENCE:
     os.environ.setdefault("SMALL_CUTS_BACKEND", "transformers")
     os.environ.setdefault("SMALL_CUTS_TTS_BACKEND", "kokoro")
 
@@ -54,7 +56,7 @@ init_sentry()
 # Eager load: download + pack weights at startup, not on the first click.
 # The @spaces.GPU mark lives on the viewer's go-live handler (via ui._gpu;
 # ZeroGPU's startup scan only finds GPU functions on what Gradio binds).
-if not VIEWER_ONLY_MODE:
+if NEEDS_LOCAL_INFERENCE:
     _backend = narrator.get_backend()
     if spaces is not None and _backend.name == "transformers":
         _backend._load()

docs/demo-readiness.md

@@ -0,0 +1,229 @@
+# Demo-Readiness Checklist
+
+Last updated: 2026-06-15 16:16 CEST.
+
+## Current Architecture Override - 2026-06-15
+
+This section supersedes the older Cloudflare engine-mode checklist items below. Keep the old
+evidence for audit/history, but do not use it as the active deploy posture for the final run.
+
+- Active judged Space: `build-small-hackathon/small-cuts-live`, public, `cpu-basic`.
+- Paused/private Spaces: `build-small-hackathon/small-cuts` and
+  `build-small-hackathon/small-cuts-buffer-poc`.
+- The live Space is currently viewer-only. It reads finished scenes from the HF bucket relay, not
+  from Cloudflare or a live engine URL. The next implementation pass should make this same Space
+  hybrid by adding the judge upload path below.
+- Current relay settings:
+  - `SMALL_CUTS_RELAY_BUCKET=build-small-hackathon/small-cuts-scenes`
+  - `SMALL_CUTS_RELAY_PREFIX=relay`
+  - `SMALL_CUTS_BACKEND=mock`
+  - `SMALL_CUTS_TTS_BACKEND=mock`
+- The relay bucket currently has only the canary/health object; intentional library population is
+  still pending.
+- Private live path remains: Ray-Ban Meta glasses -> iPhone app -> Mac Studio engine over
+  Tailnet/local network -> `SceneAudio` back to the iPhone/glasses after the wearer taps `Cut!`.
+  This local glasses-to-ear return path is non-negotiable.
+- Public Space path is post-cut: after the take is completed, publish the finished clip, generated
+  title, narration, voice, thumbnail/poster, and manifest into the HF bucket relay.
+- Test order for the final run:
+  1. Short physical glasses smoke first, before populating the public library.
+  2. Populate the library only from controlled, honest pipeline outputs.
+  3. Run the full demo rehearsal after both private ear playback and public relay playback are
+     proven.
+- Judge verification upload target for the next implementation pass: the submitted Gradio Space
+  must expose a finished-video upload path so judges can verify the app without glasses, iOS, or
+  local Tailnet access. Allow uploads up to 60 seconds by default and process them as completed
+  cuts. This matches an instant-clip/reel-length posture while keeping the Modal path bounded.
+- Before deploying upload controls to the submitted org Space, prove this through the private Modal
+  app `small-cuts-postcut`.
+- The final org Space should become a hybrid surface only after the Modal POC passes:
+  - relay/library mode for the live demo and public just-happened clips;
+  - on-demand upload mode for judge verification, with real Modal-hosted narration/TTS, not mock
+    output.
+- Keep the submitted Space on `cpu-basic` for the Modal path. The Space should not warm Qwen/Kokoro;
+  it accepts uploads, requires HF login for upload only, calls Modal server-side, and renders the
+  returned scene.
+- Modal upload inference should use the hackathon grant aggressively but bounded: H100 first with
+  A100-80GB and L40S fallbacks, one warm GPU container, one active buffer container, and up to four
+  GPU containers for parallel uploads. Do not use same-container GPU concurrency for Qwen/Kokoro
+  unless the model/TTS pipeline is explicitly proven thread-safe.
+- Glasses-origin public clips should not go through Modal. `Action!` starts capture and `Cut!`
+  finalizes the take; after the local engine has produced clip, title, narration, and speech for
+  in-ear playback, the completed scene can be auto-published to the relay bucket by the local/admin
+  publisher. Those scenes should include `source="glasses"` and render a small glasses icon in the
+  top-left of the Space stage/library tile.
+- Library population target: use longer, controlled, honest clip artifacts for the public relay
+  library instead of the current very short 24-frame samples.
+- iOS restores wearer captions/status for the private glasses path: after `Cut!`, the phone shows a
+  waiting caption, then swaps to the generated narration when `SceneAudio` arrives. This baseline is
+  live post-cut, not continuous narration while rolling.
+- `cpu-basic` remains correct for the Space if Modal handles judge-upload inference. ZeroGPU is now
+  only a contingency if Modal is deliberately ruled out after a measured failure.
+
+## Modal Post-Cut POC Evidence - 2026-06-15 15:30 CEST
+
+- [x] Modal CLI authenticated as profile `macayaven`.
+- [x] Stale Small Cuts Modal app `small-cuts-buffer-inference-poc` was stopped before creating the
+  new post-cut infra. The two interrupted `small-cuts-postcut` dev serve attempts are also stopped.
+- [x] Modal secret `small-cuts-postcut` exists in Modal environment `main` with keys `HF_TOKEN` and
+  `SMALL_CUTS_MODAL_API_TOKEN`; no token values were written to repo docs.
+- [x] Private Modal app `small-cuts-postcut` deployed at
+  `https://macayaven--small-cuts-postcut-api.modal.run`.
+- [x] Modal GPU policy encoded as H100 -> A100-80GB -> L40S, with
+  `min_containers=1`, `buffer_containers=1`, `max_containers=4`, and no same-container GPU
+  concurrency on the Qwen/Kokoro worker.
+- [x] Upload cap is now 60 seconds by default, with the Space-facing
+  `SMALL_CUTS_UPLOAD_MAX_SECONDS` remaining the deployment override. A 61-second synthetic MP4 was
+  rejected by the deployed Modal API with HTTP 422 and message
+  `video is too long; upload up to 60 seconds`.
+- [x] Local syntax/lint smoke passed:
+  `python -m py_compile modal_app/small_cuts_postcut.py`,
+  `uv run ruff check modal_app/small_cuts_postcut.py src/small_cuts/engine/library.py tests/test_engine_library.py`,
+  `uv run ruff format --check modal_app/small_cuts_postcut.py src/small_cuts/engine/library.py tests/test_engine_library.py`,
+  and
+  `uv run pytest tests/test_engine_library.py::test_write_clip_mp4_can_disable_blends -q`.
+- [x] Clean Modal dev serve smoke accepted `/private/tmp/small-cuts-codec-smoke.mp4` in 0.63 s,
+  completed with real Qwen/Kokoro output, and returned scene `modal-6da427b60106`:
+  title `The Green Screen`, model `Qwen/Qwen3-VL-8B-Instruct`, TTS `hexgrad/Kokoro-82M`.
+- [x] HF bucket artifact writing smoke passed: `relay/uploads/modal-6da427b60106/` contains exactly
+  `scene.json`, `media/frame.jpg`, `media/card.webp`, `media/clip.mp4`, and `media/voice.wav`.
+  Relay root was checked after cleanup and contains only `health.txt` plus `uploads/`.
+- [x] Space-side Modal client smoke accepted `/private/tmp/small-cuts-upload-5s.mp4` in 121.66 s
+  against the deployed endpoint, returned scene `modal-04f98e2795cd` with title
+  `The Smoke Test`, `source="upload"`, generated narration, `media/clip.mp4`, and
+  `media/voice.wav`.
+- [x] HF bucket artifact writing smoke passed for
+  `relay/uploads/modal-04f98e2795cd/`: `scene.json`, `media/frame.jpg`, `media/card.webp`,
+  `media/clip.mp4`, and `media/voice.wav`.
+
+## Local Hybrid Verification - 2026-06-15 15:49 CEST
+
+- [x] Full Python gate passed:
+  `uv run ruff check . && uv run ruff format --check . && uv run pytest`
+  (`205 passed`, 4 warnings).
+- [x] Full iOS simulator gate passed with the plan command on `iPhone 17, OS=26.5`:
+  `66 tests`, `1` expected live-engine smoke skipped, `0` failures.
+- [x] Local Gradio relay/upload-sandbox app launched on `http://127.0.0.1:7860` with
+  `SMALL_CUTS_ENABLE_UPLOAD_SANDBOX=1`, the deployed Modal URL, and the HF relay bucket.
+- [x] Local Gradio OAuth mock sign-in worked as `macayaven`; the upload icon opened the
+  video-only upload drawer while anonymous cookie-free page load returned HTTP `200`.
+- [x] Local >60-second guard rejected `/private/tmp/small-cuts-upload-61s.mp4` before any Modal
+  call with `Please upload a clip up to 60 seconds.`
+
+## Judged Space
+
+- [x] Historical Space `build-small-hackathon/small-cuts` is public; active final target is
+  `build-small-hackathon/small-cuts-live` per the architecture override above.
+- [x] Space runs on `cpu-basic` as a viewer/library, not as the inference host.
+- [x] `SMALL_CUTS_ENGINE_URL` points at the public read gate.
+- [x] Active Space endpoint uses the known-good quick tunnel:
+  `https://lincoln-greene-paragraph-tcp.trycloudflare.com`.
+- [x] Visibility controls are disabled in Space engine mode.
+- [x] Space loads a live engine scene through Cloudflare.
+- [x] Space fetches `frame.jpg`, `card.webp`, `voice.wav`, and `clip.mp4` through `/media/*`.
+- [x] Custom player uses file-backed `<audio id="sc-voice">` as the master clock.
+- [x] Play/pause is bound to trusted DOM gestures instead of a Gradio callback.
+- [x] Latest Space source deploy includes final thumbnail/title polish:
+  `3654f4e89f44a994f64332bdea980290f7c2039f`.
+- [x] Space README-only copy update deployed as `8dfd628308a0849d4e9fc0baa646af94c33b949d`;
+  runtime returned to `RUNNING` and post-rebuild browser smoke still loaded the five hero cuts.
+- [x] Browser automation verifies the active Space renders the real POV `rayuela` scene with
+  ready `clip.mp4` and `voice.wav` on desktop.
+- [x] Browser automation verifies the active Space library uses real POV `frame.jpg` thumbnails
+  after the final deploy.
+- [x] Public library is populated with five preselected first-person glasses clips sent through the
+  regular `/v1/session` engine pipeline, using 24-frame key-marked moment envelopes.
+- [x] Public generated library serves each scene with `frame.jpg`, `card.webp`, `voice.wav`, and
+  24-frame / 6 fps `clip.mp4` through the Cloudflare read gate.
+- [ ] Human browser smoke: click play on the Space and confirm video, sound, captions, and progress advance together.
+- [x] Gradio API smoke verifies the active Space `_tick` renders the latest generated title, video
+  stage, Cloudflare `clip.mp4`, ready `voice.wav`, visibility `public`, and five gallery captions.
+- [x] Mobile viewport smoke verifies no document overflow, ready `clip.mp4`/`voice.wav`, captions,
+  and the five generated library thumbnails.
+- [ ] Physical mobile smoke on iPhone Safari.
+
+## Private Live Path
+
+- [x] Mac Studio engine listens privately on Tailnet-compatible `:8077`.
+- [x] Public Cloudflare path points to read gate on `127.0.0.1:8078`, not directly to the engine.
+- [x] Public `GET /v1/scenes` returns `200`.
+- [x] Public `GET /v1/session` returns `403`.
+- [x] Public `PATCH /v1/scenes/*` returns `403`.
+- [x] Synthetic 24-frame moment returns `ack accepted` and `SceneAudio`.
+- [x] Synthetic scene stores both audio and `clip.mp4`.
+- [x] Real seed POV clip (`rayuela.mp4`) returns `ack accepted`, `SceneAudio`, idle status,
+  and public `clip.mp4`/`voice.wav` through the read gate.
+- [x] Latest local engine restart is on the retained-storage-task fix, then warmed with
+  `rayuela.mp4` scene `162a9e89-3494-45d2-b28e-bf2a03d8c3cf` on the final thumbnail code.
+- [x] Final warm-up scene stores `clip.mp4`, `voice.wav`, and a POV `frame.jpg`; active Space
+  renders it as the newest cut with no desktop overflow.
+- [x] Model-generated library audit populated a clean five-scene run from the preselected glasses
+  clips before the hero-library switch. Quality was mixed: car-door, night-drive, and rayuela were
+  usable; the desk-laptop opener was too literal because the selected frame emphasized an overlay.
+- [x] Curated hero rows were archived into SQLite table
+  `hidden_scenes_20260615_regular_pipeline_swap` and removed from the active `scenes` table, with
+  media preserved.
+- [x] The final public library now comes from session
+  `regular-pipeline-24f-keymark-glasses-20260615T083000Z`; the previous 24-frame final-frame run
+  is archived in `hidden_scenes_20260615_final_frame_24f`.
+- [x] Public media smoke confirms all five active scenes return `200` for `clip.mp4`, `voice.wav`,
+  `frame.jpg`, and `card.webp`.
+- [x] Hidden warm-up moment against the hero-root engine returned `SceneAudio` in 15.4 s on
+  2026-06-15 09:09 CEST; the warm-up row/media were pruned, leaving exactly the five hero cuts
+  visible through Cloudflare.
+- [x] `tmux` session `small-cuts-awake` is running `caffeinate -dimsu` to keep the Mac Studio
+  awake for the live services.
+- [x] iOS simulator suite passes: 64 tests, 1 live-engine smoke skipped, 0 failures.
+- [x] Opt-in Swift live-engine smoke passes against `ws://127.0.0.1:8077/v1/session`
+  with real `SceneAudio` in 4.4 s.
+- [x] Physical-device prep: `xcrun xctrace list devices` sees the iPhone 14 Pro on iOS 26.6,
+  and `xcodebuild build` for destination `00008120-001045510C3B401E` succeeded with
+  command-line signing overrides only.
+- [x] Current build installed to the physical iPhone via `xcrun devicectl device install app`.
+- [x] Relay publisher dry-run against `http://127.0.0.1:8077` with
+  `--include-private --source glasses` staged one scene locally and wrote `source="glasses"` plus
+  `source_icon="glasses"` into the staged manifest without syncing the HF bucket.
+- [x] Manual physical app launch happened after install; observed behavior is live post-cut:
+  narration returns after `Cut!`, not continuously while rolling.
+- [ ] Physical iPhone simulated-source smoke after reinstalling the latest app.
+- [ ] Physical Ray-Ban Meta glasses smoke: in-ear narration returns while the Space receives the same cut.
+
+## Submission Metadata
+
+- [x] README identifies the app as the Gradio Space submission.
+- [x] README documents models under 32B: Qwen3-VL-8B + Kokoro.
+- [x] README claims `track:wood`, `achievement:offgrid`, `achievement:offbrand`, `achievement:llama`, and `achievement:fieldnotes`.
+- [x] Redeploy README/frontmatter after this checklist update.
+- [x] Verify the Space metadata shows `offgrid` and `llama` tags after redeploy.
+- [ ] Make the field-notes URL public; `https://huggingface.co/blog/macayaven/small-cuts-field-notes`
+  returned `401` on 2026-06-15 09:06 CEST. Full publishable draft is in
+  `docs/field-notes-small-cuts.md`.
+- [ ] Add demo video link.
+- [ ] Add social post link.
+- [ ] Run the submission analyzer before final submission.
+
+## Demo Video
+
+- [ ] Capture one motion-rich first-person moment from the glasses.
+- [ ] Show in-ear narration returning to the wearer.
+- [ ] Show the HF Space receiving the same just-happened POV clip.
+- [ ] Show the custom theater player replaying video, audio, captions, and title.
+- [ ] Keep final cut under 2 minutes, ideally around 60-90 seconds.
+
+## Known Constraints
+
+- Capture is image-frame only for this version; source audio is intentionally not part of the payload.
+- The current iOS capture path is `Action!` -> `Cut!` -> local narration return. True rolling
+  micro-segment narration with chronological continuity metadata is planned next.
+- The Space is the public viewer, while local hardware runs the live small-model inference/TTS path.
+- Browser autoplay with sound is intentionally not promised; sound starts from the explicit play gesture.
+- Cloudflare quick-tunnel hostnames are ephemeral. The named `small-cuts.carloscrespomacaya.com`
+  tunnel direct smoke is `200` for reads and `403` for writes, but the HF Space stayed on
+  "Signal lost" when pointed at it during this run. Keep the Space on the known-good quick tunnel
+  until that Cloudflare/HF interaction is isolated.
+- The current public library root is `/private/tmp/small-cuts-demo-library-generated-24f-20260615`.
+  A full curated-library backup exists at
+  `/private/tmp/small-cuts-demo-library-hero-20260615.pre-generated-backup-20260615T080924Z`.
+  Earlier model-generated roots remain available as
+  `/private/tmp/small-cuts-demo-library-hero-20260615` and
+  `/private/tmp/small-cuts-demo-library-curated-20260615`.

docs/field-notes-small-cuts.md

@@ -11,6 +11,12 @@ model writes a grounded deadpan narration, Kokoro turns it into speech, the wear
 the same finished POV cut appears in a Hugging Face Gradio Space with video, voice, captions, title,
 and library thumbnail.
 
+The same public surface also supports a judge-verifiable browser upload path. From the Space's
+point of view, origin should not change the playback contract: when a cut is complete, it appears
+as a video with generated title, generated narration, generated voice, captions, and a thumbnail.
+The difference is upstream. Glasses are the private physical input. Browser uploads are a finished
+video path, authenticated with Hugging Face and processed by a private Modal GPU service.
+
 ## The product shape
 
 The important decision was to keep the Space as the public product surface, not the capture path.
@@ -19,12 +25,11 @@ the master clock, captions follow the audio, and the library shows real POV fram
 generic generated cards.
 
 The glasses path stays private. During the live demo, the iPhone writes to the local engine over
-Tailnet. Public viewers and the Space only read finished scenes through a Cloudflare read gate:
-`GET /v1/scenes`, `GET /v1/scenes/stream`, and `/media/*`. The public hostname blocks the
-WebSocket capture path and visibility writes. That split is less glamorous than making everything
-public, but it is the right product boundary: private capture, public replay. For the hackathon
-demo this rides on a Cloudflare tunnel; a production version would turn that into durable auth,
-domain, and publishing controls rather than opening the capture path.
+Tailnet. Public viewers and the Space read finished scenes through a relay/library surface rather
+than opening the capture socket. That split is less glamorous than making everything public, but it
+is the right product boundary: private capture, public replay. For the hackathon demo this relies
+on local hardware plus hosted relay artifacts; a production version would turn that into durable
+auth, domain, and publishing controls rather than opening the capture path.
 
 ## Why small models worked
 
@@ -78,10 +83,15 @@ source sound is not needed for the narrator concept, and excluding it keeps priv
 simpler.
 
 The current live model reasons over sampled frames from an intentional Action-to-Cut take. The
-viewer can show a short POV clip assembled from those supplemental frames, but full video reasoning
-is a v2 direction. The next version should buffer a low-resolution clip directly into the Space,
-generate narration fragments with timestamps, and let the finished cut feel even closer to what the
-wearer experienced.
+wearer hears the generated line after Cut, and the Space receives the completed cut. The viewer can
+show a short POV clip assembled from supplemental frames, but rolling micro-segment narration is the
+next production-grade version.
+
+That next version should send small chronological segments while the take is still rolling, attach
+device metadata such as time of day, motion, coarse location when explicitly permitted, and source
+state, and let the narrator maintain continuity across fragments. The public Space would still show
+the same completed-cut theater experience, but the wearer path would feel more like a narrator
+thinking alongside the moment rather than only after it.
 
 Title generation now shares the model call with narration: the model returns a short grounded title
 and the spoken narration together, with deterministic title derivation kept as a fallback for

docs/submission-assets-2026-06-15.md

@@ -0,0 +1,222 @@
+# Submission Assets - 2026-06-15
+
+Working timestamp: 2026-06-15 14:16 UTC / 16:16 CEST.
+
+Deadline: 2026-06-15 23:59 UTC / 2026-06-16 01:59 CEST.
+Time remaining at this pass: about 9 hours 43 minutes.
+Target latest demo start with six-hour buffer: 2026-06-15 17:59 UTC / 19:59 CEST.
+
+## Final Product Submission
+
+Submit **Small Cuts** as a public Gradio Space that turns first-person glasses moments into
+short cinematic cuts: a local small-model engine narrates the wearer POV, speaks it back in-ear,
+and publishes the finished clip to a polished Space theater/library.
+
+One-line pitch:
+
+> A deadpan AI narrator for your life: Ray-Ban Meta POV moments become tiny narrated films,
+> spoken in your ear and replayed on a public Hugging Face Space.
+
+Short description:
+
+> Small Cuts is a glasses-to-ear-to-Space loop. The iPhone sends image-frame moments from
+> Ray-Ban Meta glasses to a private Mac Studio engine. Qwen3-VL-8B through llama.cpp writes a
+> grounded deadpan narration, Kokoro speaks it, the wearer hears it, and the same just-happened
+> POV clip lands in a Gradio theater with synced captions, title, voice, and library thumbnail.
+
+Submission baseline:
+
+- The public Space is source-agnostic once a cut is complete: glasses-origin scenes and
+  authenticated browser uploads render as the same theater artifact with video, generated title,
+  generated narration, Kokoro voice, synced captions, and a library tile.
+- The browser upload path is for judge verification. It requires Hugging Face login, sends the
+  finished video to the private Modal `small-cuts-postcut` service, and does not promise glasses,
+  iOS, or real-time capture.
+- The current glasses path is live post-cut: `Action!` records, `Cut!` sends the moment to the
+  private local engine, and `SceneAudio` returns to the wearer. Rolling micro-segment narration
+  while the take is still in progress is the next production-grade phase.
+
+## Why It Can Win
+
+- It is not another chat wrapper. The product gesture is physical: look, mark, hear, replay.
+- The judged Space is polished and alive: five real first-person glasses clips now populate the
+  public library after being sent through the same WebSocket/read-gated media path as live cuts.
+- The architecture maps cleanly to the hackathon quests: small open models, Gradio Space, custom
+  Off-Brand frontend, local/offgrid inference, and llama.cpp.
+- The demo has an obvious "show a friend" moment: ordinary life becomes a tiny film with a
+  narrator that notices the absurdity.
+- If hardware is unstable, the fallback is still strong: real glasses footage, local narration,
+  Kokoro voice, and Space replay.
+
+## Known Weaknesses
+
+- The live model narrates one selected frame per moment; the mini-MP4 gives context in the viewer
+  but the VLM is not yet doing full video reasoning.
+- The current iOS wearer path is not continuous narration while rolling; narration returns after
+  `Cut!`. The planned next phase is chronological micro-segments with device metadata and continuity
+  state.
+- Browser audio cannot autoplay; the Space correctly requires a user click before sound.
+- Public viewing depends on the current Cloudflare quick tunnel until the named tunnel/HF
+  interaction is isolated.
+- The public library now uses engine-generated narration, so it is honest as a model-quality sample.
+  The take end point is curated per source clip, matching how a wearer would tap Cut! when the
+  moment is readable.
+
+## Current Public Generated Library
+
+Live root: `/private/tmp/small-cuts-demo-library-generated-24f-20260615`
+
+Public read gate:
+
+```text
+https://lincoln-greene-paragraph-tcp.trycloudflare.com
+```
+
+Scenes visible in the Space:
+
+| Order | Title | Role |
+|---:|---|---|
+| 1 | A hand, palm up, blocks the camera's view, revealing a... | Builder/desk sample; still literal but coherent |
+| 2 | The camera lingers on a concrete alleyway at night, the... | Night urban atmosphere |
+| 3 | The car door is open, revealing a black interior and a... | Strong physical POV situation |
+| 4 | The driver grips the steering wheel with both hands, thumbs... | Motion/interior sample |
+| 5 | The yellow circle with numbers is painted on the floor... | Strongest current generated hero cut |
+
+Recommended library/thumbnail hero:
+
+```text
+The yellow circle with numbers is painted on the floor...
+scene_id: aead3e4d-2459-4638-81b8-74abddd2a149
+poster: /private/tmp/small-cuts-demo-library-generated-24f-20260615/media/aead3e4d-2459-4638-81b8-74abddd2a149/frame.jpg
+clip: /private/tmp/small-cuts-demo-library-generated-24f-20260615/media/aead3e4d-2459-4638-81b8-74abddd2a149/clip.mp4
+```
+
+Reason: it is visually legible, currently active on the Space, uses the regular engine path, and
+has the best current generated line: "as if marking a spot for something that never happened."
+
+## Demo Video Plan
+
+Target duration: 60-90 seconds.
+
+Shot list:
+
+1. 3-5 seconds: show the live Space already populated with the five-cut library.
+2. 6-10 seconds: show iPhone app connected to `ws://mac-studio.tail48bab7.ts.net:8077/v1/session`
+   or current Tailnet MagicDNS equivalent.
+3. 10-25 seconds: wear glasses and capture one readable motion-rich moment.
+4. 25-40 seconds: trigger/mark the moment and capture in-ear narration returning.
+5. 40-60 seconds: show the same cut appear in the HF Space.
+6. 60-80 seconds: click play in the Space; show video, Kokoro voice, captions, progress, title,
+   and library thumbnail moving together.
+7. Final 5 seconds: hold on the Space URL and the "Small Cuts" brand.
+
+Primary live take criteria:
+
+- Move for at least four seconds before marking.
+- Choose a scene with one readable object/situation, not a visually noisy crowd.
+- Avoid faces if possible.
+- Do not trigger several marks in a row; one clean moment beats a cluttered library update.
+- Warm the engine with one throwaway moment before recording the hero take.
+
+Fallback demo if glasses/Bluetooth wobble:
+
+- Use a real glasses-recorded POV clip.
+- Send it through the local engine as a simulated moment.
+- Show in the video that the Space receives a finished cut with clip, voice, captions, title, and
+  thumbnail. State truthfully that the judged Space is the product surface and the live glasses
+  path is the intended input path under test.
+
+## Social Post Draft
+
+Short version:
+
+> Built **Small Cuts** for the @huggingface Build Small Hackathon: Ray-Ban Meta POV moments become
+> tiny narrated films. A local Qwen3-VL-8B + Kokoro engine speaks the narration in-ear, while a
+> Gradio Space replays the same just-happened cut with synced captions and a cinematic library.
+> #buildsmall
+
+Longer version:
+
+> Small Cuts is my Build Small Hackathon submission: a deadpan AI narrator for ordinary life.
+> Ray-Ban Meta glasses capture first-person moments, an iPhone sends image frames privately to a
+> Mac Studio, Qwen3-VL-8B through llama.cpp writes a grounded narration, Kokoro speaks it back in
+> the ear, and the finished POV cut lands in a public Gradio Space with video, voice, captions,
+> title, and library thumbnail. It is deliberately small, local, and weirdly cinematic. #buildsmall
+
+Add after posting:
+
+```text
+Space: https://huggingface.co/spaces/build-small-hackathon/small-cuts-live
+Demo: TODO
+```
+
+## Field Notes Draft
+
+Suggested title:
+
+```text
+Small Cuts: Building a narrator for the moments that just happened
+```
+
+Outline:
+
+1. The product idea: life becomes small narrated cuts, not a chatbot.
+2. Why glasses: first-person context makes the narration feel lived, not uploaded.
+3. Why small models: Qwen3-VL-8B is enough when the prompt is grounded and the moment is chosen.
+4. Why local/offgrid: latency, privacy, and hackathon constraints all point to the home engine.
+5. The hard parts:
+   - selecting the right frame,
+   - returning in-ear audio quickly,
+   - making the Space feel like a streaming platform, not a model demo,
+   - keeping public read separate from private write.
+6. What worked:
+   - audio-clock-driven video/caption sync,
+   - real POV thumbnails,
+   - read-gated public Cloudflare endpoint,
+   - model-generated public library from real glasses clips.
+7. What is next:
+   - rolling micro-segment narration for the glasses path,
+   - optional device metadata for chronology and narrative continuity,
+   - full video reasoning over buffered clips,
+   - stronger title generation,
+   - durable named tunnel,
+   - publish controls/auth.
+
+Closing paragraph:
+
+> The best version of Small Cuts is not a camera feature. It is a private narrator that notices
+> the little cinematic beats a person usually walks past, says one honest line in the ear, and
+> leaves behind a tiny film that feels like it happened on purpose.
+
+## Final Submission Checklist
+
+Official field guide requirements checked from `build-small-hackathon/field-guide`:
+
+- Ship a Gradio Space inside the `build-small-hackathon` org.
+- Record a public demo video.
+- Publish one social media post.
+- Put both links in the Space README.
+- Put track and badge tags in the README YAML frontmatter.
+
+- [x] Space is public and running on `cpu-basic`.
+- [x] Deployed Space SHA is `3654f4e89f44a994f64332bdea980290f7c2039f`.
+- [x] Space variable `SMALL_CUTS_ENGINE_URL` points at
+  `https://lincoln-greene-paragraph-tcp.trycloudflare.com`.
+- [x] HF metadata includes `track:wood`, `achievement:offgrid`, `achievement:offbrand`,
+  `achievement:llama`, and `achievement:fieldnotes`.
+- [x] Cloudflare public read gate serves the five key-marked generated scenes with `clip.mp4`,
+  `voice.wav`, `frame.jpg`, and `card.webp`.
+- [x] Cloudflare blocks public `/v1/session` and `PATCH /v1/scenes/*` with `403`.
+- [x] Space Gradio `_tick` smoke returns latest video/audio/subtitle markup and all five generated
+  gallery captions.
+- [ ] Field Notes URL is public, not `401`.
+- [ ] Demo video uploaded and linked in README.
+- [ ] Social post published and linked in README.
+- [ ] README redeployed to HF Space after links are inserted.
+- [ ] Human click confirms Space play starts audio, video, captions, and progress together.
+- [ ] Physical e2e: glasses/iPhone produce in-ear narration and the same cut appears in Space.
+- [ ] Submission analyzer passes.
+
+Deadline rule: if the Field Notes URL is still private near final submission, either make it public
+through the HF web editor or remove `achievement:fieldnotes` from README/frontmatter before the
+final analyzer pass. Do not submit a broken badge claim.

modal_app/small_cuts_postcut.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Any
+
+import fastapi
+import modal
+from fastapi import File, Form, Header, HTTPException, UploadFile
+from fastapi.responses import JSONResponse
+
+BUCKET_ID = "build-small-hackathon/small-cuts-scenes"
+RELAY_PREFIX = "relay"
+MAX_UPLOAD_BYTES = 80 * 1024 * 1024
+MAX_UPLOAD_SECONDS = 60.0
+MAX_SAMPLE_FRAMES = 40
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .apt_install("ffmpeg")
+    .pip_install(
+        "fastapi[standard]",
+        "huggingface-hub>=1.19",
+        "pillow>=10.0",
+        "pillow-heif>=0.18",
+        "av>=12.0",
+        "soundfile>=0.12",
+        "transformers>=4.49",
+        "torch>=2.4",
+        "torchvision>=0.19",
+        "accelerate>=1.0",
+        "kokoro>=0.9",
+    )
+    .add_local_dir("src", remote_path="/root/src")
+    .add_local_dir("docs/contracts", remote_path="/root/docs/contracts")
+)
+
+app = modal.App("small-cuts-postcut")
+web_app = fastapi.FastAPI()
+
+
+def _require_bearer(authorization: str | None) -> None:
+    expected = os.environ["SMALL_CUTS_MODAL_API_TOKEN"]
+    if authorization != f"Bearer {expected}":
+        raise HTTPException(status_code=401, detail="unauthorized")
+
+
+def _video_duration_s(path: Path) -> float:
+    import av
+
+    with av.open(str(path)) as container:
+        if container.duration is not None:
+            return float(container.duration / 1_000_000)
+        stream = container.streams.video[0]
+        if stream.duration is not None and stream.time_base is not None:
+            return float(stream.duration * stream.time_base)
+    raise ValueError("could not determine video duration")
+
+
+def _sample_interval_s(duration_s: float) -> float:
+    return max(0.5, duration_s / MAX_SAMPLE_FRAMES)
+
+
+@app.function(
+    image=image,
+    timeout=60,
+    min_containers=1,
+    buffer_containers=1,
+    scaledown_window=1200,
+    secrets=[modal.Secret.from_name("small-cuts-postcut")],
+)
+@modal.concurrent(max_inputs=20, target_inputs=10)
+@modal.asgi_app()
+def api():
+    return web_app
+
+
+@web_app.post("/v1/cuts")
+async def accept_cut(
+    video: Annotated[UploadFile, File()],
+    style_key: Annotated[str, Form()] = "deadpan",
+    scene_hint: Annotated[str, Form()] = "",
+    uploader_hf_username: Annotated[str, Form()] = "unknown",
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, str]:
+    _require_bearer(authorization)
+    payload = await video.read()
+    if len(payload) > MAX_UPLOAD_BYTES:
+        raise HTTPException(status_code=413, detail="video is too large")
+    safe_filename = Path(video.filename or "upload.mp4").name
+    with tempfile.TemporaryDirectory(prefix="small-cuts-accept-") as tmp:
+        probe_path = Path(tmp) / safe_filename
+        probe_path.write_bytes(payload)
+        try:
+            duration_s = _video_duration_s(probe_path)
+        except Exception as exc:
+            raise HTTPException(status_code=422, detail="could not decode video") from exc
+    if duration_s > MAX_UPLOAD_SECONDS + 0.25:
+        raise HTTPException(
+            status_code=422,
+            detail=f"video is too long; upload up to {MAX_UPLOAD_SECONDS:.0f} seconds",
+        )
+    call = await process_cut.spawn.aio(
+        payload,
+        safe_filename,
+        style_key,
+        scene_hint,
+        uploader_hf_username,
+        duration_s,
+    )
+    return {"job_id": call.object_id}
+
+
+@web_app.get("/v1/cuts/{job_id}")
+def poll_cut(job_id: str, authorization: str | None = Header(default=None)):
+    _require_bearer(authorization)
+    call = modal.FunctionCall.from_id(job_id)
+    try:
+        return call.get(timeout=0)
+    except TimeoutError:
+        return JSONResponse({"status": "running"}, status_code=202)
+
+
+@app.function(
+    image=image,
+    gpu=["H100", "A100-80GB", "L40S"],
+    timeout=900,
+    min_containers=1,
+    buffer_containers=1,
+    max_containers=4,
+    scaledown_window=1200,
+    secrets=[modal.Secret.from_name("small-cuts-postcut")],
+)
+def process_cut(
+    video_bytes: bytes,
+    filename: str,
+    style_key: str,
+    scene_hint: str,
+    uploader_hf_username: str,
+    upload_duration_s: float,
+) -> dict[str, Any]:
+    sys.path.insert(0, "/root/src")
+    os.environ.setdefault("SMALL_CUTS_BACKEND", "transformers")
+    os.environ.setdefault("SMALL_CUTS_TTS_BACKEND", "kokoro")
+
+    import soundfile as sf
+    from huggingface_hub import HfApi
+
+    from small_cuts.engine.library import _write_clip_mp4
+    from small_cuts.frames import pick_key_frame, sample_frames
+    from small_cuts.narrator import narrate
+    from small_cuts.title_card import render_title_card
+    from small_cuts.tts import speak
+
+    scene_id = f"modal-{uuid.uuid4().hex[:12]}"
+    work = Path(tempfile.mkdtemp(prefix="small-cuts-modal-"))
+    input_path = work / Path(filename).name
+    input_path.write_bytes(video_bytes)
+
+    frames = sample_frames(
+        input_path,
+        every_n_seconds=_sample_interval_s(upload_duration_s),
+        max_frames=MAX_SAMPLE_FRAMES,
+    )
+    if not frames:
+        raise RuntimeError("could not decode video frames")
+    key_frame = pick_key_frame(frames)
+    narration = narrate(key_frame, style_key=style_key, scene_hint=scene_hint)
+    speech = speak(narration.text)
+
+    upload_prefix = f"uploads/{scene_id}"
+    scene_dir = work / upload_prefix
+    media_dir = scene_dir / "media"
+    media_dir.mkdir(parents=True, exist_ok=True)
+    frame_path = media_dir / "frame.jpg"
+    card_path = media_dir / "card.webp"
+    clip_path = media_dir / "clip.mp4"
+    voice_path = media_dir / "voice.wav"
+    key_frame.convert("RGB").save(frame_path, "JPEG", quality=90)
+    render_title_card(narration.title or narration.text, style_key=style_key).save(
+        card_path, "WEBP"
+    )
+    _write_clip_mp4(clip_path, frames, fps=8, blend_steps=0)
+    sf.write(voice_path, speech.audio, speech.sample_rate)
+
+    scene = {
+        "scene_id": scene_id,
+        "title": narration.title,
+        "narration": narration.text,
+        "style_key": style_key,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "visibility": "public",
+        "uploader_hf_username": uploader_hf_username,
+        "source": "upload",
+        "media": {
+            "frame_url": f"{upload_prefix}/media/frame.jpg",
+            "card_url": f"{upload_prefix}/media/card.webp",
+            "clip_url": f"{upload_prefix}/media/clip.mp4",
+            "audio_url": f"{upload_prefix}/media/voice.wav",
+        },
+        "duration": len(speech.audio) / speech.sample_rate if speech.sample_rate else None,
+        "model": narration.model_id,
+        "tts_model": speech.model_id,
+    }
+    (scene_dir / "scene.json").write_text(json.dumps(scene, indent=2) + "\n")
+    HfApi().sync_bucket(
+        source=str(scene_dir),
+        dest=f"hf://buckets/{BUCKET_ID}/{RELAY_PREFIX}/{upload_prefix}",
+    )
+    return {"status": "complete", "scene": scene}

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "gradio>=5.0",
+    "itsdangerous>=2.2",
     "pillow>=10.0",
     "pillow-heif>=0.18",
     "av>=12.0",

requirements.txt

@@ -5,5 +5,6 @@ pillow-heif>=0.18
 av>=12.0
 httpx>=0.27
 huggingface-hub>=1.19
+itsdangerous>=2.2
 sentry-sdk>=2.0
 soundfile>=0.12

scripts/publish_hf_relay.py

@@ -50,6 +50,11 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Publish private scenes too. Use only for an intentional controlled demo.",
     )
+    parser.add_argument(
+        "--source",
+        default="",
+        help='Optional public provenance marker for staged scenes, e.g. "glasses".',
+    )
     parser.add_argument(
         "--delete-extra",
         action="store_true",
@@ -80,6 +85,7 @@ def publish_once(args: argparse.Namespace) -> None:
         stage_dir,
         limit=args.limit,
         include_private=args.include_private,
+        source=args.source.strip() or None,
     )
     dest = f"hf://buckets/{args.bucket}/{args.prefix.strip('/')}"
     if args.dry_run:

src/small_cuts/CLAUDE.md

@@ -20,8 +20,21 @@ the canonical command list, and the architecture live in the **root `CLAUDE.md`*
   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 **`SMALL_CUTS_ENGINE_URL`**: **set** → engine mode (polls `GET /v1/scenes`,
-  visibility `PATCH` back); **unset** → upload mode (the Space's local "go live" dropzone).
+- Decided at build time by env:
+  - **Pure relay mode**: `SMALL_CUTS_RELAY_BUCKET` set and upload sandbox unset. This is the current
+    judged-Space posture for
+    `build-small-hackathon/small-cuts-live`: viewer-only, CPU Basic, no local model/TTS load, reads a
+    finished-scene manifest + media from an 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
+    the private Modal app `small-cuts-postcut`; promote to the org Space 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**; gr.Audio stripped to **play/pause + volume**;
@@ -42,6 +55,9 @@ the canonical command list, and the architecture live in the **root `CLAUDE.md`*
   strip-and-couple path instead of the swap, since the swap touches Space file-serving.)
 
 ## ZeroGPU gotchas (hard-won — see KB `…/space/`)
+- 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.
 - `@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;
@@ -52,3 +68,7 @@ the canonical command list, and the architecture live in the **root `CLAUDE.md`*
 ## 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/_icons.py

@@ -6,6 +6,9 @@ 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"); }

src/small_cuts/engine/library.py

@@ -287,7 +287,12 @@ class SceneLibrary:
             self._db.close()
 
 
-def _write_clip_mp4(path: Path, frames: list[Image.Image], fps: int = CLIP_MP4_FPS) -> None:
+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
 
@@ -297,9 +302,7 @@ def _write_clip_mp4(path: Path, frames: list[Image.Image], fps: int = CLIP_MP4_F
     # 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=CLIP_BLEND_STEPS, size=(width, height)
-    )
+    encode_frames = _smooth_clip_frames(rgb_frames, blend_steps=blend_steps, size=(width, height))
 
     container = av.open(str(path), "w")
     try:

src/small_cuts/hf_relay.py

@@ -150,6 +150,7 @@ def prepare_relay_snapshot(
     *,
     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."""
@@ -165,7 +166,7 @@ def prepare_relay_snapshot(
         response.raise_for_status()
         scenes = response.json().get("scenes", [])[-limit:]
         published = [
-            _stage_scene_media(base_url, output, scene, http)
+            _stage_scene_media(base_url, output, scene, http, source=source)
             for scene in scenes
             if _should_publish_scene(scene, include_private=include_private)
         ]
@@ -194,8 +195,13 @@ def _stage_scene_media(
     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"] = {}

src/small_cuts/modal_upload.py

@@ -0,0 +1,87 @@
+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."""
+
+
+@dataclass
+class ModalUploadClient:
+    base_url: str
+    token: str
+    http_client: httpx.Client | None = None
+    poll_interval_s: float = 1.0
+    timeout_s: float = 180.0
+
+    def submit_video(
+        self,
+        video_path: str | Path,
+        *,
+        uploader_hf_username: str,
+        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:
+            job_id = self._submit(
+                client,
+                Path(video_path),
+                uploader_hf_username,
+                style_key,
+                scene_hint,
+            )
+            return self._poll(client, job_id)
+        finally:
+            if close:
+                client.close()
+
+    def _submit(
+        self,
+        client: httpx.Client,
+        video_path: Path,
+        uploader_hf_username: 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_hf_username": uploader_hf_username,
+                },
+                files={"video": (video_path.name, handle, "video/mp4")},
+            )
+        response.raise_for_status()
+        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
+            response.raise_for_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/viewer.py

@@ -39,6 +39,7 @@ from ._icons import ICON_CSS
 from .frames import pick_key_frame, sample_frames
 from .hf_relay import (
     DEFAULT_RELAY_PREFIX,
+    MEDIA_KEYS,
     RELAY_BUCKET_ENV,
     RELAY_PREFIX_ENV,
     BucketRelayError,
@@ -46,6 +47,7 @@ from .hf_relay import (
 from .hf_relay import (
     BucketSceneClient as _BucketSceneClient,
 )
+from .modal_upload import ModalUploadClient, ModalUploadError
 from .observability import capture_exception
 from .styles import DEFAULT_STYLE_KEY, STYLES
 from .title_card import derive_title
@@ -54,6 +56,10 @@ from .ui import THEME as THEME  # re-export: app.py launches the viewer with the
 from .ui import TITLE, _gpu, _narrate_core, _speak_handler
 
 ENGINE_URL_ENV = "SMALL_CUTS_ENGINE_URL"
+MODAL_API_URL_ENV = "SMALL_CUTS_MODAL_API_URL"
+MODAL_API_TOKEN_ENV = "SMALL_CUTS_MODAL_API_TOKEN"
+UPLOAD_SANDBOX_ENV = "SMALL_CUTS_ENABLE_UPLOAD_SANDBOX"
+UPLOAD_MAX_SECONDS_ENV = "SMALL_CUTS_UPLOAD_MAX_SECONDS"
 # The narrator-as-chat feed is dropped from the default layout (single centered column);
 # flip this on to revive it (a future "see transcription" surface for non-live clips).
 SHOW_FEED = os.environ.get("SMALL_CUTS_SHOW_FEED", "").strip().lower() not in (
@@ -68,6 +74,17 @@ FEED_LIMIT = 12
 SHELF_LIMIT = 60
 HTTP_TIMEOUT_S = 5.0
 VISIBILITIES = ("private", "shared", "public")
+_KEEP_UPLOAD_SCENE = object()
+SOURCE_ICON_LABELS = {
+    "glasses": "Glasses capture",
+    "upload": "Space upload",
+}
+GLASSES_SHELF_PREFIX = "\u2063sc-glasses\u2063"
+UPLOAD_SHELF_PREFIX = "\u2063sc-upload\u2063"
+_SOURCE_SHELF_PREFIXES = {
+    "glasses": GLASSES_SHELF_PREFIX,
+    "upload": UPLOAD_SHELF_PREFIX,
+}
 
 EMPTY_STAGE_CAPTION = (
     "The narrator clears his throat, looks at the empty screen, and waits. "
@@ -138,6 +155,15 @@ footer { display: none !important; }
   width: 100%; height: 100%; object-fit: cover; display: block; }
 .sc-stage-empty { width: 100%; height: 100%; display: flex; align-items: center;
   justify-content: center; font-size: 3rem; opacity: .35; }
+.sc-source-badge { position: absolute; top: 10px; left: 10px; z-index: 4;
+  width: 30px; height: 30px; display: inline-flex; align-items: center;
+  justify-content: center; border-radius: 999px; color: #f3efe4;
+  background: rgba(8,8,10,.68); border: 1px solid rgba(243,239,228,.24);
+  box-shadow: 0 3px 12px rgba(0,0,0,.22); backdrop-filter: blur(7px); }
+.sc-source-badge-icon { width: 17px; height: 17px; background: currentColor;
+  -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat;
+  -webkit-mask-position: center; mask-position: center;
+  -webkit-mask-size: contain; mask-size: contain; }
 .sc-subtitle { position: absolute; left: 50%; transform: translateX(-50%); bottom: 26px;
   width: min(92%, 600px); min-height: 2.7em; display: flex; align-items: center;
   justify-content: center; text-align: center; background: rgba(8,8,10,.72);
@@ -176,6 +202,23 @@ footer { display: none !important; }
 .sc-dropzone-label { font-family: 'IBM Plex Mono', monospace; font-size: .72rem;
   letter-spacing: .14em; color: #8a8894; text-transform: uppercase; }
 .sc-shelf { background: transparent !important; border: none !important; }
+.sc-shelf .thumbnail-item { position: relative; }
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-glasses\\002063"])::before,
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-upload\\002063"])::before {
+  content: ""; position: absolute; top: 6px; left: 6px; width: 24px; height: 24px;
+  border-radius: 999px; background: rgba(8,8,10,.68);
+  border: 1px solid rgba(243,239,228,.22); z-index: 3; backdrop-filter: blur(6px);
+  box-shadow: 0 2px 8px rgba(0,0,0,.2); }
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-glasses\\002063"])::after,
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-upload\\002063"])::after {
+  content: ""; position: absolute; top: 11px; left: 11px; width: 14px; height: 14px;
+  background: #f3efe4; z-index: 4; -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat;
+  -webkit-mask-position: center; mask-position: center;
+  -webkit-mask-size: contain; mask-size: contain; }
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-glasses\\002063"])::after {
+  -webkit-mask-image: var(--sc-ico-glasses-mask); mask-image: var(--sc-ico-glasses-mask); }
+.sc-shelf .thumbnail-item:has(img[alt^="\\002063sc-upload\\002063"])::after {
+  -webkit-mask-image: var(--sc-ico-upload-mask); mask-image: var(--sc-ico-upload-mask); }
 
 /* --- Review-2 relayout: single centered column, control pill, masked icons --- */
 .sc-topbar { display: flex; align-items: flex-start; gap: 12px; }
@@ -289,6 +332,42 @@ VIEWER_CSS += ICON_CSS
 # -- scene formatting (pure, both modes) -------------------------------------------
 
 
+def _truthy_env(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes")
+
+
+def upload_sandbox_enabled() -> bool:
+    """Relay-mode judge uploads are enabled only when Modal is explicitly configured."""
+    return _truthy_env(UPLOAD_SANDBOX_ENV) and bool(os.environ.get(MODAL_API_URL_ENV, "").strip())
+
+
+def upload_max_seconds() -> float:
+    raw = os.environ.get(UPLOAD_MAX_SECONDS_ENV, "60").strip()
+    try:
+        return max(1.0, float(raw))
+    except ValueError:
+        return 60.0
+
+
+def _require_upload_profile(profile: gr.OAuthProfile | None) -> str:
+    username = (
+        getattr(profile, "username", None)
+        or (profile.get("preferred_username") if isinstance(profile, dict) else None)
+        or getattr(profile, "name", None)
+    )
+    if profile is None or not username:
+        raise gr.Error("Sign in with Hugging Face to upload a cut.")
+    return str(username)
+
+
+def _modal_upload_client() -> ModalUploadClient:
+    base_url = os.environ.get(MODAL_API_URL_ENV, "").strip()
+    token = os.environ.get(MODAL_API_TOKEN_ENV, "").strip()
+    if not base_url or not token:
+        raise gr.Error("Modal upload is not configured.")
+    return ModalUploadClient(base_url, token)
+
+
 def _style_label(style_key: str) -> str:
     style = STYLES.get(style_key)
     if style is not None:
@@ -296,6 +375,13 @@ def _style_label(style_key: str) -> str:
     return style_key or "off air"
 
 
+def _source_icon(scene: dict[str, Any] | None) -> str | None:
+    if not scene:
+        return None
+    source = scene.get("source_icon") or scene.get("source")
+    return source if isinstance(source, str) and source in SOURCE_ICON_LABELS else None
+
+
 def _parse_ts(value: str | None) -> datetime | None:
     if not value:
         return None
@@ -341,6 +427,7 @@ def format_stage(
             "duration": None,
             "live": False,
             "visibility": None,
+            "source_icon": None,
         }
     base = engine_url.rstrip("/")
 
@@ -361,6 +448,7 @@ def format_stage(
         "duration": scene.get("duration"),
         "live": is_fresh(scene.get("created_at"), now=now),
         "visibility": scene.get("visibility"),
+        "source_icon": _source_icon(scene),
     }
 
 
@@ -392,6 +480,7 @@ def render_stage_html(
     live: bool,
     clip_src: str | None = None,
     duration: float | None = None,
+    source_icon: str | None = None,
 ) -> str:
     """The 9:16 stage: the moment (video clip or still frame) + lower-third caption.
 
@@ -420,7 +509,16 @@ def render_stage_html(
         caption_html = f'<div class="sc-subtitle" id="sc-subtitle"{dur_attr}>{spans}</div>'
     else:
         caption_html = ""
-    return f'<div class="sc-stage-shell">{body}{caption_html}</div>'
+    if source_icon in SOURCE_ICON_LABELS:
+        label = html.escape(SOURCE_ICON_LABELS[source_icon], quote=True)
+        icon = html.escape(source_icon, quote=True)
+        badge_html = (
+            f'<span class="sc-source-badge sc-source-{icon}" aria-label="{label}" '
+            f'title="{label}"><span class="sc-source-badge-icon sc-ico-{icon}"></span></span>'
+        )
+    else:
+        badge_html = ""
+    return f'<div class="sc-stage-shell">{badge_html}{body}{caption_html}</div>'
 
 
 def render_header_html(
@@ -523,10 +621,30 @@ def shelf_items(
         media = scene.get("media") or {}
         src = client.media_url(media.get("frame_url") or media.get("card_url"))
         if src:
-            items.append((src, scene.get("title", "")))
+            items.append((src, _shelf_caption(scene)))
     return items
 
 
+def _shelf_caption(scene: dict[str, Any]) -> str:
+    title = scene.get("title", "")
+    source_icon = _source_icon(scene)
+    return f"{_SOURCE_SHELF_PREFIXES.get(source_icon, '')}{title}"
+
+
+def _scene_with_media_urls(
+    scene: dict[str, Any], client: EngineClient | BucketSceneClient
+) -> dict[str, Any]:
+    hydrated = {**scene}
+    media = scene.get("media")
+    if not isinstance(media, dict):
+        hydrated["media"] = {}
+        return hydrated
+    hydrated["media"] = {**media}
+    for key in MEDIA_KEYS:
+        hydrated["media"][key] = client.media_url(media.get(key))
+    return hydrated
+
+
 def poll_engine(
     client: EngineClient | BucketSceneClient,
     scenes_prev: list[dict[str, Any]],
@@ -588,6 +706,7 @@ def poll_engine(
         live=on_air,
         clip_src=payload["clip_src"],
         duration=payload["duration"],
+        source_icon=payload["source_icon"],
     )
     feed = render_feed_html([feed_entry(scene) for scene in scenes[-FEED_LIMIT:]])
 
@@ -605,6 +724,21 @@ def poll_engine(
 # -- upload mode (the hackathon Space) -------------------------------------------------
 
 
+def _video_duration_s(video_path: str | Path) -> float | None:
+    try:
+        import av
+
+        with av.open(str(video_path)) as container:
+            if container.duration is not None:
+                return float(container.duration / 1_000_000)
+            stream = container.streams.video[0] if container.streams.video else None
+            if stream and stream.duration is not None and stream.time_base is not None:
+                return float(stream.duration * stream.time_base)
+    except Exception as exc:
+        capture_exception(exc)
+    return None
+
+
 def _data_uri(image: Image.Image, max_side: int = 1080) -> str:
     thumb = image.copy()
     thumb.thumbnail((max_side, max_side))
@@ -635,7 +769,7 @@ def make_local_scene(
 
 
 def local_shelf_items(scenes: list[dict[str, Any]]) -> list[tuple[Image.Image, str]]:
-    return [(scene["card_thumb"], scene.get("title", "")) for scene in scenes]
+    return [(scene["card_thumb"], _shelf_caption(scene)) for scene in scenes]
 
 
 @_gpu()
@@ -680,6 +814,7 @@ def _go_live_handler(
             live=False,
             clip_src=payload["clip_src"],
             duration=payload["duration"],
+            source_icon=payload["source_icon"],
         ),
         render_feed_html([feed_entry(s) for s in scenes[-FEED_LIMIT:]]),
         local_shelf_items(scenes),
@@ -713,11 +848,13 @@ def _is_gradio_update(value: Any) -> bool:
 def _engine_ui_state(value: Any) -> dict[str, Any]:
     data = value if isinstance(value, dict) else {}
     scenes = data.get("scenes")
+    upload_scene = data.get("upload_scene")
     return {
         "scenes": scenes if isinstance(scenes, list) else [],
         "pinned_id": data.get("pinned_id"),
         "current_id": data.get("current_id"),
         "playing_id": data.get("playing_id"),
+        "upload_scene": upload_scene if isinstance(upload_scene, dict) else None,
     }
 
 
@@ -727,6 +864,7 @@ def _pack_engine_ui_state(
     current_id: Any,
     playing_id: Any,
     previous: dict[str, Any] | None = None,
+    upload_scene: Any = _KEEP_UPLOAD_SCENE,
 ) -> dict[str, Any]:
     prev = _engine_ui_state(previous)
     return {
@@ -734,9 +872,69 @@ def _pack_engine_ui_state(
         "pinned_id": pinned_id,
         "current_id": prev["current_id"] if _is_gradio_update(current_id) else current_id,
         "playing_id": prev["playing_id"] if _is_gradio_update(playing_id) else playing_id,
+        "upload_scene": prev["upload_scene"]
+        if upload_scene is _KEEP_UPLOAD_SCENE
+        else upload_scene,
     }
 
 
+def _submit_modal_upload(
+    video_path: str | None,
+    style_key: str,
+    scene_hint: str,
+    state: Any,
+    profile: gr.OAuthProfile | None,
+    media_client: EngineClient | BucketSceneClient,
+) -> tuple[Any, ...]:
+    if not video_path:
+        raise gr.Error("Upload a video clip first.")
+
+    duration = _video_duration_s(video_path)
+    max_seconds = upload_max_seconds()
+    if duration is not None and duration > max_seconds + 0.25:
+        raise gr.Error(f"Please upload a clip up to {max_seconds:.0f} seconds.")
+
+    uploader = _require_upload_profile(profile)
+    try:
+        raw_scene = _modal_upload_client().submit_video(
+            video_path,
+            uploader_hf_username=uploader,
+            style_key=style_key,
+            scene_hint=scene_hint,
+        )
+    except (ModalUploadError, httpx.HTTPError) as exc:
+        raise gr.Error(f"Modal upload failed: {exc}") from exc
+
+    scene = _scene_with_media_urls(raw_scene, media_client)
+    current_state = _engine_ui_state(state)
+    scenes = [*current_state["scenes"], scene][-SHELF_LIMIT:]
+    payload = format_stage(scene)
+    scene_id = payload["scene_id"]
+    return (
+        render_header_html(payload["title"], payload["style_label"], live=False),
+        render_stage_html(
+            payload["frame_src"],
+            payload["caption"],
+            live=False,
+            clip_src=payload["clip_src"],
+            duration=payload["duration"],
+            source_icon=payload["source_icon"],
+        ),
+        render_feed_html([feed_entry(s) for s in scenes[-FEED_LIMIT:]]),
+        _audio_html(payload["audio_src"]) if payload["audio_src"] else gr.skip(),
+        shelf_items(scenes, media_client),
+        _pack_engine_ui_state(
+            scenes,
+            scene_id,
+            scene_id,
+            scene_id,
+            previous=current_state,
+            upload_scene=scene,
+        ),
+        gr.update(value=payload["visibility"]) if payload["visibility"] else gr.skip(),
+    )
+
+
 def _as_id_set(value: Any) -> set[str]:
     if not value:
         return set()
@@ -1025,6 +1223,8 @@ def build_viewer_app() -> gr.Blocks:
     else:
         client = None
     seed = _seed_scenes() if client is None else []
+    upload_sandbox = upload_sandbox_enabled()
+    upload_enabled = client is None or upload_sandbox
 
     if client:
         boot_header = render_header_html("Tuning the antenna…", "standby", live=False)
@@ -1039,6 +1239,7 @@ def build_viewer_app() -> gr.Blocks:
             live=False,
             clip_src=boot["clip_src"],
             duration=boot["duration"],
+            source_icon=boot["source_icon"],
         )
         boot_audio = _audio_html(boot["audio_src"])
 
@@ -1065,7 +1266,9 @@ def build_viewer_app() -> gr.Blocks:
                 "ear lands here as a cut you can keep.</span></div>",
                 padding=False,
             )
-            if client is None:
+            if upload_sandbox:
+                gr.LoginButton("Sign in", logout_value="Signed in ({})", size="sm")
+            if upload_enabled:
                 upload_btn = gr.Button("", elem_classes=["sc-icbtn", "sc-upload", "sc-ico-upload"])
         # Theater layout (Review-3): stage + controls on the left, the library as a side rail on
         # the right. Fills the width and keeps everything in one viewport (no main scroll); the
@@ -1111,10 +1314,10 @@ def build_viewer_app() -> gr.Blocks:
                     audio = gr.HTML(boot_audio, elem_classes="sc-audio-host", padding=False)
                 # The play tap is handled by PLAYBACK_SYNC_JS as a delegated DOM click so the
                 # browser keeps user activation for audio.play().
-                if client is None:
+                if upload_enabled:
                     # one signature voice — no director menu; voice-over is on by default
                     style = gr.State(DEFAULT_STYLE_KEY)
-                else:
+                if client is not None:
                     visibility_controls = os.environ.get(
                         "SMALL_CUTS_ENABLE_VISIBILITY_CONTROLS", ""
                     ).strip().lower() in ("1", "true", "yes")
@@ -1133,7 +1336,7 @@ def build_viewer_app() -> gr.Blocks:
                     padding=False,
                     visible=SHOW_FEED,
                 )
-                if client is None:
+                if upload_enabled:
                     # The upload sandbox opens on demand from the top-right icon — off the main
                     # view, video-only (the product narrates video, not stills).
                     image_none = gr.State(None)
@@ -1167,12 +1370,44 @@ def build_viewer_app() -> gr.Blocks:
         # "Back to live" is now the (clickable) header; this button stays for its un-pin /
         # re-follow-live wiring but is hidden via CSS and triggered by the header click in JS.
         live_btn = gr.Button("⟲ Back to live", elem_classes=["sc-live-btn"])
-        if client is None:
+        if upload_enabled:
             upload_btn.click(lambda: gr.update(open=True, visible=True), outputs=[tryit_panel])
 
         if client is not None:
             engine = client  # narrow the type for the closures below
 
+            if upload_sandbox:
+
+                def _go_modal_upload_ui(
+                    video_path,
+                    style_key,
+                    scene_hint,
+                    state,
+                    profile: gr.OAuthProfile | None,
+                ):
+                    return _submit_modal_upload(
+                        video_path,
+                        style_key,
+                        scene_hint,
+                        state,
+                        profile,
+                        engine,
+                    )
+
+                go.click(
+                    _go_modal_upload_ui,
+                    inputs=[drop_video, style, hint, scenes_state],
+                    outputs=[
+                        header,
+                        stage,
+                        feed,
+                        audio,
+                        shelf,
+                        scenes_state,
+                        visibility,
+                    ],
+                )
+
             def _tick(state):
                 state = _engine_ui_state(state)
                 (
@@ -1192,6 +1427,11 @@ def build_viewer_app() -> gr.Blocks:
                     state["playing_id"],
                     current_id=state["current_id"],
                 )
+                if state["upload_scene"] is not None:
+                    header_update = gr.skip()
+                    stage_update = gr.skip()
+                    audio_update = gr.skip()
+                    playing_id = state["playing_id"]
                 return (
                     header_update,
                     stage_update,
@@ -1239,6 +1479,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     _audio_html(payload["audio_src"]) if payload["audio_src"] else gr.skip(),
                     _pack_engine_ui_state(
@@ -1247,6 +1488,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["scene_id"],
                         payload["scene_id"],
                         previous=state,
+                        upload_scene=None,
                     ),
                     gr.update(value=payload["visibility"]) if payload["visibility"] else gr.skip(),
                 )
@@ -1279,6 +1521,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     _audio_html(payload["audio_src"]) if payload["audio_src"] else gr.skip(),
                     _pack_engine_ui_state(
@@ -1287,6 +1530,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["scene_id"],
                         payload["scene_id"],
                         previous=state,
+                        upload_scene=None,
                     ),
                     gr.update(value=payload["visibility"]) if payload["visibility"] else gr.skip(),
                 )
@@ -1312,6 +1556,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     audio_update,
                     _pack_engine_ui_state(
@@ -1320,6 +1565,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["scene_id"],
                         playing_id,
                         previous=state,
+                        upload_scene=None,
                     ),
                     gr.update(value=payload["visibility"]) if payload["visibility"] else gr.skip(),
                 )
@@ -1376,6 +1622,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     _audio_html(payload["audio_src"]),
                     payload["scene_id"],
@@ -1398,6 +1645,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     _audio_html(payload["audio_src"]),
                     None,
@@ -1423,6 +1671,7 @@ def build_viewer_app() -> gr.Blocks:
                         payload["live"],
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
+                        source_icon=payload["source_icon"],
                     ),
                     _audio_html(payload["audio_src"]),
                     scene["scene_id"],

tests/test_app_entrypoint.py

@@ -4,12 +4,43 @@ import sys
 import warnings
 from pathlib import Path
 
+import gradio.oauth
 from starlette.exceptions import StarletteDeprecationWarning
 
 
+def _mock_gradio_oauth(monkeypatch):
+    monkeypatch.setattr(
+        gradio.oauth,
+        "_get_mocked_oauth_info",
+        lambda: {
+            "access_token": "mock-oauth-token-for-ci",
+            "token_type": "bearer",
+            "expires_in": 3600,
+            "id_token": "AAAAAAAAAAAAAAAAAAAAAAAAAA",
+            "scope": "openid profile",
+            "expires_at": 9999999999,
+            "userinfo": {
+                "sub": "11111111111111111111111",
+                "name": "CI User",
+                "preferred_username": "ci-user",
+                "profile": "https://huggingface.co/ci-user",
+                "picture": "",
+                "website": "",
+                "aud": "00000000-0000-0000-0000-000000000000",
+                "auth_time": 1691672844,
+                "nonce": "aaaaaaaaaaaaaaaaaaa",
+                "iat": 1691672844,
+                "exp": 1691676444,
+                "iss": "https://huggingface.co",
+            },
+        },
+    )
+
+
 def test_space_engine_mode_does_not_force_local_backends(monkeypatch):
     monkeypatch.setenv("SPACE_ID", "build-small-hackathon/small-cuts")
     monkeypatch.setenv("SMALL_CUTS_ENGINE_URL", "http://127.0.0.1:9")
+    monkeypatch.delenv("SMALL_CUTS_RELAY_BUCKET", raising=False)
     monkeypatch.delenv("SMALL_CUTS_BACKEND", raising=False)
     monkeypatch.delenv("SMALL_CUTS_TTS_BACKEND", raising=False)
     monkeypatch.setitem(sys.modules, "spaces", None)
@@ -24,6 +55,45 @@ def test_space_engine_mode_does_not_force_local_backends(monkeypatch):
     assert os.environ.get("SMALL_CUTS_TTS_BACKEND") is None
 
 
+def test_space_bucket_relay_mode_does_not_force_local_backends(monkeypatch):
+    monkeypatch.setenv("SPACE_ID", "build-small-hackathon/small-cuts-live")
+    monkeypatch.delenv("SMALL_CUTS_ENGINE_URL", raising=False)
+    monkeypatch.setenv("SMALL_CUTS_RELAY_BUCKET", "build-small-hackathon/small-cuts-scenes")
+    monkeypatch.delenv("SMALL_CUTS_BACKEND", raising=False)
+    monkeypatch.delenv("SMALL_CUTS_TTS_BACKEND", raising=False)
+    monkeypatch.setitem(sys.modules, "spaces", None)
+
+    app_path = Path(__file__).resolve().parents[1] / "app.py"
+    spec = importlib.util.spec_from_file_location("_small_cuts_test_app_relay", app_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    assert os.environ.get("SMALL_CUTS_BACKEND") is None
+    assert os.environ.get("SMALL_CUTS_TTS_BACKEND") is None
+
+
+def test_space_relay_with_modal_upload_does_not_force_local_backends(monkeypatch):
+    monkeypatch.setenv("SPACE_ID", "build-small-hackathon/small-cuts-live")
+    monkeypatch.delenv("SMALL_CUTS_ENGINE_URL", raising=False)
+    monkeypatch.setenv("SMALL_CUTS_RELAY_BUCKET", "build-small-hackathon/small-cuts-scenes")
+    monkeypatch.setenv("SMALL_CUTS_ENABLE_UPLOAD_SANDBOX", "1")
+    monkeypatch.setenv("SMALL_CUTS_MODAL_API_URL", "https://example.modal.run")
+    monkeypatch.delenv("SMALL_CUTS_BACKEND", raising=False)
+    monkeypatch.delenv("SMALL_CUTS_TTS_BACKEND", raising=False)
+    monkeypatch.setitem(sys.modules, "spaces", None)
+    _mock_gradio_oauth(monkeypatch)
+
+    app_path = Path(__file__).resolve().parents[1] / "app.py"
+    spec = importlib.util.spec_from_file_location("_small_cuts_test_app_modal", app_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    assert os.environ.get("SMALL_CUTS_BACKEND") is None
+    assert os.environ.get("SMALL_CUTS_TTS_BACKEND") is None
+
+
 def test_app_filters_gradio_starlette_queue_warning(monkeypatch):
     monkeypatch.setenv("SMALL_CUTS_ENGINE_URL", "http://127.0.0.1:9")
 

tests/test_engine_library.py

@@ -28,6 +28,7 @@ from small_cuts.engine.library import (  # noqa: E402
     RGB_MODE,
     SceneLibrary,
     _smooth_clip_frames,
+    _write_clip_mp4,
 )
 from small_cuts.title_card import derive_title  # noqa: E402
 from test_engine_session import Reader, make_envelope  # noqa: E402
@@ -156,6 +157,18 @@ def test_store_writes_clip_url_and_title_for_multiframe_scene(tmp_path):
     assert clip.content == clip_path.read_bytes()
 
 
+def test_write_clip_mp4_can_disable_blends(tmp_path):
+    av = pytest.importorskip("av")
+    path = tmp_path / "clip.mp4"
+    frames = [Image.new("RGB", (64, 96), (i * 30, 20, 20)) for i in range(4)]
+
+    _write_clip_mp4(path, frames, fps=8, blend_steps=0)
+
+    with av.open(path) as container:
+        assert float(container.streams.video[0].average_rate) == pytest.approx(8)
+        assert sum(1 for _ in container.decode(video=0)) == 4
+
+
 def test_store_prefers_generated_title_when_present(tmp_path):
     lib = SceneLibrary(tmp_path / "lib")
     stored = lib.store(

tests/test_hf_relay.py

@@ -0,0 +1,112 @@
+import json
+
+import httpx
+
+from small_cuts import hf_relay
+from test_contracts import GOLDEN
+
+ENGINE_URL = "http://engine.test:8077"
+
+
+def test_prepare_relay_snapshot_writes_manifest_and_media(tmp_path):
+    scene = {
+        **GOLDEN["narrated-scene.schema.json"],
+        "visibility": "public",
+        "media": {
+            "frame_url": "/media/9f1c7e4a/frame.jpg",
+            "card_url": "/media/9f1c7e4a/card.webp",
+            "audio_url": "/media/9f1c7e4a/voice.wav",
+            "clip_url": "/media/9f1c7e4a/clip.mp4",
+        },
+    }
+    served = {
+        "/v1/scenes": httpx.Response(200, json={"scenes": [scene]}),
+        "/media/9f1c7e4a/frame.jpg": httpx.Response(200, content=b"frame"),
+        "/media/9f1c7e4a/card.webp": httpx.Response(200, content=b"card"),
+        "/media/9f1c7e4a/voice.wav": httpx.Response(200, content=b"voice"),
+        "/media/9f1c7e4a/clip.mp4": httpx.Response(200, content=b"clip"),
+    }
+
+    def handler(request):
+        return served[request.url.path]
+
+    snapshot = hf_relay.prepare_relay_snapshot(
+        ENGINE_URL,
+        tmp_path,
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    assert snapshot.scene_count == 1
+    manifest = json.loads((tmp_path / "manifest.json").read_text())
+    (published,) = manifest["scenes"]
+    assert published["media"]["frame_url"] == "media/9f1c7e4a/frame.jpg"
+    assert (tmp_path / "media/9f1c7e4a/frame.jpg").read_bytes() == b"frame"
+    assert (tmp_path / "media/9f1c7e4a/voice.wav").read_bytes() == b"voice"
+    assert manifest["source_engine"] == ENGINE_URL
+
+
+def test_prepare_relay_snapshot_skips_private_scenes_by_default(tmp_path):
+    private_scene = {**GOLDEN["narrated-scene.schema.json"], "visibility": "private"}
+
+    def handler(request):
+        assert request.url.path == "/v1/scenes"
+        return httpx.Response(200, json={"scenes": [private_scene]})
+
+    snapshot = hf_relay.prepare_relay_snapshot(
+        ENGINE_URL,
+        tmp_path,
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    assert snapshot.scene_count == 0
+    assert json.loads((tmp_path / "manifest.json").read_text())["scenes"] == []
+
+
+def test_prepare_relay_snapshot_can_include_private_scenes(tmp_path):
+    private_scene = {
+        **GOLDEN["narrated-scene.schema.json"],
+        "visibility": "private",
+        "media": {"frame_url": "/media/9f1c7e4a/frame.jpg"},
+    }
+
+    def handler(request):
+        if request.url.path == "/v1/scenes":
+            return httpx.Response(200, json={"scenes": [private_scene]})
+        assert request.url.path == "/media/9f1c7e4a/frame.jpg"
+        return httpx.Response(200, content=b"frame")
+
+    snapshot = hf_relay.prepare_relay_snapshot(
+        ENGINE_URL,
+        tmp_path,
+        include_private=True,
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    assert snapshot.scene_count == 1
+    assert (tmp_path / "media/9f1c7e4a/frame.jpg").exists()
+
+
+def test_prepare_relay_snapshot_can_mark_scene_source(tmp_path):
+    scene = {
+        **GOLDEN["narrated-scene.schema.json"],
+        "visibility": "public",
+        "media": {"frame_url": "/media/9f1c7e4a/frame.jpg"},
+    }
+
+    def handler(request):
+        if request.url.path == "/v1/scenes":
+            return httpx.Response(200, json={"scenes": [scene]})
+        assert request.url.path == "/media/9f1c7e4a/frame.jpg"
+        return httpx.Response(200, content=b"frame")
+
+    hf_relay.prepare_relay_snapshot(
+        ENGINE_URL,
+        tmp_path,
+        source="glasses",
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    manifest = json.loads((tmp_path / "manifest.json").read_text())
+    (published,) = manifest["scenes"]
+    assert published["source"] == "glasses"
+    assert published["source_icon"] == "glasses"

tests/test_modal_upload.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from small_cuts.modal_upload import ModalUploadClient, ModalUploadError
+
+
+def test_modal_client_submits_and_polls_result(tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"fake")
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, request.url.path))
+        if request.method == "POST":
+            assert request.headers["authorization"] == "Bearer secret"
+            return httpx.Response(200, json={"job_id": "job-1"})
+        if request.url.path.endswith("/job-1") and len(calls) == 2:
+            return httpx.Response(202, json={"status": "running"})
+        return httpx.Response(200, json={"status": "complete", "scene": {"scene_id": "s1"}})
+
+    client = ModalUploadClient(
+        "https://modal.example",
+        "secret",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+        poll_interval_s=0,
+    )
+
+    assert client.submit_video(video, uploader_hf_username="alice")["scene_id"] == "s1"
+    assert calls == [
+        ("POST", "/v1/cuts"),
+        ("GET", "/v1/cuts/job-1"),
+        ("GET", "/v1/cuts/job-1"),
+    ]
+
+
+def test_modal_client_rejects_missing_scene(tmp_path):
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"fake")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            return httpx.Response(200, json={"job_id": "job-1"})
+        return httpx.Response(200, json={"status": "complete"})
+
+    client = ModalUploadClient(
+        "https://modal.example",
+        "secret",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+        poll_interval_s=0,
+    )
+
+    with pytest.raises(ModalUploadError, match="scene"):
+        client.submit_video(video, uploader_hf_username="alice")

tests/test_observability.py

@@ -0,0 +1,62 @@
+from small_cuts import observability
+
+
+class FakeSentrySdk:
+    def __init__(self):
+        self.init_calls = []
+        self.captured = []
+
+    def init(self, **kwargs):
+        self.init_calls.append(kwargs)
+
+    def capture_exception(self, exc):
+        self.captured.append(exc)
+
+
+def test_sentry_init_is_noop_without_dsn(monkeypatch):
+    fake = FakeSentrySdk()
+    monkeypatch.delenv(observability.SENTRY_DSN_ENV, raising=False)
+    observability.reset_for_tests()
+
+    assert observability.init_sentry(sdk=fake) is False
+    assert fake.init_calls == []
+
+
+def test_sentry_init_scrubs_request_payload(monkeypatch):
+    fake = FakeSentrySdk()
+    monkeypatch.setenv(observability.SENTRY_DSN_ENV, "https://example@sentry.invalid/1")
+    monkeypatch.setenv("SPACE_ID", "build-small-hackathon/small-cuts-live")
+    observability.reset_for_tests()
+
+    assert observability.init_sentry(sdk=fake) is True
+    (kwargs,) = fake.init_calls
+    assert kwargs["send_default_pii"] is False
+    assert kwargs["traces_sample_rate"] == 0.0
+    event = {
+        "request": {
+            "data": "frame bytes",
+            "cookies": "session",
+            "headers": {"authorization": "secret", "content-type": "application/json"},
+            "url": "https://example.test/v1/scenes",
+        }
+    }
+
+    scrubbed = kwargs["before_send"](event, {})
+
+    assert "data" not in scrubbed["request"]
+    assert "cookies" not in scrubbed["request"]
+    assert scrubbed["request"]["headers"] == {"content-type": "application/json"}
+
+
+def test_capture_exception_requires_initialized_sentry(monkeypatch):
+    fake = FakeSentrySdk()
+    observability.reset_for_tests()
+    monkeypatch.delenv(observability.SENTRY_DSN_ENV, raising=False)
+
+    exc = RuntimeError("boom")
+    observability.capture_exception(exc, sdk=fake)
+    assert fake.captured == []
+
+    monkeypatch.setenv(observability.SENTRY_DSN_ENV, "https://example@sentry.invalid/1")
+    observability.capture_exception(exc, sdk=fake)
+    assert fake.captured == [exc]

tests/test_viewer.py

@@ -8,6 +8,8 @@ viewer's formatter is pinned to the same shape the contract suite enforces.
 import json
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
+from types import SimpleNamespace
+from urllib.parse import unquote
 
 import gradio as gr
 import httpx
@@ -47,6 +49,207 @@ def test_build_viewer_app_engine_mode_needs_no_live_engine(monkeypatch):
     assert isinstance(viewer.build_viewer_app(), gr.Blocks)
 
 
+def test_build_viewer_app_bucket_relay_mode_needs_no_live_engine(monkeypatch):
+    monkeypatch.delenv(viewer.ENGINE_URL_ENV, raising=False)
+    monkeypatch.setenv(viewer.RELAY_BUCKET_ENV, "build-small-hackathon/small-cuts-scenes")
+    assert isinstance(viewer.build_viewer_app(), gr.Blocks)
+
+
+def test_upload_sandbox_requires_modal_url(monkeypatch):
+    monkeypatch.setenv("SMALL_CUTS_ENABLE_UPLOAD_SANDBOX", "1")
+    monkeypatch.delenv("SMALL_CUTS_MODAL_API_URL", raising=False)
+
+    assert viewer.upload_sandbox_enabled() is False
+
+    monkeypatch.setenv("SMALL_CUTS_MODAL_API_URL", "https://example.modal.run")
+
+    assert viewer.upload_sandbox_enabled() is True
+
+
+def test_upload_requires_hf_profile():
+    with pytest.raises(gr.Error, match="Sign in"):
+        viewer._require_upload_profile(None)
+
+
+def test_upload_profile_uses_hf_username():
+    profile = SimpleNamespace(name="Alice Example", username="alice")
+
+    assert viewer._require_upload_profile(profile) == "alice"
+
+
+def test_uploaded_scene_is_preserved_in_engine_state():
+    upload_scene = {
+        "scene_id": "modal-upload-1",
+        "title": "A Finished Judge Upload",
+        "source": "upload",
+    }
+
+    state = viewer._pack_engine_ui_state(
+        scenes=[],
+        pinned_id=None,
+        current_id=None,
+        playing_id=None,
+        previous={"upload_scene": upload_scene},
+    )
+
+    assert state["upload_scene"]["scene_id"] == "modal-upload-1"
+
+
+def test_upload_video_cap_defaults_to_sixty_seconds(monkeypatch):
+    monkeypatch.delenv("SMALL_CUTS_UPLOAD_MAX_SECONDS", raising=False)
+
+    assert viewer.upload_max_seconds() == 60.0
+
+
+def test_modal_scene_can_drive_uploaded_stage():
+    scene = {
+        "scene_id": "modal-1",
+        "title": "A sentence.",
+        "narration": "A sentence.",
+        "style_key": "deadpan",
+        "created_at": "2026-06-15T12:00:00+00:00",
+        "media": {
+            "frame_url": "/gradio_api/file=/tmp/frame.jpg",
+            "clip_url": "/gradio_api/file=/tmp/clip.mp4",
+            "audio_url": "/gradio_api/file=/tmp/voice.wav",
+        },
+        "duration": 12.5,
+    }
+
+    payload = viewer.format_stage(scene)
+
+    assert payload["clip_src"].endswith("clip.mp4")
+    assert payload["audio_src"].endswith("voice.wav")
+    assert payload["duration"] == 12.5
+
+
+def test_format_stage_marks_source_icons():
+    scene = {**GOLDEN_SCENE, "source": "glasses"}
+    upload_scene = {**GOLDEN_SCENE, "source": "upload"}
+
+    glasses_payload = viewer.format_stage(scene, ENGINE_URL)
+    upload_payload = viewer.format_stage(upload_scene, ENGINE_URL)
+
+    assert glasses_payload["source_icon"] == "glasses"
+    assert upload_payload["source_icon"] == "upload"
+
+
+def test_submit_modal_upload_rejects_over_duration(monkeypatch):
+    monkeypatch.setenv("SMALL_CUTS_UPLOAD_MAX_SECONDS", "60")
+    monkeypatch.setattr(viewer, "_video_duration_s", lambda _path: 61.0)
+
+    with pytest.raises(gr.Error, match="up to 60 seconds"):
+        viewer._submit_modal_upload(
+            "clip.mp4",
+            "deadpan",
+            "",
+            viewer._pack_engine_ui_state([], None, None, None),
+            SimpleNamespace(name="Alice Example", username="alice"),
+            fake_client(lambda _request: httpx.Response(200, json={"scenes": []})),
+        )
+
+
+def test_submit_modal_upload_pins_returned_scene(monkeypatch):
+    scene = {
+        "scene_id": "modal-1",
+        "title": "A Modal Scene",
+        "narration": "The clip now has a real voice.",
+        "style_key": "deadpan",
+        "created_at": "2026-06-15T12:00:00+00:00",
+        "visibility": "public",
+        "media": {
+            "frame_url": "uploads/modal-1/media/frame.jpg",
+            "card_url": "uploads/modal-1/media/card.webp",
+            "clip_url": "uploads/modal-1/media/clip.mp4",
+            "audio_url": "uploads/modal-1/media/voice.wav",
+        },
+        "duration": 7.5,
+        "source": "upload",
+    }
+    calls = []
+
+    class FakeModalUploadClient:
+        def submit_video(self, video_path, *, uploader_hf_username, style_key, scene_hint):
+            calls.append((video_path, uploader_hf_username, style_key, scene_hint))
+            return scene
+
+    class FakeMediaClient:
+        base_url = ""
+
+        def media_url(self, path):
+            return f"/gradio_api/file=/tmp/{Path(path).name}" if path else None
+
+    monkeypatch.setattr(viewer, "_video_duration_s", lambda _path: 7.5)
+    monkeypatch.setattr(viewer, "_modal_upload_client", lambda: FakeModalUploadClient())
+
+    header, stage, feed, audio, shelf, state, visibility = viewer._submit_modal_upload(
+        "clip.mp4",
+        "deadpan",
+        "show the ending",
+        viewer._pack_engine_ui_state([], None, None, None),
+        SimpleNamespace(name="Alice Example", username="alice"),
+        FakeMediaClient(),
+    )
+
+    assert calls == [("clip.mp4", "alice", "deadpan", "show the ending")]
+    assert "A Modal Scene" in header
+    assert "clip.mp4" in stage
+    assert "sc-ico-upload" in stage
+    assert "real voice" in feed
+    assert "voice.wav" in audio
+    assert shelf == [
+        ("/gradio_api/file=/tmp/frame.jpg", f"{viewer.UPLOAD_SHELF_PREFIX}A Modal Scene")
+    ]
+    assert state["upload_scene"]["scene_id"] == "modal-1"
+    assert state["current_id"] == "modal-1"
+    assert state["playing_id"] == "modal-1"
+    assert visibility["value"] == "public"
+
+
+def test_bucket_scene_client_reads_manifest_and_caches_media(tmp_path, monkeypatch):
+    class FakeBucketFs:
+        def __init__(self, files):
+            self.files = files
+            self.seen = []
+
+        def cat(self, path):
+            self.seen.append(path)
+            return self.files[path]
+
+    media = {
+        "frame_url": "media/9f1c7e4a/frame.jpg",
+        "card_url": "media/9f1c7e4a/card.webp",
+        "audio_url": "media/9f1c7e4a/voice.wav",
+        "clip_url": "media/9f1c7e4a/clip.mp4",
+    }
+    scene = {**GOLDEN_SCENE, "media": media}
+    root = "hf://buckets/build-small-hackathon/small-cuts-scenes/relay"
+    fake_fs = FakeBucketFs(
+        {
+            f"{root}/manifest.json": json.dumps({"scenes": [scene]}).encode(),
+            f"{root}/media/9f1c7e4a/frame.jpg": b"frame",
+            f"{root}/media/9f1c7e4a/card.webp": b"card",
+            f"{root}/media/9f1c7e4a/voice.wav": b"voice",
+            f"{root}/media/9f1c7e4a/clip.mp4": b"clip",
+        }
+    )
+    monkeypatch.setattr(viewer.gr, "set_static_paths", lambda _paths: None)
+
+    client = viewer.BucketSceneClient(
+        "build-small-hackathon/small-cuts-scenes",
+        prefix="relay",
+        fs=fake_fs,
+        cache_dir=tmp_path,
+    )
+
+    (hydrated,) = client.list_scenes()
+    frame_url = hydrated["media"]["frame_url"]
+    assert frame_url.startswith("/gradio_api/file=")
+    assert Path(unquote(frame_url.removeprefix("/gradio_api/file="))).read_bytes() == b"frame"
+    assert (tmp_path / "media/9f1c7e4a/voice.wav").read_bytes() == b"voice"
+    assert f"{root}/manifest.json" in fake_fs.seen
+
+
 # -- scene-poll formatter --------------------------------------------------------------
 
 
@@ -74,6 +277,7 @@ def test_format_stage_no_scene_is_off_air():
     assert payload["live"] is False
     assert payload["frame_src"] is None
     assert payload["scene_id"] is None
+    assert payload["source_icon"] is None
 
 
 def test_stage_html_escapes_caption_and_has_no_rec_chip():
@@ -84,6 +288,48 @@ def test_stage_html_escapes_caption_and_has_no_rec_chip():
     assert "REC" not in out
 
 
+def test_stage_html_shows_source_badges():
+    glasses = viewer.render_stage_html(
+        "http://x/f.jpg", "caption", live=False, source_icon="glasses"
+    )
+    upload = viewer.render_stage_html("http://x/f.jpg", "caption", live=False, source_icon="upload")
+
+    assert "sc-source-badge" in glasses
+    assert "sc-ico-glasses" in glasses
+    assert "Glasses capture" in glasses
+    assert "sc-source-badge" in upload
+    assert "sc-ico-upload" in upload
+    assert "Space upload" in upload
+
+    assert "sc-source-badge" not in viewer.render_stage_html(
+        "http://x/f.jpg", "caption", live=False, source_icon=None
+    )
+
+
+def test_shelf_items_marks_source_tiles():
+    class FakeMediaClient:
+        def media_url(self, path):
+            return f"/media/{path}" if path else None
+
+    glasses_scene = {
+        **GOLDEN_SCENE,
+        "source": "glasses",
+        "title": "A Glasses Scene",
+        "media": {"frame_url": "frame.jpg"},
+    }
+    upload_scene = {
+        **GOLDEN_SCENE,
+        "source": "upload",
+        "title": "An Upload Scene",
+        "media": {"frame_url": "upload.jpg"},
+    }
+
+    items = viewer.shelf_items([glasses_scene, upload_scene], FakeMediaClient())
+
+    assert items[0] == ("/media/frame.jpg", f"{viewer.GLASSES_SHELF_PREFIX}A Glasses Scene")
+    assert items[1] == ("/media/upload.jpg", f"{viewer.UPLOAD_SHELF_PREFIX}An Upload Scene")
+
+
 def test_playback_js_uses_trusted_dom_click_for_audio():
     # Browser audio user activation is tied to the real click call stack. Routing play through
     # gr.Button.click(js=...) can run too late and trigger NotAllowedError on the Space.