docs/UI_SPEC.md

UI_SPEC.md — The Radio

Off Brand badge bar: "pushes past the default Gradio look." The interface IS a radio. No visible Gradio chrome in the primary experience.

Implementation approach

• gr.Server custom frontend: single HTML/CSS/JS page served by the Space, talking to Gradio API routes (/api/broadcast, /api/transcribe, SSE/stream endpoint for StageEvents).
• No frontend framework — vanilla JS + CSS. One file each. (Fast to build, nothing to bundle, trivially auditable for judges reading the repo.)
• Keep a minimal fallback gr.Blocks UI mounted at /plain — REQ-02 insurance (interface must be a Gradio app) and judge-accessibility if the custom UI breaks on someone's browser.

Visual design

• The object: a 1940s wooden tabletop radio, drawn in CSS (rounded walnut cabinet, brass trim, fabric speaker grille, glass dial window). Centered, ~720px wide desktop; full-bleed mobile.
• Palette: walnut #4a2f1d, brass #c9a86a, cream dial #f3e9d2, amber glow #ffb84d, off-black room background with soft vignette.
• Type: dial numerals + station idents in a condensed retro sans (e.g. "Oswald"); body text in a humanist serif. Title card "MIDNIGHT STATIC" in deco lettering.
• Texture restraint: one wood grain, one fabric weave, subtle noise on background. No skeuomorphic overload — it should look art-directed, not clip-art.

Components & states

1. Genre dial — horizontal tuning band, 6 station marks (KNOX, WEIRD, GOLD, HEART, LAFF, RAAT). Drag or click; needle animates with slight overshoot; soft static-burst audio blip (<0.3s, pre-loaded) on station change. Selected station label glows amber.
2. Premise input — a "telegram slip" beneath the radio: single text field, placeholder rotates through 3 example premises. 300 char max.
3. CALL IN button — brass push-button with red lamp. Press → hold-to- record (MediaRecorder) → release → transcript appears on the telegram slip for confirm/edit (never auto-submit ASR output).
4. ON AIR sequence — submit → dial window becomes frequency scanner: needle sweeps, station idents fade through per StageEvent (87.9 WRITING… → 91.5 CASTING… → 94.7 FOLEY… → 98.3 SCORING… → 101.1 ON AIR). Amber "ON AIR" lamp lights on completion. The sweep is driven by real events, not a fake timer — if a stage stalls, the needle hovers (honest latency theater).
5. Playback — speaker grille pulses subtly with audio amplitude (analyser node). Below the radio, the script teleprinter: lines type out karaoke-synced to playback (we know exact line timestamps from the mixer). Cast names in small caps, deliveries as stage directions.
6. After the show — three brass controls: ⬇ KEEP (download MP3), ↻ ANOTHER STATION (same premise, re-pick genre — one click), ⤴ SHARE (copies link + poster if FLUX stretch landed).
7. Showcase reruns — on first load, dial window shows "NOW PLAYING: reruns" with 3 pre-cached broadcasts playable instantly. A judge must hear audio within 10 seconds of landing (SPEC quality bar).

Mobile (judges will open it on phones)

• Radio scales to viewport width; dial becomes swipeable.
• Hold-to-record needs touch events + iOS Safari mic permission flow tested.
• Teleprinter collapses to current-line-only marquee.

Loading/error voice

All system text stays in-fiction:

• quota exhausted → "The station is at capacity — enjoy a rerun."
• pipeline fallback → "Our writer spilled coffee on page two. Improvising."
• mic denied → "The call-in line seems to be down. Type your premise."

Asset budget

Static assets <600KB total (textures as CSS gradients where possible, station blip + needle sounds as short OGGs). The Space must feel instant even before any model loads.

Build order (Day 3)

1. Static radio render + dial interaction (2h)
2. Wire /api/broadcast + StageEvent scanner (1.5h)
3. Playback + teleprinter sync (1.5h)
4. CALL IN + mobile pass (1.5h)
5. Polish: lamp glows, needle physics, AUTHENTIC_AM toggle (1h) Fallback rule: if behind schedule, ship 1–3 polished and cut 4; a flawless mouse demo beats a buggy mic demo.